别只记录 Agent 做过什么：ButterClaw 如何在本地把高风险调用拦在执行前
给编码 Agent 接上终端、浏览器、MCP 服务之后，风险并不只来自模型“答错了”。更棘手的是：Agent 已经拿到了执行能力，某段网页文本、仓库里的说明文件或工具返回值又把间接提示注入带进上下文，最后诱导它读取凭据、探测内网或执行破坏性命令。
很多团队会先接入 tracing 或日志平台。这当然有价值，但它回答的是“刚才发生了什么”。如果你要在动作发生前阻断风险调用，还需要另一层运行时执行控制。ButterClaw 是一个 Apache-2.0 许可的本地优先项目，定位为面向自主 Agent 的安全监控与强制执行层：它监测操作系统遥测和 MCP 工具调用链，在本机保存状态，并把可疑事件送入规则和本地模型组成的判定管道。
它并不是某个 Agent 框架的替代品，也不应被理解成通用 WAF。它适合放在已有 Agent 工作流旁边，为“已授权、但可能被上下文诱导”的运行过程增加一条可审计的刹车线。
为什么“事后可观测”还不够
日志、trace 与回放能帮助定位事故，却天然晚于副作用：一个外发请求可能已经携带了令牌，一个 shell 命令可能已经改坏工作区。对可执行 Agent 而言，更实用的分层是：
- 执行前的确定性门槛：已知危险模式不必等待模型推理，例如反向 shell 迹象、云元数据服务探测、带编码的外传管道。
- 上下文相关的风险判断：单个工具调用未必危险；连续调用的目标、频率和前后关系才可能显示出行为漂移。
- 可逆或不可逆响应的选择：低置信度事件先阻断并告警，高置信度且确认在受控环境中的场景，才考虑终止进程或撤销凭据。
关键不在于把所有 Agent 行为都判为恶意，而是明确哪些动作必须经过额外检查。否则，团队很容易在“减少误报”和“避免一次不可逆事故”之间只能二选一。
ButterClaw 的三段判定路径
ButterClaw 的 README 描述了一条由 Arsenal、Guardian Brain、Auditor 组成的路径。先由 Arsenal 在推理前匹配确定性签名；未命中的事件才进入 Guardian Brain，由本地 Ollama 模型结合最近五次 MCP 调用判断上下文；随后 Auditor 用独立的、更保守的提示配置复核判定。只有被判为严重风险的事件才进入响应阶段。
这一拆分有两个工程上的好处。第一，明确规则不把延迟和不确定性转嫁给模型：README 当前列出 7 个签名，其中包括凭据经由网络工具外传、Base64 外传管道、系统提示覆盖、反向 shell、云元数据服务探测和持久化机制注入。第二，模型不是唯一裁判；双阶段判断能把“模型刚好误读一段文本”与“多条连续工具调用共同构成风险”区分开。
项目还提供三档 Paranoia Dial：Observe、SIGKILL、SIGKILL 加 vault shred。这里最值得保守对待的是后两档。终止本地进程可能中断正常任务，而凭据撤销或本地保险库清除更接近事故处置而非普通告警。建议先在 Observe 模式收集基线，并把动作升级权交给明确的运维流程，而不是一开始就自动清除凭据。
用 Docker Compose 建一个可验证的本地试验环境
官方 Quick Start 要求 Docker、运行在宿主机上的 Ollama，以及可用的本地推理资源；CPU 可以作为较慢的回退。下面的命令来自项目 README，重点是先拉取模型、复制环境配置，再启动 Compose 栈：
git clone https://github.com/butterclaw-tech/butterclaw.git cd butterclaw ollama pull gemma4:e4b ollama create butterclaw-optimized -f Modelfile.example cp .env.example .env docker compose up -d --build docker compose logs -f butterclaw
首次启动时，日志会输出一次 bootstrap 管理 API key；应立即按照团队的密钥管理规范保存，避免把它放进 shell 历史或提交到仓库。README 同时说明仪表盘位于 https://localhost，且部署使用本地 TLS 证书。浏览器出现自签名证书提示是本地试验阶段的常见现象，但不要因此把这套默认配置直接暴露到公网。
部署成功不等于防护有效。项目提供了一个 live-fire 测试流程：先添加自定义测试规则，再向 Arsenal 发起模拟攻击。把它放在隔离的测试主机或无生产凭据的环境运行，确认规则路径、告警渠道与退出码都符合预期。更重要的是，测试结束后应清理临时规则和测试事件，避免演练配置被误带入日常策略：
python scripts/add_rule.py python scripts/test_attack.py
官方 README 宣称该测试集覆盖 7 个签名、25 个攻击变体，并在失败时返回非零退出码。实际接入 CI 前，仍应先核对你的版本输出；测试规则只能证明引擎对模拟输入有效，不能证明它覆盖了业务中的所有提示注入方式。
规则、模型与凭据动作要分开治理
将 ButterClaw 接入编码 Agent 时，容易犯的错误是把它当作一个“自动封禁按钮”。更稳妥的落地方式是按风险面拆开配置：
- 确定性规则：从组织明确禁止的行为开始，例如访问云元数据端点、把密钥格式内容交给网络工具、写入持久化启动项。规则应当带版本、负责人、测试样本和回滚方式。
- 模型判定：本地模型适合处理上下文关联，但输出应被视为风险信号而非事实。对其记录触发事件、前序调用摘要、判定结果和人工复核结论，才能校准误报。
- 凭据响应：先把 Agent 使用的权限缩小到短期、最小作用域的令牌。即便启用 vault 机制，也应事先确认不同 provider 的撤销动作会影响什么，而不是在事故中才发现把共享开发密钥一起撤销了。
- 告警和演练：README 列出 ntfy、Discord、Telegram、SMTP、Webhook 与 Gotify 等告警出口。选择一个能够被值班人员可靠接收、并能关联事件 ID 的渠道；定期演练“阻断后如何恢复任务”。
这种分层也解释了它与 LangSmith、Langfuse 一类可观测性工具的关系：前者用于记录和分析 Agent 轨迹，ButterClaw 试图对运行时动作实施控制。两类能力可以并存，不能互相替代。一个实用的分工是：把完整 trace 留给排障和评估系统，把高风险事件的最小必要上下文送入执行控制层。这样既不会为了安全策略复制全部业务数据，也能在告警发生后把控制层的事件 ID 回链到原始轨迹，帮助人工判断这次阻断是有效拦截、误报，还是规则需要进一步收紧。
适用边界：不要把本地部署误认为天然安全
ButterClaw 的本地优先设计适合对遥测外流敏感、又需要给 Agent 工具调用加前置防线的开发环境，例如本地编码工作站、隔离的内部自动化主机，或具备清晰凭据边界的自托管 Agent 服务。它也有清楚的边界：
- 它依赖你能看到并接入的日志或工具调用；绕过监测路径的程序不在它的保护范围内。
- 正则签名覆盖的是已知模式，攻击者可以改变表述和调用序列；本地模型判定也会有漏报与误报。
- SIGKILL 和凭据撤销属于高影响动作，必须在预生产环境演练，并配套最小权限、备份和恢复流程。
- 项目当前 README 标注版本为 v0.6.7；具体 API、签名和部署细节可能随版本变化，升级前应阅读 changelog 与部署文档。
把它看成 Agent 运行时的“安全执行层”会比把它看成万能防火墙更准确：确定性规则快速挡住明显危险输入，本地推理帮助分析连续行为，人工与运行手册决定不可逆的处置。先观察、再校准、最后才有限度地自动阻断，才能让防护提升安全性，而不是成为下一条不可预测的自动化链路。对每一次策略升级，都保留人工复盘窗口。