英文原文链接 OpenAI Codex Best practices
最佳实践
开始使用 Codex，以及获得更好结果的已验证实践。
如果你刚开始接触 Codex，或者刚开始接触编码代理（coding agents），这份指南能帮助你更快获得更好的结果。它涵盖了让 Codex 在 CLI、IDE 扩展和 Codex App 中更有效的一些核心习惯，包括提示、规划、验证、MCP、技能和自动化。
Codex 在你把它视为一个可以持续配置和改进的“队友”时，效果最好，而不是把它当成一次性助手。一个很有用的思路是：先提供正确的任务上下文，用 AGENTS.md 存放长期有效的指导，让 Codex 配合你的工作流进行配置，通过 MCP 连接外部系统，把重复工作封装成 skills，并把稳定的流程自动化。
强有力的起步：上下文与提示词
即使你的提示词并不完美，Codex 也已经足够强大，能够真正帮上忙。很多时候，你几乎不做准备，直接把一个难题交给它，它也能给出很不错的结果。清晰的提示并不是获得价值的前提，但它确实会让结果更可靠，尤其是在大型代码库或高风险任务中。
如果你在一个大型或复杂的仓库中工作，最关键的提升点是：给 Codex 正确的任务上下文，并清楚地组织你希望它完成什么。一个很好的默认做法，是在提示词中包含四项内容：
- 目标（Goal）：你想修改什么，或者构建什么？
- 上下文（Context）：这个任务涉及哪些文件、文件夹、文档、示例或报错？你也可以用
@提及特定文件作为上下文。 - 约束（Constraints）：Codex 需要遵守哪些标准、架构、安全要求或约定？
- 完成标准（Done when）：任务完成前应该满足什么条件？比如测试通过、行为发生变化、某个 bug 不再复现等。
这样可以帮助 Codex 保持聚焦、减少臆测，并产出更容易评审的结果。
你还应该根据任务难度选择合适的推理等级，并测试哪种设置最适合你的工作流。不同用户和不同任务，最合适的设置都可能不同：
- Low：适合更快、范围明确的任务
- Medium / High：适合更复杂的修改或调试
- Extra High：适合长流程、代理式、重推理任务
为了更快提供上下文，你也可以在 Codex App 里使用语音输入，直接口述你希望 Codex 做什么，而不是逐字打字。
对困难任务，先做计划
如果任务很复杂、含糊，或者你很难准确描述它，那么在开始写代码前，先让 Codex 做计划。
以下几种方式都很有效：
- 使用 Plan 模式：对大多数用户来说，这是最简单也最有效的方式。Plan 模式可以让 Codex 先收集上下文、提出澄清问题、形成更扎实的方案，再开始实现。可通过
/plan或Shift + Tab切换。 - 让 Codex 先“采访”你：如果你只有一个模糊想法，不知道该怎么准确描述，可以让它先向你提问。告诉它要质疑你的假设，在写代码之前先把模糊想法变得具体。
- 使用
PLANS.md模板：对于更高级的工作流，你可以配置 Codex 在长时任务或多步骤任务中遵循PLANS.md或执行计划模板。
用 AGENTS.md 让指导可复用
当某种提示方式已经有效，下一步就不该再靠手动重复输入。这正是 AGENTS.md 发挥作用的地方。
你可以把 AGENTS.md 理解为一个面向 agent 的开放格式 README。它会自动载入上下文，是在仓库中编码“你和你的团队希望 Codex 如何工作”的最佳位置。
一个好的 AGENTS.md 通常会包含：
- 仓库结构和重要目录
- 如何运行项目
- build、test、lint 命令
- 工程约定和 PR 期望
- 限制条件和禁止事项
- “完成”意味着什么，以及如何验证工作结果
CLI 中的 /init 斜杠命令可以快速在当前目录生成一个初始版 AGENTS.md。这是个很好的起点，但你应该根据团队真实的构建、测试、评审和发布方式去修改它。
你可以在不同层级创建 AGENTS.md 文件：比如放在 ~/.codex 中的全局 AGENTS.md 用于个人默认规则，仓库级文件用于团队共享标准，子目录中的更细粒度文件用于局部规则。如果当前目录附近存在更具体的文件，那么更具体的指导会优先生效。
保持务实。一个简短但准确的 AGENTS.md，往往比一份充满模糊规则的长文件更有价值。先写最基本的内容，只有在你发现重复错误后，再逐步增加新规则。
如果 AGENTS.md 变得太大，可以让主文件保持精简，再引用针对具体任务的 markdown 文件，比如规划、代码评审或架构文档。
当 Codex 连续两次犯同样的错误时，让它做一次复盘，然后更新 AGENTS.md。这样，指导内容会始终保持实用，并基于真实摩擦点。
配置 Codex，以保持一致性
配置是让 Codex 在不同会话和不同界面中表现更一致的主要方式之一。比如你可以设置默认模型、推理强度、沙箱模式、审批策略、profiles，以及 MCP 配置。
一个不错的起步方式是：
- 个人默认配置放在
~/.codex/config.toml - 仓库专属行为放在
.codex/config.toml - 命令行覆盖只用于一次性的特殊情况
config.toml 是你定义长期偏好的地方，例如 MCP servers、profiles、多 agent 配置和实验功能。你既可以直接编辑它，也可以让 Codex 帮你修改。
Codex 自带操作系统级别的沙箱能力，并且有两个关键可控项：approval mode 决定 Codex 在运行命令前何时需要你的许可；sandbox mode 决定 Codex 是否能读写目录，以及 agent 可以访问哪些文件。
如果你刚开始使用编码代理，先使用默认权限。默认情况下，把审批和沙箱权限收紧；只有当你在可信仓库或明确工作流中确实需要时，再逐步放宽。
另外，CLI、IDE 和 Codex App 共用同一套配置层。很多所谓“质量问题”，其实是配置问题，比如工作目录错了、没有写权限、默认模型不对、缺少工具或连接器等。因此，尽早按照真实环境配置 Codex 很重要。
通过测试和评审提升可靠性
不要停留在“让 Codex 做一次修改”这一步。你应该让它在需要时创建测试、运行相关检查、确认结果，并在你接受之前先做一轮自我评审。
Codex 可以帮你完成这个闭环，但前提是它知道“什么才算做好”。这些指导既可以来自提示词，也可以来自 AGENTS.md。
这通常包括：
- 为改动编写或更新测试
- 运行正确的测试套件
- 检查 lint、格式化或类型检查
- 确认最终行为符合需求
- 检查 diff 中是否存在 bug、回归或高风险模式
在 Codex App 中，你可以打开 diff 面板，直接在本地评审改动。点击具体某一行后给出的反馈，会作为上下文传给下一轮 Codex。
这里一个很有用的命令是 /review，它支持多种评审方式：
- 以某个基线分支为参照进行 PR 风格评审
- 评审未提交改动
- 评审某个 commit
- 使用自定义评审指令
如果你和团队维护了一个 code_review.md 文件，并且在 AGENTS.md 中引用它，Codex 也可以在评审时遵循这份指导。这对于想在多个仓库和贡献者之间保持一致评审行为的团队来说，是一个很强的模式。
Codex 不应该只会生成代码。在合适的指导下，它同样可以帮助测试、检查和评审代码。若你使用 GitHub Cloud，还可以设置 Codex 为你的 PR 执行代码评审。OpenAI 内部会让 Codex 评审 100% 的 PR。你可以启用自动评审，也可以在 @Codex 时触发它进行响应式评审。
用 MCP 获取外部上下文
当 Codex 需要的上下文不在仓库内部时，就该使用 MCP。它能让 Codex 连接到你已经在使用的工具和系统中，这样你就不必不断把实时信息复制粘贴进提示词里。
MCP，也就是 Model Context Protocol，是一种将 Codex 连接到外部工具和系统的开放标准。
以下情况适合使用 MCP：
- 所需上下文位于仓库外部
- 数据变化频繁
- 你希望 Codex 直接使用工具，而不是依赖粘贴进来的说明
- 你需要一个能在多个用户或多个项目之间重复使用的集成方式
Codex 同时支持 STDIO 和带 OAuth 的 Streamable HTTP 服务器。
在 Codex App 中，可以进入 Settings → MCP servers 查看自定义和推荐的服务器。很多时候，Codex 本身就能帮你安装所需服务器，你只需要开口让它做。CLI 中则可以使用 codex mcp add 命令，通过名称、URL 等信息来添加自定义服务器。
只在工具真正能打通某个工作流时再接入它。不要一开始就把你所有工具都接上。先从 1 到 2 个能够明确减少手动重复步骤的工具开始，之后再逐步扩展。
把可重复工作封装成 skills
当一个工作流开始变得可重复时，就别再依赖长提示词或反复来回沟通了。应该使用 Skill，把指令、SKILL.md 文件中的上下文，以及 Codex 需要稳定应用的支持逻辑打包起来。Skills 可以同时用于 CLI、IDE 扩展和 Codex App。
每个 skill 都应该只专注于一个工作。可以先从 2 到 3 个具体用例起步，定义清楚输入和输出，并在描述中明确说明：这个 skill 是做什么的，以及在什么情况下应该使用它。还应包含用户实际可能会说出的触发短语。
不要一开始就试图覆盖所有边界情况。先挑一个有代表性的任务，把它做好；然后再把这个工作流变成 skill，并持续改进。只有在脚本或附加资源确实能提高可靠性时，再把它们加进去。
一个经验法则是：如果你总在重复使用同一个提示词，或者总在纠正同一类工作流，那它大概率就应该被做成一个 skill。
Skills 尤其适合这些重复性任务：
- 日志分诊
- 发布说明草稿
- 按清单执行 PR 评审
- 迁移规划
- 遥测或事故总结
- 标准化调试流程
$skill-creator skill 是创建第一个 skill 的最佳起点；随后可以用 $skill-installer 将它安装到本地。Skill 最重要的部分之一就是描述：它必须说明这个 skill 做什么，以及什么时候用。
个人 skills 存放在 $HOME/.agents/skills 中；团队共享的 skills 可以放进仓库内的 .agents/skills。这对新成员 onboarding 特别有帮助。
对重复工作使用自动化
当一个工作流已经稳定后，你就可以安排 Codex 在后台定期替你运行它。在 Codex App 中，automations 允许你为周期性任务选择项目、提示词、执行频率和执行环境。
一旦某项任务对你来说开始变得重复，你就可以在 Codex App 的 Automations 标签页中创建自动化。你可以选择它在哪个项目中运行、运行什么 prompt（也可以调用 skills），以及按什么频率运行。你还可以选择让自动化在专用的 git worktree 中运行，还是在本地环境中运行。
适合自动化的任务包括：
- 汇总最近的 commits
- 扫描潜在 bug
- 起草发布说明
- 检查 CI 失败
- 生成 standup 总结
- 按计划运行可重复分析流程
一个很有用的原则是：skills 定义方法，automations 定义时间表。 如果一个工作流仍然需要很多人为引导，先把它做成 skill；一旦它变得可预测，自动化就会成为真正的效率放大器。
自动化不只适合执行任务，也适合用于反思和维护。你可以回顾最近的会话，总结反复出现的摩擦点，并随着时间推移不断改进提示词、说明或工作流配置。
用会话控制来组织长期工作
Codex 的 session 不只是聊天记录。它们更像是会逐步积累上下文、决策和行动的工作线程，因此管理方式会显著影响结果质量。
Codex App 的 UI 最方便做线程管理，因为你可以 pin 线程，也可以创建 worktrees。如果你使用 CLI，以下 slash commands 特别有用：
/experimental：切换实验功能，并加入config.toml/resume：恢复已保存的会话/fork：保留原始对话记录的同时创建一个新线程/compact：当线程过长时，对早期上下文做总结压缩（Codex 也会自动压缩会话）/agent：在并行 agent 之间切换当前活跃线程/theme：选择语法高亮主题/apps：在 Codex 中直接使用 ChatGPT apps/status：查看当前 session 状态
一个连贯的工作单元最好只用一个线程。如果工作仍属于同一个问题，继续留在同一线程通常更好，因为这样能保留推理轨迹。只有当工作真的分叉时，再去 fork。
你还可以使用 Codex 的 multi-agent 工作流，把边界清晰的工作从主线程中分流出去。让主 agent 专注于核心问题，而把探索、测试或分诊之类的任务交给 subagents。
常见错误
以下是刚开始使用 Codex 时常见的一些错误：
- 把长期有效的规则都塞进 prompt，而不是迁移到
AGENTS.md或 skill 中 - 没有告诉 agent 如何运行 build 和 test，导致它无法“看到”自己的工作结果
- 在多步骤或复杂任务中跳过规划
- 在你还没理解工作流前，就给 Codex 你的电脑完全权限
- 在没有使用 git worktrees 的情况下，让多个实时线程修改同一批文件
- 在某个重复任务还没有被手动验证可靠之前，就急着把它自动化
- 把 Codex 当成必须一步步盯着看的工具，而不是与你并行工作的助手
- 按“项目”而不是按“任务”开线程，导致上下文越来越臃肿，结果也会逐渐变差