最后更新：2026 年 3 月 · 源码：openclaw-security
治理与安全
OpenClaw 智能体的安全加固插件，由六个通过 JavaScript 桥接集成到 OpenClaw 钩子系统的 Python 模块组成——提供提示词注入防御、最小权限执行、审计日志、智能体间消息签名和记忆访问控制。
是什么
openclaw-security 是一个六模块安全层，在四个生命周期点钩入 OpenClaw。每个模块都针对特定的 AI 智能体威胁：外部数据向智能体注入指令、智能体执行未授权命令、智能体间消息被伪造、记忆条目被篡改。这些模块是独立的——你可以单独部署或组合部署。
为什么
一个具有 shell 访问权限且没有额外控制的原始 OpenClaw 智能体是一个重大攻击面。获取 Web 内容的智能体面临提示词注入风险：恶意页面可以嵌入智能体视为来自其操作员的指令。具有不受限制 shell 访问权限的智能体可能被引导泄露数据、删除文件或进行外部网络调用。智能体间消息没有真实性保证——被入侵的智能体可以伪造看似来自可信对等方的消息。
此模块应用 AI 智能体安全研究中的防御措施：聚光灯隔离外部数据、命令白名单执行最小权限、HMAC 签名实现智能体间信任、审计日志用于取证。设计是务实的——防御按优先级分层，而不是试图一次性解决所有威胁。
架构
按实施优先级组织的六个模块：
| 优先级 | 模块 | 功能 |
|---|---|---|
| P0 | 聚光灯隔离 | 用边界标签包装外部数据（Web、邮件、webhook），将其与系统指令隔离 |
| P0 | 审计日志 | 带文件锁定、脱敏和内置告警规则的 JSONL 工具调用日志 |
| P1 | 最小权限 | 每个智能体的命令黑名单和文件路径白名单——硬性阻止未授权的 exec 调用 |
| P1 | LLM 防护 | 对 LLM 输入和输出进行正则/llm-guard 扫描，检测注入、密钥和恶意 URL（仅警告） |
| P1 | 智能体通信 | 智能体间通信的 HMAC-SHA256 消息签名——防止消息伪造 |
| P2 | 记忆 ACL | 记忆层写入时注入检测和签名存储 |
OpenClaw 钩子集成——Python 模块通过桥接层从 JS 钩子系统调用：
| 钩子 | Python 模块 | 效果 |
|---|---|---|
| before_tool_call | permission_checker.py | 阻止未授权的 exec 调用（硬性阻止） |
| after_tool_call | audit_logger.py | 写入 JSONL 审计记录 + 评估告警规则 |
| llm_input | llm_guard_wrapper.py | 扫描注入/密钥（仅警告） |
| llm_output | llm_guard_wrapper.py | 扫描密钥/恶意 URL（仅警告） |
故障开放设计
所有桥接调用均故障开放：如果 Python 缺失、崩溃或超时，调用被允许并记录警告。这避免了误报阻断，但意味着安全是尽力而为的，而不是有保证的。
关键设计决策
优先级分层——并非所有防御都同等重要
P0 模块（聚光灯、审计日志）有最佳的努力-价值比：实现成本低，并立即提供可观测性和基本注入防护。P1 模块需要更多配置。P2 是锦上添花。仅部署 P0 就已经有意义地改善了安全态势。
故障开放——可用性优于安全性
如果 Python 安全层崩溃，智能体调用继续进行。这是明确的权衡：阻止合法智能体操作的损坏安全层比暂时缺失的安全层更糟糕。审计日志捕获发生的事情，即使在主动阻止失败时也能进行事后取证。
LLM 防护在 llm_input/llm_output 处警告，不阻止
当前 OpenClaw 钩子 API 不支持在 llm_input/llm_output 钩子处硬性阻止。LLM 防护检测被记录为警告。要对检测到的注入执行阻止，请在智能体应用层处理——LLM 防护提供信号，应用决定行动。
JavaScript 桥接——薄层，Python 处理逻辑
OpenClaw 钩子系统是 JavaScript；安全逻辑是 Python。桥接刻意很薄——只是序列化、子进程调用和错误处理。所有安全逻辑都保留在 Python 模块中，可以独立于 OpenClaw 进行测试。
如何自行构建
1. 从聚光灯和审计日志开始（P0）
聚光灯很便宜：在外部获取的内容进入智能体上下文之前用边界标记包装它。看到 [EXTERNAL_DATA_START] ... [EXTERNAL_DATA_END] 的 LLM 有一个结构信号，表明此内容是不可信的。审计日志也很便宜：在每次工具调用后写入一个 JSONL 记录，包含智能体 ID、工具名称、输入（脱敏）和时间戳。
2. 命令黑名单用正则，而非精确匹配
精确匹配命令阻止很容易绕过（添加空格，使用路径前缀）。使用无论细微变化都能匹配危险操作的正则表达式模式。基本模式：rm\s+-rf\s+/、curl\s+.*(?!localhost)、wget\s+、mkfs\b。
3. 将告警规则内置到审计日志器，而非安全模块
告警规则（敏感文件访问时触发，外部网络调用时触发）属于审计日志器，而不是分散在各个模块中。审计日志器看到所有工具调用，可以在一个地方应用跨切面规则。三个最少规则：敏感路径访问、外部网络调用、智能体间敏感内容。
4. 智能体间签名使用 HMAC-SHA256，每对使用对称密钥
对于单机多智能体部署，每对的 HMAC 对称密钥就足够且简单。每对智能体（发送方、接收方）共享存储在密钥管理器中的密钥。接收方在处理任何智能体间消息之前验证 HMAC。这防止了被入侵的智能体冒充可信对等方。
5. 保持每个模块独立且可独立测试
每个安全模块应该可以在不运行 OpenClaw 的情况下导入和测试。这使得可以在不使用完整智能体栈的情况下对安全逻辑进行单元测试。OpenClaw 集成只是一个薄桥接——模块本身是没有 OpenClaw 依赖的纯 Python。
已知限制
- LLM 防护仅警告：llm_input/llm_output 钩子在 OpenClaw 当前钩子 API 中不支持硬性阻止。检测到的威胁生成警告；阻止需要在应用层处理。
- before_tool_call 仅检查 exec：JS 桥接目前只为 exec 工具调用权限检查器。其他工具（shell、write_file）会绕过 PermissionChecker，除非你在桥接中扩展检查列表。
- 正则规则可以被绕过：LLM 防护的正则回退缺乏语义理解。复杂的提示词注入变体可能会逃避检测。对于更严格的安全要求，将正则与模型级扫描配合使用。
常见问题
什么是"聚光灯"，它为什么重要？
聚光灯将外部获取的数据（Web 结果、邮件、webhook）用将其标记为不可信外部内容的结构标签包装。这使得恶意网页更难嵌入智能体会视为来自用户或系统提示词的指令——这是常见的提示词注入向量。
审计日志器内置了哪些告警规则？
三个内置规则：(1) 敏感文件路径访问（.ssh、.aws、id_rsa、/etc/passwd），(2) 包含 curl/wget/nc 且目标非 localhost 的 shell 命令，以及 (3) 包含敏感关键词的智能体间消息。所有规则以"严重"或"警告"严重级别触发，并写入 JSONL 审计日志。
不安装 OpenClaw 可以运行测试吗？
可以。Python 模块是独立的，其测试可以独立运行。OpenClaw 插件集成只有在实时钩子测试时才需要。
Authors: Qiushi Wu & Orange 🍊