如何让 Codex 更稳定地执行长任务和大任务
在使用 Codex、AI 编程助手或类似 Agent 工具处理大型工程任务时，很多人都会遇到一个问题：任务一开始表现不错，但执行一段时间后就停了，或者只完成了一部分，最后留下半成品。
这类问题不一定是模型”不够聪明”，更多时候是任务组织方式不适合长时间执行。对于复杂工程任务，不能只靠一句”请完整实现，不要停下来”。更好的方式是把任务工程化，让它具备清晰边界、阶段划分、权限策略、进度记录和验收标准。
OpenAI 官方最佳实践也强调，复杂仓库里最重要的是给 Codex 明确的任务上下文和结构化目标，包括 Goal、Context、Constraints、Done when。也就是说，长任务能否稳定执行，很大程度上取决于你是否告诉它：要改什么、参考什么、遵守什么规则、做到什么程度才算完成。
一、不要把大任务一次性塞给 Codex
很多人会这样写 Prompt：
1
请根据这些文档完整实现整个方案，实施过程中不要停下来，直到全部完成为止。
这种写法方向没错，但问题是任务边界太大。
一个大型工程任务往往包含以下环节：
1
2
3
阅读文档 → 理解现有代码 → 梳理差异 → 制定方案
→ 修改后端 → 修改前端 → 补充测试 → 修复测试失败
→ 做最终 Review → 生成实施记录
如果全部混在一个 Prompt 里，Codex 很容易在完成某个阶段后误以为任务已经结束，或者因为上下文过长、权限确认、测试阻塞、外部服务不可用而停下来。
更好的方式是把大任务拆成多个阶段：
1
2
3
4
5
6
7
阶段 0：阅读文档和代码，生成实施计划，不改代码
阶段 1：完成基础结构调整
阶段 2：完成核心业务逻辑实现
阶段 3：补充测试并修复测试失败
阶段 4：完成前端或调用方对齐
阶段 5：联调与回归测试
阶段 6：最终 Review，生成证据文档
每个阶段都应该是可执行、可测试、可验收的。OpenAI 官方也建议对复杂或模糊任务先使用 Plan mode，或者使用 PLANS.md / execution-plan 模板来管理多步骤工作。
二、给仓库添加 AGENTS.md
如果你长期使用 Codex 处理同一个项目，建议在仓库根目录添加一个 AGENTS.md 文件。
AGENTS.md 的作用是告诉 Codex：
- 项目结构是什么
- 哪些目录负责什么
- 使用什么命令启动项目
- 使用什么命令运行测试
- 有哪些编码规范
- 有哪些禁止事项
- 什么才算任务完成
OpenAI 官方文档说明，Codex 会在开始工作前读取 AGENTS.md，并且支持全局、仓库级、子目录级的分层规则。越靠近当前工作目录的规则优先级越高；同时需要注意，过长的规则文件可能被截断或失效。
一个简化示例：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
# AGENTS.md
## Project Rules
- 可以重构代码结构，但不得改变现有业务行为。
- 修改认证、权限、安全、会话、数据存储相关逻辑时，必须补充测试。
- 不要只给建议，任务要求实现时必须实际修改代码。
- 修改完成后必须运行相关测试。
- 如果测试失败，优先自行定位并修复。
## Backend Commands
- Run unit tests: go test ./...
- Run integration tests: make test-integration
- Run e2e tests: make test-e2e
- Start services: docker compose up -d
## Frontend Commands
- Install dependencies: npm install
- Run tests: npm test
- Run lint: npm run lint
- Build: npm run build
## Done Criteria
任务完成必须满足：
1. 代码已经实现。
2. 测试已经补充或更新。
3. 相关测试通过。
4. 没有明显回归。
5. 进度文档已经更新。
AGENTS.md 不应该写成一本长篇手册。官方也建议保持实用和简洁，把构建命令、测试命令、Review 规则、目录约定、禁止事项写清楚即可。重复犯错时，再把规则补进去。
三、使用 execution-plan.md 管理长任务
对于大型任务，建议让 Codex 先生成一个实施计划文件，例如：
1
docs/codex-execution-plan.md
这个文件不只是普通计划，而是任务执行清单。它应该包含：
- 阶段目标
- 涉及文件
- 实施步骤
- 测试命令
- 验收标准
- 当前状态
示例 Prompt：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
先不要改代码。
请阅读项目文档和当前代码，生成 docs/codex-execution-plan.md。
要求：
1. 按阶段拆分任务。
2. 每个阶段必须控制在可独立提交、可独立测试的粒度。
3. 每个阶段包含：
- 目标
- 涉及文件
- 实施步骤
- 测试命令
- 验收标准
4. 标出阶段之间的依赖关系。
5. 生成计划后，立即开始执行阶段 1。
6. 每完成一个阶段，更新进度文档，然后继续下一个阶段。
7. 除非遇到无法自行解决的外部阻塞，否则不要停止。
这样即使 Codex 中途停下来，也可以根据计划文件继续执行，而不是每次都重新开始。
四、使用 progress.md 记录进度和证据
长任务最怕的问题是：执行到一半停了，下一次不知道已经做了什么。
所以建议增加一个进度文件，例如：
1
docs/codex-progress.md
每完成一个阶段，就让 Codex 更新这个文件：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
# Codex Progress
## 当前阶段
阶段 2：核心业务逻辑实现
## 已完成事项
- 完成某模块重构
- 修复某接口行为不一致问题
- 补充某类测试
## 修改文件
- src/xxx
- tests/xxx
- docs/xxx
## 已执行验证
go test ./...
npm test
## 验证结果
- 单元测试通过
- 集成测试通过
- 前端构建通过
## 未完成事项
- 还需要补充 e2e 测试
- 还需要检查接口字段一致性
## 下一步
继续执行阶段 3。
这个文件相当于 Codex 的”断点记录”。后续如果任务中断，可以直接让它继续：
1
2
3
4
请阅读 docs/codex-execution-plan.md 和 docs/codex-progress.md，
从当前未完成阶段继续执行。
不要重复已经完成的阶段。
每完成一个阶段，继续更新 progress 文档。
如果你使用 Codex CLI，也可以使用 codex resume 继续之前的交互会话。官方 CLI reference 说明，codex resume 可继续之前的交互会话或最近一次会话。
五、正确理解权限、沙盒和审批
Codex 中途停下，很多时候不是 Prompt 写得不够强，而是权限策略要求它必须停下来询问。
OpenAI 官方文档里，sandbox 和 approval 是两套配合使用的控制机制：sandbox 决定 Codex 能访问、修改和运行什么；approval 决定它什么时候必须停下来请求用户确认。只要任务保持在 sandbox 边界内，Codex 就更容易持续推进；一旦需要越界（例如访问工作区外文件、使用网络、执行高风险命令），就可能触发审批。
常见模式可以这样理解：
| 模式 | 说明 |
|---|---|
| Read-only | 适合阅读代码、审查方案、生成计划，不适合自动改代码 |
| workspace-write | 适合大多数本地工程任务，Codex 可在当前工作区读写和运行常规命令 |
| danger-full-access / Full Access | 权限很大，适合隔离环境、CI runner、临时容器，不建议在日常主力机器上随意使用 |
官方文档也明确建议，在自动化场景下应使用完成任务所需的最小权限；danger-full-access 只适合受控环境，例如隔离的 CI runner 或容器。
因此，与其简单写”不要问我，全部自动执行”，不如给它一个安全边界：
1
2
3
codex exec \
--sandbox workspace-write \
"按照 docs/codex-execution-plan.md 从当前未完成阶段继续执行"
六、用 config.toml 固化默认行为
AGENTS.md 解决的是”这个项目应该怎么做”；config.toml 解决的是”Codex 默认应该怎么运行”。
OpenAI 官方最佳实践提到，配置可以用来统一模型选择、推理强度、sandbox、approval、profile、MCP 等行为。个人默认配置通常放在 ~/.codex/config.toml，项目级配置可以放在 .codex/config.toml。
对于经常跑长任务的人，可以考虑固化这些方向：
1
2
3
4
5
6
7
8
9
10
# 示例，仅表达思路，具体字段以当前 Codex 文档为准
# 默认使用适合复杂任务的推理强度
# reasoning_effort = "high"
# 默认限制在工作区写入
# sandbox = "workspace-write"
# 默认审批策略
# approval_policy = "on-request"
不要把所有权限都默认开到最大。更稳的方式是默认安全，确实需要时再临时提升。
七、让 Codex 自己处理测试失败
很多长任务中断，是因为 Codex 跑测试后发现失败，然后停下来汇报。
对于工程实施任务，更好的要求是：
1
2
3
如果测试失败，不要立即停止。
请先自行分析失败原因，修复问题，然后重新运行测试。
只有在遇到缺少密钥、外部服务不可访问、账号权限不足等无法自行解决的问题时，才记录阻塞。
也可以写得更明确：
1
2
3
4
5
6
7
8
遇到测试失败时，按以下流程处理：
1. 阅读失败日志。
2. 判断是代码问题、测试问题、环境问题还是外部依赖问题。
3. 如果是代码或测试问题，自行修复。
4. 修复后重新运行对应测试。
5. 将失败原因、修复方式、最终结果写入 progress 文档。
6. 不要因为第一次测试失败就结束任务。
OpenAI 官方最佳实践也建议，不要只让 Codex 生成代码，还应该让它创建或更新测试、运行相关检查、确认结果，并 review diff。
八、善用 CLI、IDE 和 Cloud 的分工
Codex 有多个使用场景，不同场景适合不同任务：
| 场景 | 适用任务 |
|---|---|
| IDE 插件 | 边看代码边交流、快速修改、查看 diff、局部重构 |
| CLI | 在本地仓库里跑较长任务、执行测试、生成计划、持续修改 |
| Cloud | 后台任务、并行任务、较长实现任务，尤其适合把明确阶段委托出去处理 |
OpenAI 官方文档说明，Codex IDE extension 可以在 VS Code 等编辑器中使用，也可以把任务委托给 Codex Cloud；Codex Cloud 可以在自己的云环境中后台处理任务，包括并行任务。
如果你希望命令行自动化，可以使用非交互模式：
1
codex exec "summarize the repository structure and list the top 5 risky areas"
官方文档说明，codex exec 会把进度流输出到 stderr，最终结果输出到 stdout，也支持 JSON Lines 输出，方便脚本或 CI 消费。
对于长任务，可以这样组织：
1
2
3
codex exec \
--sandbox workspace-write \
"$(cat docs/codex-long-task-prompt.md)"
如果中途停了，再让它根据 execution-plan.md 和 progress.md 继续，而不是重跑整个任务。
九、不要让一个任务同时做太多事情
即使有很好的 Prompt，也不建议把所有事情都交给一个 Codex 会话一次性完成。
更稳的方式是分多个任务：
1
2
3
4
5
6
任务 1：只做设计与现状审查
任务 2：只做核心实现
任务 3：只做测试补齐
任务 4：只做调用方或前端对齐
任务 5：只做联调和回归
任务 6：只做最终 Review
每个任务都基于同一份 execution-plan.md 和 progress.md，这样上下文更稳定，也更容易检查结果。
对于高度并行的复杂任务，也可以考虑 subagents。OpenAI 官方文档说明，Codex 可以显式运行 subagent workflows，把复杂任务分发给专门的子 Agent 并汇总结果，但这通常会消耗更多 token。
十、把重复流程做成 Skill 或固定模板
如果你经常执行类似流程，例如：
- 大重构实施
- 安全 Review
- 测试补齐
- 接口契约检查
- 发布前回归
- 文档同步
不要每次都复制一大段 Prompt。可以把它沉淀成：
| 形式 | 用途 |
|---|---|
AGENTS.md | 项目规则 |
PLANS.md | 实施计划模板 |
code_review.md | Review 规则 |
docs/codex-long-task-prompt.md | 长任务模板 |
| Codex Skill | 可复用工作流 |
OpenAI 官方文档说明，Codex 的 customization 层包括 AGENTS.md、Skills、MCP、Subagents 等：AGENTS.md 适合持久项目规则，Skills 适合封装可复用工作流，MCP 适合连接外部系统，Subagents 适合把复杂任务交给专门 Agent。
十一、推荐的长任务 Prompt 模板
下面是一份比较通用的长任务 Prompt 模板：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
你现在是该仓库的工程实施 Agent。请严格按照以下规则执行长任务。
核心原则：
1. 不要只做建议，任务要求实现时必须实际修改代码。
2. 可以在保持业务行为不变的前提下重构代码结构。
3. 不得改变现有功能、业务逻辑和可见用户行为，除非任务明确要求。
4. 不要因为完成一个小阶段就停止。
5. 只有所有 Done Criteria 全部满足，才可以结束任务。
工作方式：
1. 先阅读 AGENTS.md、项目文档、任务清单和当前代码。
2. 生成或更新 docs/codex-execution-plan.md。
3. 将任务拆分成多个阶段，每个阶段必须可独立实施、测试和验收。
4. 从第一个未完成阶段开始执行。
5. 每完成一个阶段，更新 docs/codex-progress.md，记录：
- 完成内容
- 修改文件
- 测试命令
- 测试结果
- 仍未完成事项
- 下一步
6. 更新 progress 文档后，自动继续下一个阶段。
7. 如果遇到测试失败，先自行定位并修复，再重新测试。
8. 如果发现文档与代码不一致，以当前代码为准，判断文档是否过时，并在不改变业务行为的前提下给出合理实现。
9. 如果遇到无法自行解决的外部阻塞，例如缺少密钥、外部服务不可访问、账号权限不足，请记录到 progress 文档，并继续处理不依赖该阻塞的其他任务。
验收标准：
1. 相关代码已经实现。
2. 相关测试已经补充或更新。
3. 单元测试通过。
4. 集成测试通过。
5. e2e 测试通过。
6. 接口契约一致。
7. 安全、认证、权限、会话、数据一致性等关键路径有测试覆盖。
8. docs/codex-progress.md 有完整证据记录。
9. 最终执行一次 Review，排查遗漏、Bug 和回归风险，并修复发现的问题。
现在开始执行，不要停在计划阶段。
十二、中断后的继续执行 Prompt
如果 Codex 中途停了，不要重新把所有需求再贴一遍。应该让它从已有进度继续：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
请继续执行当前长任务。
先阅读：
1. AGENTS.md
2. docs/codex-execution-plan.md
3. docs/codex-progress.md
4. 当前代码状态
然后从第一个未完成阶段继续执行。
要求：
1. 不要重复已经完成的阶段。
2. 不要重新设计已经确认的方案，除非发现明确问题。
3. 每完成一个阶段，更新 progress 文档。
4. 运行对应测试。
5. 如果测试失败，先自行修复再继续。
6. 直到所有 Done Criteria 完成后再结束。
如果使用 CLI，可以优先考虑：
1
codex resume
或者在非交互模式下让它基于进度文档继续：
1
2
3
codex exec \
--sandbox workspace-write \
"阅读 docs/codex-execution-plan.md 和 docs/codex-progress.md，从第一个未完成阶段继续执行"
十三、长任务执行的核心原则
让 Codex 跑长任务，关键不是让它”更听话”，而是让任务本身具备工程结构。
可以总结为八点：
- 用
AGENTS.md固化项目规则。 - 用
codex-execution-plan.md拆分阶段。 - 用
codex-progress.md记录断点和证据。 - 用
config.toml固化默认模型、权限和审批策略。 - 每个阶段都要有测试命令和验收标准。
- 测试失败时要求 Codex 自行定位、修复、重跑。
- 大任务不要一次性全塞给一个会话，尽量分阶段执行。
- 默认保持安全权限，只在可信、隔离、可回滚环境里放宽权限。
一句话总结：不要把 Codex 当成一个能无限记忆、无限执行的聊天窗口，而要把它当成一个需要任务计划、权限边界、进度记录和验收标准的工程 Agent。
只要任务被拆得足够清楚，过程有记录，结果可验证，权限边界合理，Codex 执行长任务的稳定性会明显提高。