multi-agent-dev
> OpenClaw + Ralph Loop 多智能体协作开发工作流
核心思想：Ralph Loop 是迭代引擎，底层执行器可切换。执行器通过 --agent 参数指定，Skill 顶部统一配置。
⚙️ 配置区（执行器抽象）
# 当前使用的执行器（6选1）
ACTIVE_AGENT: opencode # opencode | claude-code | codex | copilot | cursor-agent | qwen-code
# 执行器对应的二进制命令
AGENT_BINARY: opencode # ralph --agent 使用的名字
AGENT_MODEL: minimax/MiniMax-M2.7 # 默认模型（可覆盖）
# 可选：自定义二进制路径（留空则用 PATH 中的）
#RALPH_OPENCODE_BINARY:
#RALPH_CLAUDE_BINARY:
> 切换执行器：把 ACTIVE_AGENT 改成 claude-code，AGENT_BINARY 改成 claude，模型改成 claude-sonnet-4。
> Ralph 命令格式不变，所有示例自动适配新执行器。
触发条件
触发词（满足任一即可）：
- 含「开发」：协作开发、帮我开发、用 Ralph 开发、多 agent 开发
- 含「研发」：研发模式、研发流程
- 含「编码」：编码、写代码
- 「Ralph Loop」
- 「OpenClaw Ralph 配合」
核心原理
发起任务
↓
OpenClaw（主控大脑，理解意图、协调、记忆）
↓
任务分类决策：
├─ 简单任务（<100行改动）→ OpenClaw 直接执行
├─ 中等任务（多步骤）→ sessions_spawn 子代理
└─ 复杂/迭代任务 → Ralph Loop 自主迭代
↓
Ralph Loop（迭代引擎，底层执行器可切换）
├─ --agent opencode → OpenCode（当前默认）
├─ --agent claude-code → Claude Code
├─ --agent codex → OpenAI Codex
├─ --agent copilot → GitHub Copilot CLI
├─ --agent cursor-agent → Cursor Agent
└─ --agent qwen-code → Qwen Code
↓
Ralph 持续迭代直到 <promise>COMPLETE</promise> 或达上限
↓
结果交付 + 记忆记录
Agent 选择决策树
任务来了
↓
是简单问答/文件读取？
├─ YES → OpenClaw 原生能力执行
└─ NO ↓
需要持续迭代直到达标？
├─ YES → Ralph Loop（用选定的执行器）
└─ NO ↓
sessions_spawn 子代理执行
执行器选择参考
| 执行器 | 优势 | 劣势 | 推荐场景 |
|---|---|---|---|
| opencode | MiniMax/MiniMax-M3 支持好，默认使用 | 插件生态较弱 | 日常开发、Skill 改写 |
| claude-code | Claude 4 系列强，多工具调用 | 需要 Anthropic API Key | 复杂推理、代码审查 |
| codex | GPT-5 支持，OpenAI 生态 | 需要 OpenAI API Key | OpenAI 相关项目 |
| copilot | GitHub 深度集成 | 需要 Copilot 订阅 | GitHub 项目维护 |
| cursor-agent | 上下文感知强 | 需要 Cursor 账号 | Cursor 用户 |
| qwen-code | Qwen 系列强 | 生态较新 | 阿里云/Qwen 项目 |
> 默认使用：opencode（MiniMax 模型已配置好，无需额外 API Key）
Ralph Loop 任务模板
当需要 Ralph Loop 时，使用以下格式生成任务：
## 任务：<任务名称>
### Goal
<一句话描述最终目标>
### Scope
- 包含：<明确范围>
- 不包含：<明确边界>
### Requirements
1. <可测试的需求1>
2. <可测试的需求2>
### Constraints
- 技术栈：<约束>
- 兼容性：<约束>
### Acceptance Criteria
- [ ] <验收项1>
- [ ] <验收项2>
### 完成承诺
<任务完成后，输出以下标记之一>：
- `<promise>COMPLETE</promise>` — 任务成功完成
- `<promise>PARTIAL</promise>` — 部分完成，需要人工介入
Ralph Loop 调用命令
cd <工作目录>
ralph "<任务描述，包含完成承诺>"
--agent {{ACTIVE_AGENT}} # 从配置区读取
--model {{AGENT_MODEL}} # 可选，覆盖默认模型
--max-iterations <最大迭代次数>
--no-plugins # 避免插件冲突
完整示例（OpenCode，当前默认）
cd ~/GitHub/mba-thesis-workflow
ralph "优化 SKILL.md，增加 xxx 章节。完成后输出 <promise>COMPLETE</promise>。"
--agent opencode
--model minimax/MiniMax-M2.7
--max-iterations 5
--no-plugins
Claude Code 示例（切换执行器时）
cd ~/GitHub/my-project
ralph "实现登录功能，包含注册、登录、登出。测试通过后输出 <promise>COMPLETE</promise>。"
--agent claude-code
--model claude-sonnet-4
--max-iterations 10
--no-plugins
Codex 示例
cd ~/GitHub/my-project
ralph "生成所有工具函数的单元测试。完成后输出 <promise>COMPLETE</promise>。"
--agent codex
--model gpt-5-codex
--max-iterations 8
--no-plugins
Agent Rotation（轮换）
Ralph 支持在多次迭代中轮换不同的 agent/model 组合：
ralph "重构认证模块"
--rotation "opencode:minimax/MiniMax-M2.7,claude-code:claude-sonnet-4"
--max-iterations 10
--no-plugins
单次任务模板（不经 Ralph Loop）
适合单次简单执行，不需要迭代：
cd <工作目录>
ralph "<单次任务>"
--agent {{ACTIVE_AGENT}}
--max-iterations 1
--no-plugins
工作目录规范
| 项目类型 | 推荐工作目录 |
|---|---|
| MBA Thesis Workflow | ~/GitHub/mba-thesis-workflow/ |
| Skill 开发 | ~/.openclaw/workspace/skills/<skill-name>/ |
| 其他项目 | ~/GitHub/<project-name>/ |
异常处理
| 异常 | 处理方式 |
|---|---|
| Ralph Loop 超过 max-iterations | 输出部分结果，提示人工介入 <promise>PARTIAL</promise> |
| Agent API Key 失效 | 降级到 OpenClaw 原生执行 |
| TTY 错误 | 使用 --no-plugins + --no-questions 重试 |
| 工作目录不存在 | 自动创建或提示用户确认 |
| 执行器不在 PATH | 设置 RALPH_<AGENT>_BINARY 环境变量 |
最佳实践
1. 任务描述要具体
❌ 模糊：「帮我优化一下 skill」
✅ 具体：「在 ~/.openclaw/skills/xxx/SKILL.md 末尾增加「使用示例」章节，包含2个代码示例」
2. 设置合理的 max-iterations
- 简单任务：3-5次
- 复杂任务：10-15次
- 迭代优化：5-10次
- 保险上限：不超过 20 次
3. Ralph Loop 的好场景
- ✅ Skill 改写、重构
- ✅ 多文件代码生成
- ✅ 测试覆盖优化
- ✅ 文档完善
- ❌ 纯问答、简单查询
- ❌ 需要人工判断的创意任务
4. 多轮迭代技巧
如果 Ralph 在某次迭代后卡住，可以：
1. 在下次迭代时加更多上下文：ralph "<任务> + <上次的失败原因>"
2. 缩小范围，分步完成
3. 改用 sessions_spawn 手动介入
5. 切换执行器
切换执行器时，只需：
1. 改 ACTIVE_AGENT 和 AGENT_BINARY（配置区顶部）
2. 确认对应 API Key 已配置
3. 所有 ralph 命令格式不变，Ralph 自动使用新执行器
协作记忆
任务完成后，简要记录：
- 做了什么改动
- 涉及的文件
- 未完成的事项（如有）
格式：
## [YYYY-MM-DD] multi-agent-dev 任务记录
- 任务：<简述>
- 目录：<工作目录>
- 执行器：<ACTIVE_AGENT>
- 改动：<文件列表>
- Ralph 迭代：<N> 次
- 备注：<如有>
