Claude Code 永动机：ralph-loop 无限循环迭代插件详解（安装 / 原理 / 最佳实践 / 避坑）

• Claude Code 插件 ralph-loop 全解析：Stop Hook 无限迭代、completion-promise 退出条件与最佳实践
• ralph-loop 使用指南：让 Claude Code 自动“撞墙”直到成功（原理、参数、场景、风险）
• 用 ralph-loop 把开环任务做成闭环：Claude Code 无限续杯工作流与提示词范式

关键词 ：Claude Code、ralph-loop、Claude 插件、Stop Hook、commands/hooks、completion-promise、自动迭代、AI Agent、闭环工作流、无限循环

一句话结论：它解决的是什么

我在使用后的最大的感受是——解放注意力。不用每隔 5 分钟检查一次“修复完了吗”，而是定义好目标，让 AI 自己去“撞墙”直到撞开。这种“设置后即忘”的体验，才更像真正的 AI 副驾驶：大力出奇迹。

Ralph Loop 是什么

这个插件原本叫ralph-wiggum，昨天改名ralph-loop，据说为了避免版权问题。它的功能就是：一直循环执行固定的提示词，直到设定的条件触发才退出。

类比最直观：抢票时不停刷新，直到看到“有票”才停止刷新并下单。
再夸张一点：让它一直运行，直到赚到一个小目标为止（当然别真这么干，token 会哭）。

Ralph Loop是一个基于 “Ralph Wiggum” 技术（即“持续迭代直至成功”）的 Claude Code 插件。它的核心理念是通过拦截 Claude 的“退出/完成”操作，强行将相同的 Prompt 再次输入给 Claude，从而迫使 AI 在一个无限或受限的循环中自我修正、迭代代码，直到满足特定的完成条件。

安装（保姆级）

ralph-loop 的源码在 anthropics 的官方插件仓库中：
https://github.com/anthropics/claude-plugins-official/tree/main/plugins/ralph-loop
包含 commands + hooks 的实现，3 个 .md 文件 + 2 个 sh 脚本。

安装步骤：

1. 终端输入claude启动 Claude Code（CC）
2. 输入/plugin，然后在输入框中输入ralph搜索到ralph-loop
3. 上下方向键选中，回车
4. 选择安装空间（默认用户空间）
5. 安装成功后退出当前会话，重新打开会话生效

使用方法（最关键的只有一个点：completion-promise）

1）查看指令

输入/ralph-loop可看到支持的指令：目前就是开启循环与取消循环。

2）启动循环：三个参数

• 你的指令：也就是提示词（必填）
• --completion-promise：结束循环的条件（最重要）（必填）
• --max-iterations：最大循环次数（强烈建议加，避免死循环烧光 token）

代码示例（原样保留）：

/ralph-loop"Your task description"--completion-promise"DONE"--max-iterations50

3）completion-promise 的“严格规则”

只有 CC 退出前的最后一句输出内容是completion-promise配置的设定词时，循环才会退出。

注意：是字符串匹配，不是语义匹配。（这点决定了你怎么设计“通关密语”）

执行流程（发生了什么）

• 1.Claude 在每次迭代中接收相同的提示词
• 2.执行任务，并对文件进行修改
• 3.修改完成，尝试退出
• 4.停止钩子（Stop hook）进行拦截，阻止退出，并将相同的提示词再次传入
• 5.Claude 通过文件及 Git 历史记录查看先前的工作成果
• 6.持续迭代优化，直至任务完成

原理详解（看懂这一段，你就能写出“必收敛”的提示词）

1. 循环是如何启动的

核心原理：基于“拦截 + 回旋镖”机制的伪循环

Ralph Loop 的“循环”并不是你写的while(true)，因为 Claude 本质是对话系统：一次只处理一个回合。所谓“循环”是靠一套动作强行制造出来的：阻止下班 + 把作业扔回去。

实现流程（按时序）：

1. 触发拦截 (Trigger)
   Claude 认为任务完成准备退出（Exit）时，Claude Code 自动运行stop-hook.sh

2. 构建阻断指令 (Block Decision)
   如果脚本判断任务没完成（没达到次数且没收到 Promise），它会向控制台输出一段特定 JSON 指令（不是“安静退出”）

3. JSON 的三要素

   • "decision": "block"：核心指令——不准退出
   • "reason": "原始 Prompt"：回旋镖——把你最初的任务描述再次当成“用户输入”发回给 Claude
   • "systemMessage": "..."：旁白——告诉 Claude 这是第 N 次迭代

4. 强制重入 (Re-injection)
   Claude Code 收到 block 后取消退出，并把reason当作用户刚输入的一句新消息再次投喂给 Claude

通俗解释：
像一个严格老师（Hook 脚本）守着门。学生（Claude）交卷想回家时，老师检查“次数”和“通关密语”：不满足就大喊“不行（Block）！”，把同一张卷子（Prompt）拍回桌上，逼你再做一遍。于是就“循环”了。

2. 退出条件是如何匹配的

核心原理：读会话日志 + 正则提取 + 严格字符串比对

Ralph Loop 不是实时监听对话流，而是像查档案一样读取硬盘上的对话日志，然后验证completion-promise。

流程如下：

1. 溯源：查阅会话日志 (Reading Transcript)

   • 拦截触发时，脚本从输入拿到当前会话的剧本文件路径transcript_path
   • 该文件一般是 JSONL，记录全对话历史
   • 脚本用grep筛出assistant消息并取最后一行
   • 意义：确保检查的是 Claude 尝试退出前的“最后一句”

2. 提取：解析纯文本 (JSON Parsing)

   • 用jq从 JSON 中提取message.content的.text并拼成完整字符串
   • 还原 Claude 的“原话”

3. 定位：正则抓取标签 (Regex Extraction)

   • 用 Perl 正则提取<promise>...</promise>中的内容
   • 非贪婪匹配：多个标签只取第一个
   • 多行支持：跨行也能提取

4. 标准化：清洗格式 (Normalization)

   • 去掉首尾空格
   • 压缩内部空白（换行/制表符/多空格 → 一个空格）
   • 结论：Claude 不用和排版较劲，只要字面一致

5. 判决：严格比对 (Strict Comparison)

   • 与你设置的completion-promise做字面量相等比对
   • 相等 → 删除状态文件并放行退出
   • 不相等 → 拦截退出，进入下一轮

✅ 这也解释了为什么你要把“通关密语”写得可验证、可复现、可严格命中。

3. 如何计数与结束循环

核心原理：基于文件的外部计数器

Claude 本身不会“记得运行了多少次”。迭代次数保存在外部状态文件：

• .claude/ralph-loop.local.md

max-iterations就写在这里。

具体流程：

1. 初始化：首次/ralph-loop会创建状态文件，iteration = 1，并记录max_iterations

2. 检查与终止：Stop Hook 每次读取状态文件并比较：

   • 当前迭代数iteration
   • 最大迭代数max_iterations
   • 若iteration >= max_iterations且max_iterations > 0：判定结束
   • 删除状态文件并放行退出

3. 递增计数：未满足 Promise 且未到上限：

   • 计算iteration + 1
   • 用sed原子更新状态文件
   • 再次投喂原 Prompt 开始下一轮

4. 如何主动结束循环

核心原理：物理销毁“循环状态”

循环依赖状态文件存在：.claude/ralph-loop.local.md
/cancel-ralph本质是删除它：

1. 执行删除：rm .claude/ralph-loop.local.md
2. Stop Hook 下次执行发现文件不存在 → 直接放行（exit 0）→ Claude 正常退出

一句话：监工靠“纸条”（状态文件）执法；你把纸条撕了，监工就没法拦人了。

最佳实践：如何写出“必收敛”的 completion-promise

X 上 Daisy Hollman@The_Whole_Daisy 分享了一个当前最佳的 ralph-loop 使用实践，非常具有参考意义。它的特点是：把任务成功标准写成可检查清单，并让completion-promise与之严格对应。

（代码原样保留；注意原文末尾引号可能需要自行补齐后使用）

/ralph-loop:ralph-loop 'Monitor the PR for any of the following: - Inline comments where the change requested has not yet been pushed to the PR. - Inline comments where the last message in the thread is not a response from Claude - CI failures, even if they appear to be unrelated to your changes (if you think that a test might actually be a flake, you can rerun it with the `gh` command line tool) - Merge conflicts - Extra changes in the PR If you are waiting on CI, do not waste time running sleep. Run some of the pr-review-toolkit agents to try and improve on your PR, or trace through the tests you are waiting on step-by-step, documenting the flow in your dev log, to make sure that the changes actually fix the test.' --completion-promise 'All comments have been addressed, all changes addressing those comments have been pushed to the PR, and all CI tests are passing. There are no merge conflicts in my PR, and it contains only changes relevant to the functionality in the PR

写好 completion-promise 的三条原则

1. 明确性：避免模糊词汇

• ❌ “代码看起来不错”
• ✅ “所有测试通过，0 个错误”

2. 完整性：覆盖所有成功标准

• ❌ “测试通过了”（没提 CI、没提冲突）
• ✅ “所有测试通过，CI 检查通过，无 merge conflicts”

3. 可验证性：能被工具自动确认

• 利用测试套件、gh命令、linters、静态分析
• 避免“我觉得”“看起来”等主观判断

一个好用的经验：把 completion-promise 写成“验收报告的最后一句话”，并要求 Claude 用<promise>...</promise>包起来（如果你的工作流允许）。

使用场景：什么任务值得“永动机”，什么任务别碰

适合

• 定义明确且成功标准清晰的任务
• 需要反复迭代与优化的任务（例如修代码直到测试全绿）
• 可随时丢弃的新项目（实验性质）
• 具备自动验证机制的任务（测试 / Lint / 静态分析）

不适合

• 需要人类判断或设计决策的任务
• 一次性操作（One-shot operations）
• 成功标准模糊的任务
• 生产环境调试（建议用更可控的调试手段）

风险与避坑（别把 token 当无限）

• Token 成本：每一轮都在烧钱，--max-iterations建议必加
• 退出条件太“飘”：只要无法严格命中 promise，就会无限战争
• 验收标准写漏：没覆盖的点会反复返工，迭代越跑越偏
• 字符串匹配：不是“意思对了就行”，而是“字面必须对”

最后：它真正厉害的不是“循环”，而是“闭环”

ralph-loop 本质是在把开环任务变成闭环迭代：

• 传统方式：你写 Prompt → AI 执行 → 你检查 → 不满意手动再调 → 循环往复
• ralph-loop：你定义目标 + 退出条件 → AI 自动迭代 → 直到达成目标

它考验的是两件事：

1. 任务拆解能力：你能不能把“做完”写成可验收的条件
2. 验证机制：你有没有测试、lint、命令行检查等“硬指标”

记住：每次循环都消耗 token。看好你的钱包，别陷入无限战争。