OpenClaw integration

How DefenseClaw integrates with OpenClaw end-to-end — fetch interceptor, before_tool_call hook, correlation headers, plugin-mediated HITL approvals, and the audit loop.

OpenClaw is the connector DefenseClaw was designed against. It is also the only connector that ships a first-party plugin in the same repository (extensions/defenseclaw/). That plugin owns the OpenClaw-side wiring; the gateway and CLI own everything else.

Plugin install + first guardrail. The DefenseClaw plugin loads inside OpenClaw, routes supported traffic through the sidecar, and returns policy decisions through OpenClaw's native surfaces.

Components

DefenseClaw plugin

TypeScript plugin under extensions/defenseclaw/. Hooks into OpenClaw's fetch interceptor and before_tool_call lifecycle.

defenseclaw-gateway

Go sidecar. Receives plugin requests, evaluates policy, returns verdicts, and writes the audit row.

DefenseClaw CLI

Python operator surface. Runs setup and exposes the TUI for audit, alerts, logs, and inventory.

Protocol compatibility

The DefenseClaw gateway client speaks the OpenClaw WebSocket handshake across the protocol v3-v4 range. During connect it sends minProtocol: 3 and maxProtocol: 4; OpenClaw returns the negotiated hello-ok protocol plus the supported method and event feature sets. That keeps current OpenClaw protocol v4 installs compatible while preserving the v3 challenge-response device flow for older OpenClaw endpoints.

End-to-end flow

  1. 01User / approver OpenClaw

    prompt

  2. 02OpenClaw DefenseClaw plugin

    fetch (LLM request)

  3. 03DefenseClaw plugin DefenseClaw sidecar

    redirect through guardrail proxy

  4. 04DefenseClaw sidecar Model provider

    forward allowed request

  5. 05Model provider DefenseClaw sidecar

    model response

  6. 06DefenseClaw sidecar DefenseClaw plugin

    scanned response (or block)

  7. 07DefenseClaw plugin OpenClaw

    fetch response

  8. 08OpenClaw DefenseClaw plugin

    before_tool_call(name, args)

  9. 09DefenseClaw plugin DefenseClaw sidecar

    POST /api/v1/inspect/tool

  10. 10DefenseClaw sidecar DefenseClaw plugin

    allow / block / confirm

  11. 11DefenseClaw plugin OpenClaw

    allow / block / requireApproval

  12. 12OpenClaw User / approver

    native approval request (confirm only)

  13. 13User / approver OpenClaw

    approve / deny

  14. 14OpenClaw DefenseClaw plugin

    resolution callback (log only)

  15. 15OpenClaw User / approver

    response

The plugin proxies LLM fetches through the guardrail and sends before_tool_call events to the sidecar. Native approval requests are returned to OpenClaw; OpenClaw owns the operator decision.

Correlation headers

There is no X-DefenseClaw-Correlation-Id header. Depending on the available context, plugin requests use the shared header vocabulary 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 also identifies itself with X-DefenseClaw-Client.

Optional fields are omitted when OpenClaw has not supplied their context. The fetch interceptor mints a fresh trace ID for each intercepted LLM call and reuses the most recently observed tool context for run/session attribution. The sidecar can echo sticky agent/sidecar instance IDs so later requests converge on the same runtime identities.

HITL: the only connector with plugin-mediated approval

OpenClaw provides a native, plugin-mediated approval flow in its chat origin, so the operator approves or denies without leaving OpenClaw. For an action-mode confirm verdict, the plugin returns OpenClaw's requireApproval object with a deny-on-timeout policy. OpenClaw applies the decision. The plugin's onResolution callback logs the resolution; it does not send a separate "resolve approval" request to the DefenseClaw gateway. Other native-ask connectors use their own host hook UI instead of this plugin path.

Connectors and hook events without native ask apply their documented alert/allow/context fallback. Their events remain visible in audit and defenseclaw tui, but the TUI cannot resume the original call. See the HITL page for the per-connector matrix.

Files DefenseClaw owns inside the OpenClaw tree

openclaw.json (allow + load entries for the DefenseClaw plugin)

In normal, non-sandbox plugin setup, DefenseClaw limits its OpenClaw-tree changes to extensions/defenseclaw/ and its managed allow/load entries in openclaw.json. Backups are byte-for-byte; teardown either restores the file or surgically removes only DefenseClaw entries when the file has drifted. The experimental OpenShell sandbox has a separate, explicit ownership, pairing, networking, and config-patching lifecycle.

When this is the right connector

Pick OpenClaw when:

  • You want the strongest enforcement contract: proxy-mode interception, sandbox subprocess policy, native ask + plugin-mediated approval.
  • You're already running OpenClaw or are open to switching from Codex / Claude Code for security-critical workflows.
  • You need fail-closed behaviour on transport failures.

If you're not running OpenClaw, the Claude Code connector is the closest hook-only equivalent and supports native ask on PreToolUse.

Defaults

What every fresh DefenseClaw install ships with — three OPA policies (permissive / default / strict), three matching guardrail rule packs, the operator-config defaults, and how to pick the combination that fits your team's risk tolerance.

Observability

Configure DefenseClaw v8 logs, traces, metrics, redaction, local history, and independent export destinations from one observability graph.