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.
Platform support
| Platform | Status | Notes |
|---|---|---|
| macOS and Linux | Supported | DefenseClaw hosts the required guardrail proxy and installs the first-party plugin. Subprocess policy is shell shims on both. |
| Native Windows x64 | Unsupported | DefenseClaw 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 --restartThe 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 statusThe agent appears under Agents with its mode. defenseclaw doctor reports no failed check for it.
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.localhostmeans127.0.0.1. With any other host the plugin sends nothing, anddefenseclaw doctorfails 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 doctornames 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_IDReplace 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:
| Scope | What DefenseClaw uses it for |
|---|---|
operator.read | Read the config, tool catalog and skill status, and receive session events (sessions.subscribe). |
operator.write | Send DefenseClaw security notices into a session (sessions.send). |
operator.approvals | Answer OpenClaw exec approvals (exec.approval.resolve). |
operator.admin | Change 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).
| Knob | Value when omitted | Flag to override |
|---|---|---|
| Scanner backend | local (bundled regex packs, no key) | --scanner-mode local|remote|both |
| Rule pack | unset, built-in baseline | --rule-pack default|strict|permissive |
| LLM judge | off (regex-only triage) | --judge-model <model> plus --judge-api-key-env |
| Detection strategy | regex_judge if the judge is on, else regex-only | --detection-strategy regex_only|regex_judge|judge_first |
| HITL | off | --human-approval plus --hilt-min-severity |
| HITL minimum severity | HIGH when --human-approval is on | --hilt-min-severity low|medium|high|critical |
| Gateway outage | The 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 it | defenseclaw guardrail fail-mode open|closed --connector openclaw on default and permissive; strict and managed stay closed |
| Proxy port | 4000 | --port <int> |
| Block message | empty (built-in copy) | --block-message "<text>" |
| Redaction | v8 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 --restartHuman 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.comOpenClaw 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 runsinitorsetup. DefenseClaw refuses a variable that holds one of its own credentials:- a key in
~/.defenseclaw/.env, other thanOPENCLAW_GATEWAY_TOKENandDEFENSECLAW_GATEWAY_TOKEN; - a variable named by an
api_key_envsetting; - a credential that
defenseclaw keys listnames, such asSPLUNK_ACCESS_TOKEN; - an LLM provider key name, such as
OPENAI_API_KEYorAWS_BEARER_TOKEN_BEDROCK; - a name that starts with
DEFENSECLAW_, or containsAPI_KEY,SECRET,PASSWORD,ACCESS_KEY,PRIVATE_KEYorSESSION_TOKEN.
- a key in
- DefenseClaw cannot read other secret sources, such as
"source": "store". For those,initandsetupprint 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_TOKENYou 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
| What | Where |
|---|---|
| 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 shims | on 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.
| Transport | Redirected through the proxy when | Unclassified request |
|---|---|---|
globalThis.fetch | The 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.request | The destination is a known provider or its path has a recognized LLM suffix. | Passes through and emits egress passthrough telemetry. |
http.request and http.get | Its non-safe destination has a recognized LLM path, including supported known or local-provider paths. | Passes through without guaranteed passthrough telemetry. |
| Undici global dispatcher | Its non-safe destination is a known provider or has a recognized LLM path. | Passes through without guaranteed passthrough telemetry. |
| Undici copy that OpenClaw ships | Same 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
List view for small screens. Use the expand button to open the drawing.
- OpenClaw
- runsDefenseClaw plugin
- DefenseClaw pluginloads inside OpenClaw
- redirects LLM callsGuardrail proxy :4000
- asks before toolsInspect API :18970
- Inspect API :18970checks the tool call
- Guardrail proxy :4000checks request and response
- forwards if allowedModel provider
- Model provider
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_callbecomes OpenClaw's own approval request, which denies on timeout. Answer it in the OpenClaw Control UI (openclaw dashboard), with/approveon a chat channel that forwards approvals, or inopenclaw tuifrom 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 withNo API provider registered for api: bedrock-converse-stream, and setup warns. Runopenclaw plugins install @openclaw/amazon-bedrock-provider, thenopenclaw gateway restart. - The install watcher disables an OpenClaw skill it blocks without naming a connector.
defenseclaw skill enable <name> --connector openclawre-enables the skill in OpenClaw and clears that record, soskill infoandskill liststop saying disabled. Another connector-wide disable stays, and the command names it. - If you move OpenClaw's gateway port, run
defenseclaw setup openclawagain. - 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 --yesThis 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 --forceTurn 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.
Codex
Codex connector wires the documented lifecycle hook set. Hook contracts vary by Codex version, and Codex has no native ask.
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.