最佳实践

如果您对 Codex 或一般编码代理不熟悉，本指南将帮助您更快地获得更好的结果。它涵盖了使 Codex 在 CLI、 IDE 扩展 和 Codex app 中更有效的核心习惯，从提示和计划到验证、MCP、技能和自动化。

Codex works best when you treat it less like a one-off assistant and more like a teammate you configure and improve over time.

思考这个问题的一个有用方法是：从正确的任务上下文开始，使用 AGENTS.md 提供持久指导，配置 Codex 以匹配您的工作流程，使用 MCP 连接外部系统，将重复的工作转化为技能，并自动化稳定的工作流程。

Codex is already strong enough to be useful even when your prompt isn’t perfect. You can often hand it a hard problem with minimal setup and still get a strong result. Clear prompting isn’t required to get value, but it does make results more reliable, especially in larger codebases or higher-stakes tasks.

如果您在大型或复杂的存储库中工作，最大的解锁就是为 Codex 提供正确的任务上下文和清晰的结构来完成您想要完成的任务。

一个好的默认设置是在提示中包含四件事：

这有助于 Codex 保持范围，减少假设，并生成更容易审查的工作。

根据任务的难度选择推理级别，并测试最适合您的工作流程的推理级别。不同的用户和任务在不同的设置下效果最佳。

为了更快地提供上下文，请尝试在 Codex app 内使用语音听写来指示您希望 Codex 执行的操作，而不是键入它。

如果任务复杂、不明确或难以描述，请要求 Codex 在开始编码之前进行计划。

有几种方法效果很好：

使用计划模式：对于大多数用户来说，这是最简单且最有效的选项。计划模式让 Codex 收集背景信息、提出澄清问题并在实施之前制定更强有力的计划。使用 /plan 或 Shift+Tab 进行切换。

请 Codex 采访您：如果您大致了解自己想要什么，但不确定如何很好地描述它，请先请 Codex 向您提问。在编写代码之前，告诉它挑战您的假设并将模糊的想法变成具体的东西。

使用 PLANS.md 模板：对于更高级的工作流程，您可以将 Codex 配置为遵循 PLANS.md 或 execution-plan 模板来进行 longer-running 或 multi-step 工作。有关更多详细信息，请参阅 执行计划指南 。

一旦提示模式起作用，下一步就是停止手动重复它。这就是 AGENTS.md 的用武之地。

将 AGENTS.md 视为代理的 open-format README。它会自动加载到上下文中，并且是对您和您的团队希望 Codex 在存储库中工作的方式进行编码的最佳位置。

一个好的 AGENTS.md 涵盖：

CLI 中的 /init 斜线命令是 quick-start 命令，用于在当前目录中搭建启动器 AGENTS.md。这是一个很好的起点，但您应该编辑结果以匹配您的团队实际构建、测试、审查和发布代码的方式。

您可以在不同级别创建 AGENTS.md 文件：位于 ~/.codex 中的用于个人默认设置的全局 AGENTS.md、用于共享标准的 repo-level 文件以及用于本地规则的子目录中的更具体文件。如果有一个更具体的文件更接近您当前的目录，则该指南获胜。

保持实用。简短而准确的 AGENTS.md 比充满模糊规则的长文件更有用。从基础知识开始，只有在发现重复的错误后才添加新规则。

如果 AGENTS.md 开始变得太大，请保持主文件简洁，并参考 task-specific Markdown 文件进行规划、代码审查或架构等。

当Codex两次犯同样的错误时，要求其回顾并更新AGENTS.md。指导保持实用并基于真实的摩擦。

配置是使 Codex 在会话和表面上表现更加一致的主要方法之一。例如，您可以设置模型选择、推理工作、沙盒模式、批准策略、配置文件和 MCP 设置的默认值。

一个好的起始模式是：

config.toml 是您定义持久首选项的位置，例如 MCP 服务器、multi-agent 设置和功能标志。 Profile-specific 覆盖单独的 $CODEX_HOME/profile-name.config.toml 文件中的实时内容。

Codex ships with operating level sandboxing and has two key knobs that you can control. Approval mode determines when Codex asks for your permission to run a command and sandbox mode determines if Codex can read or write in the directory and what files the agent can access.

如果您不熟悉编码代理，请从默认权限开始。默认情况下保持严格的审批和沙箱，然后在需求明确后仅放宽受信任的存储库或特定工作流程的权限。

请注意，CLI、IDE 和 Codex app 均共享相同的配置层。在示例配置页面上了解更多信息。

尽早为您的真实环境配置 Codex。许多质量问题实际上都是设置问题，例如错误的工作目录、缺少写入权限、错误的模型默认值或缺少工具和连接器。

不要停止要求 Codex 进行更改。要求它在需要时创建测试，运行相关检查，确认结果，并在接受之前审查工作。

Codex can do this loop for you, but only if it knows what “good” looks like. That guidance can come from either the prompt or AGENTS.md.

这可以包括：

切换 Codex app 中的差异面板以直接在本地查看更改。单击特定行可提供反馈，该反馈将作为上下文提供给下一个 Codex 回合。

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

如果您和您的团队拥有 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.

如果您使用 GitHub Cloud，则可以设置 Codex 来为您的 PR 运行代码审查。在 OpenAI，Codex 审核了 100% 的 PR。您可以启用自动审核或在 @Codex 时让 Codex 进行反应性审核。

当上下文 Codex 需要位于存储库之外时，请使用 MCP。它允许 Codex 连接到您已经使用的工具和系统，因此您不必不断将实时信息复制并粘贴到提示中。

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

在以下情况下使用 MCP：

Codex supports both STDIO and Streamable HTTP servers with OAuth.

在 Codex App 中，前往“设置”→“MCP 服务器”以查看自定义和推荐的服务器。通常，Codex 可以帮助您安装所需的服务器。您所需要做的就是询问。您还可以在 CLI 中使用 codex mcp add 命令来添加自定义服务器及其名称、URL 和其他详细信息。

仅当工具解锁真正的工作流程时才添加工具。不要一开始就为您使用的每个工具接线。从一两个工具开始，这些工具可以清楚地消除您经常使用的手动循环，然后从那里进行扩展。

一旦工作流程变得可重复，请停止依赖长提示或重复的 back-and-forth。使用 技能 将指令打包在 SKILL.md 文件中，上下文和支持逻辑 Codex 应一致应用。 技能 适用于 CLI、IDE 扩展和 Codex app。

让每项技能只适用于一项工作。从 2 到 3 个具体用例开始，定义清晰的输入和输出，并编写描述，以便说明该技能的作用以及何时使用它。包括用户实际会说的触发短语类型。

不要试图预先涵盖所有边缘情况。从一项代表性任务开始，让它顺利运行，然后将该工作流程转化为一项技能，并从那里开始改进。仅当脚本或额外资产提高可靠性时才包含它们。

一个好的经验法则：如果您不断重复使用相同的提示或纠正相同的工作流程，它可能应该成为一项技能。

技能对于重复性工作特别有用，例如：

$skill-creator 技能是开始构建技能第一个版本的最佳位置。迭代时将第一个版本保留在本地。当准备好广泛共享时，将其打包为 插件 。技能最重要的部分之一是描述。它应该说明该技能的作用以及何时使用它。

个人技能存储在 $HOME/.agents/skills 中，共享团队技能可以签入存储库内的 .agents/skills 中。这对于新队友的入职特别有帮助。

一旦工作流程稳定，您可以安排 Codex 在后台为您运行它。在 Codex app 中， 自动化 允许您为重复任务选择项目、提示、节奏和执行环境。

一旦任务变得重复，您可以在 Codex app 的“自动化”选项卡中创建自动化。您可以选择它在哪个项目中运行、它运行的提示（您可以调用技能）以及它将运行的节奏。您还可以选择自动化是在专用 git 工作树中运行还是在本地环境中运行。了解有关 git 工作树的更多信息。

好的候选人包括：

一个有用的规则是技能定义方法，自动化定义时间表。如果工作流程仍然需要大量指导，请首先将其转变为技能。一旦可以预测，自动化就会成为力量倍增器。

使用自动化进行反思和维护，而不仅仅是执行。查看最近的会话，总结重复的摩擦，并随着时间的推移改进提示、说明或工作流程设置。

Codex sessions aren’t just chat history. They’re working threads that accumulate context, decisions, and actions over time, so managing them well has a big impact on quality.

Codex app UI 使线程管理变得最简单，因为您可以固定线程并创建工作树。如果您使用 CLI，这些 斜线命令 特别有用：

每个连贯的工作单元保留一个线程。如果工作仍然是同一问题的一部分，那么留在同一个线程中通常会更好，因为它保留了推理线索。仅当工作真正分支时才进行分叉。

使用 Codex 的 子代理 工作流程从主线程卸载有界工作。让主代理专注于核心问题，并使用 子代理 执行探索、测试或分类等任务。

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