OpenClaw Guardian
The missing safety layer for AI agents.
Why?
OpenClaw gives agents direct access to shell, files, email, browser, and more.
99% of that is harmless. Guardian catches the 1% that isn't — without slowing
down the rest.
How It Works
Tool Call → Blacklist Matcher (regex rules, 0ms)
↓
No match → Pass instantly (99% of calls)
Warning hit → 1 LLM vote ("did the user ask for this?")
Critical hit → 3 LLM votes (all must confirm user intent)
Two Blacklist Levels
| Level |
LLM Votes |
Latency |
Examples |
| No match |
0 |
~0ms |
Reading files, git, normal ops |
| Warning |
1 |
~1-2s |
rm -rf /tmp/cache, chmod 777, sudo apt |
| Critical |
3 (unanimous) |
~2-4s |
rm -rf ~/, mkfs, dd of=/dev/, shutdown |
What Gets Checked
Only three tool types are inspected:
exec → command string matched against exec blacklistwrite / edit → file path canonicalized and matched against path blacklist- Everything else passes through instantly
LLM Intent Verification
When a blacklist rule matches, Guardian asks a lightweight LLM: "Did the user
explicitly request this?" It reads recent conversation context to prevent
false positives.
- Warning: 1 LLM call. Confirmed → proceed.
- Critical: 3 parallel LLM calls. All 3 must confirm. Any "no" → block.
Auto-discovers a cheap/fast model from your existing OpenClaw provider config
(prefers Haiku). No separate API key needed.
LLM Fallback
- Critical + LLM down → blocked (fail-safe)
- Warning + LLM down → asks user for manual confirmation
Blacklist Rules
Critical (exec)
rm -rf on system paths (excludes /tmp/ and workspace)mkfs, dd to block devices, redirects to /dev/sd*- Writes to
/etc/passwd, /etc/shadow, /etc/sudoers
shutdown, reboot, disable SSH- Bypass:
eval, absolute-path rm, interpreter-based (python -c, node -e)
- Pipe attacks:
curl | sh, wget | bash, base64 -d | sh
- Chain attacks: download +
chmod +x + execute
Warning (exec)
rm -rf on safe paths, sudo, chmod 777, chown root- Package install/remove, service management
- Crontab mods, SSH/SCP, Docker ops,
kill/killall
Path Rules (write/edit)
- Critical: system auth files, SSH keys, systemd units
- Warning: dotfiles,
/etc/ configs, .env files, authorized_keys
Audit Log
Every blacklist hit logged to ~/.openclaw/guardian-audit.jsonl with SHA-256
hash chain — tamper-evident, each entry covers full content + previous hash.
Installation
openclaw plugins install openclaw-guardian
Or manually:
cd ~/.openclaw/workspace
git clone https://github.com/fatcatMaoFei/openclaw-guardian.git
Token Cost
| Scenario |
% of Ops |
Extra Cost |
| No match |
~99% |
0 |
| Warning |
~0.5-1% |
~500 tokens |
| Critical |
<0.5% |
~1500 tokens |
Prefers cheap models (Haiku, GPT-4o-mini, Gemini Flash).
File Structure
extensions/guardian/
├── index.ts # Entry — registers before_tool_call hook
├── src/
│ ├── blacklist.ts # Two-tier regex rules (critical/warning)
│ ├── llm-voter.ts # LLM intent verification
│ └── audit-log.ts # SHA-256 hash-chain audit logger
├── test/
│ └── blacklist.test.ts # Blacklist rule tests
├── openclaw.plugin.json # Plugin manifest
└── default-policies.json # Enable/disable toggle
License
MIT
1---2name: openclaw-guardian3description: A security layer plugin for OpenClaw that intercepts dangerous tool calls (exec, write, edit) through two-tier regex blacklist rules and LLM-based intent verification. Critical operations require 3/3 unanimous LLM votes, warning-level operations require 1 LLM confirmation. 99% of normal operations pass instantly with zero overhead. Includes bypass/pipe-attack detection, path canonicalization, SHA-256 hash-chain audit logging, and auto-discovers a cheap model from your existing provider config.4---5
6# OpenClaw Guardian
7
8> The missing safety layer for AI agents.
9
10## Why?
11
12OpenClaw gives agents direct access to shell, files, email, browser, and more.
1399% of that is harmless. Guardian catches the 1% that isn't — without slowing
14down the rest.
15
16## How It Works
17
18```
19Tool Call → Blacklist Matcher (regex rules, 0ms)
20 ↓
21 No match → Pass instantly (99% of calls)
22 Warning hit → 1 LLM vote ("did the user ask for this?")
23 Critical hit → 3 LLM votes (all must confirm user intent)
24```
25
26### Two Blacklist Levels
27
28| Level | LLM Votes | Latency | Examples |
29|-------|-----------|---------|---------|
30| No match | 0 | ~0ms | Reading files, git, normal ops |
31| Warning | 1 | ~1-2s | `rm -rf /tmp/cache`, `chmod 777`, `sudo apt` |
32| Critical | 3 (unanimous) | ~2-4s | `rm -rf ~/`, `mkfs`, `dd of=/dev/`, `shutdown` |
33
34### What Gets Checked
35
36Only three tool types are inspected:
37
38- `exec` → command string matched against exec blacklist
39- `write` / `edit` → file path canonicalized and matched against path blacklist
40- Everything else passes through instantly
41
42### LLM Intent Verification
43
44When a blacklist rule matches, Guardian asks a lightweight LLM: "Did the user
45explicitly request this?" It reads recent conversation context to prevent
46false positives.
47
48- Warning: 1 LLM call. Confirmed → proceed.
49- Critical: 3 parallel LLM calls. All 3 must confirm. Any "no" → block.
50
51Auto-discovers a cheap/fast model from your existing OpenClaw provider config
52(prefers Haiku). No separate API key needed.
53
54### LLM Fallback
55
56- Critical + LLM down → blocked (fail-safe)
57- Warning + LLM down → asks user for manual confirmation
58
59## Blacklist Rules
60
61### Critical (exec)
62- `rm -rf` on system paths (excludes `/tmp/` and workspace)
63- `mkfs`, `dd` to block devices, redirects to `/dev/sd*`
64- Writes to `/etc/passwd`, `/etc/shadow`, `/etc/sudoers`
65- `shutdown`, `reboot`, disable SSH
66- Bypass: `eval`, absolute-path rm, interpreter-based (`python -c`, `node -e`)
67- Pipe attacks: `curl | sh`, `wget | bash`, `base64 -d | sh`
68- Chain attacks: download + `chmod +x` + execute
69
70### Warning (exec)
71- `rm -rf` on safe paths, `sudo`, `chmod 777`, `chown root`
72- Package install/remove, service management
73- Crontab mods, SSH/SCP, Docker ops, `kill`/`killall`
74
75### Path Rules (write/edit)
76- Critical: system auth files, SSH keys, systemd units
77- Warning: dotfiles, `/etc/` configs, `.env` files, `authorized_keys`
78
79## Audit Log
80
81Every blacklist hit logged to `~/.openclaw/guardian-audit.jsonl` with SHA-256
82hash chain — tamper-evident, each entry covers full content + previous hash.
83
84## Installation
85
86```bash
87openclaw plugins install openclaw-guardian
88```
89
90Or manually:
91
92```bash
93cd ~/.openclaw/workspace
94git clone https://github.com/fatcatMaoFei/openclaw-guardian.git
95```
96
97## Token Cost
98
99| Scenario | % of Ops | Extra Cost |
100|----------|----------|------------|
101| No match | ~99% | 0 |
102| Warning | ~0.5-1% | ~500 tokens |
103| Critical | <0.5% | ~1500 tokens |
104
105Prefers cheap models (Haiku, GPT-4o-mini, Gemini Flash).
106
107## File Structure
108
109```
110extensions/guardian/
111├── index.ts # Entry — registers before_tool_call hook
112├── src/
113│ ├── blacklist.ts # Two-tier regex rules (critical/warning)
114│ ├── llm-voter.ts # LLM intent verification
115│ └── audit-log.ts # SHA-256 hash-chain audit logger
116├── test/
117│ └── blacklist.test.ts # Blacklist rule tests
118├── openclaw.plugin.json # Plugin manifest
119└── default-policies.json # Enable/disable toggle
120```
121
122## License
123
124MIT
modbender