Coding Agent Loops

编码智能体循环（Coding Agent Loops）

在持久化、自愈式会话中运行 AI 编码智能体，支持自动重试与完成通知。

核心理念

摒弃单次长时智能体会话（易卡顿或意外终止），转而采用多次短时会话循环执行。每次迭代均从干净状态启动——无累积上下文。智能体通过文件系统和 Git 历史记录恢复进度。此即“Ralph 循环”（Ralph loop）模式。

前置条件

• 已安装 tmux
• 已全局安装 ralphy-cli：npm install -g ralphy-cli
• 已配置编码智能体：codex（Codex CLI）或 claude（Claude Code）
• 使用稳定的 tmux socket 路径：始终指定 ~/.tmux/sock（默认的 /tmp socket 在 macOS 上可能被系统自动清理）

快速开始

单任务执行

tmux -S ~/.tmux/sock new -d -s my-task \
  "cd /path/to/repo && ralphy --codex 'Fix the authentication bug'; \
   EXIT_CODE=$?; echo EXITED: $EXIT_CODE; \
   openclaw system event --text 'Ralph loop my-task finished (exit $EXIT_CODE) in $(pwd)' --mode now; \
   sleep 999999"

基于 PRD 的工作流（推荐用于多步骤任务）

tmux -S ~/.tmux/sock new -d -s feature-build \
  "cd /path/to/repo && ralphy --codex --prd PRD.md; \
   EXIT_CODE=$?; echo EXITED: $EXIT_CODE; \
   openclaw system event --text 'Ralph loop feature-build finished (exit $EXIT_CODE) in $(pwd)' --mode now; \
   sleep 999999"

并行执行多个智能体（处理不同任务）

ralphy --codex --parallel --prd PRD.md

会话管理

查看进度

tmux -S ~/.tmux/sock capture-pane -t my-task -p | tail -20

列出活跃会话

tmux -S ~/.tmux/sock list-sessions

终止指定会话

tmux -S ~/.tmux/sock kill-session -t my-task

完成钩子（Completion Hook，必需）

所有 tmux 命令末尾必须追加以下钩子：

; EXIT_CODE=$?; echo "EXITED: $EXIT_CODE"; \
openclaw system event --text "Ralph loopfinished (exit $EXIT_CODE) in $(pwd)" --mode now; \
sleep 999999

各部分作用说明：

• EXIT_CODE=$? —— 捕获智能体进程退出码
• echo "EXITED: $EXIT_CODE" —— 在 tmux pane 输出中可见，便于人工核查
• openclaw system event —— 触发唤醒事件，确保 OpenClaw 实时向你推送完成通知
• sleep 999999 —— 保持 shell 进程存活，使输出持续可读

PRD 文件格式

Ralph 通过 Markdown 复选框追踪任务完成状态：

## Tasks
- [ ] Create the API endpoint
- [ ] Add input validation
- [ ] Write tests
- [x] Already done (skipped)

Ralph 仅在 PRD 中所有复选框均被勾选（[x]）后，才接受智能体发出的完成信号。

场景与工具选型指南

关键原则

1. 始终使用 tmux —— 后台执行的普通进程会在网关或宿主机重启后丢失；tmux 会话具备持久性。
2. 始终使用稳定 socket 路径（~/.tmux/sock）—— 默认 /tmp 下的 socket 可能被系统定期清理。
3. 始终添加完成钩子 —— 缺少该钩子将导致你无法获知智能体是否已完成。
4. 记录活跃会话 —— 将正在运行的会话名称记入每日笔记或专用跟踪文件，避免遗忘或失控。
5. 判定失败前务必验证 —— 进程结束后，应先检查 git log、git diff 及终端输出，再确认是否真正失败。
6. 注意 tmux 中的 PATH 环境变量 —— tmux 可能未继承完整的用户 PATH。若工具（如 codex）无法识别，请在命令前显式添加路径前缀，例如：/opt/homebrew/bin:...

故障排查

• 智能体立即退出：检查 ~/.codex/log/codex-tui.log 是否存在认证错误；必要时执行 codex auth login。
• Ralph 显示任务完成但无任何提交：Ralph 可能在智能体静默失败时仍标记 PRD 项为完成。请始终通过 git log --oneline -3 和 git diff --stat 手动验证变更。
• API 请求频率超限（HTTP 429）：多智能体并行运行时常见。Ralph 内置重试机制可缓解，但若问题持续，请降低并行度。
• 会话意外消失：tmux 会话可能因内存溢出（OOM）或系统重启而终止。可用 tmux -S ~/.tmux/sock has-session -t 检查存在性，并按需重启。