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