防止Agent失控：best-of-Agent-Harnesses 的 runaway-guard 安全钩子安装教程-平芜编程栈

【免费下载链接】best-of-Agent-Harnesses

🏆 Ranked list of 167 AI agent harnesses, plus templates, playbooks, MCP, and learning resources. Rescored weekly.

项目地址：https://gitcode.com/gh_mirrors/be/best-of-Agent-Harnesses

best-of-Agent-Harnesses 是一个收录了 167 个 AI Agent 框架（Harness）的开源榜单项目，除了每周更新的排行榜，它还自带一套实用的 Agent 技能包。其中runaway-guard是一个安全钩子（Hook）：当你的 Agent 反复执行同一条命令、连续失败或花费超过你设定的美元上限时，它会自动"踩刹车"，防止 Agent 失控烧钱。本教程带你快速完成 runaway-guard 的安装与配置。

为什么 Agent 需要"刹车"？

把编码 Agent 丢在后台跑任务时，你可能遇到过这些情况：

🔄死循环：Agent 反复执行同一条失败命令，读同一个文件、重试同一个 API；
💸烧钱：无人值守的会话持续消耗 Token，账单悄悄飙升；
⚡连续失败：同一个错误反复重试，却毫无进展。

Claude Code 内置的--max-budget-usd只在打印模式（claude -p）下生效，交互会话需要像 runaway-guard 这样的钩子来兜底。它的工作原理是：在每一次工具调用之前，由框架执行一段检查脚本，决定是否放行、询问或拦截该次调用。

三条"绊线"：失控如何被触发

runaway-guard 设有三条绊线（Trip Wire），任何一条触发都会介入：

绊线	默认规则	触发后的动作
💰 花费（Spend）	单会话超过$10上限	80% 时提前警告；到上限后拦截所有工具调用并结束本轮
🔄 循环（Loop）	同一调用第 3 次原样重复	直接拦截，直到操作发生变化
❌ 连续失败（Failures）	连续 5 次调用失败	Claude Code 会弹窗询问你是否继续

设计上有不少细节避免误伤：读文件、搜索不算"变化"，但一次编辑、另一条命令或你的新输入都会重置循环计数；sleep、wait这类有意等待的调用永不计入循环。它的检查约 50 毫秒完成，且只在本机读取会话记录，不发起任何网络请求。规则细节可参考 references/how-it-decides.md。

一键安装步骤

第 1 步：获取技能目录

先克隆仓库，再把 runaway-guard 技能文件夹复制到你的 Agent 技能目录：

git clone https://gitcode.com/gh_mirrors/be/best-of-Agent-Harnesses

Claude Code：复制到~/.claude/skills/
Codex、Gemini CLI、Cursor、OpenCode：复制到~/.agents/skills/

第 2 步：先试运行（Dry Run）

安装脚本会先展示计划、不写任何文件，确认你同意后才写入：

python3 ~/.claude/skills/runaway-guard/scripts/install.py --cap 20

--cap 20表示把单会话花费上限设为 20 美元。输出会显示将要修改哪个设置文件、新增哪条钩子条目，以及已存在的其他钩子不受影响。

第 3 步：正式安装

确认无误后，加上--write参数正式应用：

python3 ~/.claude/skills/runaway-guard/scripts/install.py --cap 20 --write

常用可选参数：

--harness codex：安装到 Codex（默认是 Claude Code）；
--scope project：只保护当前项目（写入.claude/settings.local.json，不共享给团队）；
不加则默认保护该用户的全部会话。

完整参数说明见 scripts/install.py。

常用配置参数速查

上限等参数保存在runaway-guard.json中，也可用环境变量覆盖，详见 references/how-it-decides.md：

参数	默认值	环境变量	含义
`spend_cap_usd`	10	`RUNAWAY_GUARD_CAP_USD`	单会话美元上限，0 表示关闭
`warn_at`	0.8	`RUNAWAY_GUARD_WARN_AT`	花费警告比例（80% 时提醒）
`loop_repeats`	3	`RUNAWAY_GUARD_LOOP_REPEATS`	视为循环的重复次数
`failure_streak`	5	`RUNAWAY_GUARD_FAILURE_STREAK`	触发询问的连续失败次数

💡 项目级配置可以让限制更严格，但不能比用户级更宽松——这意味着你克隆的仓库无法关掉你设的"刹车"。

查看状态与解除保护

随时可以查看某次会话的花费与绊线触发情况：

python3 ~/.claude/skills/runaway-guard/scripts/status.py

报告会给出会话花费、各绊线当前值、触发次数和最近事件。想从零重新计数：status.py --session <会话ID> --reset。

不再需要时，卸载只移除 runaway-guard 自己的条目，并把设置文件原样恢复：

python3 ~/.claude/skills/runaway-guard/scripts/install.py --uninstall python3 ~/.claude/skills/runaway-guard/scripts/install.py --uninstall --write

Agent 被拦截后怎么办？

花费到上限：所有工具调用（包括查状态的）都会被拦截，需要你在自己的终端里提高spend_cap_usd，或运行status.py --session <ID> --reset重置计数——Agent 无法自己解除自己的上限；
循环拦截：换个思路，而不是原样重试同一条调用；
失败询问：在权限提示中决定是否放行，计数随后重新开始。

兼容性说明

框架	支持情况
Claude Code	✅ 完整支持，三条绊线全部可用
Codex	✅ 支持（需在`/hooks`中信任一次该钩子）
Gemini CLI / OpenCode	❌ 不支持（两者自带循环检测）
Cursor	❌ 不支持（会话记录缺少 Token 计数）

详细差异见 references/harness-hooks.md。

小结

runaway-guard 用三条简单直观的绊线——花费上限、循环拦截、连续失败询问——给后台运行的 Agent 装上了刹车。安装全程先预览后写入、数据不出本机，配合 skills/runaway-guard/README.md 里的完整文档，以及榜单项目中的 session-waste-report（钱花在哪了）、guardrail-tester（护栏是否有效）等技能，可以组成一套完整的 Agent 安全防护组合。趁夜跑长任务之前，给它装上这道"保险丝"吧。🛡️