Agent Chaperone

技能简介

Agent Chaperone 是一款面向 AI Agent 的运行时安全筛查层，它位于 Agent 与其工具之间，双向读取流量：既能在一项工具调用真正执行之前拦住危险操作，也能在工具结果被 Agent 读到之前筛查其中夹带的注入指令。它由 agent-chaperone 团队开源，以 npm 包形式发布，既可以作为 MCP 代理接入，也能以 hooks 适配器形式守护客户端内置工具。

它的定位是"一个经过校准的 AI Agent 工具调用防火墙"：每一次判断都以概率形式返回，每一道阈值都写在策略文件里而非提示词中，每一次决策都连同产生它的数字一并写入本地日志。它默认以 shadow（影子）模式启动，此模式下不拦截任何操作，只记录"它本来会拦下什么"，让你先读自己的日志，再决定是否切到强制执行。

核心能力

• 调用前筛查：在工具调用执行前读取其内容，识别破坏性命令（如会删除不可恢复数据的操作）、向外部目标外泄的密钥、与任务无关的调用。
• 结果侧筛查：在工具结果进入模型之前检查，识别藏在抓取页面或文件里、写给 Agent 而非写给人的注入指令。
• 概率化判断 + 策略文件：所有判断以概率返回，阈值全部以数字形式配置在策略文件中，避免把安全边界托付给提示词。
• 本地审计日志：每次决策都写入本地日志，附带产生该判断的具体数值，便于事后复盘与调参。
• 影子模式先行：默认不拦截，只记录"本来会拦住什么"，让上线决策建立在你自己的真实流量上。
• 确定性规则优先：允许/拒绝名单、密钥模式、危险 shell 形式、隐藏文本检测等规则先确定性执行，无需模型参与。
• 双层处理档位：结果侧 0.5 及以上会被标注（Agent 仍可读，但带"部分内容可能意在指挥读者"的横幅）；0.8 及以上且危害判断同时达标时结果会被扣留，Agent 被告知"该调用没有返回内容"。

安装配置

1. 全局安装：执行 npm install -g agent-chaperone。
2. 配置模型后端密钥：在环境中设置 TYPESAFE_API_KEY；若不设置，确定性规则（允许/拒绝名单与密钥模式）仍会运行，且每条判断都会记录"未请求模型"。也可用 OPENROUTER_API_KEY 或 AI_GATEWAY_API_KEY 走通用模型，并通过 AGENT_CHAPERONE_MODEL 指定模型。
3. 选择接入方式：作为 MCP 代理时，仅在客户端 MCP 配置中改一处，把 agent-chaperone 放在 -- 之前、原本要运行的服务器放在其后；作为内置工具守护时，配置 PreToolUse / PostToolUse / PostToolUseFailure 挂钩调用 agent-chaperone hook pre|post。
4. （可选）记录当前任务：运行 agent-chaperone task "fix the login redirect" 记录当前目录下的任务意图，代理与挂钩都会读取它，用于判断某次调用是否与任务相关；该意图有效期为 12 小时。

使用步骤

1. 先以默认 shadow 模式运行，观察日志中"本来会拦下"的记录，对照自己的真实流量判断阈值是否合适。
2. 用 agent-chaperone wrap 自动改写客户端 MCP 配置（默认只打印改动、不写入，加 --write 才落盘，并会保留原文件备份；--unwrap 可还原，重复执行不会产生变化）。
3. 按需调整策略文件中的阈值，或对必须留在本地的内容按服务器粒度关闭筛查。
4. 确认无误后切换到 enforce 模式：扣留需你批准的调用、拦截策略拒绝的操作、扣留读起来像指令的结果；如需更严格可用 strict 模式。

适用场景

• 高危命令防护：拦截 rm 之类不可恢复的破坏性操作，且能区分路径是 src/auth.ts 还是 ~/.ssh/authorized_keys。
• 密钥外泄拦截：识别形似密钥的字符串并先行脱敏，阻止其被发往外部目标。
• 提示注入防御：在网页抓取、文件读取等返回结果中揪出隐藏的指令载荷。
• 离题调用识别：判断某次调用是否与你记录的任务意图完全无关。
• Agent 安全审计：通过影子模式与本地日志，为团队提供可核验的决策依据。

适用人群

适合已经在生产或半生产环境使用 Claude Code 等 Agent 客户端的开发者、安全工程师与平台团队。需要特别注意的是：它不是沙箱，无法阻止服务器执行调用未描述的行为，应与操作系统级隔离配合使用；它也不能替代客户端的权限提示，而是提供"读过内容的第二意见"，且从不替你自动批准任何操作。此外它并非本地专属，被筛查的参数与结果会发往所配置的模型后端，应先替换形似密钥的字符串。作者也坦诚它不是保证，针对它编写的自适应攻击仍可能绕过。

• 官方仓库：https://github.com/agent-chaperone/agent-chaperone
• 官方站点：https://agentchaperone.dev