Ralph Loop (Agent Mode)

Ralph Loop

概述

本技能指导 OpenClaw agents 使用 exec 和 process 工具执行 Ralph Loop 工作流。Agent 按照 Ralph playbook 流程编排 AI 编码 Agent 会话：

1) 定义需求 → JTBD → 聚焦主题 → 生成/更新 specs/*.md  
2) PLANNING 循环 → 创建或更新 IMPLEMENTATION_PLAN.md（仅规划，不实现）  
3) BUILDING 循环 → 实现任务、运行测试（引入反压机制）、更新计划、提交变更

该循环通过 PROMPT.md + AGENTS.md（每次迭代均加载）以及磁盘上的计划与规格文件持续维护上下文。

本技能的工作原理

本技能为 OpenClaw agents 生成执行 Ralph Loop 的指令，依赖 exec 和 process 工具：

• Agent 调用 exec 工具并传入编码 Agent 命令；
• 设置 pty: true 以提供 TTY 支持，满足交互式 CLI 需求；
• 设置 background: true 以启用后台执行与监控能力；
• 使用 process 工具监控进程状态并检测完成信号。

重要提示：用户无需手动运行这些脚本——全部由 OpenClaw agent 利用其内置工具能力自动执行。

Agent 工具使用模式

交互式 CLI（推荐模式）

适用于 OpenCode、Codex、Claude Code、Pi 和 Goose 等需 TTY 支持的编码 Agent：

当我在（作为 Agent）收到 Ralph Loop 请求时，我将执行以下操作：

1. 使用 exec 工具启动编码 Agent：

   exec 工具参数：  
   - command: "opencode run --model\"$(cat PROMPT.md)\""  
   - workdir:- background: true  
   - pty: true  
   - yieldMs: 60000  
   - timeout: 3600

2. 从 exec 工具响应中捕获 session ID

3. 使用 process 工具进行监控：

   process 工具参数：  
   - action: "poll"  
   - sessionId:process 工具参数：  
   - action: "log"  
   - sessionId:- offset: -30  （获取最近 30 行输出）

4. 通过读取 IMPLEMENTATION_PLAN.md 中的标记文本判断是否完成

5. 如需清理，调用 process 工具终止进程：

   process 工具参数：  
   - action: "kill"  
   - sessionId:

优势：支持 TTY、实时日志输出、超时控制、并行会话、工作目录隔离

Agent 工具使用的详细示例

示例 1：OpenCode Ralph Loop

Agent 执行如下序列：

步骤 1：使用 exec 工具启动 OpenCode  
{  
  command: "opencode run --model github-copilot/claude-opus-4.5 \"$(cat PROMPT.md)\"",  
  workdir: "/path/to/project",  
  background: true,  
  pty: true,  
  timeout: 3600,  
  yieldMs: 60000  
}  

步骤 2：从响应中提取 session ID  
sessionId: "abc123"  

步骤 3：每 10–30 秒调用一次 process 工具轮询状态  
{  
  action: "poll",  
  sessionId: "abc123"  
}  

步骤 4：检查最近日志输出  
{  
  action: "log",  
  sessionId: "abc123",  
  offset: -30  
}  

步骤 5：读取 IMPLEMENTATION_PLAN.md 判断完成状态  
- 查找标记文本："STATUS: COMPLETE" 或 "STATUS: PLANNING_COMPLETE"  

步骤 6：若已完成或超时，则执行清理  
{  
  action: "kill",  
  sessionId: "abc123"  
}

示例 2：Codex 全自动模式（Full Auto）

Agent 工具调用如下：

exec 工具：  
{  
  command: "codex exec --full-auto --model anthropic/claude-opus-4 \"$(cat PROMPT.md)\"",  
  workdir: "/path/to/project",  
  background: true,  
  pty: true,  
  timeout: 3600  
}  

# 后续使用 process 工具监控（同上）

安全性与防护机制

自动批准标志（高风险！）

• Codex：--full-auto（沙箱内自动批准）或 --yolo（无沙箱！）
• Claude：--dangerously-skip-permissions
• 建议：始终使用沙箱（Docker / E2B / Fly）并限制凭证权限

应急逃生通道

• 中断执行：Ctrl+C
• 终止会话：process 工具调用 action: "kill"
• 回滚变更：git reset --hard HEAD~N

最佳实践

1. 从小开始：先测试 1–2 轮迭代；
2. 工作目录隔离：防止读取无关文件；
3. 设置合理超时：默认 1 小时可能不适用于所有任务；
4. 主动监控：定期检查日志，避免过早终止；
5. 先明确需求：在构建前确保 specs/*.md 清晰完整；
6. 尽早引入反压：从项目初期即添加测试用例。

许可证

MIT

致谢

本技能基于以下贡献者的工作构建：

• @jordyvandomselaar — Ralph Loop 原始概念与工作流设计
• @steipete — 编码 Agent 使用模式及带 pty 支持的 exec/process 工具实践

关键改进：采用 OpenClaw 的 exec 工具并启用 pty: true，为交互式 CLI 提供完整 TTY 支持，彻底解决传统后台 Bash 执行导致的挂起问题。