OpenClaw

Guard OpenClaw with a DefenseClaw plugin that sends model calls through the guardrail proxy and checks each tool call before it runs.

DefenseClaw ships a plugin for OpenClaw. It redirects recognized model calls through the guardrail proxy, which checks the request and the response, and asks the gateway about each tool call before it runs. This is a proxy 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.

Plugin install and first guardrail on DefenseClaw 1.0.4: setup writes the DefenseClaw plugin into OpenClaw, restarts the gateway, and the first tool call is checked.

Platform support

PlatformStatusNotes
macOS and LinuxSupportedDefenseClaw hosts the required guardrail proxy and installs the first-party plugin. Subprocess policy is shell shims on both.
Native Windows x64UnsupportedDefenseClaw is hook-only on Windows, while the OpenClaw connector requires the guardrail proxy, which DefenseClaw does not host on Windows. There is no supported WSL, Docker, VM or mixed workaround.

Setup

On a new install, run defenseclaw init --connector openclaw first. Until DefenseClaw is initialized, defenseclaw setup openclaw stops with DefenseClaw is not initialized — run 'defenseclaw init' first.

OpenClaw's own gateway must be running (or be a service that openclaw gateway restart can start) before defenseclaw setup openclaw changes anything. If nothing answers at the gateway address in openclaw.json, setup stops with No changes made.: start it with openclaw gateway run and run the same command again.

defenseclaw setup openclaw --mode observe --restart
defenseclaw setup openclaw --mode action --human-approval --rule-pack default --restart

The proxy is in the data path in both modes. Observe records policy findings without blocking on those findings. During a gateway outage, the saved outage mode decides whether a model request continues directly to its configured provider with a warning. Action enforces policy. Run defenseclaw doctor to check the result.

Check it

defenseclaw status

The agent appears under Agents with its mode. defenseclaw doctor reports no failed check for it.

A full OpenClaw run on DefenseClaw 1.0.4: a prompt reaches the gateway, policy decides, OpenClaw asks for approval on a confirm verdict in its Control UI, the tool runs or is denied, and the audit row is written.

The sequence of a model call and a tool call, with approvals, is on the OpenClaw integration page.

Same user, own ports

Run the DefenseClaw gateway and the OpenClaw gateway as the same OS user. The plugin runs inside OpenClaw and reads that user's ~/.defenseclaw, and the DefenseClaw gateway connects to OpenClaw with that user's OpenClaw token.

Use one OS account for each DefenseClaw and OpenClaw pair. On a shared machine, give each account its own ports: gateway.api_port and guardrail.port for DefenseClaw, gateway.port in openclaw.json for OpenClaw.

DefenseClaw checks the listener before it sends a token. This protects against a process of another account that takes a port while a gateway restarts:

  • The plugin sends the DefenseClaw token and provider keys only to a loopback gateway.host. localhost means 127.0.0.1. With any other host the plugin sends nothing, and defenseclaw doctor fails the OpenClaw gateway.host row.
  • The listener must prove it holds the same token (/api/v1/hook-listener-proof). The gateway answers that proof only to its own OS account. When the proof fails, nothing is sent. A listener that answers without the proof is not an outage: in every policy a tool check is blocked and a model call fails as in a closed-mode gateway outage. A proof that finds nothing listening, or times out, is an outage and follows the saved outage mode.
  • Tool checks and the plugin's other gateway calls prove the very connection that carries the token. Model calls, health checks and telemetry prove the listener right before each request. A process that takes the port in the gap between that proof and the request, well under a millisecond on loopback, could still receive that one request.
  • Before it connects to a loopback OpenClaw gateway port, the DefenseClaw gateway checks who owns the listener. On Linux it must be the same account or root; on macOS, the same account. Otherwise it sends nothing, keeps retrying, and defenseclaw doctor names the step.

Tested OpenClaw versions

We test DefenseClaw with OpenClaw 2026.6.8, 2026.9.8 and 2026.10.9. We test against new OpenClaw releases as they come out.

Device pairing

DefenseClaw connects to the OpenClaw gateway as an operator device named gateway-client. OpenClaw approves a new device on a loopback connection by itself, so a normal single-user install needs no step. DefenseClaw never writes OpenClaw's pairing files.

OpenClaw asks you to approve the device when the connection is not loopback, when gateway.nodes.pairing.autoApproveLocal is false, or when a device asks for more scopes than OpenClaw approved. DefenseClaw then keeps retrying. defenseclaw doctor and defenseclaw-gateway status show the device ID and the step:

openclaw devices list
openclaw devices approve REQUEST_ID

Replace REQUEST_ID with the request ID the list shows. Run openclaw devices list right before you approve: OpenClaw gives a new request ID when the device retries with changed details.

OpenClaw operator scopes

DefenseClaw asks OpenClaw for these scopes:

ScopeWhat DefenseClaw uses it for
operator.readRead the config, tool catalog and skill status, and receive session events (sessions.subscribe).
operator.writeSend DefenseClaw security notices into a session (sessions.send).
operator.approvalsAnswer OpenClaw exec approvals (exec.approval.resolve).
operator.adminChange OpenClaw's config to disable a blocked skill, plugin or MCP server (config.patch, skills.update).

What this command sets vs. leaves at defaults

defenseclaw setup openclaw is the dedicated alias. It delegates to the shared guardrail setup and exposes the common options, not every setup guardrail flag (quick-alias reference, full guardrail setup). The flags above set the connector, mode, optional HITL and optional rule pack. Everything else uses the shipped defaults (Defaults).

KnobValue when omittedFlag to override
Scanner backendlocal (bundled regex packs, no key)--scanner-mode local|remote|both
Rule packunset, built-in baseline--rule-pack default|strict|permissive
LLM judgeoff (regex-only triage)--judge-model <model> plus --judge-api-key-env
Detection strategyregex_judge if the judge is on, else regex-only--detection-strategy regex_only|regex_judge|judge_first
HITLoff--human-approval plus --hilt-min-severity
HITL minimum severityHIGH when --human-approval is on--hilt-min-severity low|medium|high|critical
Gateway outageThe saved outage mode, see the gateway outage table: per-user default and permissive continue with a warning, strict and managed closed; status, the setup summary and guardrail fail-mode all show itdefenseclaw guardrail fail-mode open|closed --connector openclaw on default and permissive; strict and managed stay closed
Proxy port4000--port <int>
Block messageempty (built-in copy)--block-message "<text>"
Redactionv8 bucket and profile policy (none for fresh v8)Edit observability.destinations[].routes[].selector.buckets and observability.redaction_profiles (Redaction)

Common variations

# Pilot: nothing blocks. Run for at least a week before promoting.
defenseclaw setup openclaw --mode observe --rule-pack permissive --restart

# Action with human approval. HIGH can pause for approval, CRITICAL still blocks.
defenseclaw setup openclaw --mode action --human-approval --hilt-min-severity high --restart

# Strict: block MEDIUM and above, alert on LOW.
defenseclaw policy activate strict
defenseclaw setup openclaw --mode action --rule-pack strict --restart

Human approval needs OpenClaw 2026.3.28 or later. The OpenClaw that install.sh installs (2026.3.24) has no plugin approvals, so setup refuses --human-approval there and changes nothing. Upgrade OpenClaw first (npm install -g openclaw@2026.3.28 or later), or set up without human approval.

An earlier setup with --human-approval may have written an approvals.plugin block (enabled: true, mode: session) into openclaw.json. An OpenClaw before 2026.3.28 rejects it and its gateway does not start. A setup without human approval, and teardown, take that exact block back when OpenClaw lacks plugin approvals. Any other approvals.plugin shape stays as you wrote it.

For a second-pass LLM judge, export a key and add --detection-strategy regex_judge --judge-model <model> --judge-api-key-env DEFENSECLAW_LLM_KEY. Latency and cost depend on the model.

Bedrock through a VPC endpoint

When bedrock-runtime.<region>.amazonaws.com resolves to an AWS PrivateLink (VPC interface) endpoint, the proxy refuses the private address and every turn fails. The agent shows DefenseClaw refused a private LLM endpoint; if you trust it, run: defenseclaw guardrail allow-private-upstream <host>, and defenseclaw doctor warns with a Private upstream row. Allow the endpoint. The command restarts a running gateway.

defenseclaw guardrail allow-private-upstream bedrock-runtime.us-east-1.amazonaws.com

OpenClaw gateway on another port

defenseclaw setup openclaw reads the OpenClaw gateway port from openclaw.json (gateway.port). If you onboard OpenClaw on another port later, run defenseclaw setup openclaw again or defenseclaw setup gateway --port <port>.

OpenClaw gateway token

DefenseClaw also reads the gateway token from openclaw.json (gateway.auth.token):

  • A plain string is used as it is.
  • A secret reference with "source": "env" is read from that variable in the environment of the shell that runs init or setup. DefenseClaw refuses a variable that holds one of its own credentials:
    • a key in ~/.defenseclaw/.env, other than OPENCLAW_GATEWAY_TOKEN and DEFENSECLAW_GATEWAY_TOKEN;
    • a variable named by an api_key_env setting;
    • a credential that defenseclaw keys list names, such as SPLUNK_ACCESS_TOKEN;
    • an LLM provider key name, such as OPENAI_API_KEY or AWS_BEARER_TOKEN_BEDROCK;
    • a name that starts with DEFENSECLAW_, or contains API_KEY, SECRET, PASSWORD, ACCESS_KEY, PRIVATE_KEY or SESSION_TOKEN.
  • DefenseClaw cannot read other secret sources, such as "source": "store". For those, init and setup print a warning and finish.

DefenseClaw saves a token it reads to ~/.defenseclaw/.env (mode 0600). If it could not read the token, give it yourself:

defenseclaw keys set DEFENSECLAW_GATEWAY_TOKEN

You can also set OPENCLAW_GATEWAY_TOKEN or DEFENSECLAW_GATEWAY_TOKEN in the environment of the gateway.

DefenseClaw 1.0.5 and 1.0.6 could save the secret reference text itself in ~/.defenseclaw/.env when init failed. Later builds ignore that line. init and defenseclaw doctor --fix remove it and say so.

Files DefenseClaw will modify

WhatWhere
Plugin allow and load entries~/.openclaw/openclaw.json
Plugin~/.openclaw/extensions/defenseclaw/ (openclaw.plugin.json, package.json, dist/index.js)
Hook scripts~/.defenseclaw/hooks
Subprocess shimson PATH, for curl, wget, ssh, nc, pip and npm

DefenseClaw limits its OpenClaw-tree changes to extensions/defenseclaw/ and its managed entries in openclaw.json. DefenseClaw backs up openclaw.json first. Backups are byte for byte and hash-checked. Teardown restores the file, or removes only DefenseClaw's entries when the file drifted. OpenClaw saves openclaw.json itself while it runs (it keeps its own metadata there), and DefenseClaw counts that as a change: the uninstall then keeps OpenClaw's version, takes out only DefenseClaw's entries, and prints a notice that the file is not byte for byte the copy from before setup. A file nobody changed comes back exactly.

Transport coverage

The plugin patches globalThis.fetch, Node https.request, http.request and http.get, the global Undici dispatcher, and the Undici copy OpenClaw ships. A matching request is redirected through the guardrail proxy. Only recognized model traffic is redirected. Other requests pass through unchecked.

TransportRedirected through the proxy whenUnclassified request
globalThis.fetchThe destination is a known provider, or the method, path and readable body form a recognized LLM request shape.Passes through and emits egress passthrough telemetry.
https.requestThe destination is a known provider or its path has a recognized LLM suffix.Passes through and emits egress passthrough telemetry.
http.request and http.getIts non-safe destination has a recognized LLM path, including supported known or local-provider paths.Passes through without guaranteed passthrough telemetry.
Undici global dispatcherIts non-safe destination is a known provider or has a recognized LLM path.Passes through without guaranteed passthrough telemetry.
Undici copy that OpenClaw shipsSame rule as the global dispatcher. OpenClaw sends model requests through an SSRF-guarded fetch that gives Undici a dispatcher of its own, which skips every layer above.Passes through without guaranteed passthrough telemetry.

Raw sockets, custom transports and libraries that bypass every patched entry point are outside the boundary. An egress event proves the plugin observed a transport branch, not that the request was proxied and inspected.

The plugin patches the main thread of the OpenClaw process. A model call made from a Node worker thread is not redirected and not inspected. The OpenClaw interception row of defenseclaw doctor fails when the latest model call took no proxy hop, so it reports such a call.

OpenClaw >=2026.6.8 is the range that first required the Undici dispatcher layers. defenseclaw doctor fails the OpenClaw interception row when the plugin's sentinel self-test, which never leaves the host, cannot prove a rewrite onto the guardrail proxy, even if /health returns 200. The gateway pairs each model call OpenClaw completes with a proxy hop of its own. Doctor fails the row when the latest call took no hop, and warns when an earlier one did not but the calls after it did. Counts restart when defenseclaw-gateway restarts. If turns succeed while doctor says traffic is not intercepted, restart OpenClaw so the plugin reloads, then rerun doctor. Confirm a real INCOMING REQUEST delta in gateway.log only when that log can grow.

What the plugin does

runs
redirects LLM calls
asks before tools
forwards if allowed
OpenClaw
DefenseClaw pluginloads inside OpenClaw
Guardrail proxy :4000checks request and response
Inspect API :18970checks the tool call
Model provider

List view for small screens. Use the expand button to open the drawing.

  1. OpenClaw
    • runsDefenseClaw plugin
  2. DefenseClaw pluginloads inside OpenClaw
    • redirects LLM callsGuardrail proxy :4000
    • asks before toolsInspect API :18970
  3. Inspect API :18970checks the tool call
  4. Guardrail proxy :4000checks request and response
    • forwards if allowedModel provider
  5. Model provider
The plugin's two checkpoints. Both listeners belong to defenseclaw-gateway. The ports shown are the defaults.

The plugin hooks OpenClaw's fetch interceptor and the before_tool_call lifecycle. See Components.

Hook capabilities

Block events

  • before_tool_call
  • fetch_request
  • fetch_response

Native ask events

  • before_tool_call

Proxy connector: not gated by a hook contract version.

What it can block or ask

  • The proxy can block a checked request, a checked response and a tool call.
  • OpenClaw is the connector with plugin-mediated approval. In action mode a confirm verdict on before_tool_call becomes OpenClaw's own approval request, which denies on timeout. Answer it in the OpenClaw Control UI (openclaw dashboard), with /approve on a chat channel that forwards approvals, or in openclaw tui from OpenClaw 2026.10.9, where Allow once works too. Where OpenClaw shows no request, the call is denied when it times out, and the OpenClaw gateway log says where to answer.
  • Only recognized model traffic is redirected. Other requests pass through unchecked.

Verdict mapping

The gateway answers allow, alert, confirm or block. In action mode a block stops the tool and a confirm becomes OpenClaw's requireApproval. Allow and alert let the tool run. For model calls, the guardrail proxy checks the request before it forwards it and the response before it returns it.

Fail mode

OpenClaw model requests use the proxy while the gateway is running. On a classified proxy outage (nothing listens on the gateway port, or the connection times out), the per-user default and permissive policies continue the original request to its configured provider with an agent warning; strict and managed policies block. The plugin's tool-inspection call follows the same saved mode: a default or permissive outage lets an ordinary tool run with a warning in its result, while strict and managed block. Direct protected targets remain blocked. A listener that answers without proving it is the account's gateway is not an outage: the plugin sends it nothing and blocks model requests and tool checks in every policy. DEFENSECLAW_TOOL_INSPECT_FAIL_OPEN is ignored by the 1.0.9 plugin. See Fail modes.

When the gateway cannot write the audit record of a tool check or a prompt, for example on a full disk, the strict policy blocks the call. The default and permissive policies allow it and say that DefenseClaw audit is degraded. Tool results and model responses keep their verdict.

On OpenClaw 2026.4.24 and later, Setup grants the DefenseClaw prompt hook access so the model outage warning reaches the agent, unless the operator already set plugins.entries.defenseclaw.hooks.allowConversationAccess. If an operator disables prompt injection hooks, the warning still appears in the OpenClaw log.

Subprocess policy

The policy is shims on every platform. Setup installs PATH shims for curl, wget, ssh, nc, pip and npm that send each invocation to the gateway's tool-inspection endpoint before running the real binary. They inspect those command paths only and give no syscall, filesystem or network isolation. While the gateway is not running, the shims follow the policy: the default and permissive policies print DefenseClaw warning: gateway peer is unverified or unavailable; running <tool> without inspection, write a hook-failures.jsonl record and run the real tool; the strict policy refuses it (DefenseClaw: gateway peer is unverified or unavailable — refusing to exec <tool>, exit 1).

OpenClaw does not run in an OpenShell sandbox. The legacy standalone sandbox that ran it as a separate Linux user was removed. A host that still carries it removes what it left by hand (remove a retired standalone sandbox). OpenShell support for OpenClaw is pending in the capability matrix.

Limits

  • Native Windows is unsupported: the connector needs the guardrail proxy, which DefenseClaw does not host on Windows.
  • Raw sockets, custom transports and libraries that bypass every patched entry point are outside the boundary. They are not inspected.
  • The shims inspect those six commands only. They give no syscall, filesystem or network isolation.
  • If a Bedrock endpoint resolves to a private VPC address, the proxy refuses it. Allow it with defenseclaw guardrail allow-private-upstream <host>.
  • OpenClaw 2026.5.12 and later load Amazon Bedrock from the external plugin @openclaw/amazon-bedrock-provider. Without it every model call fails with No API provider registered for api: bedrock-converse-stream, and setup warns. Run openclaw plugins install @openclaw/amazon-bedrock-provider, then openclaw gateway restart.
  • The install watcher disables an OpenClaw skill it blocks without naming a connector. defenseclaw skill enable <name> --connector openclaw re-enables the skill in OpenClaw and clears that record, so skill info and skill list stop saying disabled. Another connector-wide disable stays, and the command names it.
  • If you move OpenClaw's gateway port, run defenseclaw setup openclaw again.
  • Model calls made from Node worker threads are not intercepted (see Transport coverage).
  • The DefenseClaw gateway and OpenClaw must run as the same OS user, one account per pair.
  • OpenClaw does not run in an OpenShell sandbox. OpenShell support is pending in the capability matrix.

Troubleshooting

If a prompt reports Unknown model for a still-installed provider after OpenClaw removes or disables another extension, wait for the plugin reload to finish and retry. If the error remains, run openclaw models list --refresh --provider amazon-bedrock (substitute your provider name) and retry.

If defenseclaw setup openclaw fails after the OpenClaw gateway stopped, DefenseClaw does not rewrite openclaw.json. The failure says the file changed during setup and may still contain DefenseClaw entries. Run defenseclaw-gateway connector teardown --connector openclaw to remove them. The command works on ~/.openclaw/openclaw.json whether or not OpenClaw is still a configured connector, keeps everything else in the file, and leaves a copy at another path as it is. Empty plugins.allow or plugins.load.paths arrays can remain afterwards; they are harmless.

Disable

For a per-user, single-connector install:

defenseclaw guardrail disable --yes

This restores openclaw.json, removes the plugin entries and stops the proxy. To drop the connector from the configuration, run defenseclaw setup remove openclaw --yes. If OpenClaw is the last connector, removal refuses because the gateway would enforce nothing. To deliberately remove that last connector, run:

defenseclaw setup remove openclaw --yes --force

Turn it back on by running the Set up command again, for example defenseclaw setup openclaw --restart. Leaving out --mode keeps the mode you saved before disabling the guardrail. defenseclaw guardrail enable turns OpenClaw back on only when guardrail.model is set (defenseclaw setup guardrail); otherwise it stops with Cannot enable: guardrail.model is not set.

OpenClaw is proxy-backed and cannot run next to hook connectors. While any hook connector is configured, defenseclaw setup openclaw refuses and changes nothing; defenseclaw setup openclaw --replace removes the hook connectors and sets up OpenClaw in their place.