这篇讲什么
Codex 是 OpenAI 的”扔个任务、走开、回来看 PR”代码 agent。它在云端沙盒里跑、自己拿一份仓库副本——并行任务很合适，但也带来一类新 bug：环境漂移、缺 secrets、过度热心地”顺手改”。这篇讲清安装、能产出可审 PR 的任务 spec 格式、以及新手第一周必踩的坑。
这篇适合谁看
想要云端 agent 任务的开发者：重构、依赖升级、补测试、审计扫描、所有不需要和本地机器共定位的活。单干受不了切换上下文的人受益最大；团队想加一道”提 PR 前自动 pass”也很合适。
什么时候适合用
长任务，不需要和你机器共定位：30 个文件的重构、依赖升级、测试覆盖率扫描、文档批改。用 AI 审计 React Native 项目这种全仓扫描尤其合适。需要实时看编辑落地的，去用 Cursor 或 Claude Code。
什么时候不建议用
需要看到中间产出并介入的任务、紧反馈循环、需要沙盒拿不到的 secrets、一行小改（配置成本超过节省）。
开始前准备
- 确认仓库的 CI 在
main上是绿的。脏起点 Codex 会继承失败基线。 - 在 README 或 AGENTS.md 里写清构建 / 测试命令，沙盒能读到。Codex 需要知道怎么跑你的测试。
- 测试需要的 secrets 在沙盒里配好（多数对外任务不需要）。
- 想清分支命名和 PR 约定，让 agent 输出能直接进你的工作流。
具体步骤
- 登录并连接仓库。如果你对这个代码库不熟，写任务 spec 前先做一次快速 AI 代码库导览——让 spec 里写的是真实名字，不是猜的。
- 建任务，写明验收标准。一个具体起手任务：用 Codex 审查 sitemap。Spec 像”bug 票 + 测试”那样写：
目标：将 `src/api/` 内已弃用的 `request.json()` 调用替换为 `await request.json()`。
约束：
- 不要修改 `src/api/` 之外的任何文件。
- 保留现有错误处理模式。
- 用项目现有的 async 风格（参考 `src/api/auth.ts`）。
验收：
- 现有测试全过。
- `src/api/__tests__/json-parse.test.ts` 新增测试覆盖新行为。
- `npm test` 无 console warning。- 让 Codex 跑。它会开沙盒、起分支、改代码、跑测试、开 PR。小任务通常 5-15 分钟，全仓扫描 30-60 分钟。
- 审 PR 像审人类 PR 一样。每个改动文件都读。看证明改动的测试。本地拉分支跑一遍。
- 在 PR 评论里迭代。Codex 会读评论并 push 跟进 commit。这一步用来做小修正，不是用来重写目标。
- 满意就合。合后发现遗漏的情况，开新任务——不要在 agent 分支上 push 跟进 commit 到合并后。
第一次实操怎么跑
- 选一个拖延已久的低风险重构：改函数名、更新老 API 调用、补缺失的 prop 类型。
- 用上面”目标 + 约束 + 验收”格式写 spec。验收别省。
- 跑任务。走开 15 分钟。回来冷读 PR。
- 标 spec 漏的地方。几乎永远是”约束太少”，不是”字数太少”。
完成后检查
- Codex 有没有遵守”不要碰 X 外的文件”？diff 文件数一眼能看出来。
- 测试全过了吗，包括你没明说的那些？看 CI 日志里有没有 skipped。
- agent 有没有”顺手”加你没要的改动？多送的重构是常见失败模式，要回滚。
- PR 描述准确吗？Codex 偶尔会夸大它做了什么。读代码、不读总结。
怎么复用这套流程
- 按任务类型存 spec 模板——重构、升级、补测试、文档批改。每周同模板换 scope。
- 仓库根放一个
AGENTS.md：构建命令、测试命令、编码规范、“绝不这么写”清单。Codex 会读。 - 跑出干净 PR 的任务和翻车的任务都记下来。规律告诉你下次约束该加严哪里。
- 季度复测一遍。沙盒配额、secret 处理、PR 约定都在变。
建议的操作流程
选任务 → 写”目标 + 约束 + 验收” spec → 跑 → 走开 → 冷审 PR → PR 评论迭代 → 合或关。
容易踩的坑
- 任务描述模糊，比如”修登录 bug”。agent 会挑一种修法，未必是你要的。
- 没写验收。没有”完成”的具体测试，agent 的”完成”不是你的”完成”。
- 不熟悉的仓库跳过代码库导览。spec 里要用真实名字，不写就靠猜，猜的都错。
- 把 PR 当生产可用而不审。Codex 产出是”PR 质量初稿”，不是”不读就合”。
- 让 Codex 改 CI 配置或 secret 处理。在约束里显式排除。
- 在相关文件上并行跑任务。两个 agent 碰相邻代码会以很难看的方式冲突。
FAQ
- Codex 能访问私有仓库吗？: 支持的计划上可以，通过连接步骤。授权前先看权限范围。
- 能跑我完整的测试套件吗？: 沙盒里能跑。确保依赖能用文档化的命令干净安装。
- 任务中途失败怎么办？: Codex 通常会带着已做的部分开 PR 并附失败说明。读失败日志、精修 spec、重跑。
- 跟 Claude Code、Cursor 有啥不同？: Codex 是异步云端；Cursor、Claude Code 是交互式。并行工作选异步，紧反馈循环选交互。