正文内容
Ralph Loop（事件驱动）
增强版 Ralph 模式，采用 事件驱动通知机制 —— Codex/Claude 在需要人工关注时主动调用 OpenClaw，而非轮询。
核心概念
清洁会话（Clean Sessions）
每次迭代均启动一个全新的代理会话，上下文完全干净。这是有意为之的设计：
- 避免上下文窗口长度限制
- 每次
codex exec均为独立进程，不保留此前运行的任何记忆 - 记忆通过文件持久化：
IMPLEMENTATION_PLAN.md、AGENTS.md、Git 历史记录
基于文件的通知回退机制（File-Based Notification Fallback）
若 Codex 发送唤醒通知时 OpenClaw 遭遇限流：
- 该通知将被写入
.ralph/pending-notification.txt - 尝试执行唤醒（可能失败）
- 当 OpenClaw 恢复后，自动检查是否存在待处理通知
- 工作永不丢失 —— 所有状态均保存在 Git 或文件中
文件结构
project/ ├── PROMPT.md # 每次迭代加载（按 mode 区分） ├── AGENTS.md # 项目上下文、测试命令、经验总结 ├── IMPLEMENTATION_PLAN.md # 含状态的任务清单 ├── specs/ # 需求规格说明 │ ├── overview.md │ └──.md └── .ralph/ ├── ralph.log # 执行日志 ├── pending-notification.txt # 当前待处理通知（如有） └── last-notification.txt # 上一次通知（供参考）
通知格式
.ralph/pending-notification.txt 示例：
{
"timestamp": "2026-02-07T02:30:00+01:00",
"project": "/home/user/my-project",
"message": "DONE: All tasks complete.",
"iteration": 15,
"max_iterations": 20,
"cli": "codex",
"status": "pending"
}
status 取值说明：
-
pending— 唤醒失败或尚未尝试 -
delivered— 唤醒成功
工作流程
1. 收集需求
如未提供，需主动询问以下信息：
- 目标 / JTBD（Jobs To Be Done）：期望达成何种结果？
-
CLI 工具：
codex、claude、opencode或goose -
模式（Mode）：
PLANNING、BUILDING或BOTH - 技术栈：编程语言、框架、数据库等
- 验证命令（Test command）：如何确认实现正确性
- 最大迭代次数（Max iterations）：默认为 20
2. 生成规格文档（Specs）
将目标拆解为若干 关注主题（topics of concern） → 输出至 specs/*.md：
# specs/overview.md ## Goal ## Tech Stack - Language: Python 3.11 - Framework: FastAPI - Database: SQLite - Frontend: HTMX + Tailwind ## Success Criteria - [ ] Criterion 1 - [ ] Criterion 2
3. 生成 AGENTS.md
# AGENTS.md ## Project ## Commands - **Install**: `pip install -e .` - **Test**: `pytest` - **Lint**: `ruff check .` - **Run**: `python -m app` ## Backpressure 每次实现后需执行： 1. `ruff check . --fix` 2. `pytest` ## Human Decisions ## Learnings
4. 生成 PROMPT.md（按 Mode 定制）
PLANNING 模式
# Ralph PLANNING Loop ## Goal## Context - 阅读：specs/*.md - 阅读：当前代码库结构 - 更新：IMPLEMENTATION_PLAN.md ## Rules 1. 禁止编写实现代码 2. 禁止提交（commit） 3. 分析规格与当前状态之间的差距 4. 创建/更新 IMPLEMENTATION_PLAN.md，列出优先级明确的任务 5. 每项任务应足够小（≤ 1 小时工作量） 6. 若需求不明确，列出待澄清问题 ## Notifications 当需要人工输入或规划完成时，调用：
openclaw gateway wake --text "PLANNING:
支持前缀： - `DECISION:` — 需人类对某项选择做决定 - `QUESTION:` — 需求不清晰，需进一步澄清 - `DONE:` — 规划已完成 ## Completion 当计划完备且可进入构建阶段时，在 IMPLEMENTATION_PLAN.md 中添加：
STATUS: PLANNING_COMPLETE
随后通知：
openclaw gateway wake --text "DONE: Planning complete. X tasks identified." --mode now
BUILDING 模式
# Ralph BUILDING Loop ## Goal## Context - 阅读：specs/*.md、IMPLEMENTATION_PLAN.md、AGENTS.md - 实现：每次迭代仅完成一项任务 - 测试：执行 AGENTS.md 中定义的 backpressure 命令 ## Rules 1. 从 IMPLEMENTATION_PLAN.md 中选取最高优先级的未完成任务 2. 修改前先调研相关代码 3. 实现该任务 4. 运行 backpressure 命令（lint、test） 5. 若测试通过：以清晰信息提交（commit），并标记任务为完成 6. 若测试失败：最多尝试修复 3 次；失败后立即通知 7. 在 AGENTS.md 中记录任何新的操作性经验 8. 在 IMPLEMENTATION_PLAN.md 中更新进度 ## Notifications 按需调用 OpenClaw：
openclaw gateway wake --text "
前缀说明： - `DECISION:` — 需人类输入（例如：“SQLite vs PostgreSQL？”） - `ERROR:` — 经过 3 次尝试后测试仍失败 - `BLOCKED:` — 缺失依赖、凭据或规格不明确 - `PROGRESS:` — 达成重要里程碑（可选） - `DONE:` — 所有任务均已完工 ## Completion 当所有任务完成时： 1. 在 IMPLEMENTATION_PLAN.md 中添加：`STATUS: COMPLETE` 2. 发送通知：
openclaw gateway wake --text "DONE: All tasks complete. Summary:
5. 运行循环
使用提供的 scripts/ralph.sh 脚本：
# 默认：20 次迭代，使用 Codex ./scripts/ralph.sh 20 # 使用 Claude Code RALPH_CLI=claude ./scripts/ralph.sh 10 # 启用测试（通过 RALPH_TEST 指定命令） RALPH_TEST="pytest" ./scripts/ralph.sh
CLI 工具特异性说明
Codex
- 要求项目为 Git 仓库
-
每次
codex exec均为全新会话 —— 调用间无状态共享 -
--full-auto：在 workspace 中自动批准（沙箱环境内安全） -
--yolo：禁用沙箱与审批（危险但快速） - 默认模型：gpt-5.2-codex
Claude Code
-
--dangerously-skip-permissions：自动批准（建议仅用于 sandbox） - 无需 Git 仓库
- 每次调用均为全新会话
OpenCode
opencode run "$(cat PROMPT.md)"
Goose
goose run "$(cat PROMPT.md)"
快速上手
# 1. 创建项目目录 mkdir my-project && cd my-project && git init # 2. 从 skill 复制模板 cp /path/to/ralph-loop/templates/* . mv PROMPT-PLANNING.md PROMPT.md # 3. 创建 specs 目录及概览文件 mkdir specs cat > specs/overview.md示例：古董目录系统（Antique Catalogue）
# specs/overview.md ## Goal 构建一个 Web 应用，用于录入古董物品的元数据、图片和分类信息。 ## Tech Stack - Python 3.11 + FastAPI - SQLite + SQLAlchemy - HTMX + Tailwind CSS - 图片本地文件存储 ## Features 1. 物品 CRUD（名称、描述、年代、购入信息、尺寸） 2. 图片上传（每件物品支持多图） 3. 标签（Tags）与分类（Categories） 4. 搜索与筛选功能 5. 多种视图模式（网格、列表、详情）代理将依次执行：
- （PLANNING 阶段）将需求拆解为 10–15 个可执行任务
- （BUILDING 阶段）每次迭代实现一个任务
- 每次成功实现后提交（commit）
- 完成或受阻时主动通知（wake）