OpenClaw Guardian

AI 智能体缺失的安全防护层。

为何需要？

OpenClaw 允许智能体直接访问 shell、文件系统、邮件、浏览器等能力。 其中 99% 的操作是安全无害的。Guardian 专门拦截那危险的 1%，且不影响其余 99% 的执行效率。

工作原理

工具调用 → 黑名单匹配器（正则规则，耗时 0ms）
              ↓
   未命中        → 立即放行（99% 的调用）
   触发警告      → 1 次 LLM 投票（“用户是否明确要求此操作？”）
   触发严重风险  → 3 次 LLM 投票（须全部确认用户意图）

两级黑名单机制

检测范围

仅对以下三类工具调用进行检查：

• exec → 对命令字符串执行 exec 黑名单匹配
• write / edit → 对文件路径做规范化处理后，匹配路径黑名单
• 其余所有工具调用均立即放行

LLM 意图验证

当触发黑名单规则时，Guardian 调用一个轻量级 LLM 提问：“用户是否明确请求了该操作？” 它会读取最近的对话上下文，以最大限度避免误报。

• 警告级：发起 1 次 LLM 调用；若确认，则继续执行。
• 严重风险级：并行发起 3 次 LLM 调用；必须全部返回确认；任一拒绝即阻断。

自动从您已配置的 OpenClaw provider 中发现低成本、低延迟模型（优先选用 Haiku），无需额外配置 API Key。

LLM 故障降级策略

• 严重风险级 + LLM 不可用 → 直接阻断（安全优先）
• 警告级 + LLM 不可用 → 向用户请求手动确认

黑名单规则

严重风险级（exec）

• rm -rf 作用于系统路径（排除 /tmp/ 和 workspace 路径）
• 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 + 执行

警告级（exec）

• rm -rf 作用于安全路径、使用 sudo、chmod 777、chown root
• 软件包安装/卸载、系统服务管理
• cron 任务修改、SSH/SCP 操作、Docker 操作、kill/killall

路径规则（write/edit）

• 严重风险级：系统认证文件、SSH 密钥、systemd unit 文件
• 警告级：点文件（dotfiles）、/etc/ 下的配置文件、.env 文件、authorized_keys

审计日志

每次黑名单命中均记录至 ~/.openclaw/guardian-audit.jsonl，采用 SHA-256 哈希链结构——具备防篡改特性，每条日志包含完整内容及前一条日志的哈希值。

安装方式

openclaw plugins install openclaw-guardian

或手动安装：

cd ~/.openclaw/workspace
git clone https://github.com/fatcatMaoFei/openclaw-guardian.git

Token 开销

优先选用低成本模型（如 Haiku、GPT-4o-mini、Gemini Flash）。

文件结构

extensions/guardian/
├── index.ts                # 入口文件 — 注册 before_tool_call 钩子
├── src/
│   ├── blacklist.ts        # 双级正则规则（严重风险/警告）
│   ├── llm-voter.ts        # LLM 意图验证逻辑
│   └── audit-log.ts        # 基于 SHA-256 哈希链的审计日志记录器
├── test/
│   └── blacklist.test.ts   # 黑名单规则单元测试
├── openclaw.plugin.json    # 插件清单文件
└── default-policies.json   # 启用/禁用开关配置

许可证

MIT