最佳实践
如果你刚开始使用 Codex，或刚接触编码 Agent，这份指南可以帮助你更快获得更好的结果。它涵盖了让 Codex 在 CLI、IDE extension 和 ChatGPT desktop app 中更加高效的核心习惯，包括提示、规划、验证、MCP、技能和计划任务。
使用 Codex 时，最好不要把它当作一次性的助手，而要把它当作一个可以持续配置和改进的队友。
可以这样理解：先为任务提供正确的上下文，使用 AGENTS.md 保存持久化指导，将 Codex 配置为适合你的工作流，通过 MCP 连接外部系统，把重复性工作转化为技能，并自动化稳定的工作流。
初次使用的关键：上下文与提示
Section titled “初次使用的关键：上下文与提示”即使你的提示并不完美，Codex 也已经足够强大，可以提供帮助。你通常只需进行少量设置，就可以把棘手的问题交给它，并获得良好的结果。清晰的提示并不是获得价值的必要条件，但它可以让结果更加可靠，尤其是在大型代码库或高风险任务中。
如果你在大型或复杂的代码仓库中工作，最大的突破在于为任务提供正确的上下文，并清晰地说明你希望完成什么。
一个不错的默认做法是在提示中包含以下四项内容：
- 目标： 你想要更改或构建什么？
- 上下文： 哪些文件、文件夹、文档、示例或错误与此任务相关？你可以使用 @ 提及某些文件，将其作为上下文。
- 约束： Codex 应遵循哪些标准、架构、安全要求或约定？
- 完成标准： 任务完成前应满足什么条件，例如测试通过、行为发生变化，或错误不再复现？
这有助于 Codex 保持任务范围明确、减少假设，并产出更易于审查的成果。
根据任务难度选择推理级别，并测试哪种设置最适合你的工作流。不同用户和任务适合的设置可能不同。
- Low：适用于更快完成、范围明确的任务
- Medium 或 High：适用于更复杂的更改或调试
- Extra High：适用于耗时较长、Agent 自主性较强且需要大量推理的任务
为了更快提供上下文，可以尝试在 ChatGPT desktop app 中使用语音听写，直接口述你希望 Codex 完成的任务，而不是手动输入。
困难任务先制定计划
Section titled “困难任务先制定计划”如果任务复杂、含糊不清，或难以准确描述，请先让 Codex 制定计划，再开始编写代码。
以下几种方法效果不错：
使用 Plan mode： 对大多数用户来说，这是最简单、最有效的选项。Plan mode 允许 Codex 收集上下文、提出澄清性问题，并在实现前制定更完善的计划。使用 /plan 或 Shift+Tab 切换。
让 Codex 采访你： 如果你对想要的结果只有一个粗略想法，但不确定如何清晰描述，可以先让 Codex 向你提问。告诉它先挑战你的假设，在编写代码前把模糊的想法转化为具体方案。
使用 PLANS.md 模板： 对于更高级的工作流，你可以配置 Codex 遵循 PLANS.md 或执行计划模板，以处理运行时间较长或包含多个步骤的工作。有关更多详情，请参阅执行计划指南。
使用 AGENTS.md 复用指导
Section titled “使用 AGENTS.md 复用指导”当一种提示模式发挥作用后，下一步就是停止手动重复它。这正是 AGENTS.md 的用途。
可以把 AGENTS.md 看作面向 Agent 的开放格式 README。它会自动加载到上下文中，是记录你和团队希望 Codex 如何在代码仓库中工作的最佳位置。
一份好的 AGENTS.md 应涵盖：
- 仓库布局和重要目录
- 如何运行项目
- 构建、测试和 lint 命令
- 工程约定和 PR 预期
- 约束条件和禁止事项
- 完成的定义以及如何验证工作
CLI 中的 /init 斜杠命令可以快速在当前目录生成初始 AGENTS.md。这是一个很好的起点，但你应根据团队实际构建、测试、审查和交付代码的方式编辑生成的内容。
你可以在不同层级创建 AGENTS.md 文件：位于 ~/.codex 中、用于个人默认设置的全局 AGENTS.md，用于共享标准的仓库级文件，以及位于子目录中、用于本地规则的更具体文件。如果距离当前目录更近的位置存在更具体的文件，则该指导具有更高优先级。
保持实用性。简短、准确的 AGENTS.md 比充满模糊规则的长文件更有用。先从基础内容开始，只有在发现反复出现的错误后，再添加新规则。
如果 AGENTS.md 开始变得过大，请保持主文件简洁，并引用特定任务的 Markdown 文件，例如规划、代码审查或架构相关文件。
当 Codex 两次犯下同一个错误时，让它进行回顾，并更新
AGENTS.md。这样，指导会始终实用，并以真实的摩擦点为基础。
配置 Codex 以保持一致性
Section titled “配置 Codex 以保持一致性”配置是让 Codex 在不同会话和界面中表现更加一致的主要方式之一。例如，你可以设置模型选择、推理强度、沙箱模式、审批策略、配置文件和 MCP 设置的默认值。
一个不错的起始模式是：
- 将个人默认设置放在
~/.codex/config.toml中（在 ChatGPT desktop app 中依次选择 Settings > Configuration > Open config.toml） - 将仓库专属行为放在
.codex/config.toml中 - 仅在一次性场景中使用命令行覆盖设置（如果你使用 CLI）
config.toml 用于定义持久化偏好，例如 MCP 服务器、多 Agent 设置和功能标志。特定配置文件的覆盖设置位于单独的 $CODEX_HOME/profile-name.config.toml 文件中。
Codex 提供操作系统级别的沙箱机制，并且有两个可由你控制的关键开关。审批模式决定 Codex 何时请求你许可其运行命令；沙箱模式决定 Codex 是否可以在目录中读取或写入，以及 Agent 可以访问哪些文件。
如果你刚开始使用编码 Agent，请从默认权限开始。默认情况下保持严格的审批和沙箱限制，只有在明确需要时，才针对受信任的仓库或特定工作流放宽权限。
请注意，CLI、IDE extension 和 ChatGPT desktop app 共享相同的配置层。详情请参阅示例配置页面。
尽早根据真实环境配置 Codex。许多质量问题实际上是设置问题，例如工作目录错误、缺少写入权限、模型默认设置错误，或缺少工具和连接器。
通过测试和审查提高可靠性
Section titled “通过测试和审查提高可靠性”不要只让 Codex 完成更改。在需要时让它创建测试、运行相关检查、确认结果，并在你接受成果前审查工作。
Codex 可以为你完成这个循环，但前提是它知道什么才算“好”。这些指导可以来自提示，也可以来自 AGENTS.md。
这可以包括：
- 为更改编写或更新测试
- 运行正确的测试套件
- 检查 lint、格式化或类型检查
- 确认最终行为符合请求
- 审查差异，检查错误、回归或有风险的模式
在 ChatGPT desktop app 中切换差异面板，可以直接在本地审查更改。点击特定行即可提供反馈，这些反馈会作为上下文传递给 Codex 的下一轮对话。
这里有一个实用选项：斜杠命令 /review 提供了多种代码审查方式：
- 针对基础分支进行 PR 风格的审查
- 审查未提交的更改
- 审查某个提交
- 使用自定义审查说明
如果你和团队拥有 code_review.md 文件，并在 AGENTS.md 中引用它，Codex 也可以在审查期间遵循其中的指导。对于希望在不同仓库和贡献者之间保持一致审查行为的团队来说，这是一种很好的模式。
Codex 不应只是生成代码。在适当的指令下，它还可以帮助你测试、检查和审查代码。
如果你使用 GitHub Cloud，可以设置 Codex 为你的 PR 执行代码审查。在 OpenAI，Codex 会审查 100% 的 PR。你可以启用自动审查，也可以在 @Codex 时让 Codex 响应式地进行审查。
使用 MCP 获取外部上下文
Section titled “使用 MCP 获取外部上下文”当 Codex 所需的上下文位于仓库之外时，请使用 MCP。它可以让 Codex 连接到你已经在使用的工具和系统，因此你不必再将实时信息反复复制粘贴到提示中。
Model Context Protocol，即 MCP，是一种用于将 Codex 连接到外部工具和系统的开放标准。
以下情况适合使用 MCP：
- 所需上下文位于仓库之外
- 数据经常变化
- 你希望 Codex 使用工具，而不是依赖粘贴的指令
- 你需要在不同用户或项目之间复用某种集成
Codex 同时支持带 OAuth 的 STDIO 和 Streamable HTTP 服务器。
在 ChatGPT desktop app 中，前往 Settings > MCP servers 查看自定义和推荐的服务器。通常，Codex 可以帮助你安装所需的服务器。你只需提出请求即可。你也可以在 CLI 中使用 codex mcp add 命令，通过名称、URL 和其他详细信息添加自定义服务器。
仅在工具能够解锁真实工作流时才添加它们。不要一开始就接入你使用的所有工具。先从一两个能够明显消除你经常执行的手动循环的工具开始，然后再逐步扩展。
将重复性工作转化为技能
Section titled “将重复性工作转化为技能”当工作流变得可重复后，不要再依赖冗长的提示或反复来回沟通。使用技能，将指令打包到 SKILL.md 文件、上下文和 Codex 应持续应用的辅助逻辑中。技能可跨 CLI、IDE extension 和 ChatGPT desktop app 使用。
让每项技能只负责一项工作。先从 2 到 3 个具体用例开始，定义清晰的输入和输出，并编写描述，说明技能的功能和使用时机。加入用户实际可能说出的触发短语。
不要一开始就试图覆盖所有边界情况。先从一个具有代表性的任务开始，将其完善，然后把该工作流转化为技能，再逐步改进。只有在确实能够提高可靠性时，才加入脚本或额外资源。
一个实用的经验法则是：如果你不断重复使用同一个提示，或不断纠正同一个工作流，它可能就应该成为一项技能。
技能尤其适用于以下重复性工作：
- 日志分类处理
- 起草发行说明
- 根据检查清单审查 PR
- 制定迁移计划
- 汇总遥测数据或事件
- 标准调试流程
$skill-creator 技能是为技能搭建第一个版本的最佳起点。在迭代期间，先将第一个版本保存在本地。准备好广泛共享时，将其打包为一个插件。技能最重要的部分之一是描述，它应说明技能的功能和使用时机。
个人技能存储在 $HOME/.agents/skills 中，共享的团队技能可以提交到仓库内的 .agents/skills 中。这对于帮助新团队成员入门尤其有用。
使用计划任务处理重复性工作
Section titled “使用计划任务处理重复性工作”当工作流稳定后，你可以安排 Codex 在后台为你运行。在 ChatGPT desktop app 中，计划任务允许你选择项目、提示、执行频率和重复性工作的执行环境。
在 Scheduled 页面创建计划任务。选择项目、提示、执行频率，以及任务是在专用 Git worktree 中还是在本地环境中运行。提示可以调用技能。详情请参阅 Git worktrees。
适合的候选工作包括：
- 汇总近期提交
- 扫描可能存在的错误
- 起草发行说明
- 检查 CI 失败
- 生成站会摘要
- 按计划运行可重复的分析工作流
一个实用的规则是：技能定义方法，计划任务定义时间安排。如果工作流仍然需要大量引导，请先将其转化为技能。等它变得可预测后，再安排计划任务可以节省时间。
使用计划任务进行复盘和维护，而不只是执行。定期查看近期聊天、总结反复出现的摩擦点，并持续改进提示、指令或工作流设置。
管理长期运行的聊天
Section titled “管理长期运行的聊天”聊天会随着时间积累上下文、决策和操作，因此妥善管理聊天会对质量产生很大影响。
ChatGPT desktop app 允许你置顶聊天并创建 worktree。如果你使用 CLI，以下斜杠命令尤其有用：
/experimental：切换实验性功能并将其添加到config.toml/resume：恢复已保存的聊天/fork：在保留原始聊天记录的同时创建新聊天/compact：当聊天变得很长且你希望获得早期上下文的摘要版本时使用。Codex 也会自动压缩聊天/agent：运行并行 Agent 时，在活动 Agent 线程之间切换/theme：选择语法高亮主题/apps：直接在 Codex 中使用 ChatGPT apps/status：查看当前会话状态
每个连贯的工作单元使用一个聊天。如果工作仍属于同一个问题，通常最好继续使用同一个聊天，因为这样可以保留推理过程。只有在工作真正分支时才创建分支。
使用 Codex 的 subagent 工作流，将范围明确的工作分派出去。让主 Agent 专注于核心问题，并将探索、测试或分类处理等任务交给子 Agent。
初次使用 Codex 时，应避免以下几种常见错误：
- 在提示中堆积持久化规则，而不是将其移入
AGENTS.md或技能 - 不提供如何最佳运行构建和测试命令的详细信息，导致 Agent 无法查看自己的工作
- 在多步骤和复杂任务中跳过规划
- 在了解工作流之前就授予 Codex 计算机的完整权限
- 不使用 Git worktrees，却在相同文件上运行实时任务
- 在手动执行尚不可靠之前，就安排重复性任务
- 把 Codex 当作必须逐步监看的工具，而不是与自己的工作并行使用
- 为整个项目使用一个聊天，而不是每个连贯成果使用一个聊天。这会导致上下文随时间膨胀，结果变差