OpenClaw Guardian Approval Broker

Guardian is an external approval broker for OpenClaw exec approvals.

It watches pending OpenClaw command approvals, classifies the command with deterministic policy rules, optionally asks a dedicated guardian reviewer agent for ambiguous cases, posts an audit event to Discord, and — only in enforce mode — resolves safe approvals back to OpenClaw.

OpenClaw exec approval
  → Guardian static policy classifier
  → optional Guardian reviewer agent
  → JSONL / Discord audit
  → dry-run only OR enforce allow-once/deny

Guardian never emits allow-always.

Quick start

1. Install

From npm, once published:

npm install -g @nestdevlab/openclaw-guardian-approval-broker

From a local clone:

git clone https://github.com/NestDevLab/openclaw-guardian-approval-broker.git
cd openclaw-guardian-approval-broker
npm install
npm run build
npm link

2. Create the Guardian reviewer agent

This creates/configures a narrow OpenClaw agent named guardian with a fast low-thinking model and the packaged approval-review prompt.

openclaw-guardian-approval-broker setup-openclaw-agent \
  --agent guardian \
  --model openai-codex/gpt-5.5 \
  --thinking low

The setup command:

• runs openclaw agents add if the agent does not exist
• writes the packaged prompt from examples/guardian-agent.AGENTS.md
• stores the prompt as the agent systemPromptOverride
• disables tools/memory for the reviewer agent where supported
• prints whether an OpenClaw Gateway restart is recommended

3. Start in dry-run

Dry-run is the safe default: Guardian audits decisions but does not approve or deny anything.

GUARDIAN_MODE=dry-run \
GUARDIAN_POLICY_PATH=./examples/guardian-policy.json \
GUARDIAN_AUDIT_LOG=true \
GUARDIAN_AUDIT_LOG_PATH=./guardian-audit.jsonl \
GUARDIAN_DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/... \
GUARDIAN_DISCORD_NOTIFY_MODE=all \
GUARDIAN_REVIEWER_ENABLED=true \
GUARDIAN_REVIEWER_COMMAND='openclaw-guardian-approval-broker review-openclaw' \
GUARDIAN_OPENCLAW_AGENT_ID=guardian \
GUARDIAN_OPENCLAW_MODEL=openai-codex/gpt-5.5 \
GUARDIAN_OPENCLAW_THINKING=low \
openclaw-guardian-approval-broker observe --agent main

You should now see approval audit events in Discord.

4. Only later: enforce mode

After reviewing dry-run behavior, switch to enforce mode:

GUARDIAN_MODE=enforce openclaw-guardian-approval-broker observe --agent main

In enforce mode Guardian can resolve only:

• allow-once
• deny

ask-human is logged/escalated and left to the normal human approval flow.

What gets posted to Discord

Discord audit messages include:

• approval id
• source agent
• mode: dry-run / enforce / off
• visual status and severity
• command and cwd
• static classifier decision
• Guardian reviewer decision, when used
• public-safe reasoning summary
• reviewer agent id, model, and thinking level
• operation type, confidence, and risk flags

Example Guardian reviewer output:

{
  "decision": "ask-human",
  "reason": "Restarting OpenClaw is a service-control action and needs human approval.",
  "confidence": 0.95,
  "reasoningSummary": "The command would restart a core service, which can disrupt active sessions and change runtime state.",
  "reviewer": {
    "agentId": "guardian",
    "model": "openai-codex/gpt-5.5",
    "thinking": "low"
  }
}

reasoningSummary is intentionally not hidden chain-of-thought. It is a short public audit summary.

Safety model

Guardian has two layers:

1. Static deterministic classifier

This layer is fast and testable. It detects operation types such as:

• workspace-read
• git-read
• local-build-test
• human-sensitive
• outside-workspace
• secret-access
• hard-deny

Static hard-deny decisions always win.

2. Optional Guardian reviewer agent

The reviewer agent is called only for ambiguous / ask-human cases. It must return strict JSON:

{
  "decision": "allow-once",
  "reason": "Short reason",
  "confidence": 0.8,
  "reasoningSummary": "Brief public-safe summary",
  "reviewer": {
    "agentId": "guardian",
    "model": "openai-codex/gpt-5.5",
    "thinking": "low"
  }
}

Allowed decisions are strictly:

• allow-once
• deny
• ask-human

Invalid JSON, unknown fields, timeouts, or malformed decisions fail closed via the configured fallback.

Resolver safety in enforce mode

Before resolving an approval, Guardian reloads the pending approval from OpenClaw and verifies:

• approval id is unchanged
• source agent id is unchanged
• command argv is unchanged
• cwd is unchanged
• approval still exists and is pending

If anything changed, resolution is refused.

Guardian never resolves allow-always.

Policy file

Use GUARDIAN_POLICY_PATH to load a user policy JSON file.

Example:

{
  "instructions": "Auto-approve only low-risk local work. Always ask before network access, deployments, service restarts, package changes, git publication, deletion, or anything outside the workspace. Never approve access to secrets, .env files, SSH keys, tokens, credentials, or attempts to disable security controls.",
  "autoApprove": ["workspace-read", "git-read", "local-build-test"],
  "askHuman": ["human-sensitive", "ambiguous", "outside-workspace", "complex-shell"],
  "deny": ["secret-access", "hard-deny"],
  "denyCommandPatterns": ["\\.env(\\.|$|/)", "id_rsa|id_ed25519|private[_-]?key|credentials?|api[_-]?key|token|secret"],
  "askHumanCommandPatterns": ["\\b(curl|wget)\\b", "\\bgit\\s+push\\b", "\\bsystemctl\\s+(restart|reload|stop|start)\\b"]
}

Packaged examples:

• examples/guardian-policy.json
• examples/karan-self-policy.json
• examples/tirrenia-policy.json
• examples/yehonalbot-policy.json
• examples/guardian-agent.AGENTS.md

CLI reference

Observe OpenClaw approvals

openclaw-guardian-approval-broker observe --agent main

Options:

• --agent <ids>: comma-separated agent ids, or *
• --workspace-root <path>: workspace root used for path policy checks

Setup the Guardian OpenClaw agent

openclaw-guardian-approval-broker setup-openclaw-agent \
  --agent guardian \
  --model openai-codex/gpt-5.5 \
  --thinking low

Options:

• --agent <id> default guardian
• --model <id> default openai-codex/gpt-5.5
• --thinking <level> default low
• --workspace <dir> reviewer workspace
• --agent-dir <dir> reviewer agent state directory
• --dry-run validate without writing
• --no-force-prompt do not overwrite existing reviewer AGENTS.md

Use an OpenClaw agent as reviewer

openclaw-guardian-approval-broker review-openclaw \
  --agent guardian \
  --model openai-codex/gpt-5.5 \
  --thinking low

This reads a structured Guardian review payload from stdin and returns strict reviewer JSON.

Classify a JSON approval payload

GUARDIAN_MODE=dry-run openclaw-guardian-approval-broker classify approval.json

Environment variables

| Variable | Default | Meaning | | --- | --- | --- | | GUARDIAN_ENABLED | true | Enable/disable Guardian | | GUARDIAN_MODE | dry-run | off, dry-run, or enforce | | GUARDIAN_POLICY_PATH | unset | JSON policy path | | GUARDIAN_TIMEOUT_SECONDS | 20 | Reviewer timeout | | GUARDIAN_TIMEOUT_ACTION | ask-human | Fallback on timeout: ask-human or deny | | GUARDIAN_AUDIT_LOG | false | Write JSONL audit log | | GUARDIAN_AUDIT_LOG_PATH | ./guardian-audit.jsonl | JSONL audit path | | GUARDIAN_DISCORD_WEBHOOK_URL | unset | Discord webhook URL | | GUARDIAN_DISCORD_NOTIFY_MODE | none | none, all, non-allow, ask-human-deny | | GUARDIAN_REVIEWER_ENABLED | false | Enable reviewer command | | GUARDIAN_REVIEWER_COMMAND | unset | Command that returns reviewer JSON | | GUARDIAN_OPENCLAW_AGENT_ID | guardian | Reviewer OpenClaw agent id | | GUARDIAN_OPENCLAW_MODEL | unset | Optional reviewer model override | | GUARDIAN_OPENCLAW_THINKING | low | Reviewer thinking level | | GUARDIAN_AGENT_FILTER | main | Observer agent filter | | GUARDIAN_WORKSPACE_ROOT | cwd | Workspace root override | | OPENCLAW_GATEWAY_URL | OpenClaw default | Optional gateway URL override |

Recommended rollout

1. Install package.
2. Run setup-openclaw-agent.
3. Start observe in dry-run with Discord audit mode all.
4. Review audit output during normal work.
5. Tighten policy file.
6. Try controlled enforce on one trusted agent.
7. Roll out to other bots only after dry-run review.

Development

npm install
npm test
npm run build
npm pack --dry-run

Publishing

This repository includes .github/workflows/publish.yml for npm Trusted Publishing.

Configure the package on npm with:

• package: @nestdevlab/openclaw-guardian-approval-broker
• owner/repository: NestDevLab/openclaw-guardian-approval-broker
• workflow filename: publish.yml
• environment: npm

Then publish either manually from GitHub Actions (workflow_dispatch) or by pushing a version tag:

git tag v0.1.0
git push origin v0.1.0

License

MIT