OpenClaw
The reference proxy connector. DefenseClaw ships a TypeScript plugin that wires OpenClaw's fetch interceptor and before_tool_call hook directly into the gateway.
OpenClaw is the connector DefenseClaw was designed against. It ships a
first-party TypeScript plugin (extensions/defenseclaw/) that routes
recognized LLM provider requests and their responses through the guardrail
proxy and sends OpenClaw's before_tool_call lifecycle events to the
DefenseClaw gateway. Coverage depends on which Node transport emitted the
request; unclassified traffic is not claimed as inspected or uniformly
observable.
Platform support
| Platform | Status | Notes |
|---|---|---|
| macOS and Linux | Supported | DefenseClaw hosts the required guardrail proxy and installs the first-party OpenClaw plugin. Linux can use the real OpenShell sandbox; macOS resolves that preference to shell shims. |
| Native Windows x64 | Unsupported | DefenseClaw is hook-only on Windows, while the OpenClaw connector requires the guardrail proxy. |
Setup
defenseclaw setup openclaw --mode observe --restart
defenseclaw setup openclaw --mode action --human-approval --rule-pack default --restartNative Windows setup is unsupported
DefenseClaw does not host the guardrail proxy on Windows, so it cannot install or enforce the OpenClaw connector there. There is no supported WSL, Docker, VM, or mixed native/POSIX workaround; run the connector on macOS or Linux.
setup openclaw is the dedicated OpenClaw alias. It delegates to the shared
guardrail setup backend and exposes the proxy connector's common setup
options; it is not a byte-for-byte copy of every setup guardrail flag. See
the quick-alias reference for the alias and
full guardrail setup for the complete wizard. The
proxy is always in the data path: --mode observe records without policy
blocking, while --mode action enforces.
What this command sets vs. leaves at defaults
The flags above explicitly set: connector, mode, optional HITL, and optional rule pack. Every other knob falls back to the values DefenseClaw ships with — schema-defined in internal/config/config.go and documented on the Defaults page.
| Knob | Value when omitted | Flag to override |
|---|---|---|
| Scanner backend | local (bundled regex packs, zero key) | --scanner-mode local|remote|both |
| Rule pack | unset → built-in baseline (no overlay) | --rule-pack default|strict|permissive |
| LLM judge | off (regex-only triage) | --judge-model <model> plus --judge-api-key-env |
| Detection strategy | regex_judge if judge is on, else regex-only | --detection-strategy regex_only|regex_judge|judge_first |
| HITL | off (no operator approval prompts) | --human-approval plus --hilt-min-severity ... |
| HITL minimum severity | HIGH (when --human-approval is on; stored uppercase in config) | --hilt-min-severity low|medium|high|critical (case-insensitive) |
| Hook fail-mode | current config; closed on a fresh install (open is retained for migrated legacy configs) | defenseclaw guardrail fail-mode <open|closed> (no flag) |
| Proxy port | 4000 | --port <int> |
| Block message | empty (uses built-in copy) | --block-message "<text>" |
| Redaction | v8 bucket/profile policy (none for fresh v8) | Edit observability.destinations[].routes[].selector.buckets and observability.redaction_profiles; then follow Redaction → Verify policy. |
| Verify after setup | on | --no-verify |
See the full flag reference for the complete table or run defenseclaw setup guardrail --help.
Common variations — pick the recipe that fits your phase
defenseclaw setup openclaw \
--mode observe \
--rule-pack permissive \
--restartThe proxy is in the data path but nothing blocks. Every collected prompt, response, and tool call lands in mandatory SQLite event history; optional v8 destinations receive their selected, redacted projections. Run this for at least a week before promoting — see Defaults → tuning by risk tolerance.
defenseclaw setup openclaw \
--mode action \
--human-approval \
--hilt-min-severity high \
--restartHIGH findings can pause for operator approval; CRITICAL still blocks unconditionally. OpenClaw's bundled DefenseClaw plugin provides a native chat-origin approval surface, so approvals reach the agent UI directly. See the HITL page for the per-connector matrix.
export DEFENSECLAW_LLM_KEY='replace-with-your-key'
defenseclaw setup openclaw \
--mode action \
--human-approval \
--hilt-min-severity high \
--detection-strategy regex_judge \
--judge-model anthropic/claude-sonnet-4-20250514 \
--judge-api-key-env DEFENSECLAW_LLM_KEY \
--restartAdds the configured LLM judge as a second pass on regex-flagged prompts. Latency and provider cost depend on the selected judge model.
defenseclaw policy activate strict
defenseclaw setup openclaw \
--mode action \
--rule-pack strict \
--restartBlock MEDIUM and above, alert on LOW, and do not offer approval for findings that have already crossed the block threshold. Pair it with the OpenShell sandbox profile and a reviewed first-party allow-list for additional containment.
Decision aids — should I turn this on?
Human-in-the-loop (HITL)
When --human-approval is worth it. OpenClaw approvals reach chat-origin sessions via the bundled plugin, not just the TUI.
Mode + judge recipes
Side-by-side bash for observe / action / action+HITL / action+judge — copy-paste ready.
Defaults & rule packs
What permissive / default / strict actually ship, and which one matches your risk tolerance.
Interactive wizard
Animated terminal demo of the prompt-by-prompt setup flow — the safest path the first time.
Not sure what to pick? Run defenseclaw setup guardrail (no flags) — the interactive wizard walks you through every choice with safe defaults pre-selected and inline help. The Prompt → flag mapping table gives you the CI-shaped command for the same configuration.
Files DefenseClaw will modify
A hash-checked backup of openclaw.json is stored before edits; teardown restores or surgically removes only DefenseClaw-owned entries.
Transport coverage
The plugin patches globalThis.fetch, Node https.request, http.request and
http.get, and the global Undici dispatcher. A matching request is redirected
through the guardrail proxy, where DefenseClaw can inspect its request and
response. The match and passthrough boundaries are transport-specific:
| Transport | Redirected through the proxy when | Unclassified request behavior |
|---|---|---|
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 / 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. |
Raw sockets, custom transports, and libraries that bypass all patched entry points are outside this inspection boundary. An egress event proves that the plugin observed a transport branch; it does not mean the request or response was proxied and inspected.
OpenClaw ≥2026.6.8 is the release range that first required the undici
dispatcher layer. defenseclaw doctor now fails the OpenClaw
interception row when the plugin self-test cannot prove a rewrite onto
:4000, even if /health/liveliness returns 200.
What the plugin does
prompt
recognized LLM request
proxy request + X-DC-Target-URL
inspected upstream response
response (or policy block)
before_tool_call(name, args)
POST /api/v1/inspect/tool
verdict
allow / block / pause
response
Hook capabilities
The proxy can block inspected fetch requests, fetch responses, and tool calls.
The bundled plugin provides native approval for before_tool_call, including
chat-origin sessions.
Subprocess policy
The preferred policy is sandbox. On Linux, DefenseClaw installs the real
OpenShell sandbox policy using Landlock and seccomp, with shell shims as a
supplement. On macOS, sandbox resolves to shell shims only; those shims
inspect supported command paths but do not provide Linux syscall or filesystem
isolation. See Sandbox setup for the Linux workflow.
Disable
defenseclaw guardrail disable --yesRestores ~/.openclaw/openclaw.json from the backup, removes the plugin entries, and stops the proxy.