构建可恢复的AI编码代理工作流：告别上下文遗忘与需求漂移

1. 项目概述：一个能“闭环”的AI编码代理工作流引擎

如果你也受够了AI编码助手那种“三分钟热度”的毛病——聊得好好的，突然就忘了上下文、跑偏了需求，或者干脆在某个任务中间“暴毙”，留下一堆烂摊子让你重启重来——那你来对地方了。openclaw-build不是一个新模型，而是一个解决上述所有痛点的工程化工作流框架。它的核心思想很简单：把一次性的、脆弱的、容易失忆的AI对话，变成一个结构化的、可追溯的、能自动恢复的“生产流水线”。

简单来说，它给你的AI助手（比如Codex、Claude Code）套上了一套项目管理方法论。从你提出一个模糊的想法开始，到最终代码落地，整个过程被清晰地划分为“需求确认”和“构建执行”两个阶段，中间设置了关键的“批准关卡”，确保AI不会在你没点头的情况下乱来。最妙的是，构建阶段被设计成一系列短小、独立、可重启的迭代任务，每个任务都基于一个统一的“需求说明书”（PRD）和项目记忆文件来执行，彻底告别了上下文丢失和需求漂移。

我自己在尝试用AI辅助开发一些中小型工具和API时，被这些问题折磨得不轻。每次都要重新解释需求，看着AI写出似是而非的代码，或者在一个长会话后期开始胡言乱语，效率反而比我自己写还低。openclaw-build的出现，让我终于能把AI当作一个靠谱的、可管理的“初级工程师”来用了，而不是一个随时可能掉线的“天才儿童”。

2. 核心设计哲学：为什么传统的AI编码代理会失败？

在深入细节之前，我们得先搞清楚问题出在哪。直接给AI一个模糊指令然后让它自由发挥，为什么行不通？根据我的实战经验，主要有三大死穴：

2.1 上下文遗忘与污染这是最致命的问题。大多数AI模型的上下文窗口是有限的，而且随着对话轮次增加，早期的重要指令（比如“不要用全局变量”、“必须用TypeScript”）会被逐渐稀释或覆盖。更糟糕的是，AI在生成代码过程中可能会产生大量中间推理、错误尝试的“思维垃圾”，这些垃圾会污染后续的上下文，导致输出质量断崖式下降。openclaw-build的解决方案是“短会话+外部记忆”。每次构建迭代都是一个全新的、干净的会话，但它会先读取外部的.ralphy/progress.txt文件来获取项目历史和学习点，完成任务后再把本次的收获写回去。这样既保持了会话的“纯洁性”，又实现了知识的累积。

2.2 需求漂移与目标丢失你让AI“做一个登录页面”，它可能一开始做了个表单，然后突然开始优化按钮阴影，最后跑去写后端验证逻辑了。这是因为AI缺乏一个持久化的、权威的目标参照物。openclaw-build引入了PRD（产品需求文档）作为单一事实来源。这个PRD.md文件在需求确认阶段由AI和你共同敲定，里面用清晰的复选框（- [ ]）列出了一系列原子任务。构建循环的唯一目标就是勾选所有这些复选框。AI每完成一个任务，就标记一个，永远不会忘记终极目标是什么。

2.3 会话中断与状态丢失网络波动、API限制、进程崩溃，都可能导致一个运行了几个小时的AI会话突然中断。传统方式下，你几乎无法从中断点恢复，因为所有的中间状态都在那个消失的会话里。openclaw-build的构建循环天生就是为可恢复性设计的。每个任务独立执行、独立提交到Git。即使整个进程被杀掉，重启后，它会扫描PRD.md和 Git 日志，自动跳过已完成的（已勾选且已提交）的任务，从第一个未完成的任务开始。这种基于Git和文件系统的状态管理，比依赖易失的会话内存可靠得多。

理解了这些，你就能明白openclaw-build里那些看似繁琐的步骤（比如写PRD、初始化项目记忆、短迭代）都不是官僚主义，而是为了解决这些工程实践中的硬伤而设计的必要约束。

3. 从零开始：完整安装与环境配置指南

纸上谈兵结束，我们开始动手。openclaw-build的安装是一站式的，但前提是它的运行时环境OpenClaw必须就位。下面是我一步步踩过来的配置流程，我会注明每个环节的意图和可能遇到的坑。

3.1 基础依赖安装首先，确保你的系统有Node.js 18+、Git和tmux。tmux是关键，因为它允许我们在后台运行长时间的构建会话而不怕SSH断开。

# 在 Ubuntu/Debian 上 sudo apt update sudo apt install -y nodejs git tmux # 在 macOS 上 brew install node git tmux

注意：ralphy（构建循环运行器）是一个Node全局包，所以Node.js版本不能太老，否则可能安装失败。

3.2 安装 OpenClaw 运行时这是openclaw-build的基石，负责系统事件、通信通道等底层功能。按照官方的一键脚本安装通常很顺利：

curl -fsSL https://openclaw.ai/install.sh | bash

安装完成后，务必执行一次 onboarding 流程。通常脚本会提示你，或者你需要手动运行openclaw onboard。这个过程会引导你配置AI引擎（如Codex、Claude）的API密钥和通信渠道（如Slack、Discord）。我强烈建议即使你主要用CLI，也至少配置一个通知渠道（比如Slack），这样当构建完成或出错时，你能及时收到提醒。

3.3 安装 openclaw-build 本体现在可以安装主角了：

curl -fsSL https://raw.githubusercontent.com/bkochavy/openclaw-build/main/install.sh | bash

这个脚本会做几件事：

1. 克隆openclaw-build仓库到本地。
2. 将必要的工具脚本链接到你的PATH中（比如ralphy的包装器）。
3. 安装ralphy-cli这个核心的Node包。

安装完成后，在终端输入ralphy --help，如果能看到一长串命令说明，就证明安装成功了。

3.4 配置你的AI引擎后端openclaw-build本身不生成代码，它是指挥官，需要士兵。你需要至少配置一个“士兵”：

• Codex (推荐用于后端/逻辑)：如果你用OpenAI的模型，你需要安装并配置codexCLI。通常需要pip install codex-cli然后codex auth login。关键一步是编辑~/.codex/config.toml，确保设置了model_reasoning_effort = "high"，这样才能让Codex进行深度思考。
• Claude Code (推荐用于前端/UI)：如果你用Anthropic的Claude，需要相应的CLI工具。注意，Claude的“高努力度”模式无法持久化在配置文件中，必须在每次调用时通过-- --effort high参数显式指定，这是一个容易忘记的坑。

3.5 验证安装运行一个简单的健康检查：

# 检查 openclaw 是否就绪 openclaw --version # 检查 ralphy 是否就绪 ralphy --version # 尝试让AI做一个微型自检（需要引擎已配置） echo "Write a hello world function in Python." > test_task.txt # 注意：这里只是演示命令格式，实际需要更完整的PRD

如果以上步骤都没报错，那么你的openclaw-build作战平台就已经搭建完毕，可以投入使用了。

4. 实战演练：构建一个完整的速率限制API

光说不练假把式。我们用一个真实的例子贯穿始终：构建一个带Redis缓存的API速率限制中间件。我会展示从“一句话需求”到“代码落地”的全过程。

4.1 第一阶段：需求访谈与PRD生成这是控制AI不跑偏的第一道闸门。我们通过OpenClaw向AI代理发出指令。

你（通过Slack/CLI）：@openclaw spec a rate limiting API endpoint with Redis for a Node.js Express app. Limit by IP, 100 requests per minute.

AI代理不会立刻开始写代码，它会启动一个访谈流程：

1. 理解与复述：AI会先复述你的需求：“您想要一个用于Node.js Express应用的API速率限制中间件，使用Redis存储计数，基于IP地址限制，频率是每分钟100次请求。对吗？”
2. 澄清问题：接着，AI会提出一系列关键问题，通常以投票选择形式呈现，确保需求无歧义：
   • “超出限制后，返回什么HTTP状态码？429 Too Many Requests 还是 503 Service Unavailable？”
   • “是否需要在响应头中返回剩余请求数（X-RateLimit-Remaining）和重置时间（X-RateLimit-Reset）？”
   • “Redis连接失败时，中间件应该直接报错阻断请求，还是降级为无限制模式？”
   • “需要支持不同的时间窗口吗？比如同时支持每秒、每分钟、每小时限制？”
3. 架构计划：在你回答完问题后，AI会总结并给出一个技术实现方案，比如：“我将使用express-rate-limit库作为基础，搭配redis存储。项目结构将包含中间件文件、Redis配置工厂、以及单元测试。” 这时，你会收到第一个批准关卡（Gate 1）的请求。你必须明确批准（例如回复“批准”），AI才会进入下一步。

批准后，AI会在当前目录下创建projects/rate-limiter/PRD.md文件，并生成一份详细的、包含任务清单的需求文档。完成后，你会看到第二个批准关卡（Gate 2），即对这份PRD的最终确认。只有你再次批准，构建流程才会自动启动，或者你可以选择手动启动。

4.2 解读生成的PRD.md让我们看看AI生成的PRD.md可能长什么样。这是整个项目的蓝图。

# Rate Limiter API Middleware ## Overview Build a Redis-backed rate limiting middleware for Express.js, limiting 100 requests per minute per IP. ## Tasks - [ ] Initialize npm project with TypeScript configuration. - [ ] Install dependencies: express, redis, express-rate-limit, @types/... - [ ] Create a Redis connection utility with error handling. - [ ] Implement the rate limit middleware factory function. - [ ] Configure the middleware to use IP address, 100 req/min, and set proper headers. - [ ] Write unit tests for the middleware using Jest. - [ ] Create a simple demo Express app to test the middleware. - [ ] Update README with usage instructions. ## Verification Commands - `npm run type-check` - `npm test` - `npm run lint`

这份PRD就是“宪法”。任务（- [ ]）必须是非嵌套的、原子级的，每个预估在3-5分钟内完成。## Verification Commands部分是黄金标准，AI在标记每个任务完成前，必须成功运行这些命令。

4.3 第二阶段：启动构建循环批准PRD后，AI会自动或在你的手动命令下，启动构建循环。背后的核心命令是：

cd /path/to/your/project ralphy --codex --verbose --prd projects/rate-limiter/PRD.md -- -c model_reasoning_effort="high"

为了让这个长时任务在后台安全运行，我们使用tmux来托管它：

SESSION="rate-limiter-build" tmux -S ~/.tmux/sock new -d -s $SESSION \ "cd /path/to/your/project && \ ralphy --codex --verbose --prd projects/rate-limiter/PRD.md -- -c model_reasoning_effort=\"high\"; \ EXIT_CODE=\$?; \ openclaw system event --text 'Session $SESSION finished (exit '\$EXIT_CODE').' --mode now; \ sleep 999999"

这个命令做了几件聪明事：

1. 在后台 (-d) 创建一个名为rate-limiter-build的tmux会话。
2. 在该会话中执行ralphy构建命令。
3. 构建结束后，无论成功与否，都会通过openclaw system event发送一个通知到你配置的渠道（如Slack）。
4. 最后sleep是为了保持会话不立即关闭，方便你后续进去查看日志。

4.4 构建循环内部发生了什么？AI开始“打工”了。它会严格遵循PRD：

1. 读取记忆：首先读取.ralphy/progress.txt（如果存在），了解之前已经尝试过什么，学到了什么。
2. 选取任务：扫描PRD.md，找到第一个未勾选的任务，比如“Initialize npm project...”。
3. 执行任务：在一个独立的、上下文干净的新会话中，AI会思考如何完成这个任务，并执行操作（创建文件、写代码、运行命令）。
4. 验证：运行PRD中定义的Verification Commands（如npm run type-check）。如果失败，AI会尝试修复（默认最多重试3次）。
5. 提交与记录：任务通过验证后，AI会执行git commit，将更改持久化。然后，它将本次任务的“经验教训”追加到.ralphy/progress.txt，并在PRD.md中勾选这个任务（- [ ]->- [x]）。
6. 循环：移动到下一个未完成的任务，重复步骤2-5，直到所有复选框都被勾选。

你可以随时用tmux -S ~/.tmux/sock capture-pane -t rate-limiter-build -p | tail -50来查看最新的构建日志，就像监工一样。

5. 高级技巧与实战心得

掌握了基础流程后，下面这些技巧能让你把openclaw-build的威力发挥到极致，这些大多是我在实战中踩坑总结出来的。

5.1 如何编写“AI友好”的PRDPRD的质量直接决定构建的成败。经过多次实践，我总结出几个要点：

• 任务原子化：每个- [ ]任务必须足够小，能在3-5分钟内被AI理解和执行。“实现用户登录系统”太大，应该拆分为“创建用户模型”、“设计登录API路由”、“实现密码加密验证”、“生成JWT令牌”等。
• 指令明确化：在任务描述中嵌入关键约束。例如：“- [ ] CreateUserServiceclass.Must use dependency injection forUserRepository.Write unit tests with 90%+ coverage.”
• 验证命令具体化：## Verification Commands里的命令必须是项目内可运行的、无副作用的。npm test比 “手动测试” 好一万倍。可以指定具体测试文件，如npm test -- services/user.service.test.ts。
• 利用模板：项目自带的loops/templates/PRD.md.template和loops/templates/AGENTS.md.template是宝藏。后者定义了给AI看的规则，比如“总是先写测试再写实现”、“每个函数必须有JSDoc注释”。你可以在项目初始化时 (ralphy --init) 后，用ralphy --add-rule添加你自己的团队规范。

5.2 并行构建与冲突管理对于大型项目，串行构建太慢。openclaw-build支持通过--parallel和--max-parallel进行并行构建。其原理是利用Git的worktree功能，为每个并行任务创建一个独立的代码目录副本。

ralphy --codex --parallel --max-parallel 3 --prd PRD.md --verbose --

警告：并行构建是双刃剑。如果任务之间有依赖（比如任务B需要任务A创建的模块），并行就会导致失败。解决方案是在PRD中使用YAML元数据来分组任务：

--- parallel_group: database --- - [ ] Design database schema. - [ ] Create migration scripts. --- parallel_group: api --- - [ ] Design REST API endpoints. - [ ] Implement controller stubs.

这样，同组内的任务会串行执行，不同组间的任务可以并行。这是管理复杂依赖关系的核心技巧。

5.3 跨模型审查：用另一个AI来审计代码这是保证代码质量的杀手锏。你可以在所有构建任务完成后，或者在中途，启动一个由另一个AI模型执行的审查任务。

# 用 Claude 审查 Codex 写的代码 ralphy --claude --verbose -- --effort high "Review the last 5 commits in this repo. Focus on code style, potential bugs, and adherence to the PRD. Output a REVIEW.md file with findings and suggestions." # 用 Codex 审查 Claude 写的UI代码 ralphy --codex --verbose -- -c model_reasoning_effort="high" "Review the frontend components for accessibility issues and React best practices. Create a FIXES.md with specific code changes."

这种“左右互搏”能发现很多单一模型盲点的问题，比如Codex可能更擅长逻辑正确性，而Claude对代码可读性和样式有更好的判断。

5.4 无人值守（AFK）运行的安全策略你不可能一直盯着。让AI自己跑通宵，需要设置安全护栏：

• 迭代次数上限 (--max-iterations)：这是必须设置的！假设你的PRD有10个任务，就设置--max-iterations 15或20。这是为了防止AI在某个任务上陷入死循环（比如不断重试一个永远无法通过的测试）。达到上限后，构建会自动停止并通知你。
• 使用监控守护进程：项目内置的监控脚本可以定期检查tmux会话状态。如果会话卡住（长时间无输出）或完成，它会通过OpenClaw通知你。关键是，这个监控本身不消耗AI API的token。
• 沙箱模式 (--sandbox)：对于不信任的或探索性的任务，可以使用沙箱模式运行。这样AI对文件系统的修改会被隔离，不会污染主项目目录。适合用来尝试不同的库或解决方案。

6. 故障排除与常见问题实录

即使流程设计得再完美，实战中还是会遇到各种妖魔鬼怪。下面是我遇到过的典型问题及解决方案，希望能帮你节省数小时的调试时间。

6.1 问题：构建循环一开始就立即退出，没有错误输出。

• 排查：这通常不是ralphy的问题，而是底层AI引擎的认证或配置错误。
• 解决：
  1. 检查Codex/Claude CLI认证：运行codex whoami或claude --version，看是否需要重新登录 (codex auth login)。
  2. 查看引擎日志：对于Codex，查看~/.codex/log/codex-tui.log；对于Claude，查看其CLI的输出。这里通常会有“token expired”或“invalid API key”的明确错误。
  3. 检查--分隔符：确保ralphy的命令行参数在--之前，引擎专用参数在--之后。ralphy --codex --prd file.md -- -c key=value是正确的。如果把--prd放到--后面，它会被忽略。

6.2 问题：AI报告的任务数量和我PRD里看到的不一致。

• 排查：ralphy通过正则表达式^- [ ]来统计任务。如果你的PRD格式不对，统计就会出错。
• 解决：
  1. 禁止嵌套复选框：确保任务前没有缩进。- [ ] Task是对的，- [ ] Subtask会被ralphy的预检脚本 (rg -n '^[[:space:]]+- [ ] ') 捕获并报错。
  2. 禁止错误格式：- []（中间没空格）也是错误格式。
  3. 手动验证：在项目根目录运行rg -c '^- [ ] ' PRD.md，看看数量是否匹配你的预期。

6.3 问题：并行构建时出现Git合并冲突。

• 排查：当两个并行任务修改了同一个文件的相近区域时，在最终合并回主分支时就会冲突。
• 解决：
  1. 预防优于治疗：如前所述，使用parallel_groupYAML元数据将有潜在冲突的任务放在同一组内串行执行。
  2. 事后处理：如果冲突发生，构建会暂停。你需要手动介入解决冲突。解决后，可以手动运行ralphy --resume（如果支持）或重新启动构建，它会跳过已完成的任务。
  3. 设计任务时考虑隔离性：尽量让任务基于不同的文件或目录工作。例如，一个任务只改src/services/，另一个只改src/components/。

6.4 问题：AI总是在同一个简单任务上失败重试，消耗大量token。

• 排查：查看该任务的构建日志。通常是因为验证命令太严格（比如测试用例本身有误），或者AI缺乏完成该任务的上下文。
• 解决：
  1. 优化验证命令：确保npm test等命令是确定性的，且不依赖外部服务（如数据库）处于特定状态。使用 mocking。
  2. 增强项目记忆：在.ralphy/progress.txt的开头，手动添加一些针对性的指导。例如：“注意：本项目使用uuid库的v4版本生成ID，不要使用crypto.randomUUID。”
  3. 拆分任务：如果AI卡在“实现X函数”上，可能因为这个函数太复杂。将PRD中的这个任务拆分成“设计函数接口”、“编写函数主体”、“编写边界情况处理”等多个子任务。
  4. 介入并手动完成：有时AI就是绕不过某个弯。最经济的做法是手动完成这个任务，提交代码，并在PRD中手动勾选它。然后重启构建，AI会愉快地继续下一个任务。

6.5 问题：如何优雅地终止或暂停一个正在运行的构建会话？

• 查看会话：tmux -S ~/.tmux/sock list-sessions
• 查看日志：tmux -S ~/.tmux/sock capture-pane -t SESSION_NAME -p | less
• 终止会话：tmux -S ~/.tmux/sock kill-session -t SESSION_NAME
• 暂停（不推荐直接杀进程）：可以进入tmux会话 (tmux -S ~/.tmux/sock attach -t SESSION_NAME)，然后按Ctrl+C中断当前任务。ralphy在接收到中断信号后，通常会优雅地结束当前迭代，下次重启时会从上次未完成的任务继续。