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