AI Guardian Plugin (tool-audit)

OpenClaw plugin that audits and optionally blocks agent tool calls via an external policy API. Use it to enforce red/green/yellow policies or "jail" the agent when too many actions are red-flagged.

Install

From the plugin directory (e.g. after cloning this repo):

openclaw plugins install /path/to/ai-guardian-plugin

Or from npm (once published):

openclaw plugins install @yourscope/ai-guardian-plugin

Config

In ~/.openclaw/openclaw.json under plugins.entries["tool-audit"]:

| Option | Description | |--------|-------------| | enabled | Enable the plugin (default: true) | | endpoint | Your policy API URL (POST). Plugin sends kind, tool, params, args, sessionKey, runId, etc. | | enforceDecision | If true, use API response to block: API returns allow: false → tool/agent is blocked | | decisionField | JSON field name for allow/deny (default: "allow") | | apiKey | Optional Bearer token for the API | | timeoutMs | Request timeout (default: 3000) | | debug | Extra gateway logs for hook firing | | localAuditPath | Optional path to append audit events (e.g. ~/.openclaw/logs/tool-audit.jsonl) | | chromiaBrid | Chromia BRID for on-chain policy decisions (enables Chromia mode when set with nodes) | | chromiaNodes | Chromia node URL list (array or comma-separated string) | | chromiaJudgeOperation | Operation name to submit action for judging (default: judge_action) | | chromiaStatusQuery | Query name to poll verdict status (default: get_judgment_status) | | chromiaPollIntervalMs | Poll interval for verdict checks (default: 1000) | | chromiaPollTimeoutMs | Max poll time for verdict checks (default: 20000) | | chromiaEncryptedAction | Optional encrypted_action argument for judge_action | | chromiaCliPath | Path to Chromia CLI binary (default: chr) | | chromiaTxAwait | Whether to submit tx with --await (default: true) | | chromiaTxTimeoutMs | Timeout for chr tx call in ms (default: 10000) | | chromiaQueryTimeoutMs | Timeout for each chr query poll call in ms (default: 5000) | | chromiaSecretPath | Optional path passed as --secret to chr tx | | chromiaFtAuth | If true, adds --ft-auth to chr tx |

Your API must respond with JSON, e.g. { "allow": true } or { "allow": false, "reason": "blocked by policy" }.

Chromia mode (on-chain decisioning)

When chromiaBrid + chromiaNodes are set, decisioning uses Chromia instead of HTTP endpoint:

1. Submit operation: judge_action(id, action_text, action_context, encrypted_action)
2. Poll query each second (configurable): get_judgment_status(id)
3. If query returns status = "answered":
   • verdict = "red" -> block (allow: false)
   • verdict = "green" or "yellow" -> allow (allow: true)
   • reason is forwarded as plugin reason text

Notes:

• If chromiaBrid is not set, plugin falls back to CLAWCHAIN_BRID env var.
• If chromiaNodes is not set, plugin falls back to CLAWCHAIN_NODE env var (comma-separated accepted).
• To match FT-authenticated runtime usage, set chromiaSecretPath and chromiaFtAuth: true.

Hooks

• before_agent_start – Fires before an agent run. When enforceDecision is on and the API returns allow: false, the agent start can be blocked (if the runtime honors it).
• before_tool_call – Fires before each tool execution. When enforceDecision is on and the API returns allow: false, the tool is blocked. Uses api.on() so OpenClaw’s hook runner sees it.

Tools

The tools/ directory includes:

• dummy-audit-server.mjs – Test server that accepts audit POSTs and returns allow/block. Default: allow all; set BLOCK_TOOLS=1 to block all.
• openclaw-tool-audit-example.json – Example config snippet for plugins.entries["tool-audit"].
• transcript-audit-forwarder.mjs – Forwards session transcript events to your audit endpoint.
• log-audit-forwarder.mjs – Tails the gateway log and forwards tool-related lines to your audit endpoint.

See tools/README.md for usage.

License

MIT