Ralph 循环（事件驱动型）

增强版 Ralph 模式，采用 事件驱动通知机制 —— Codex/Claude 在需要关注时主动调用 OpenClaw，而非轮询。

核心概念

干净的会话（Clean Sessions）

每次迭代均启动一个 全新的代理会话（fresh agent session），上下文完全清空。这是有意为之的设计：

• 规避上下文窗口长度限制
• 每次 codex exec 均为独立进程，不保留此前任何运行记录
• 状态通过文件持久化：如 IMPLEMENTATION_PLAN.md、AGENTS.md 及 git 历史

基于文件的通知回退机制（File-Based Notification Fallback）

若 Codex 发送唤醒通知时 OpenClaw 遭遇限流：

1. 该通知将写入 .ralph/pending-notification.txt
2. 尝试唤醒（可能失败）
3. OpenClaw 恢复后，自动检查是否存在待处理通知
4. 工作永不丢失 —— 所有内容均保存在 git 或文件中

文件结构

project/
├── PROMPT.md                      # 每次迭代加载（按模式区分）
├── 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 — 唤醒成功

OpenClaw 故障恢复流程

在遭遇限流或服务中断后重新上线时，务必检查是否存在待处理通知：

# 在所有项目中查找 pending-notification.txt
find ~/projects -name "pending-notification.txt" -path "*/.ralph/*" 2>/dev/null

# 或检查指定项目
cat /path/to/project/.ralph/pending-notification.txt

按消息前缀执行恢复操作

注入人工响应

为下一轮迭代提供决策/问题的答案：

echo "## Human Decisions
- [$(date '+%Y-%m-%d %H:%M')] Q: ? A: " >> AGENTS.md

下一次 Codex 会话将读取 AGENTS.md 并识别该答案。

清除通知

处理完通知后，请及时清除：

mv .ralph/pending-notification.txt .ralph/last-notification.txt

工作流

1. 收集需求

若未提供，则需主动询问以下信息：

• 目标 / JTBD（Jobs To Be Done）：期望达成何种成果？
• CLI 工具：codex、claude、opencode、goose
• 运行模式：PLANNING、BUILDING 或 BOTH
• 技术栈：编程语言、框架、数据库等
• 测试命令：如何验证实现正确性
• 最大迭代次数：默认为 20

2. 生成规格文档（Specs）

将目标拆解为若干 关注主题（topics of concern） → 输出至 specs/*.md：

# specs/overview.md
## Goal
<一句话 JTBD 描述>

## 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（按模式定制）

PLANNING 模式

# Ralph PLANNING 循环

## Goal


## Context
- 阅读：specs/*.md
- 阅读：当前代码库结构
- 更新：IMPLEMENTATION_PLAN.md

## Rules
1. 禁止编写代码
2. 禁止提交变更
3. 分析规格与现状之间的差距
4. 创建/更新 IMPLEMENTATION_PLAN.md，列出优先级明确的任务
5. 每项任务应足够小（≤ 1 小时工作量）
6. 若需求不清晰，需列出具体问题

## Notifications
当需要人工输入或规划完成时，调用：
```bash
openclaw gateway wake --text "PLANNING: " --mode now

推荐使用如下前缀：

• DECISION: — 需人工就某项选择做决策
• QUESTION: — 需求表述不清
• DONE: — 规划已完成

完成标志

当规划完成且已准备好进入构建阶段，在 IMPLEMENTATION_PLAN.md 中添加：

STATUS: PLANNING_COMPLETE

随后发送通知：

openclaw gateway wake --text "DONE: Planning complete. X tasks identified." --mode now

#### BUILDING 模式

```markdown
# Ralph BUILDING 循环

## Goal


## Context
- 阅读：specs/*.md、IMPLEMENTATION_PLAN.md、AGENTS.md
- 实现：每次迭代仅处理一项任务
- 测试：执行 AGENTS.md 中定义的 backpressure 命令

## Rules
1. 从 IMPLEMENTATION_PLAN.md 中选取最高优先级且尚未完成的任务
2. 修改前先调研相关代码
3. 实现该任务
4. 运行 backpressure 命令（lint、test）
5. 若测试通过：以清晰信息提交变更，并标记任务为已完成
6. 若测试失败：最多尝试修复 3 次，之后发出通知
7. 在 AGENTS.md 中更新任何操作性经验
8. 在 IMPLEMENTATION_PLAN.md 中更新进度

## Notifications
需要时调用 OpenClaw：
```bash
openclaw gateway wake --text ": " --mode now

前缀说明：

• DECISION: — 需人工输入（例如：“SQLite 还是 PostgreSQL？”）
• ERROR: — 经过 3 次尝试后测试仍失败
• BLOCKED: — 缺失依赖、凭证或规格描述不清
• PROGRESS: — 完成重大里程碑（可选）
• DONE: — 所有任务均已完工

完成标志

当所有任务均完成时：

1. 在 IMPLEMENTATION_PLAN.md 中添加：STATUS: COMPLETE
2. 发送通知：

openclaw gateway wake --text "DONE: All tasks complete. Summary: " --mode now

### 5. 启动循环

使用提供的脚本 scripts/ralph.sh：

```bash
# 默认：使用 Codex 执行 20 次迭代
./scripts/ralph.sh 20

# 使用 Claude Code
RALPH_CLI=claude ./scripts/ralph.sh 10

# 启用测试
RALPH_TEST="pytest" ./scripts/ralph.sh

并行执行

对于相互独立的任务，可使用 git worktree：

# 创建多个 worktree 以支持并行开发
git worktree add /tmp/task-auth main
git worktree add /tmp/task-upload main

# 启动并行会话（每个会话均为干净、独立环境）
exec pty:true background:true workdir:/tmp/task-auth command:"codex exec --full-auto 'Implement user authentication...'"
exec pty:true background:true workdir:/tmp/task-upload command:"codex exec --full-auto 'Implement image upload...'"

会话跟踪表：

各 Codex 实例独立发送通知。请分别检查各 worktree 下的 .ralph/pending-notification.txt。

CLI 工具专用说明

Codex

• 要求项目位于 git 仓库中
• 每次 codex exec 均为全新会话 —— 各次调用之间无状态共享
• --full-auto：在 workspace（沙箱环境）中自动批准
• --yolo：禁用沙箱、跳过审批（高风险但高效）
• 默认模型：gpt-5.2-codex

Claude Code

• --dangerously-skip-permissions：自动批准（建议仅在沙箱中使用）
• 不要求 git 仓库
• 每次调用均为全新会话

OpenCode

• opencode run "$(cat PROMPT.md)"

Goose

• goose run "$(cat PROMPT.md)"

安全须知

⚠️ 自动批准参数具有高风险。请始终遵守以下原则：

1. 在专用目录或分支中运行
2. 对不可信项目使用沙箱（Docker/VM）
3. 随时准备执行 git reset --hard 作为紧急逃生手段
4. 推送前务必人工审查所有提交

快速开始

# 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 << 'EOF'
## Goal
Build a web app that...

## Tech Stack
- Python 3.11 + FastAPI
- SQLite
- HTMX + Tailwind

## Features
1. Feature one
2. Feature two
EOF

# 4. 编辑 PROMPT.md，填入您的具体目标

# 5. 启动 Ralph 循环
./ralph.sh 20

示例：古董目录系统

# specs/overview.md
## Goal
用于管理古董物品元数据、图片与分类的 Web 应用。

## Tech Stack
- Python 3.11 + FastAPI
- SQLite + SQLAlchemy
- HTMX + Tailwind CSS
- 图片本地文件存储

## Features
1. 物品 CRUD（名称、描述、年代、购买信息、尺寸）
2. 图片上传（每件物品支持多张图片）
3. 标签与分类管理
4. 搜索与筛选功能
5. 多种视图模式（网格、列表、详情）

Agent 将执行以下步骤：

1. （PLANNING 阶段）将上述需求拆解为 10–15 个子任务
2. （BUILDING 阶段）每次迭代实现一个子任务
3. 每次成功实现后提交变更
4. 完成或受阻时主动发出通知