Ralph for Claude Code 是什么？
Ralph for Claude 是一个面向 Claude Code 的开源工具集，旨在实现自治开发循环，自动执行项目指令并在满足退出条件时智能停止。该工具通过会话连续性、速率限制与断路器等机制防止无限循环与超额调用，并结合响应分析与多阶段错误过滤来提高执行稳定性与可靠性。
和Claude Code插件Ralph Wiggum的区别
| Ralph Wiggum 插件 | Ralph for Claude Code (本项目) | |
|---|---|---|
| 类型 | Claude Code 官方插件 | 独立的 bash 脚本系统 |
| 运行方式 | 在 Claude Code 内部通过 /ralph-wiggum:ralph-loop 命令运行 |
在 Claude Code 外部，通过 shell 脚本反复调用 Claude CLI |
| 来源 | Anthropic 官方提供 | 社区项目（frankbria） |
| 安装 | /plugin → Discover → 搜索安装 |
./install.sh 全局安装 |
对比Claude Code插件Ralph Wiggum的优势
1. 更完善的安全机制
| 功能 | Ralph Wiggum | Ralph for Claude Code |
|---|---|---|
| 最大迭代限制 | ✅ --max-iterations |
✅ 支持 |
| 速率限制 | ❌ 无 | ✅ 每小时 100 次调用限制 |
| 熔断器模式 | ❌ 无 | ✅ 3次无进展/5次重复错误自动停止 |
| 5小时API限制处理 | ❌ 无 | ✅ 检测并提示用户 |
| 两阶段错误过滤 | ❌ 无 | ✅ 避免误判 JSON 字段为错误 |
2. 更智能的退出检测
Ralph Wiggum：
- 简单的
--completion-promise文本匹配 - 或达到
--max-iterations后停止
Ralph for Claude Code：
- 双重验证机制 ：需要同时满足
- 检测到 ≥2 个完成指标（自然语言分析）
- Claude 明确设置
EXIT_SIGNAL: true
- 避免在 Claude 说"这个功能完成了，继续下一个"时误判退出
3. 实时监控仪表板
Ralph Wiggum: 无监控界面，只能看 Claude Code 输出
Ralph for Claude Code: tmux 集成的实时仪表板
- 当前循环次数
- API 调用使用量
- 速率限制倒计时
- 实时日志核心工作流程
┌─────────────────────────────────────────────────────────────┐
│ Ralph 工作循环 │
├─────────────────────────────────────────────────────────────┤
│ 1. 读取指令 (PROMPT.md) │
│ ↓ │
│ 2. 执行 Claude Code │
│ ↓ │
│ 3. 追踪进度 (更新任务列表和日志) │
│ ↓ │
│ 4. 评估完成度 (检查退出条件) │
│ ↓ │
│ 5. 未完成 → 回到步骤 1 继续循环 │
│ 已完成 → 退出 │
└─────────────────────────────────────────────────────────────┘主要特性
1. 智能退出检测（双重验证）
Ralph 使用双重条件检查防止过早退出：
- 需要检测到 ≥2 个完成指标（如"任务完成"的自然语言模式）
- 且 Claude 必须明确设置
EXIT_SIGNAL: true
2. 安全保护机制
| 机制 | 功能 |
|---|---|
| 速率限制 | 默认每小时 100 次 API 调用，可配置 |
| 熔断器 | 检测到停滞（3次无进展）或重复错误（5次）时自动停止 |
| 5小时限制处理 | 检测 Claude API 限制，提示用户等待或退出 |
| 会话过期 | 24小时自动重置会话（可配置） |
3. 会话连续性
- 跨循环保持上下文（使用
--continue标志） - 会话自动重置：熔断器触发、手动中断、项目完成时
4. 实时监控
- tmux 集成的实时仪表板
- 显示循环次数、API 使用量、日志等
项目状态
- 版本: v0.10.1（活跃开发中）
- 测试: 310 个测试，100% 通过率
- Stars: 5.5k ⭐
- Forks: 366
典型使用场景
场景示例：你有一个产品需求文档（PRD），想让 AI 自动完成开发：
bash
# 1. 安装 Ralph（一次性）
./install.sh
# 2. 导入需求文档，创建项目
ralph-import my-requirements.md my-project
cd my-project
# 3. 启动自主开发循环
ralph --monitor
# 然后...离开去喝杯咖啡 ☕
# Ralph 会自动调用 Claude Code 完成任务总结
Ralph = Claude Code 的自动驾驶模式
它解决的核心问题是：让 AI 编程助手能够无人值守地持续工作，同时有足够的安全机制（速率限制、熔断器、智能退出检测）防止失控或浪费 API 调用。
更多详情可以查看：GitHub - frankbria/ralph-claude-code