OpenClaw integration
How the DefenseClaw plugin works inside OpenClaw: components, end-to-end sequences for a model call and a tool call, correlation headers, approvals and the protocol range.
This page is the reference for the OpenClaw connector. It is the only connector that ships a first-party plugin in this repository (extensions/defenseclaw/). The plugin owns the OpenClaw-side wiring. The gateway and CLI own everything else.
Components
| Component | Role |
|---|---|
Plugin (extensions/defenseclaw/, TypeScript) | Hooks OpenClaw's fetch interceptor and the before_tool_call lifecycle. |
defenseclaw-gateway (Go) | Receives plugin requests, evaluates policy, returns verdicts and writes the audit row. |
defenseclaw CLI (Python) | Runs setup and exposes the TUI for audit, alerts, logs and inventory. |
The plugin's two checkpoints, the guardrail proxy and the inspect API, are drawn in the connector page.
Protocol compatibility
The gateway client speaks the OpenClaw WebSocket handshake across protocol v3 to v4. On connect it sends minProtocol: 3 and maxProtocol: 4. OpenClaw returns the negotiated hello-ok protocol plus its supported methods and events. Protocol v4 installs work, and the v3 challenge-response device flow is kept for older endpoints.
End-to-end flow
A model call
calls the model
redirects to the proxy
forwards if allowed
model response
checked response, or a block
response
A tool call
about to run a tool
POST /api/v1/inspect/tool
allow · alert · confirm · block
run, block, or requireApproval
asks for approval (confirm only)
approve or deny
reports the answer (logged)
Correlation headers
There is no X-DefenseClaw-Correlation-Id header. Depending on available context, plugin requests use X-DefenseClaw-Run-Id, X-DefenseClaw-Session-Id, X-DefenseClaw-Trace-Id, X-DefenseClaw-Agent-Id, X-DefenseClaw-Agent-Name, X-DefenseClaw-Policy-Id, X-DefenseClaw-Agent-Instance-Id and X-DefenseClaw-Sidecar-Instance-Id. The HTTP client identifies itself with X-DefenseClaw-Client. Optional fields are omitted when OpenClaw supplies no context. The fetch interceptor mints a fresh trace ID for each intercepted LLM call and reuses the most recent tool context for run and session attribution. The sidecar can echo sticky agent and sidecar instance IDs so later requests converge on the same identities.
HITL: the only connector with plugin-mediated approval
For a confirm verdict in action mode the plugin returns OpenClaw's requireApproval object with timeoutBehavior: "deny". OpenClaw applies the decision. The plugin's onResolution callback only logs it. It sends no separate "resolve approval" request to the gateway. OpenClaw is the only connector with plugin-mediated approval in its chat origin. Other native-ask connectors use their own host UI. See Human approval for the per-connector matrix.
Files DefenseClaw owns inside the OpenClaw tree
| What | Path |
|---|---|
| Allow and load entries | ~/.openclaw/openclaw.json |
| Plugin | ~/.openclaw/extensions/defenseclaw/ (openclaw.plugin.json, package.json, dist/index.js) |
| Hook scripts | ~/.defenseclaw/hooks |
DefenseClaw limits its OpenClaw-tree changes to extensions/defenseclaw/ and its managed entries in openclaw.json. Backups are byte for byte and hash-checked. Teardown restores the file, or removes only DefenseClaw's entries when the file drifted.
OpenClaw
Guard OpenClaw with a DefenseClaw plugin that sends model calls through the guardrail proxy and checks each tool call before it runs.
Cursor
Cursor connector installs user hooks that observe events or deny actions before they run. Action mode denies with Cursor's own response and does not enable native ask.