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
CODEBLOCK0
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 blacklist - INLINECODE8 /
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) - INLINECODE12 ,
dd to block devices, redirects to INLINECODE14 - Writes to
/etc/passwd, /etc/shadow, INLINECODE17 - INLINECODE18 ,
reboot, disable SSH - Bypass:
eval, absolute-path rm, interpreter-based (python -c, node -e) - Pipe attacks:
curl | sh, wget | bash, INLINECODE25 - Chain attacks: download +
chmod +x + execute
Warning (exec)
- -
rm -rf on safe paths, sudo, chmod 777, INLINECODE30 - Package install/remove, service management
- Crontab mods, SSH/SCP, Docker ops,
kill/ INLINECODE32
Path Rules (write/edit)
- - Critical: system auth files, SSH keys, systemd units
- Warning: dotfiles,
/etc/ configs, .env files, INLINECODE35
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
CODEBLOCK1
Or manually:
CODEBLOCK2
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
CODEBLOCK3
License
MIT
OpenClaw Guardian
AI代理缺失的安全层。
为什么？
OpenClaw 让代理可以直接访问 shell、文件、电子邮件、浏览器等。
其中 99% 的操作是无害的。Guardian 负责捕捉那 1% 的危险操作——同时不影响其余操作的执行速度。
工作原理
工具调用 → 黑名单匹配器（正则规则，0毫秒）
↓
未匹配 → 立即通过（99%的调用）
警告命中 → 1次LLM投票（用户是否请求了此操作？）
严重命中 → 3次LLM投票（全部必须确认用户意图）
两级黑名单
| 级别 | LLM投票数 | 延迟 | 示例 |
|---|
| 未匹配 | 0 | ~0毫秒 | 读取文件、git、常规操作 |
| 警告 |
1 | ~1-2秒 | rm -rf /tmp/cache、chmod 777、sudo apt |
| 严重 | 3（全票通过） | ~2-4秒 | rm -rf ~/、mkfs、dd of=/dev/、shutdown |
检查范围
仅检查三种工具类型：
- - exec → 命令字符串与执行黑名单匹配
- write / edit → 文件路径规范化后与路径黑名单匹配
- 其他所有工具类型立即通过
LLM意图验证
当黑名单规则匹配时，Guardian 会询问一个轻量级LLM：用户是否明确请求了此操作？它会读取最近的对话上下文以防止误报。
- - 警告：1次LLM调用。确认 → 继续执行。
- 严重：3次并行LLM调用。全部必须确认。任何否 → 阻止。
从您现有的OpenClaw提供程序配置中自动发现廉价/快速模型（优先使用Haiku）。无需单独的API密钥。
LLM回退
- - 严重 + LLM宕机 → 阻止（故障安全）
- 警告 + LLM宕机 → 请求用户手动确认
黑名单规则
严重（执行）
- - 对系统路径执行rm -rf（排除/tmp/和工作空间）
- mkfs、对块设备执行dd、重定向到/dev/sd*
- 写入/etc/passwd、/etc/shadow、/etc/sudoers
- shutdown、reboot、禁用SSH
- 绕过方式：eval、绝对路径rm、基于解释器（python -c、node -e）
- 管道攻击：curl | sh、wget | bash、base64 -d | sh
- 链式攻击：下载 + chmod +x + 执行
警告（执行）
- - 对安全路径执行rm -rf、sudo、chmod 777、chown root
- 包安装/卸载、服务管理
- Crontab修改、SSH/SCP、Docker操作、kill/killall
路径规则（写入/编辑）
- - 严重：系统认证文件、SSH密钥、systemd单元
- 警告：点文件、/etc/配置、.env文件、authorized_keys
审计日志
每次黑名单命中记录到~/.openclaw/guardian-audit.jsonl，带有SHA-256哈希链——防篡改，每条记录包含完整内容及前一条哈希值。
安装
bash
openclaw plugins install openclaw-guardian
或手动安装：
bash
cd ~/.openclaw/workspace
git clone https://github.com/fatcatMaoFei/openclaw-guardian.git
Token消耗
~0.5-1% | ~500 tokens |
| 严重 | <0.5% | ~1500 tokens |
优先使用廉价模型（Haiku、GPT-4o-mini、Gemini Flash）。
文件结构
extensions/guardian/
├── index.ts # 入口 — 注册beforetoolcall钩子
├── src/
│ ├── blacklist.ts # 两级正则规则（严重/警告）
│ ├── llm-voter.ts # LLM意图验证
│ └── audit-log.ts # SHA-256哈希链审计日志记录器
├── test/
│ └── blacklist.test.ts # 黑名单规则测试
├── openclaw.plugin.json # 插件清单
└── default-policies.json # 启用/禁用开关
许可证
MIT
