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

ComponentRole
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

OpenClaw
Plugin
Gateway
Model
calls the model
redirects to the proxy
forwards if allowed
model response
checked response, or a block
response
  1. 1OpenClaw to Plugin

    calls the model

  2. 2Plugin to Gateway

    redirects to the proxy

  3. 3Gateway to Model

    forwards if allowed

  4. 4Model to Gatewayreply

    model response

  5. 5Gateway to Pluginreply

    checked response, or a block

  6. 6Plugin to OpenClawreply

    response

The plugin's fetch interceptor sends each recognized LLM request to the guardrail proxy (port 4000 by default), keeping the original address in the X-DC-Target-URL header. The proxy checks the request before it forwards it and the response before it returns it.

A tool call

User
OpenClaw
Plugin
Gateway
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)
  1. 1OpenClaw to Plugin

    about to run a tool

  2. 2Plugin to Gateway

    POST /api/v1/inspect/tool

  3. 3Gateway to Pluginreply

    allow · alert · confirm · block

  4. 4Plugin to OpenClawreply

    run, block, or requireApproval

  5. 5OpenClaw to User

    asks for approval (confirm only)

  6. 6User to OpenClawreply

    approve or deny

  7. 7OpenClaw to Plugin

    reports the answer (logged)

Before each tool runs, the plugin posts it to the inspect API (port 18970 by default). In action mode a block verdict stops the tool and a confirm verdict becomes OpenClaw's requireApproval, which denies on timeout. Allow and alert let the tool run. OpenClaw asks the user and applies the answer. The plugin only logs it.

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

WhatPath
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.