Multi-connector
One DefenseClaw gateway enforces guardrail policy for several hook connectors at once, each with its own mode, fail mode, HITL, block message and rule pack under guardrail.connectors. Add a connector with setup <connector> and choose Add.
One gateway guards several agents at once, each with its own mode. Adding, replacing or removing an agent never deletes audit history: each audit row keeps the connector that produced it.
Before you start
- DefenseClaw is set up for one agent.
- The new agent is a hook agent. OpenClaw and ZeptoClaw run through a proxy and cannot sit next to hook agents. To switch between a hook agent and a proxy agent, use
--replace(see Changing connectors).
How one gateway enforces N connectors
One gateway enforces several hook connectors. Each connector has an optional block under guardrail.connectors.<name> in ~/.defenseclaw/config.yaml. An unset field inherits the global guardrail.* value, so a block carries only what differs. Proxy connectors (OpenClaw, ZeptoClaw) cannot be multi-connector peers: they own a proxy listener, so only one runs at a time.
guardrail:
enabled: true
mode: action
hook_fail_mode: closed
rule_pack: default
connectors:
codex:
mode: action
hook_fail_mode: open
claudecode:
mode: observe
hilt:
enabled: true
min_severity: HIGHclaw.mode keeps one primary connector
claw.mode and guardrail.connector name the active connector on a single-connector install. With several connectors they keep naming one primary connector: the existing one when you add a connector, otherwise the first name in sorted order. Read the full roster from guardrail.connectors, defenseclaw status or defenseclaw guardrail status. While more than one connector is active, the gateway leaves out the process-level defenseclaw.claw.mode resource attribute; use the per-event connector metric label or the defenseclaw.connector.source span attribute.
Adding a connector (Add vs Replace)
Run the hook setup for the agent you want to add. Setup first asks the new agent's enforcement mode, prints what it will change, and then, if another agent is already guarded, asks how to combine them. The questions, in order, are listed in Changing connectors.
-
Run the agent's setup command.
defenseclaw setup codexEnforcement mode for Codex [1] observe — scan and report findings, never block (recommended to start) [2] action — scan and block/confirm when policy requires (PreToolUse deny) Select mode (1, 2) [1]: … DefenseClaw is already configured for: claudecode You are setting up: codex [a] Add — run it alongside the existing connector(s) (multi-connector) [r] Replace — switch to only this connector [c] Cancel — make no changes Choose (a, r, c) [a]: a … OK Desired roster staged for 'codex' - 2 connectors selected: claudecode, codex OK codex mode=observeAdd is the default, also with
--yes. The new agent starts in observe mode. Add--mode actionto block from the start. The picker's "never block" covers policy findings. Observe still blocks an agent that changes DefenseClaw's own files, such as a copy into~/.defenseclaw(ruletamper.detector_state_write, with every rule pack). -
Check both agents.
defenseclaw guardrail status* enabled: yes Connector Key State Mode Fail Rule pack Block/alert HILT Scan Judge ----------- ---------- ------- ------- ------ --------- ---------------- ---- ---------- ----- Claude Code claudecode enabled observe open default CRITICAL/MEDIUM+ off regex_only off Codex codex enabled observe open default CRITICAL/MEDIUM+ off regex_only offFailisopenunder the default policy: while the gateway is not running a call runs with one warning. The strict policy, or a savedclosed, showsclosed. -
Give one agent its own settings. Add
--connectorto any guardrail command.defenseclaw guardrail mode action --connector codex defenseclaw guardrail hilt on --min-severity HIGH --connector claudecodeThe per-connector overrides table lists what each agent can override.
Per-connector overrides
The fields you can override per connector mirror the global guardrail knobs:
| Field | Meaning | Inherits when unset |
|---|---|---|
enabled | Per-connector on/off switch (guardrail disable --connector X). Drops it from the active set and removes its hooks; re-enable restores it with no re-prompt. | enabled |
mode | observe (log only) or action (enforce). | global guardrail.mode |
hook_fail_mode | open / closed — what to do while the gateway is not running. Error, malformed or missing gateway answers block in either mode. | global guardrail.hook_fail_mode |
hilt | { enabled, min_severity } — per-connector human-in-the-loop policy. | global guardrail.hilt |
block_message | Custom block text shown to this connector's agent. | global guardrail.block_message |
rule_pack | The rule pack this connector scans against: a preset or a guardrail.custom_packs name. | global guardrail.rule_pack |
rules | Rule customisation layered over this connector's pack: protections, enable, disable, severity_overrides, suppressions, sensitive_tools. See Rules and custom packs. | the global guardrail.rules only |
block_at | Lowest severity that blocks: CRITICAL, HIGH, MEDIUM or LOW. | global guardrail.block_at, then the rule pack's level |
alert_at | Lowest severity that alerts, same values; never above the block level. | global guardrail.alert_at, then the rule pack's level |
Set any override with --connector:
defenseclaw guardrail fail-mode closed --connector codex
defenseclaw guardrail hilt on --min-severity HIGH --connector claudecode
defenseclaw guardrail block-message "Codex policy blocked this" --connector codex
defenseclaw guardrail block-at CRITICAL --connector codex
defenseclaw guardrail use-pack strict --connector codex
defenseclaw guardrail rule disable CMD-REVSHELL-NC --connector codex
defenseclaw guardrail disable --connector codex
defenseclaw guardrail enable --connector codexguardrail hilt, fail-mode, block-message, enable and disable print what they will change and ask Proceed? [Y/n]; Enter applies it, and --yes skips the question in scripts. mode, block-at and use-pack apply at once.
On a multi-connector install, --connector X writes only that connector's override. fail-mode --connector X then refreshes and verifies that connector's hook registration (every hook connector, Kiro included); for the proxy-backed OpenClaw and ZeptoClaw, which have no hooks, it saves and installs the mode of their PATH shims (curl, wget, ssh, nc, pip, npm). The capability matrix says what each connector does while the gateway is down. Unscoped writes are the broad path: fail-mode, hilt and block-message also reconcile active connector posture so an old override does not keep the old value. On a single-connector install, --connector may name the active connector; enable, disable, fail-mode, hilt and block-message then use their global setting. A name that is not installed is refused.
CLI contract: read vs write
| Commands | Scope | How to narrow |
|---|---|---|
defenseclaw status, defenseclaw doctor, bare defenseclaw guardrail status, bare guardrail fail-mode / hilt / block-message, skill list, mcp list, plugin list, tool list, tool status, codeguard status | Read — fans out to every active connector. Identical layout whether one or N are wired. | guardrail status --connector X, skill list --connector X, mcp list --connector X, plugin list --connector X, tool list --connector X, and tool status --connector X narrow where supported. |
alerts | Read — recent decisions across connectors by default. | alerts --connector X filters to events attributed to one connector. |
guardrail enable / disable / fail-mode / hilt / block-message (with an argument) | Guardrail write — scoped or broad. --connector X writes one connector override. Omit --connector for the broad path: enable/disable is global; fail-mode, HITL, and block-message update active connector posture. | --connector X to target a specific connector. |
skill, mcp, plugin, and tool policy verbs (block, allow, unblock, plus runtime verbs such as disable / enable where supported) | Asset-policy write — broad fallback by default, connector-scoped when requested. Bare writes apply across matching configured connector copies or the unscoped fallback tier for that asset family. | --connector X writes or clears only that connector's scoped state. |
mcp set / mcp unset, skill install, plugin remove, codeguard install / install-skill | Config/install write — all configured/active connectors by default. | --connector X writes or removes only one connector's source. |
skill scan / mcp scan / plugin scan / aibom scan | Scan — configured/active connectors by default. | Positional target and --connector X narrow where supported. |
The firewall stays global
Per-connector policy is a guardrail concept. The egress firewall is not per-connector: DefenseClaw compiles one firewall.yaml into the host-wide pf/iptables filter and merges each active connector's allowed hosts into one allowlist at boot. Those rules see network attributes, not the connector label, so they cannot attribute a connection to one of several agents.
Check it worked
defenseclaw guardrail status lists only the agents you kept, and defenseclaw doctor reports no leftover hooks.
See also
- Changing connectors — add, reconfigure, remove, or replace connector wiring
- Set up the guardrail — the central setup command
- Generate a setup command
- Turn on blocking
- Setup aliases
- User- and group-based policies — per-user, per-group and per-agent profiles that layer on top of
guardrail.connectors
Quick setup aliases
Connector-oriented setup aliases for supported DefenseClaw integrations.
User- and group-based policies
Give a directory group, a user, a connector or a single agent its own guardrail policy with guardrail profiles. Write the assignments, see which profile a person gets, read the audit record, and ship the same config to managed hosts.