开启拉尔夫·维格姆

面向 Claude Code、Codex、Copilot CLI 以及 OpenCode 的自主代理循环

可与Claude Code、OpenAI Codex、Copilot CLI 以及 OpenCode 无缝协作——只需使用 --agent 即可切换代理。
基于 Geoffrey Huntley 提出的 Ralph Wiggum 技术

支持的代理 • 什么是 Ralph? • 安装 • 快速入门 • 命令

厌倦了代理破坏你的本地环境吗？
🏝️ 使用 sandboxed.sh，为每个任务提供一个隔离的 Linux 工作区。完全自托管，且数据存储在 Git 中。

💬 加入社区： relens.ai/community

---

支持的代理

Open Ralph Wiggum 可以与多种 AI 编码代理协同工作。只需使用 --agent 标志即可在它们之间自由切换：

代理	标志	说明
Claude Code	--agent claude-code	Anthropic 的 Claude Code CLI，用于实现自主编码
Codex	--agent codex	OpenAI 的 Codex CLI，专为 AI 驱动的开发而设计
Copilot CLI	--agent copilot	GitHub Copilot CLI，用于代理式编码
OpenCode	--agent opencode	默认代理，开源的 AI 编码助手

# 使用 Claude Code
ralph "构建一个 REST API" --agent claude-code --max-iterations 10

# 使用 OpenAI Codex
ralph "创建一个 CLI 工具" --agent codex --max-iterations 10

# 使用 Copilot CLI
ralph "重构身份验证模块" --agent copilot --max-iterations 10

# 使用 OpenCode（默认）
ralph "修复失败的测试" --max-iterations 10

---

什么是 Open Ralph Wiggum？

Open Ralph Wiggum 实现了 Ralph Wiggum 技术——一种自主代理循环：AI 编码代理（如 Claude Code、Codex 或 OpenCode）会反复接收相同的提示，直到完成任务。每次迭代时，AI 都能查看自己之前的工作成果以及 Git 历史记录，从而实现自我修正和逐步推进。

这是一款 CLI 工具，可将任何受支持的 AI 编码代理封装进一个持久化的开发循环中。无需插件——只需安装并运行即可。

# Ralph 循环的核心：
while true; do
  claude-code "构建功能 X。完成后输出 <promise>DONE</promise>。"  # 或 codex、opencode
done

为什么这样有效？ AI 在每次迭代之间不会彼此对话。它每次都会看到相同的提示，但代码库却已从之前的迭代中发生了变化。这种机制形成了强大的反馈回路：代理会不断迭代优化自己的工作，直至所有测试全部通过。

多代理灵活性

在不改变工作流程的前提下，轻松在不同 AI 编码代理之间切换：

• Claude Code (--agent claude-code) — Anthropic 强大的编码代理
• Codex (--agent codex) — OpenAI 专为代码优化的模型
• Copilot CLI (--agent copilot) — GitHub 的代理式编码工具
• OpenCode (--agent opencode) — 开源的默认选项

核心功能

• 多代理支持 — 采用相同的工作流，同时使用 Claude Code、Codex 或 OpenCode
• 自我修正循环 — 代理能够看到自己之前的工作，并及时纠正错误
• 自主执行 — 设置好循环后，随时返回到已完成的代码
• 任务追踪 — 内置任务管理功能，支持使用 --tasks 模式
• 实时监控 — 通过 --status 命令，在另一个终端中查看进度
• 循环中期提示 — 无需中断，只需使用 --add-context 注入指导信息

为什么选择代理式循环？

优势	工作原理
自我修正	AI 能够识别并修复先前运行中出现的测试失败问题
持久性	离开后，再次回到已完成的工作中
迭代式推进	将复杂任务分解为多个逐步推进的环节
自动化	无需人工看管——循环会自动处理重试
可观察性	通过 --status 监控进展，查看历史记录和困难指标
循环中期指导	通过 --add-context 注入提示，而不中断循环

安装

前提条件：

• Bun 运行时
• 至少一种 AI 编码代理 CLI：
  • Claude Code — Anthropic 的 Claude Code CLI
  • Codex — OpenAI 的 Codex CLI
  • Copilot CLI — GitHub 的 Copilot CLI
  • OpenCode — 开源的 AI 编码助手

npm（推荐）

npm install -g @th0rgal/ralph-wiggum

Bun

bun add -g @th0rgal/ralph-wiggum

从源代码获取

git clone https://github.com/Th0rgal/open-ralph-wiggum
cd open-ralph-wiggum
./install.sh

git clone https://github.com/Th0rgal/open-ralph-wiggum
cd open-ralph-wiggum
.\install.ps1

此操作会将 ralph CLI 命令全局安装。

快速入门

# 简单任务，设置迭代上限
ralph "创建一个名为 'Hello World' 的 hello.txt 文件。完成后输出 <promise>DONE</promise>。" \
  --max-iterations 5

# 构建实际项目
ralph "构建一个用于 todo 的 REST API，支持 CRUD 操作及测试。每次修改后运行测试。当所有测试通过时，输出 <promise>COMPLETE</promise>。" \
  --max-iterations 20

# 用 Claude Code 替代 OpenCode
ralph "创建一个小型 CLI 并记录使用方法。完成后输出 <promise>COMPLETE</promise>。" \
  --agent claude-code --model claude-sonnet-4 --max-iterations 5

# 用 Codex 替代 OpenCode
ralph "创建一个小型 CLI 并记录使用方法。完成后输出 <promise>COMPLETE</promise>。" \
  --agent codex --model gpt-5-codex --max-iterations 5

# 用 Copilot CLI
ralph "创建一个小型 CLI 并记录使用方法。完成后输出 <promise>COMPLETE</promise>。" \
  --agent copilot --max-iterations 5

# 复杂项目，采用任务模式
ralph "构建一个全栈 Web 应用，包含用户认证和数据库功能" \
  --tasks --max-iterations 50

环境变量

通过以下环境变量来配置代理二进制文件：

变量	说明	默认值
RALPH_OPENCODE_BINARY	OpenCode CLI 的路径	"opencode"
RALPH_CLAUDE_BINARY	Claude Code CLI 的路径	"claude"
RALPH_CODEX_BINARY	Codex CLI 的路径	"codex"
RALPH_COPILOT_BINARY	Copilot CLI 的路径	"copilot"

Windows 用户请注意： Ralph 会自动为 npm 安装的 CLI 解析 .cmd 扩展名。若遇到“命令未找到”的错误，您可以使用这些环境变量来指定可执行文件的完整路径。

命令

运行循环

ralph "<prompt>" [选项]

选项：
  --agent AGENT            要使用的 AI 代理：opencode（默认）、claude-code、codex、copilot
  --min-iterations N       允许完成前的最小迭代次数（默认：1）
  --max-iterations N       在达到 N 次迭代后停止（默认：无限制）
  --completion-promise T   表示完成的文本（默认：COMPLETE）
  --abort-promise TEXT     表示提前终止的短语（例如：前置条件失败）
  --tasks, -t              启用任务模式，用于结构化任务跟踪
  --task-promise T         表示任务完成的文本（默认：READY_FOR_NEXT_TASK）
  --model MODEL            要使用的模型（仅限代理特定的模型）
  --rotation LIST          每次迭代时的代理/模型旋转顺序（以逗号分隔）
  --prompt-file, --file, -f  从文件中读取提示内容
  --prompt-template PATH   使用自定义提示模板（请参阅自定义提示）
  --no-stream              缓存代理输出，并在末尾打印
  --verbose-tools          打印每一条工具行（禁用紧凑的工具摘要）
  --questions              启用交互式问题处理（默认启用）
  --no-questions           禁用交互式问题处理（代理将对问题进行循环处理）
  --no-plugins             禁用本次运行中的非认证 OpenCode 插件（仅适用于 opencode）
  --no-commit              不在迭代结束后自动提交
  --allow-all              自动批准所有工具权限（默认开启）
  --no-allow-all           需要交互式权限提示
  --config PATH            使用自定义代理配置文件
  --init-config [PATH]     将默认代理配置写入 PATH 并退出
  --help                   显示帮助信息

任务模式

任务模式允许您将复杂项目拆分为更小、更易于管理的任务。Ralph 一次专注于一项任务，并在 Markdown 文件中记录进度。

# 启用任务模式
ralph "构建一个完整的 Web 应用程序" --tasks --max-iterations 20

# 自定义任务完成信号
ralph "多功能项目" --tasks --task-promise "TASK_DONE"

任务管理命令

# 列出当前任务
ralph --list-tasks

# 添加新任务
ralph --add-task "实现用户身份验证"

# 根据索引移除任务
ralph --remove-task 3

# 显示状态（当任务模式启用时，任务会自动显示）
ralph --status

任务模式的工作原理

1. 任务文件：任务存储在 .ralph/ralph-tasks.md 中。
2. 每次迭代一个任务：Ralph 专注于单一任务，以减少混淆。
3. 自动推进进度：当某项任务完成时（READY_FOR_NEXT_TASK），Ralph 会继续下一个任务。
4. 持久化状态：任务在循环重启后依然保留。
5. 专注的上下文：每次迭代中更小的上下文能够降低成本并提升可靠性。

任务状态指示器：

• [ ] - 未开始
• [/] - 正在进行中
• [x] - 已完成

示例任务文件：

# Ralph 任务

- [ ] 设置项目结构
- [x] 初始化 Git 仓库
- [/] 实现用户身份验证
  - [ ] 创建登录页面
  - [ ] 添加 JWT 处理
- [ ] 构建仪表盘界面

自定义提示模板

您可以完全自定义发送给代理的提示，使用 --prompt-template。这在与自定义工作流或工具集成时非常有用。

ralph "构建一个 REST API" --prompt-template ./my-template.md

可用变量：

变量	说明
{{iteration}}	当前迭代编号
{{max_iterations}}	最大迭代次数（或“无限制”）
{{min_iterations}}	最小迭代次数
{{prompt}}	用户的任务提示
{{completion_promise}}	完成承诺文本（例如：“COMPLETE”）
{{abort_promise}}	中止承诺文本（如已配置）
{{task_promise}}	任务承诺文本（适用于任务模式）
{{context}}	在循环过程中添加的额外上下文
{{tasks}}	任务列表内容（适用于任务模式）

示例模板 (my-template.md):

# 迭代 {{iteration}} / {{max_iterations}}

## 任务
{{prompt}}

## 指令
1. 检查珠子的当前状态
2. 决定下一步该做什么
3. 当珠子上的整个任务完成时，输出：
   <promise>{{completion_promise}}</promise>

{{context}}

监控与控制

# 检查活跃循环的状态（从另一个终端运行）
ralph --status

# 为下一次迭代添加上下文/提示
ralph --add-context "重点先修复身份验证模块"

# 清空待处理的上下文
ralph --clear-context

状态仪表板

--status 命令会显示：

• 活跃循环信息：当前迭代、已耗时、提示内容
• 待处理的上下文：任何已排队等待下一次迭代的提示
• 当前任务：当任务模式启用时会自动显示（或使用 --tasks）
• 迭代历史：最近 5 次迭代的工具使用情况及持续时间
• 困难指标：如果代理陷入停滞（无进展、重复报错），则会显示警告

╔══════════════════════════════════════════════════════════════════╗
║                    Ralph Wiggum 状态                           ║
╚══════════════════════════════════════════════════════════════════╝

🔄 ACTIVE LOOP
   迭代：    3 / 10
   已耗时： 5 分 23 秒
   提示：      COMPLETE
   提示内容： 构建一个 REST API...

📊 历史记录（3 次迭代）
   总耗时：   5 分 23 秒

   最近几次迭代：
   🔄 #1：2 分 10 秒 | Bash:5 写入:3 阅读:2
   🔄 #2：1 分 45 秒 | 编辑:4 Bash:3 阅读:2
   🔄 #3：1 分 28 秒 | Bash:2 编辑:1

⚠️ 困难指标：
   - 3 次迭代中未发生文件变更
   💡 可考虑使用：ralph --add-context "你的提示在这里"

循环中注入上下文

在循环运行期间，引导陷入困境的代理，而无需中断循环：

# 在另一个终端中，循环仍在运行
ralph --add-context "错误出现在 utils/parser.ts 第 42 行"
ralph --add-context "尝试使用单例模式来管理配置"

上下文会在一次迭代后自动被消耗。

故障排除

插件错误

本包仅支持 CLI 使用。若 OpenCode 尝试加载 ralph-wiggum 或 open-ralph-wiggum 插件， 请将其从 OpenCode 的 plugin 列表中移除（opencode.json），或运行：

ralph "您的任务" --no-plugins

提供商模型未找到 / 模型未配置

如果您看到 ProviderModelNotFoundError 或“提供商会返回错误”，则需要配置一个默认模型：

对于 OpenCode：

1. 编辑 ~/.config/opencode/opencode.json：

   {
     "$schema": "https://opencode.ai/config.json",
     "model": "your-provider/model-name"
   }
   

2. 或者使用 --model 标志：ralph "task" --model provider/model

对于其他代理： 请使用 --model 标志明确指定模型。

Windows 上出现“命令未找到”错误

Ralph 会在 Windows 系统中自动尝试使用 .cmd 扩展名。如果仍然遇到问题：

1. 使用环境变量设置完整路径：

   $env:RALPH_OPENCODE_BINARY = "C:\path\to\opencode.cmd"
   

2. 或者将 CLI 添加到您的 PATH 中

“bun: 命令未找到”

请安装 Bun：https://bun.sh

如何撰写优质提示词

包含清晰的成功标准

❌ 不佳示例：

构建一个待办事项 API

✅ 良好示例：

构建一个用于待办事项的 REST API，具备以下功能：
- CRUD 接口（GET、POST、PUT、DELETE）
- 输入验证
- 对每个接口进行测试
在代码变更后运行测试。当所有测试通过时，输出 `<promise>COMPLETE</promise>`。

使用可验证的条件

❌ 不佳示例：

让代码变得更好

✅ 良好示例：

重构 auth.ts，具体步骤如下：
1. 将验证逻辑提取至独立函数中
2. 添加网络失败的错误处理机制
3. 确保所有现有测试依然通过

当重构完成且测试通过时，输出 `<promise>DONE</promise>`。

始终设置最大迭代次数

# 安全网，防止循环失控
ralph "您的任务" --max-iterations 20

推荐的 PRD 格式

Ralph 将提示词文件视为纯文本格式，因此任何格式均可使用。为获得最佳效果，请使用简洁明了的 PRD 文件，其中包含以下内容：

• 目标：一句话概括期望达成的结果
• 范围：明确哪些内容在内，哪些内容在外
• 需求：按编号列出、可测试的项目
• 约束条件：技术栈、性能、安全性、兼容性
• 验收标准：明确的成功验证条件
• 完成承诺：务必添加 <promise>COMPLETE</promise>（或与您的 --completion-promise 相匹配）

示例（Markdown）：

# PRD：添加导出按钮

## 目标
让用户能够从仪表板导出报表为 CSV 格式。

## 范围
- 在：导出当前报表视图
- 在：后台导出并进行调度

## 需求
1. 在仪表板页眉处添加“导出 CSV”按钮。
2. CSV 报表应包含以下列：日期、收入、会话数。
3. 支持最多 1 万行的报表。

## 约束条件
- 保持当前的 UI 样式。
- 使用 utils/csv.ts 中已有的 CSV 工具。

## 验收标准
- 点击按钮后，可下载有效的 CSV 文件。
- CSV 文件能顺利打开并显示在 Excel/Excel 表格中。
- 所有现有测试均通过。

## 完成承诺
<promise>COMPLETE</promise>

JSON 功能列表（适用于复杂项目）

对于大型项目，采用结构化的 JSON 功能列表比使用散文形式更有效。根据 Anthropic 关于高效代理架构的研究 的发现，JSON 格式能够降低代理不当修改测试定义的风险。

创建一个 features.json 文件：

{
  "features": [
    {
      "category": "功能性",
      "description": "导出按钮可下载包含当前报表数据的 CSV 文件",
      "steps": [
        "导航至仪表板",
        "点击‘导出 CSV’按钮",
        "验证 CSV 文件已成功下载",
        "打开 CSV 文件并确认列：日期、收入、会话数",
        "确保数据与报表中的实际内容一致"
      ],
      "passes": false
    },
    {
      "category": "功能性",
      "description": "导出功能可处理高达 1 万行的大型报表",
      "steps": [
        "加载包含 1 万行数据的报表",
        "点击‘导出 CSV’按钮",
        "验证导出过程无超时问题",
        "确认 CSV 文件中包含所有所需行"
      ],
      "passes": false
    },
    {
      "category": "UI",
      "description": "导出按钮与现有仪表板风格相匹配",
      "steps": [
        "导航至仪表板",
        "验证按钮是否使用了现有的按钮组件",
        "确认按钮位于仪表板页眉区域"
      ],
      "passes": false
    }
  ]
}

随后，在提示词中引用该文件：

阅读 `features.json` 文件以了解功能列表。逐一完成每个功能的测试。
在确认某个功能能够实现端到端的完整流程后，将该功能的 `passes` 字段更新为 `true`。
切勿修改描述或步骤——仅需更改 `passes` 布尔值。
当所有功能均通过测试时，输出 `<promise>COMPLETE</promise>`。

为什么选择 JSON？ 与 Markdown 相比，代理更不容易对 JSON 测试定义进行不当修改。结构化的格式有助于代理专注于实现工作，而非重新定义成功标准。

何时使用 Ralph

适合场景：

• 需要自动验证的任务（测试、Linter、类型检查）
• 任务定义清晰、成功标准明确
• 绿色开发项目，您可以随时退出
• 迭代式优化（确保测试不断通过）

不适用场景：

• 需要人工判断的任务
• 一次性操作
• 成功标准不明确
• 生产环境调试

工作原理

┌─────────────────────────────────────────────────────────────┐
│                                                             │
│   ┌──────────┐    同样的提示词    ┌──────────┐              │
│   │          │ ───────────────▶  │          │              │
│   │  ralph   │                   │ AI 代理 │              │
│   │  CLI    │ ◀─────────────── │          │              │
│   │          │  输出 + 文件  │          │              │
│   └──────────┘                   └──────────┘              │
│        │                              │                     │
│        │ 检查                        │ 修改                │
│        │ <promise>                    │ 文件                │
│        ▼                              ▼                     │
│   ┌──────────┐                   ┌──────────┐              │
│   │ 完成 │                   │   Git    │              │
│   │  重试   │                   │  仓库    │              │
│   └──────────┘                   └──────────┘              │
│                                                             │
└─────────────────────────────────────────────────────────────┘

1. Ralph 将您的提示词发送给选定的代理
2. 代理开始执行任务，并修改相关文件
3. Ralph 检查输出结果，以确认是否满足完成承诺
4. 若未达到预期，重复使用相同的提示词
5. AI 会查看文件中之前已完成的工作
6. 循环直至成功或达到最大迭代次数

项目结构

ralph-wiggum/
├── bin/ralph.js                  # CLI 入口点（npm 包装器）
├── ralph.ts                      # 主循环实现
├── package.json                  # 包配置
├── install.sh / install.ps1     # 安装脚本
└── uninstall.sh / uninstall.ps1 # 卸载脚本

状态文件（位于 .ralph/ 目录下）

在运行过程中，Ralph 会将状态存储于 .ralph/ 目录中：

• ralph-loop.state.json — 活跃循环状态
• ralph-history.json — 迭代历史与指标
• ralph-context.md — 下一次迭代的待处理上下文
• ralph-tasks.md — 任务模式下的任务列表（在使用 --tasks 参数时生成）
• ralph-questions.json — 用户对客服人员问题的待处理回答

卸载

npm uninstall -g @th0rgal/ralph-wiggum

npm uninstall -g @th0rgal/ralph-wiggum

代理特定注意事项

Claude Code

Claude Code 是 Anthropic 为 Claude 提供的官方命令行工具。将其与 Open Ralph Wiggum 结合使用，可实现强大的自主代码编写功能：

ralph "重构身份验证模块，并确保测试通过" \
  --agent claude-code \
  --model claude-sonnet-4 \
  --max-iterations 15

OpenAI Codex

Codex 是 OpenAI 专为代码开发设计的代理工具，非常适合用于代码生成与重构任务：

ralph "为所有实用函数生成单元测试" \
  --agent codex \
  --model gpt-5-codex \
  --max-iterations 10

OpenCode

OpenCode 是一款开源的 AI 编码助手，也是默认的代理工具：

ralph "修复所有 TypeScript 错误" --max-iterations 10

Copilot CLI

Copilot CLI 是 GitHub 的代理式代码生成工具（公测版）。使用该工具需订阅 GitHub Copilot 并通过 GH_TOKEN、GITHUB_TOKEN 或先前的 copilot /login 进行身份验证。

安装：

npm install -g @github/copilot
# 或
brew install copilot-cli

使用方法：

ralph "重构身份验证模块并添加测试" \
  --agent copilot \
  --max-iterations 15

# 使用特定模型
ralph "构建 REST API" \
  --agent copilot \
  --model claude-opus-4.6 \
  --max-iterations 10

注意事项：

• 默认模型为 Claude Sonnet 4.5；可通过 --model 参数进行覆盖。
• --allow-all（默认值）等同于 Copilot CLI 中的 --allow-all + --no-ask-user。
• --no-plugins 在 Copilot CLI 中无任何效果。
• 身份验证：需设置环境变量 GH_TOKEN 或 GITHUB_TOKEN，或先运行 copilot /login。

代理轮换

代理轮换功能允许您在多次迭代中交替使用不同的代理/模型组合。这一功能非常适用于充分利用不同模型的优势，或对比它们在某项任务中的表现。

格式

每次轮换条目均采用 agent:model 的格式：

--rotation "agent1:model1,agent2:model2,agent3:model3"

有效代理： opencode、claude-code、codex、copilot

示例用法

# 在 OpenCode 和 Claude Code 之间切换
ralph "构建 REST API" \
  --rotation "opencode:claude-sonnet-4,claude-code:claude-sonnet-4" \
  --max-iterations 10

# 在三种不同配置间循环切换
ralph "重构身份验证模块" \
  --rotation "opencode:claude-sonnet-4,claude-code:claude-sonnet-4,codex:gpt-5-codex" \
  --max-iterations 15

# 在轮换中加入 Copilot
ralph "构建 REST API" \
  --rotation "opencode:claude-sonnet-4,copilot:claude-sonnet-4" \
  --max-iterations 10

标志交互

当使用 --rotation 时，--agent 和 --model 标志会被 忽略。轮换列表将优先作为代理/模型选择的依据。

循环行为

当轮换到达末尾后，循环会回到第一个条目：

• 第 1 次迭代 → 第 1 个条目
• 第 2 次迭代 → 第 2 个条目
• 第 3 次迭代 → 第 1 个条目（循环往复，形成 2 个条目的轮换）
• ……以此类推

错误提示

无效的轮换条目会显示清晰的错误信息：

无效的代理名称：

Error: 无效的代理 'invalid' 在轮换条目 'invalid:model' 中。有效代理：opencode、claude-code、codex、copilot

格式不正确（缺少冒号）：

Error: 无效的轮换条目 'opencode-model'。应遵循以下格式：agent:model

空值：

Error: 无效的轮换条目 'opencode:'。代理和模型都必须填写。

状态显示

当使用 --status 启动活跃轮换时，输出会显示所有轮换条目，并标记当前的轮换条目：

🔄 ACTIVE LOOP
   迭代：    3 / 10
   提示：       构建 REST API...

   轮换（位置 1/2）：
   1. opencode:claude-sonnet-4  **ACTIVE**
   2. claude-code:claude-sonnet-4

迭代历史

--status 命令会显示每次迭代所使用的代理和模型：

📊 HISTORY (3 次迭代)
   总耗时：   5 分 23 秒

   最近的迭代：
   #1  2 分 10 秒  opencode / claude-sonnet-4  Bash(5) Write(3) Read(2)
   #2  1 分 45 秒  claude-code / claude-sonnet-4  Edit(4) Bash(3) Read(2)
   #3  1 分 28 秒  opencode / claude-sonnet-4  Bash(2) Edit(1)

了解更多

• Geoffrey Huntley 原创的 Ralph Wiggum 技术
• Ralph Orchestrator

参考链接

欢迎查看 🏝️ sandboxed.sh — 一个用于协调 AI 代理、管理工作区、实时监控以及多代理工作流的仪表盘。

许可证

MIT

Open Ralph Wiggum 快速上手指南

Open Ralph Wiggum 是一个基于"Ralph Wiggum 技术”的自主代理循环工具。它通过让 AI 编程助手（如 Claude Code、Codex、Copilot CLI 或 OpenCode）反复接收相同的提示，直到任务完成。在每次迭代中，AI 能看到之前的代码变更和 Git 历史，从而实现自我修正和增量开发。

环境准备

在开始之前，请确保您的系统满足以下要求：

1. 运行时环境

必须安装 Bun 运行时：

# macOS/Linux
curl -fsSL https://bun.sh/install | bash

# Windows (PowerShell)
powershell -c "irm bun.sh/install.ps1 | iex"

2. AI 编程助手 CLI

您至少需要安装以下任意一个 AI 编程助手的命令行工具，并确保它们已在系统路径中可用：

• Claude Code: Anthropic 的官方 CLI
• Codex: OpenAI 的 Codex CLI
• Copilot CLI: GitHub Copilot CLI
• OpenCode: 开源 AI 编程助手（默认选项）

注意：请根据您选择的 Agent 提前完成对应的账号认证和配置（例如 claude login 或 copilot auth）。

安装步骤

推荐使用 npm 或 Bun 进行全局安装：

方式一：使用 npm（推荐）

npm install -g @th0rgal/ralph-wiggum

方式二：使用 Bun

bun add -g @th0rgal/ralph-wiggum

方式三：从源码安装

git clone https://github.com/Th0rgal/open-ralph-wiggum
cd open-ralph-wiggum
./install.sh
# Windows 用户请使用: .\install.ps1

安装完成后，您可以在终端直接使用 ralph 命令。

基本使用

1. 运行一个简单的任务

最基本的用法是直接传入任务描述。默认情况下，它会使用 OpenCode 作为代理，并持续运行直到检测到完成信号（默认为 <promise>COMPLETE</promise>）。

ralph "Create a hello.txt file with 'Hello World'. Output <promise>DONE</promise> when complete." --max-iterations 5

2. 切换不同的 AI 代理

使用 --agent 参数可以轻松切换底层使用的 AI 工具：

使用 Claude Code:

ralph "Build a REST API for todos with CRUD operations and tests. Run tests after each change. Output <promise>COMPLETE</promise> when all tests pass." --agent claude-code --max-iterations 20

使用 OpenAI Codex:

ralph "Create a CLI tool" --agent codex --max-iterations 10

使用 GitHub Copilot CLI:

ralph "Refactor the auth module" --agent copilot --max-iterations 10

3. 启用任务模式 (Tasks Mode)

对于复杂项目，可以使用 --tasks 模式将大目标拆解为小任务。Ralph 会自动管理 .ralph/ralph-tasks.md 文件，逐个完成任务。

ralph "Build a full-stack web application with user auth and database" --tasks --max-iterations 50

在此模式下，当 AI 输出 <promise>READY_FOR_NEXT_TASK</promise> 时，会自动进入下一个子任务。

4. 监控与干预

您可以在另一个终端窗口监控运行状态或注入新的上下文提示，而无需停止循环：

查看当前状态：

ralph --status

在运行中注入提示（例如指导修复方向）：

ralph --add-context "Focus on fixing the auth module first"

常用参数速查

• --agent [name]: 指定代理 (opencode, claude-code, codex, copilot)
• --max-iterations N: 最大迭代次数
• --completion-promise TEXT: 自定义完成信号文本
• --tasks: 开启任务管理模式
• --model MODEL: 指定具体模型版本