最后核验：2026-10-23
先看结论
Codex 本身已经足够强，新手最常见的问题不是“提示词没写好”，而是工作方式：规则放错地方、没告诉它怎么验证、跳过规划、权限给得太早、所有事情堆在一个对话里。
OpenAI 在官方最佳实践（Best practices）的结尾列了 8 个常见错误，本文逐条展开：
- 把长期规则塞进提示词，而不是放进
AGENTS.md或 Skill。 - 没告诉 Codex 怎么跑构建和测试，它看不到自己的工作结果。
- 复杂、多步骤的任务跳过规划。
- 还没理解流程，就给了电脑的全部权限。
- 在同一批文件上并行跑多个任务，却不用 Git worktree。
- 手工都不稳定的任务，就设成定时任务。
- 把 Codex 当成要一步一步盯着的东西，而不是与你并行工作。
- 一个对话做完整个项目，而不是一个对话对应一个完整成果。
每一条下面有四部分：症状、怎么改（来自官方）、怎么验证。其中“怎么验证”除特别注明的官方命令外，是编者的建议，不是官方规则。内容整理自 OpenAI 官方文档，核验日期 2026-10-23；界面与命令以你当前版本为准。
错误 1：把长期规则塞进提示词
症状： 每开一个新任务，都要重复一遍“用 pnpm、改完跑测试、别动某个目录”。提示越写越长，换个对话就忘。
怎么改： 稳定的约定写进 AGENTS.md，它会在 Codex 开始工作前自动载入；反复出现的流程做成 Skill。官方给了一条经验法则：如果你总在复用同一条提示，或总在纠正同一个流程，它大概就该变成 Skill。 写法见AGENTS.md 怎么写才有用和Codex Skills 实战。
怎么验证： 新开一个会话，不重复这些规则，看 Codex 是否照做。官方提供了检查命令：
codex --ask-for-approval never "Summarize the current instructions."
Codex 应该复述 AGENTS.md 里的内容。
错误 2：没告诉 Codex 怎么构建和测试
症状： 改完代码不跑测试，或者跑错命令，最后给你一段“看起来对”的 diff。
怎么改： 官方的说法是：不要让 agent 看不到自己的工作。把构建、测试、lint 命令和“怎么算做完”写进 AGENTS.md 或任务提示。官方还建议要求 Codex 写或更新测试、运行相关检查、确认最终行为符合要求，并在你接受前复查 diff。这个闭环只有在它知道“好”的标准时才成立，标准可以来自提示，也可以来自 AGENTS.md。
任务提示里怎么写这个标准，见一条好任务怎么写里的 “Done when”。
怎么验证： 看 Codex 的最终报告是否列出了它实际跑过的命令和结果；没有，就把命令补进 AGENTS.md（编者建议）。
错误 3：复杂任务跳过规划
症状： 任务模糊、牵涉多个模块，Codex 一上来就改，改到一半方向不对。
怎么改： 官方给了三种做法：
- Plan mode：对多数用户最简单有效，Codex 会先收集上下文、提问，再形成方案。用
/plan或Shift+Tab切换。 - 让 Codex 采访你：想法还模糊时，让它先提问、挑战你的假设，把想法变具体再写代码。
PLANS.md模板：更高级的长任务可配置执行计划模板，官方 Cookbook 有执行计划指南。
怎么验证： 方案里是否包含你关心的约束和完成条件；没有就先补充再放行（编者建议）。
错误 4：还没理解流程就给全盘权限
症状： 为了少点“允许”，一开始就把权限开到最大。
怎么改： 官方建议新手先用默认权限，让审批和沙箱保持收紧，等某个仓库或流程可信、确实需要时再放宽。Codex 有两个旋钮：审批模式决定什么时候问你，沙箱模式决定它能读写哪里。官方文档里的三档沙箱是：
read-only：只能看，改文件或执行命令需要审批。workspace-write：能读文件、在工作区内编辑、运行常规本地命令，是本地工作默认的低摩擦模式。danger-full-access：没有沙箱限制，只在你确实要它完全放开时用。
官方把 sandbox_mode = "workspace-write" 加 approval_policy = "on-request"（命令行是 --sandbox workspace-write --ask-for-approval on-request）称为较低风险的本地预设；danger-full-access 加 never 才是完全放开。
怎么验证： 在命令行里启动时显式写出这两个参数，让权限一目了然，而不是依赖隐式默认；放宽前先想清楚是哪个仓库、哪个流程需要（编者建议）。
错误 5：在同一批文件上并行跑任务，却不用 worktree
症状： 两个任务同时改同一个目录，互相覆盖，或者你自己在改的时候 Codex 也在改。
怎么改： 并行任务用 Git worktree：它是仓库的第二份检出，让 Codex 在后台工作而不打扰你当前的本地目录。ChatGPT 桌面应用里，在新对话的输入框下选择 Worktree 即可；Codex 管理的 worktree 通常一个对话一个。官方特别提醒：Git 同一时间只允许一个分支在一个位置检出，所以要在本地继续时，用 Handoff 把对话移到本地，而不是两边同时检出同一分支。
完整的上手步骤、Handoff 与清理规则见Codex 并行干活不打架：用 Worktree 同时跑多个任务。
worktree 里代码跑不起来也很常见：它只继承 Git 里提交的文件，依赖和被忽略的配置文件（比如 .env）需要通过本地环境的安装脚本或 .worktreeinclude 带过去。
怎么验证： 先让一个任务在 worktree 里跑完，再 Handoff 回本地检查，确认没有同一分支冲突提示（编者建议）。
错误 6：手工都不稳定，就设成定时任务
症状： 把一个还要靠人盯着修正的流程设成每天自动跑，结果每天产出一堆需要返工的东西。
怎么改： 官方的顺序是：先稳定，再自动化。Skill 定义方法，定时任务定义时间。 一个流程如果还需要大量引导，先把它做成 Skill；等它变得可预测，再去定时。适合定时的例子包括：总结最近提交、扫描潜在 bug、起草发布说明、检查 CI 失败、生成站会摘要。
定时任务多了还会产生大量 worktree，官方排障页的建议是：归档不再需要的运行记录，除非要保留对应 worktree，否则不要固定（pin）这些运行。
怎么验证： 同一个提示手工连续跑几次，结果稳定了再设定时（编者建议）。
错误 7：把 Codex 当成要一步步盯着的东西
症状： 你盯着屏幕等它跑完，自己的活什么也没干。
怎么改： 官方的建议是把它当成与你并行的队友：把任务交出去，自己做别的；需要纠偏时再介入。运行中追加消息有两种方式：引导（steer） 把消息加入当前这一轮，用来改方向或补信息；排队（queue） 把消息留给下一轮，用来放等当前工作做完再处理的跟进。在 Codex CLI 里，工作中按 Enter 是引导，按 Tab 是排队；桌面应用里可以在 Settings > General > Follow-up behavior 里选默认行为。
边界清晰的探索、测试、分流类工作，还可以交给子智能体，让主线程保持专注。
怎么验证： 一次提交两个互不相干的任务（各用独立 worktree），看你能否在等待期间做自己的事（编者建议）。
错误 8：一个对话做完整个项目
症状： 对话越拉越长，上下文里堆满过期的决定，结果越来越差。
怎么改： 一个对话对应一个完整的成果。 同一个问题的延续，留在同一个对话里往往更好，因为保留了推理轨迹；只有工作真的分叉了才分叉。CLI 里这几个命令最常用：
/compact：对话变长时，把早先的上下文压缩成摘要（Codex 也会自动压缩）。/fork：创建新对话，同时保留原对话记录。/resume：恢复已保存的对话。/status：查看当前会话状态。
怎么验证： 对话开头的目标和现在做的事是否还是同一件事；不是，就开新对话（编者建议）。
一个更根本的习惯：同一个错误出现两次就复盘
官方还建议：当 Codex 犯了同一个错误两次，让它做一次复盘，再据此更新 AGENTS.md。这样规则来自真实摩擦，而不是凭空猜测。这比一开始就写一份很长的规则文件有效，详见AGENTS.md 怎么写才有用。
自查清单
- 重复出现的规则，是不是已经在
AGENTS.md或 Skill 里？ - Codex 知道怎么构建、测试，以及什么条件算完成吗？
- 复杂任务有没有先规划？
- 当前权限是不是还是默认的、够用就行的？
- 并行任务是不是用了各自的 worktree？
- 要定时的流程，手工是否已经稳定？
- 你是不是在等待期间做别的事，而不是盯着？
- 这个对话是不是只对应一个成果？
下一步读什么
- 想把任务写得更准：一条好任务怎么写：Goal、Context、Constraints、Done when
- 想沉淀长期规则：AGENTS.md 怎么写才有用
- 想跑很久的任务：Codex 长任务工作流
- 想选模型：GPT-6 系列怎么选
- 想让 Codex 帮你审代码：用 Codex 做代码审查
- 想接进脚本和 CI：codex exec 入门
官方来源
- Best practices：常见错误清单、规划、
AGENTS.md、配置、审查、MCP、Skills、定时任务与长对话管理 - Prompting：引导与排队
- Sandboxing：沙箱模式、审批策略与低风险本地预设
- Worktrees：worktree 的用法、Handoff、分支限制与
.worktreeinclude - Troubleshooting：worktree 里代码跑不起来、定时任务产生大量 worktree
- Custom instructions with AGENTS.md：检查
AGENTS.md是否载入的命令 - Execution plans guide：
PLANS.md与执行计划
核验日期：2026-10-23。
