跳到主要内容

本文为非官方中文翻译，内容以 OpenAI 官方英文文档为准。
官方来源：https://developers.openai.com/codex/learn/best-practices

最佳实践

开始使用 Codex，以及获得更好结果的成熟实践

如果你刚接触 Codex，或者刚接触编码代理，这份指南将帮助你更快获得更好的结果。它涵盖了让 Codex 在 CLI、IDE extension 和 Codex app 中更高效的核心习惯，从提示与规划到验证、MCP、skills 和自动化。

当你不把 Codex 当作一次性的助手，而是把它当作一个你可以随着时间持续配置和改进的队友时，它的效果最好。

一个有用的思考方式是：从正确的任务上下文开始，使用 AGENTS.md 提供持久指导，配置 Codex 以匹配你的工作流，用 MCP 连接外部系统，把重复工作变成 skills，并将稳定的工作流自动化。

强有力的首次使用：上下文与提示​

即使你的提示并不完美，Codex 也已经足够强大，能够发挥作用。你通常可以在几乎不做准备的情况下直接交给它一个困难问题，依然得到很好的结果。清晰的prompting 不是获得价值的必要条件，但它确实能让结果更可靠，尤其是在大型代码库或高风险任务中。

如果你在大型或复杂的仓库中工作，最大的突破点在于为 Codex 提供正确的任务上下文，以及你希望它完成工作的清晰结构。

一个很好的默认做法，是在提示中包含四项内容：

  • Goal： 你想修改或构建什么？
  • Context： 哪些文件、文件夹、文档、示例或错误与这个任务相关？你可以用 @ 提及某些文件作为上下文。
  • Constraints： Codex 应该遵循哪些标准、架构、安全要求或约定？
  • Done when： 在任务完成之前，应该满足什么条件，例如测试通过、行为发生变化，或者某个 bug 不再复现？

这有助于 Codex 保持范围清晰、减少臆测，并产出更容易审查的工作结果。

根据任务难度选择推理级别，并测试什么设置最适合你的工作流。不同用户和任务，最佳设置也不同。

  • Low：适合更快、范围明确的任务
  • Medium 或 High：适合更复杂的变更或调试
  • Extra High：适合更长、更具代理性、推理负担更重的任务

为了更快提供上下文，试着在 Codex app 中使用语音听写， 用口述告诉 Codex 你想让它做什么，而不是手动输入。

先为困难任务制定计划​

如果任务复杂、模糊，或难以清楚描述，请让 Codex 在开始写代码之前先制定计划。

以下几种方法效果很好：

使用 Plan mode： 对大多数用户来说，这是最简单也最有效的选项。Plan mode 让 Codex 在实现前先收集上下文、提出澄清问题，并制定更扎实的计划。可使用 /plan 或 Shift+Tab 切换。

让 Codex 采访你： 如果你对自己想要什么只有一个大致想法，但不确定如何清楚表达，可以先让 Codex 向你提问。告诉它挑战你的假设，在写代码前把模糊的想法变成具体的内容。

使用 PLANS.md 模板： 对于更高级的工作流，你可以配置 Codex，让它在较长周期或多步骤工作中遵循 PLANS.md 或执行计划模板。更多细节见执行计划指南。

用 AGENTS.md 让指导可复用​

一旦某种提示模式开始奏效，下一步就是不要再手动重复它。这正是 AGENTS.md 的作用所在。

可以把 AGENTS.md 看作是面向 agents 的开放格式 README。它会自动加载进上下文，也是编码你和团队希望 Codex 在仓库中如何工作的最佳位置。

一个好的 AGENTS.md 应包括：

  • 仓库布局和重要目录
  • 如何运行项目
  • 构建、测试和 lint 命令
  • 工程约定和 PR 期望
  • 约束与禁止事项
  • “完成”意味着什么，以及如何验证工作结果

CLI 中的 /init 斜杠命令，是在当前目录中快速生成初始 AGENTS.md 的入门命令。这是一个很好的起点，但你应该编辑生成结果，使其符合你的团队实际构建、测试、审查和发布代码的方式。

你可以在不同层级创建 AGENTS.md 文件：位于 ~/.codex 中、用于个人默认设置的全局 AGENTS.md，用于共享标准的仓库级文件，以及子目录中更具体的局部规则文件。如果有一个离当前目录更近、也更具体的文件，则以那份指导为准。

保持实用。一个简短而准确的 AGENTS.md，比一个充满模糊规则的长文件更有用。先从基础内容开始，然后只在你注意到重复错误之后再添加新规则。

如果 AGENTS.md 开始变得过大，请保持主文件简洁，并引用任务专用的 markdown 文件，用于规划、代码审查或架构等内容。

当 Codex 两次犯下同样的错误时，让它做一次复盘，并更新 AGENTS.md。这样指导就会保持实用，并基于真实摩擦点。

配置 Codex 以保持一致性​

配置是让 Codex 在不同会话和不同使用界面中表现更一致的主要方式之一。例如，你可以设置 model 选择、推理强度、sandbox mode、approval policy、profiles 以及 MCP 设置的默认值。

一个良好的起始模式是：

  • 将个人默认设置保存在 ~/.codex/config.toml 中（在 Codex app 中：Settings → Configuration → Open config.toml）
  • 将仓库特定行为保存在 .codex/config.toml 中
  • 仅在一次性场景中使用命令行覆盖（如果你使用 CLI）

config.toml 是你定义持久偏好的地方，例如 MCP servers、profiles、多代理设置和 feature flags。你可以直接编辑它，也可以让 Codex 替你更新它。

Codex 自带操作系统级别的沙箱机制，并有两个你可以控制的关键旋钮。approval mode 决定 Codex 何时会请求你的许可来运行命令，sandbox mode 决定 Codex 是否可以在目录中读取或写入，以及代理可以访问哪些文件。

如果你刚开始使用编码代理，请从默认权限开始。默认情况下，让 approval 和 sandboxing 保持严格；只有在对可信仓库或特定工作流确实有需要时，再放宽权限。

请注意，CLI、IDE 和 Codex app 都共享同一套配置层。更多信息请参见示例配置页面。

尽早根据你的真实环境配置 Codex。许多质量问题 实际上都是设置问题，比如错误的工作目录、缺失写权限、 错误的 model 默认值，或缺少工具和连接器。

用测试和审查提升可靠性​

不要停留在让 Codex 做出变更这一步。必要时，也要让它创建测试、运行相关检查、确认结果，并在你接受之前审查工作内容。

Codex 可以替你完成这个循环，但前提是它知道“好”的标准是什么。这些指导既可以来自提示，也可以来自 AGENTS.md。

这可以包括：

  • 为变更编写或更新测试
  • 运行正确的测试套件
  • 检查 lint、格式化或类型检查
  • 确认最终行为符合请求
  • 审查 diff 中是否存在 bug、回归或高风险模式

在 Codex app 中切换 diff 面板，可以直接在本地审查变更。 点击某一特定行即可提供反馈，这些反馈会作为上下文传递给 Codex 的下一轮交互。

这里一个很有用的选项是斜杠命令 /review，它为你提供了几种审查代码的方式：

  • 基于某个 base branch 进行类似 PR 的审查
  • 审查未提交的变更
  • 审查某个 commit
  • 使用自定义审查说明

如果你和团队有一个 code_review.md 文件，并在 AGENTS.md 中引用它，那么 Codex 在审查时也可以遵循这些指导。对于希望在不同仓库和贡献者之间保持审查行为一致的团队来说，这是一个很强的模式。

Codex 不应该只生成代码。只要有合适的指令，它也可以帮助你测试、检查和审查代码。

如果你使用 GitHub Cloud，可以设置 Codex 来为你的 PR 运行代码审查。在 OpenAI，Codex 会审查 100% 的 PR。你可以启用自动审查，也可以让 Codex 在你 @Codex 时进行响应式审查。

使用 MCP 获取外部上下文​

当 Codex 所需的上下文存在于仓库之外时，请使用 MCP。它让 Codex 能连接到你已经在使用的工具和系统，因此你不必不断把实时信息复制粘贴到提示中。

Model Context Protocol，即 MCP，是一个用于将 Codex 连接到外部工具和系统的开放标准。

在以下情况下使用 MCP：

  • 所需上下文存在于仓库之外
  • 数据变化频繁
  • 你希望 Codex 使用工具，而不是依赖粘贴的说明
  • 你需要在不同用户或项目之间实现可重复的集成

Codex 同时支持带有 OAuth 的 STDIO 和 Streamable HTTP 服务器。

在 Codex App 中，前往 Settings → MCP servers 查看自定义和推荐的服务器。通常，Codex 可以帮助你安装所需的服务器。你要做的只是提出请求。你也可以在 CLI 中使用 codex mcp add 命令，通过名称、URL 和其他详细信息来添加你的自定义服务器。

仅在工具能真正解锁某个工作流时才添加它们。不要一开始就把 你使用的每个工具都接进来。先从一两个能明确消除你经常重复执行的 手动循环的工具开始，然后再逐步扩展。

将可重复的工作变成 Skills​

一旦某个工作流变得可重复，就不要再依赖冗长的提示词或反复来回沟通。使用一个 Skill，通过 SKILL.md 文件、上下文和支持性逻辑来封装 Codex 应持续一致应用的指令。Skills 可在 CLI、IDE 扩展和 Codex app 中使用。

让每个 skill 都只聚焦于一项工作。先从 2 到 3 个具体用例开始，定义清晰的输入和输出，并编写说明，明确 skill 做什么以及应在何时使用它。包含用户实际会说出的触发短语类型。

不要试图一开始就覆盖每个边缘情况。先从一个有代表性的任务开始，把它做好，然后把该工作流变成一个 skill，并在此基础上持续改进。只有在脚本或额外资源能提高可靠性时，才将它们加入。

一个很好的经验法则是：如果你不断重复使用同一个提示词，或不断修正同一个工作流，它大概率就应该变成一个 skill。

Skills 特别适合以下这类重复性工作：

  • 日志分诊
  • 发布说明起草
  • 按清单进行 PR 审查
  • 迁移规划
  • 遥测或事故总结
  • 标准调试流程

$skill-creator skill 是开始搭建 skill 首个版本的最佳起点。迭代期间，先将第一个版本保留在本地。准备好广泛共享后，再将其打包为一个 plugin。skill 最重要的部分之一是说明。它应明确说明 skill 的作用以及何时使用它。

个人 skills 存储在 $HOME/.agents/skills 中，而共享的团队 skills 可以检入仓库内的 .agents/skills。这对新团队成员的入门 尤其有帮助。

对重复工作使用 automations​

一旦某个工作流稳定下来，你就可以安排 Codex 在后台为你运行它。在 Codex app 中，automations 允许你为周期性任务选择项目、提示词、执行频率和执行环境。

一旦某项任务对你来说变得重复，你就可以在 Codex app 的 Automations 标签中创建一个 automation。你可以选择它运行在哪个项目中、它运行的提示词（你可以调用 skills）以及它的运行频率。你还可以选择 automation 是在专用的 git worktree 中运行，还是在你的本地环境中运行。进一步了解 git worktrees。

适合的候选任务包括：

  • 总结最近的提交
  • 扫描可能存在的 bug
  • 起草发布说明
  • 检查 CI 失败
  • 生成站会总结
  • 按计划运行可重复的分析工作流

一个有用的规则是：skills 定义方法，automations 定义计划。如果某个工作流仍然需要大量引导，先把它变成一个 skill。一旦它变得可预测，automation 就会成为效率倍增器。

不要只把 automations 用于执行，也要用于回顾和维护。审查 最近的会话，总结重复出现的阻碍，并随着时间推移改进提示词、 指令或工作流设置。

使用会话控制来组织长时间运行的工作​

Codex 会话不只是聊天记录。它们是会随着时间积累上下文、决策和操作的工作线程，因此妥善管理它们会对质量产生很大影响。

Codex app UI 让线程管理最为容易，因为你可以固定线程并创建 worktrees。如果你在使用 CLI，这些 slash commands 尤其有用：

  • /experimental：切换实验性功能并将其添加到你的 config.toml
  • /resume：恢复已保存的对话
  • /fork：在保留原始记录的同时创建一个新线程
  • /compact：当线程变得很长且你想要更早上下文的摘要版本时使用。注意 Codex 也会自动为你压缩对话
  • /agent：当你在运行并行 agents 且想在线程间切换当前活跃的 agent 时使用
  • /theme：选择语法高亮主题
  • /apps：直接在 Codex 中使用 ChatGPT apps
  • /status：检查当前会话状态

每个连贯的工作单元保持一个线程。如果工作仍属于同一个问题，保留在同一个线程中通常更好，因为这样可以保留推理轨迹。只有在工作确实分叉时才 fork。

使用 Codex 的 subagent 工作流，将边界明确的 工作从主线程中分流出去。让主 agent 专注于核心问题， 并使用 subagents 处理探索、测试或分诊等任务。

常见错误​

初次使用 Codex 时，需要避免的一些常见错误：

  • 用持久性规则把提示词塞得过满，而不是把它们移入 AGENTS.md 或某个 skill
  • 没有通过提供如何最佳运行构建和测试命令的细节，让 agent 看到自己的工作
  • 在多步骤和复杂任务中跳过规划
  • 在你理解工作流之前，就给 Codex 你的计算机完整权限
  • 在未使用 git worktrees 的情况下，在同一文件上运行实时线程
  • 在某个重复任务尚未能手动可靠完成之前，就把它变成一个 automation
  • 把 Codex 当成你必须逐步盯着看的东西，而不是在你自己工作时并行使用它
  • 按项目而不是按任务使用一个线程。这会导致上下文臃肿，并随着时间推移让结果变差