Setup guardrail: every flag and recipe
Every prompt, flag and non-interactive recipe of defenseclaw setup guardrail - connector, mode, scanner, judge, human approval, rule pack and the judge provider options.
This is the reference for defenseclaw setup guardrail. For the short path, see Set up the guardrail.
Prompt-flag mapping
Each row is one wizard prompt, with the default that Enter selects and the flag to use in scripts.
| Prompt (default) | Flag, or how to script it |
|---|---|
| Which agent framework are you using? (first setup only; suggests an agent it finds) | --connector / --agent: claudecode, codex, cursor, devin, copilot, hermes, antigravity, opencode, amp, kiro, openclaw; on Linux and macOS also zeptoclaw. Native Windows runs OpenClaw 2026.8.35 or later in native hook mode, and refuses zeptoclaw (it needs the guardrail proxy, which Windows does not run) with the reason. |
| Enable guardrail? (Y) | Implied by running setup. --disable turns the guardrail off. |
| Select mode (observe on first setup, then the current mode) | --mode observe|action. observe records; action enforces. |
| Select hook fail mode (asked only when this run turns the guardrail on or switches between observe and action; Enter keeps the saved choice, or none so the policy tier decides) | No flag on setup guardrail. Use defenseclaw setup <connector> --fail-mode open|closed, defenseclaw init --fail-mode, or defenseclaw guardrail fail-mode open|closed afterwards. |
| Human approval for risky actions? (action mode only; current setting) | --human-approval / --no-human-approval. |
| Approval minimum severity (if HITL is on; HIGH) | --hilt-min-severity high|medium|low|critical, matched case-insensitively. |
| Select engine (local) | --scanner-mode local|remote|both. The wizard offers only local and remote; pass both to run the two together. |
| API endpoint / API key env var name / Timeout (remote scanner only) | --cisco-endpoint, --cisco-api-key-env, --cisco-timeout-ms. Defaults come from the existing cisco_ai_defense config. |
| Select action connector(s) for LLM judge. (a checkbox of the action-mode connectors, unchecked unless the judge already covers them), or Add LLM judge on top of rule scanning? (when there is no action-mode hook connector; current setting) | --judge-model turns the judge on. --detection-strategy regex_only turns it off; there is no --no-judge flag on this command. |
| Use this LLM for the judge? (Y, when an LLM is already configured) | --judge-provider, --judge-model, --judge-api-key-env; --inherit-llm or --inherit-from guardrail|scanners.skill|scanners.mcp|scanners.plugin copies another LLM block. To start from the saved judge settings, use defenseclaw setup llm --role judge --inherit-from guardrail.judge. |
| How should DefenseClaw use the LLM? (proxy connectors only) | --llm-role judge_only|judge_and_agent. Hook connectors always get judge_only; see Hook-based vs proxy-based connectors. |
| Configure fallback models? (N) | No flag. Set guardrail.judge.fallbacks (a list of model ids) in ~/.defenseclaw/config.yaml. |
| Configure advanced options? (N) | Opens the next two prompts. |
| Guardrail proxy port (4000) | --port. Used by the proxy connectors; hook connectors bind no proxy. |
| Use a custom block message? (action mode only) | --block-message. |
For the remote Cisco AI Defense scanner, an unset or empty
cisco_ai_defense.enabled_rules sends no config.enabled_rules list; the AI
Defense connection's own policy applies. A nonempty operator list is sent in
the order configured.
On a multi-connector install, --connector <name> scopes this setup run to that
connector. When --block-message is passed without --connector, setup treats
it as broad operator intent: it updates the shared block message and reconciles
the active connector overrides, so no connector keeps stale block text.
Two wizard choices have no setup guardrail flag. The hook fail mode question appears only when the run turns the guardrail on or changes the mode; defenseclaw init already turns the guardrail on, so a later run that keeps the mode does not ask it. Set the fail mode with defenseclaw setup <connector> --fail-mode or defenseclaw guardrail fail-mode. Judge fallback models live in guardrail.judge.fallbacks in config.yaml.
Redaction has its own workflow
Telemetry redaction is configured per destination with defenseclaw setup redaction, not by this command. See Redaction.
Connector resolution
When you omit --connector, DefenseClaw resolves it in this order:
- The
--connectorflag. - The
guardrail.connectoran earlier setup run saved. - The
<data_dir>/picked_connectorhint, written byinstall.sh --connector ...and by connector setup, when that agent is installed on this machine. - Otherwise pass
--connector. The interactive wizard suggests an agent it finds on this machine; the non-interactive path does no detection.
Recipes
defenseclaw setup guardrail --non-interactive --connector claudecode --mode observe --scanner-mode local --restartFindings go to the audit database. Nothing blocks.
defenseclaw setup guardrail --non-interactive --connector claudecode --mode action --scanner-mode local --rule-pack default --restartWith the default pack, CRITICAL blocks, HIGH and MEDIUM alert, LOW is allowed.
defenseclaw setup guardrail --non-interactive --connector claudecode --mode action --rule-pack default \
--human-approval --hilt-min-severity high --restartHIGH findings are eligible for confirmation. CRITICAL still blocks. See which agents can ask.
defenseclaw keys set DEFENSECLAW_LLM_KEY # a Bedrock API key
defenseclaw setup guardrail --non-interactive --connector claudecode --mode action \
--detection-strategy regex_judge \
--judge-provider openai-compatible \
--judge-model google.gemma-4-31b \
--judge-api-base https://bedrock-mantle.us-east-1.api.aws/openai/v1 \
--judge-api-key-env DEFENSECLAW_LLM_KEY --restartThis is the recommended judge, Gemma 4 31B on Amazon Bedrock. Any other model works the same way: pass its --judge-provider and --judge-model. Regex runs first and the judge adjudicates what regex flags. --detection-strategy judge_first flips the order. To cut judge calls on tool calls, put a decision model in front of the judge. Hook connectors are judged only in action mode; --judge-hook-connectors chooses which. A judge verdict goes through block_at and alert_at like a rule finding.
defenseclaw setup guardrail --non-interactive --connector codex --mode action --scanner-mode local --restart
defenseclaw setup decision-model --base-url http://127.0.0.1:8791/v1/systemone --model my-model --connectors codex --pingTool calls go through one of three cascades per connector: rules only (the default); rules, then the decision model with no judge (the connectors in --connectors); or rules, the decision model, then the LLM judge (the connectors the judge covers). Without a judge, a confident allow allows, a confident block blocks, and anything else asks the user where the agent can ask and is a HIGH alert where it cannot. A decision model that is down leaves the rule verdict, as a judge outage does.
defenseclaw setup guardrail --non-interactive --connector claudecode --mode action \
--detection-strategy regex_judge \
--judge-provider bedrock \
--judge-model us.anthropic.claude-sonnet-4-6 \
--judge-bedrock-region us-east-1 \
--judge-bedrock-auth-mode iam_credentials \
--judge-bedrock-access-key-env AWS_ACCESS_KEY_ID \
--judge-bedrock-secret-key-env AWS_SECRET_ACCESS_KEY \
--judge-bedrock-inference-profile us. --restartGive defenseclaw setup llm --provider bedrock the full Bedrock model id, for example us.anthropic.claude-haiku-4-5-20251001-v1:0. The short names haiku-4.5 and luna become their full ids, and setup refuses any other name that is not a Bedrock model id. Without --bedrock-region, setup saves AWS_REGION, then AWS_DEFAULT_REGION, then us-east-1, and prints which one it used.
When you write a Bedrock model into a config file yourself, for example llm.model or guardrail.judge.llm.model in the managed admin config, write it with or without the bedrock/ prefix: bedrock/us.anthropic.claude-haiku-4-5-20251001-v1:0 and us.anthropic.claude-haiku-4-5-20251001-v1:0 both use Bedrock. In 1.0.5 an id without the prefix made the administrator's scan skill report Authentication failed and scan mcp report an analyzer DNS error.
The hook judge works with GPT-5.6 Luna on Bedrock (us.openai.gpt-5.6-luna) as well as with the Anthropic models: it calls Luna through the Bedrock Converse API, as the skill and MCP scans do, and leaves out the sampling temperature the model refuses. In 1.0.5 every hook-time judge call with Luna failed (Bedrock 502) and verify warned judge_failing; hooks kept the rule verdict.
Use --judge-provider vertex_ai with the --judge-vertex-* flags, or --judge-provider azure with the --judge-azure-* flags. For a self-signed endpoint add --judge-tls-ca-cert-file. If the settings are already on a custom provider entry, --judge-instance-name <name> inherits them; role-level flags win field by field. See LLM providers.
Every flag
The table follows defenseclaw setup guardrail --help.
Prop
Type
Setup commands
DefenseClaw setup and configuration surfaces in one place — from the central guardrail wizard to keys, webhooks, registries, observability, OpenShell sandboxes, and per-connector hooks, plus the options, exit codes and startup behavior of install.sh and install.ps1.
Sandbox CLI
Every defenseclaw sandbox command and flag for NVIDIA OpenShell sandboxes, with an example for each. Covers setup and doctor, run and connect, the activity feed and asks, undo, review and pull, policy and packs, images, wrappers, and teardown.