OpenAI 官方万字长文:Codex 最佳实践完全指南

导读

OpenAI 官方开发者文档重磅更新了《Codex 最佳实践指南》。这份指南不仅涵盖了从 Prompt 编写、规划模式到 AGENTS.md 配置的全流程，更深入讲解了如何利用 MCP 扩展边界、如何将重复工作转化为 Skills 和自动化流。官方更是首次披露了内部工作流：Codex 如何审查 100% 的 PR，以及如何通过 Git Worktrees 实现并行开发。

本文基于 OpenAI 官方《Best practices – Codex》文档编译整理。

📖 核心理念：Codex works best when...

OpenAI 在指南开篇即明确了 Codex 的最佳定位：

"Codex works best when you treat it less like a one-off assistant and more like a teammate you configure and improve over time." （当你不再把 Codex 当作一次性助手，而是当作一个可以不断配置、迭代和改进的队友时，它的效果最好。）

官方建议的思维框架是：从正确的任务上下文开始 → 使用 AGENTS.md 提供持久指导 → 配置 Codex 匹配你的工作流 → 通过 MCP 连接外部系统 → 将重复工作转化为 Skills → 自动化稳定的工作流。

接下来，我们将逐一拆解这六大步骤的官方最佳实践。

1️⃣ 强效起手：上下文与提示词 (Context and Prompts)

"Codex is already strong enough to be useful even when your prompt isn't perfect." （Codex 已经足够强大，即使你的提示词不完美，它依然有用。）

你可以直接扔给它一个难题，哪怕没有太多铺垫，它也能给出不错的结果。但清晰的提示词确实能让结果更可靠，尤其是在大型代码库或高风险任务中。

在大型或复杂的仓库中，最大的突破点在于给 Codex 提供正确的任务上下文和清晰的结构。官方建议，一个优秀的默认提示词应包含以下 四大要素：

目标 (Goal)：你想改变或构建什么？
上下文 (Context)：哪些文件、文件夹、文档、示例或错误与当前任务相关？（你可以使用 @ 提及特定文件作为上下文）。
约束 (Constraints)：Codex 应该遵循哪些标准、架构、安全要求或代码规范？
完成标准 (Done when)：在任务完成前，哪些条件必须满足？例如测试通过、行为改变、或 Bug 不再复现。

为什么这很重要？ 这能帮助 Codex 保持范围聚焦，减少假设，并产出更易于审查的工作成果。

💡 推理级别的选择 (Reasoning Level) 官方明确指出，应根据任务的难度选择推理级别：

Low：适用于快速、范围明确的任务。
Medium 或 High：适用于更复杂的变更或调试。
Extra High：适用于长期的、智能体性质的、需要重度推理的任务。

此外，官方还透露了一个小技巧：使用语音听写 (Speech Dictation)。在 Codex App 中，直接说出你想让它做什么，比打字能更快地提供上下文。

2️⃣ 复杂任务：先计划，后动手 (Plan First)

如果任务复杂、模糊或难以清晰描述，请在它开始写代码之前，要求 Codex 先进行计划。官方推荐以下三种方法：

🔹 使用 Plan 模式 (推荐) 对大多数用户来说，这是最简单有效的选项。Plan 模式允许 Codex 在实施之前收集上下文、提出澄清问题，并构建更强大的计划。你可以通过 /plan 命令或快捷键 Shift + Tab 切换此模式。
🔹 让 Codex 采访你 (Ask Codex to interview you) 如果你对想要什么只有模糊的想法，但不确定如何清晰描述，请让 Codex 先提问。告诉它挑战你的假设，在写代码之前，将这个模糊的想法转化为具体的需求。
🔹 使用 PLANS.md 模板 对于更高级的工作流，你可以配置 Codex 遵循 PLANS.md 或执行计划模板，用于长期或多步骤工作。

3️⃣ 沉淀团队知识：AGENTS.md

"Once a prompting pattern works, the next step is to stop repeating it manually. That's where AGENTS.md comes in." （一旦某种提示词模式奏效，下一步就是停止手动重复。这就是 AGENTS.md 的用武之地。）

把 AGENTS.md 想象成 给智能体看的 README。它会自动加载到上下文中，是记录你和团队希望 Codex 如何在仓库中工作的最佳场所。

一个优秀的 AGENTS.md 应涵盖：

仓库布局和重要目录。
如何运行项目。
构建、测试和 Lint 命令。
工程规范和 PR 期望。
约束和"Do-Not"规则。
"Done"的定义以及如何验证工作。

💡 快速上手与分层管理 CLI 中的 /init 命令是快速生成初始 AGENTS.md 的捷径。这是一个很好的起点，但你应该根据团队实际的构建、测试、审查和发布流程来编辑它。

你可以创建不同层级的 AGENTS.md：

全局级：放在 ~/.codex 中，用于个人默认设置。
仓库级：放在仓库根目录，用于共享标准。
目录级：放在子目录中，用于局部规则（越靠近当前目录的文件优先级越高）。

⚠️ 保持精简 一个简短、准确的 AGENTS.md 比一个充满模糊规则的长文件更有用。 从基础开始，只有当你注意到重复的错误时，才添加新规则。如果 AGENTS.md 变得太大，请保持主文件简洁，并引用特定任务的 Markdown 文件（如规划、代码审查或架构说明）。

当 Codex 犯了两次同样的错误时，要求它进行复盘 (retrospective)，然后更新 AGENTS.md。这样，指导始终保持实用，并基于真实的摩擦点。

4️⃣ 配置一致性 (Configure Codex for Consistency)

配置是让 Codex 在不同会话和界面中表现一致的主要方式。你可以设置模型选择、推理努力、沙盒模式、审批策略、配置文件和 MCP 设置的默认值。

官方推荐的配置模式：

个人默认：放在 ~/.codex/config.toml（在 Codex App 中：Settings → Configuration → Open config.toml）。
仓库特定：放在 .codex/config.toml。
命令行覆盖：仅用于一次性情况（如果你使用 CLI）。

config.toml 是你定义持久偏好的地方，包括 MCP 服务器、配置文件、多智能体设置和功能标志。你可以直接编辑，也可以要求 Codex 帮你更新。

🛡️ 沙盒与审批 Codex 自带操作系统级别的沙盒。两个关键旋钮：

审批模式 (Approval mode)：决定 Codex 何时请求运行命令的权限。
沙盒模式 (Sandbox mode)：决定 Codex 是否可以在目录中读写，以及它能访问哪些文件。

官方建议：如果你是编码智能体的新手，请从默认权限开始。 默认保持审批和沙盒的严格性，只在受信任的仓库或特定工作流中明确需要时才放宽权限。

5️⃣ 提升可靠性：测试与审查 (Testing and Review)

"Don't stop at asking Codex to make a change." （不要只停留在要求 Codex 进行变更上。）

要求它在需要时创建测试、运行相关检查、确认结果，并在你接受之前审查工作。Codex 可以为你完成这个循环，但前提是它知道“好”是什么样子的。这种指导可以来自提示词或 AGENTS.md。

这个循环应该包括：

为变更编写或更新测试。
运行正确的测试套件。
检查 Lint、格式化或类型检查。
确认最终行为符合请求。
审查 Diff，查找 Bug、回归或高风险模式。

💡 审查的最佳实践 在 Codex App 中，你可以切换 Diff 面板直接在本地审查变更。点击特定行提供反馈，这些反馈会作为上下文传递给 Codex 的下一次交互。

官方强烈推荐 /review 斜杠命令，它提供了几种代码审查方式：

基于 Base Branch 的 PR 风格审查。
审查未提交的变更。
审查特定 Commit。
使用自定义审查指令（如果你有 code_review.md 并在 AGENTS.md 中引用它，Codex 会在审查期间遵循这些指导）。

官方数据披露：“Codex shouldn't just generate code. With the right instructions, it can also help test it, check it, and review it.” 在 OpenAI 内部，Codex 审查了 100% 的 PR。你也可以在 GitHub 上配置自动审查，或让 Codex 在你 @Codex 时进行响应式审查。

6️⃣ 扩展边界：MCP、Skills 与自动化 (MCPs, Skills, Automations)

这是 Codex 从“代码助手”向“全能员工”进化的关键三步。

🔗 6.1 使用 MCP 连接外部上下文

当 Codex 需要的上下文存在于仓库之外时，请使用 MCP (Model Context Protocol)。它是一个开放标准，用于连接 Codex 与外部工具和系统，让你无需再反复复制粘贴实时信息到提示词中。

何时使用 MCP？

需要的上下文在仓库外。
数据频繁变化。
你希望 Codex 使用工具，而不是依赖粘贴的指令。
你需要跨用户或项目的可重复集成。

Codex 支持 STDIO 和 Streamable HTTP 服务器（带 OAuth）。在 App 中，前往 Settings → MCP servers 查看自定义和推荐服务器。你也可以使用 CLI 的 codex mcp add 命令添加。

官方忠告：“Add tools only when they unlock a real workflow. Do not start by wiring in every tool you use.”（只在工具能解锁真实工作流时才添加。不要一开始就把所有工具都接上。）

🛠️ 6.2 将重复工作转化为 Skills (技能)

一旦工作流变得可重复，就停止依赖长提示词或反复来回。使用 Skill 将指令、上下文和支持逻辑打包在 SKILL.md 文件中，Codex 应一致地应用这些逻辑。Skills 可在 CLI、IDE 扩展和 Codex App 中跨平台使用。

创建 Skill 的要点：

保持范围聚焦：每个 Skill 只负责一项工作。
从 2-3 个具体用例开始，定义清晰的输入和输出。
编写描述：说明 Skill 做什么以及何时使用。包含用户实际会说的触发短语。
不要试图一开始就覆盖所有边缘情况。从一个代表性任务开始，运行良好后，再将其转化为 Skill 并持续改进。
仅在实际提高可靠性时才包含脚本或额外资产。

经验法则：如果你不断重复使用同一个提示词或纠正同一个工作流，它就应该变成一个 Skill。

Skills 特别适用于：日志分类、Release Note 起草、PR 审查清单、迁移规划、遥测或事件总结、标准调试流程。

$skill-creator Skill 是搭建第一个版本的最佳起点。个人技能存储在 $HOME/.agents/skills，团队共享技能可以签入仓库的 .agents/skills 中。当准备广泛分享时，将其打包为 Plugin。

🤖 6.3 使用自动化 (Automations) 处理重复工作

一旦工作流稳定，你就可以安排 Codex 在后台为你运行它。在 Codex App 的 Automations 选项卡中，你可以选择项目、提示词、执行节奏（Cadence）和执行环境。

优秀的自动化候选任务包括：

总结最近的 Commits。
扫描潜在 Bug。
起草 Release Notes。
检查 CI 失败。
生成 Standup 总结。
按计划运行可重复的分析工作流。

官方给出了一个极其精辟的总结：

"Skills define the method, automations define the schedule." （技能定义方法，自动化定义调度。）

如果一个工作流仍需要大量引导，先把它变成 Skill。一旦它变得可预测，自动化就会成为力量倍增器。自动化不仅用于执行，还应用于反思和维护：回顾最近的会话，总结重复的摩擦点，并随时间改进提示词、指令或工作流设置。

7️⃣ 组织长期工作：会话控制 (Session Controls)

Codex 会话不仅仅是聊天记录。它们是工作线程 (Working Threads)，随时间积累上下文、决策和操作。因此，管理好它们对质量影响巨大。

CLI 中尤其有用的斜杠命令：

/experimental：切换实验性功能并添加到 config.toml。
/resume：恢复保存的对话。
/fork：创建新线程，同时保留原始记录。
/compact：当线程变长时，获取早期上下文的摘要版本（注意：Codex 也会自动压缩对话）。
/agent：当你运行并行智能体时，切换活动智能体线程。
/status：检查当前会话状态。

💡 会话管理最佳实践

保持一个连贯的工作单元对应一个线程。 如果工作仍是同一个问题的一部分，留在同一个线程通常更好，因为它保留了推理轨迹。
仅在工作真正分叉时才 Fork。
使用 Codex 的子智能体工作流 (Subagent Workflows) 从主线程卸载有边界的工作。保持主智能体专注于核心问题，使用子智能体进行探索、测试或分类。

🚫 官方避坑指南 (Common Mistakes)

官方最后列出了新手使用 Codex 时常犯的 8 个错误，请务必避免：

❌ 将持久规则塞满提示词（应该移到 AGENTS.md 或 Skill 中）。
❌ 不让智能体看到自己的工作（没有提供如何最佳运行构建和测试命令的细节）。
❌ 在多步和复杂任务上跳过计划。
❌ 在理解工作流之前就给 Codex 完全权限。
❌ 在同一文件上运行实时线程而不使用 Git Worktrees。
❌ 在手动执行还不可靠时就将重复任务转为自动化。
❌ 把 Codex 当作需要步步盯着工具（而不是与你的工作并行使用）。
❌ 一个项目只用一个线程（应该一个任务一个线程。这会导致上下文膨胀，长期结果更差）。

🌟 结语

OpenAI 的这份《Codex 最佳实践指南》不仅是一份工具说明书，更是一份现代 AI 工程团队的运作手册。

从 Prompt 的“四要素”结构，到 AGENTS.md 的团队知识沉淀；从测试、审查的闭环验证，到 MCP、Skills、自动化的三层进化；再到并行开发与子智能体的高效调度……Codex 正在重新定义“程序员”与“AI 队友”的协作边界。

正如官方所言：“Codex 不应该只是生成代码。有了正确的指令，它还能帮你测试、检查和审查。”

掌握这些最佳实践，你的 Codex 将不再是一个简单的代码补全工具，而是一个真正能理解业务、遵循规范、自主闭环的超级智能体员工。

🦞 龙虾之心 | OpenClaw Heart | AI 智能体成长伙伴