最佳实践
如需完整文档索引，请参阅 llms.txt。文档页面的 Markdown 版本可通过在页面后追加
.md来获取 URL。
如果你刚开始使用 Codex，或刚接触编码 Agent，这份指南可以帮助你更快获得更好的结果。它涵盖了让 Codex 在 CLI、IDE extension 和 ChatGPT desktop app 中更高效的核心习惯，包括提示、规划、验证、MCP、技能和计划任务。
使用 Codex 时，最好不要把它当作一次性的助手，而要把它当作一个可以持续配置和改进的队友。
可以这样理解：先为任务提供正确的上下文，使用 AGENTS.md 保存持久化指导，将 Codex 配置为适合你的工作流，通过 MCP 连接外部系统，把重复性工作转化为技能，并自动化稳定的工作流。
良好的首次使用：上下文与提示
Section titled “良好的首次使用：上下文与提示”即使你的提示并不完美，Codex 也已经足够强大，可以提供帮助。你通常只需进行少量设置，就可以把棘手的问题交给它，并获得良好的结果。清晰的提示并不是获得价值的必要条件，但它可以让结果更加可靠，尤其是在大型代码库或高风险任务中。
如果你在大型或复杂的代码库中工作，最大的突破是为任务提供 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 预期
- 约束条件和禁止事项
- 完成的定义以及如何验证工作
该 /init 斜杠命令位于 CLI 中，是用于在当前目录搭建初始 AGENTS.md 的快速入门命令。它是一个很好的起点，但你应该编辑生成结果，使其符合团队实际构建、测试、评审和发布代码的方式。
你可以创建 AGENTS.md 文件并放在不同层级：全局 AGENTS.md 用于个人默认设置，位于 ~/.codex；仓库级文件用于共享标准；子目录中的更具体文件用于局部规则。如果当前目录附近有更具体的文件，则以该指导为准。
保持实用性。简短、准确的 AGENTS.md 比充满模糊规则的长文件更有用。先从基础内容开始，只有在发现反复出现的错误后，再添加新规则。
如果 AGENTS.md 开始变得过大，请保持主文件简洁，并引用特定任务的 Markdown 文件，例如规划、代码审查或架构相关文件。
当 Codex 两次犯下同一个错误时，让它进行回顾，并更新
AGENTS.md。这样，指导会始终实用，并以真实的摩擦点为基础。
配置 Codex 以保持一致性
Section titled “配置 Codex 以保持一致性”配置是让 Codex 在不同会话和界面中表现更加一致的主要方式之一。例如，你可以设置模型选择、推理强度、沙箱模式、审批策略、配置文件和 MCP 设置的默认值。
一个不错的起始模式是：
- 将个人默认设置保存在
~/.codex/config.toml（设置 > 配置 > 打开 config.toml 在 ChatGPT 桌面应用中） - 将仓库特定行为保存在
.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 桌面应用中切换差异面板，以便直接 评审 变更 本地内容。点击某一具体行即可 提供反馈，该反馈会作为上下文传递给下一 Codex 轮。
这里有一个实用选项：斜杠命令 /review 提供了多种代码审查方式：
- 针对基础分支进行 PR 风格的审查
- 审查未提交的更改
- 审查某个提交
- 使用自定义审查说明
如果你和团队拥有 code_review.md 文件，并在 AGENTS.md 中引用它，Codex 也可以在审查期间遵循其中的指导。对于希望在不同仓库和贡献者之间保持一致审查行为的团队来说，这是一种很好的模式。
Codex 不应只是生成代码。在适当的指令下，它还可以帮助你测试、检查和审查代码。
如果你使用 GitHub Cloud，可以设置 Codex 来运行 针对你的 PRs的代码评审。在 OpenAI， Codex 会评审 100% 的 PRs。你可以启用自动评审，或让 Codex 在你 @Codex时被动进行评审。
使用 MCPs 获取外部上下文
Section titled “使用 MCPs 获取外部上下文”当 MCPs 需要的上下文 Codex 位于仓库之外时，使用 Codex 。它让 ChatGPT 连接到你已经使用的工具和系统，因此你不必不断把实时信息复制粘贴到提示词中。
Model Context Protocol，即 MCP，是一种用于将 Codex 连接到外部工具和系统的开放标准。
以下情况适合使用 MCP：
- 所需上下文位于仓库之外
- 数据经常变化
- 你希望 Codex 使用工具，而不是依赖粘贴的指令
- 你需要在不同用户或项目之间复用某种集成
Codex 同时支持 STDIO 和 Streamable HTTP 服务器，使用 OAuth。
在 ChatGPT 桌面应用中，前往 设置 > MCP 服务器 以查看自定义和推荐服务器。通常， Codex 可以帮助你安装所需服务器。你只需要提出请求。你也可以使用 codex mcp add 中的 CLI 命令，通过名称、 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 中，计划任务允许你选择项目、提示、执行频率和重复性工作的执行环境。
从 计划任务 页面创建计划任务。选择项目、提示词、 执行频率，以及任务是在专用 Git 工作树中运行，还是在你的本地 环境中运行。提示词可以调用技能。了解更多关于 Git 工作树的信息。
适合的候选工作包括：
- 汇总近期提交
- 扫描可能存在的错误
- 起草发行说明
- 检查 CI 失败
- 生成站会摘要
- 按计划运行可重复的分析工作流
一个实用的规则是：技能定义方法，计划任务定义时间安排。如果工作流仍然需要大量引导，请先将其转化为技能。等它变得可预测后，再安排计划任务可以节省时间。
将计划任务用于反思和维护，而不仅仅是执行。回顾 最近的聊天，总结反复出现的阻碍，并随着时间改进提示词、说明 或工作流设置。
管理长期运行的聊天
Section titled “管理长期运行的聊天”聊天会随着时间积累上下文、决策和操作，因此妥善管理聊天会对质量产生很大影响。
ChatGPT desktop app 允许你置顶聊天并创建 worktree。如果你使用 CLI，以下斜杠命令尤其有用：
/experimental用于切换实验性功能并添加到你的config.toml/resume用于恢复已保存的聊天/fork用于在保留原始转录内容的同时创建新聊天/compact当聊天变长，而你希望获得早期上下文的摘要版本时使用。 Codex 也会自动压缩聊天/agent当你运行并行 Agent，并想在活跃 Agent 线程之间切换时使用/theme用于选择语法高亮主题/apps用于使用 ChatGPT 应用直接在 Codex/status用于检查当前会话状态
每个连贯的工作单元保留一个聊天。如果工作仍属于同一个 问题，留在同一个聊天中通常更好，因为它会保留 推理轨迹。只有当工作真正分支时才 fork。
使用 Codex的 子 Agent 工作流来 从主线程卸载有边界的工作。让主 Agent 专注于 核心问题，并将探索、测试或分诊等任务交给子 Agent。
初次使用 Codex 时，应避免以下几种常见错误：
- 在提示中堆积持久化规则，而不是将其移入
AGENTS.md或技能 - 不提供如何最佳运行构建和测试命令的详细信息，导致 Agent 无法查看自己的工作
- 在多步骤和复杂任务中跳过规划
- 在了解工作流之前就授予 Codex 计算机的完整权限
- 不使用 Git worktrees，却在相同文件上运行实时任务
- 在手动执行尚不可靠之前，就安排重复性任务
- 把 Codex 当作必须逐步监看的工具，而不是与自己的工作并行使用
- 为整个项目使用一个聊天，而不是每个连贯成果使用一个聊天。这会导致上下文随时间膨胀，结果变差