Codex 入门指南：获取更佳结果的最佳实践

如果你刚开始接触 @OpenAI Codex 或编程 Agent，本指南能帮你更快获得更好的结果。它涵盖了让 Codex 在 CLI、IDE 扩展和 Codex 应用中更高效的核心习惯，从提示和规划到验证、MCP、技能和自动化。

Codex 的最佳用法是，不要把它当成一次性的助手，而是当成一个需要你持续配置和优化的队友。

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

1. 通过清晰的上下文和提示让 Codex 在初次使用时表现强劲

即使你的提示不够完美，Codex 也已经足够强大，能派上用场。你通常可以给它一个难题，只需很少的设置就能得到不错的结果。清晰的提示并非获得价值的必要条件，但它能让结果更可靠，尤其是在较大的代码库或高风险的场景中。

如果你在一个大型或复杂的仓库中工作，最大的突破口通常是给 Codex 提供正确的任务上下文和明确的任务结构。

一个好的默认做法是在提示中包含以下四部分：

• 目标： 你想改变或构建什么？
• 上下文： 哪些文件、文件夹、文档、示例或错误与这个任务相关？你可以通过 @ 提及某些文件作为上下文。
• 约束： Codex 应遵循哪些标准、架构、安全要求或约定？
• 完成条件： 任务完成前应满足什么条件，例如测试通过、行为改变或 bug 修复？

这有助于 Codex 保持范围明确，减少假设，并产生更易于审查和验证的成果。

根据任务的难度选择合适的推理级别，并测试哪种设置最适合你的工作流。不同的用户和任务受益于不同的设置。

• 低：用于快速、范围明确的任务
• 中或高：用于更复杂的变更或调试
• 超高：用于长时间、智能体式、推理密集型任务

新用户提示

：大多数人通过先取得一些简单的小成果来快速上手，比如向 Codex 询问代码库的问题，或者用它做一个小范围的修复。强烈推荐在 Codex 应用中使用语音输入来加速迭代。

Codex 推理级别

2. 通过让 Codex 先规划来减少复杂任务中的错误

如果任务复杂、模糊或难以清晰描述，先让 Codex 规划，再开始编码。

有几种有效的方法：

使用计划模式： 对大多数用户来说，这是最简单、最有效的选项。计划模式让 Codex 收集上下文、提出澄清问题，并在实施前构建更完善的计划。通过 /plan 或 Shift+Tab 切换。

让 Codex 先采访你： 如果你对想要的东西有一个粗略的想法，但不确定如何很好地描述，让 Codex 先向你提问。告诉它挑战你的假设，在写代码之前把模糊的想法变成具体的方案。

使用 PLANS.md 模板： 对于更高级的工作流，你可以配置 Codex 遵循 PLANS.md 或执行计划模板，用于长时间运行或多步骤的工作。更多细节请查看我们的执行计划指南。

计划模式

3. 通过 AGENTS.md 让成功的指导可复用

一旦某个提示模式有效，下一步就是停止手动重复。这就是 AGENTS.md 发挥作用的地方。

将 AGENTS.md 视为面向 Agent 的 README。它是一个简单、开放的格式，会自动加载到上下文中，是编码你和团队希望 Codex 在仓库中如何工作的最佳位置。

一个好的 AGENTS.md 通常包括：

• 仓库布局和重要目录
• 如何运行项目
• 构建、测试和 lint 命令
• 工程规范和 PR 期望
• 约束和禁止规则
• 完成意味着什么，以及如何验证工作

CLI 中的 /init 斜杠命令是快速命令，用于在当前目录中搭建一个初始的 AGENTS.md。这是一个很好的起点，但你应该根据团队实际构建、测试、审查和发布代码的方式编辑结果。

你可以在多个级别创建 AGENTS.md 文件：一个全局的 AGENTS.md 放在 ~/.codex 中用于个人默认设置，一个仓库级别的文件用于共享标准，以及子目录中更具体的文件用于局部规则。如果当前目录附近有更具体的文件，则优先使用该指导。

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

如果 AGENTS.md 变得太大，保持主文件简洁，并引用特定任务的 markdown 文件，用于规划、代码审查或架构等事项。

提示

：当 Codex 两次犯同样的错误时，让它做一次回顾并更新 AGENTS.md。这样指导能保持实用，并基于实际痛点。

AGENTS.md 网站

4. 通过配置 Codex 匹配你的工作流来获得更一致的行为

配置是让 Codex 跨会话和界面表现更一致的主要方式之一。例如，你可以设置模型选择、推理级别、沙箱模式、审批策略、配置文件和 MCP 设置等的默认值。

一个好的起始模式是：

• 将个人默认设置放在 ~/.codex/config.toml 中（设置 → 配置 → 从 Codex 应用打开 config.toml）
• 将仓库特定行为放在 .codex/config.toml 中
• 仅在一对一场景下使用命令行覆盖（如果你使用 CLI）

Config.toml 是你定义持久偏好（如 MCP 服务器、配置文件、多 Agent 设置和实验性功能）的地方。你可以直接编辑它，或者让 Codex 为你更新。

Codex 内置了操作系统级别的沙箱，并提供了两个你可以控制的关键旋钮。审批模式决定了 Codex 何时需要你的许可才能运行命令，沙箱模式决定了 Codex 能否读取或写入目录，以及 Agent 可以访问哪些文件。

如果你是编程 Agent 的完全新手，建议从保守的默认权限开始。默认保持审批和沙箱严格，只有在明确需要时才对可信仓库或特定工作流放宽权限。

注意，CLI、IDE 和 Codex 应用共享相同的配置层。更多信息请查看我们的示例配置文档页面。

提示

：尽早为你的实际环境配置 Codex。很多质量问题实际上是设置问题，比如工作目录错误、缺少写权限、模型默认值不对，或者缺少工具和连接器。

5. 通过让 Codex 测试、验证和审查工作来提高可靠性

不要止步于让 Codex 做出更改。让它根据需要创建测试、运行相关检查、验证结果，并在你接受前审查工作。

Codex 可以为你完成这个循环，但前提是它知道“好”的标准。这个指导可以来自提示或 AGENTS.md。

它可以包括：

• 为变更编写或更新测试
• 运行正确的测试套件
• 检查 lint、格式或类型检查
• 确认最终行为符合要求
• 审查 diff 中的 bug、回归或风险模式

提示：

在 Codex 应用中切换 diff 面板，直接

审查更改 。点击特定行提供反馈，该反馈会作为上下文提供给 Codex 的下一次轮次。

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

• 针对基础分支进行 PR 风格的审查
• 审查未提交的更改
• 审查一个提交
• 使用自定义审查指令

如果你和团队有一个 code_review.md 文件，并在 AGENTS.md 中引用了它，Codex 可以在审查时遵循该指导。对于希望审查行为在仓库和贡献者之间保持一致的团队来说，这是一个强大的模式。

Codex 不应该只是生成代码。有了正确的指令，它还可以测试、验证和审查代码。

如果你使用 GitHub Cloud，可以轻松设置 Codex 来运行 PR 的代码审查。OpenAI 内部 100% 的 PR 都由 Codex 审查。你可以选择启用自动审查，或者让 Codex 在 @Codex 时进行响应式审查。

Codex CLI 中的 /review

6. 通过 MCP 将外部工具和实时上下文引入 Codex

当 Codex 需要的上下文位于仓库之外时，使用 MCP。它让 Codex 连接到你已经使用的工具和系统，这样你就不必反复将实时信息复制粘贴到提示中。

模型上下文协议（MCP）是一个开放标准，用于将 Codex 连接到外部工具和系统。

在以下情况下使用 MCP：

• 所需的上下文位于仓库之外
• 数据频繁变化
• 你希望 Codex 使用工具，而不是依赖粘贴的指令
• 你需要跨用户或项目重复的集成

Codex 同时支持 STDIO 和带 OAuth 的可流式 HTTP 服务器。

在 Codex 应用中，前往设置 → MCP 服务器查看自定义和推荐服务器。通常，Codex 可以帮助你安装所需的服务器。你只需要问一句。你也可以在 CLI 中使用 codex mcp add 命令，通过名称、URL 和任何附加信息添加自定义服务器。

提示

：仅在工具能解锁实际工作流时才添加。不要一开始就连接你使用的所有工具。从一两个能明显消除你经常做的手动循环的工具开始，然后逐步扩展。

MCP 服务器管理

7. 将重复工作流转化为可复用的技能

一旦某个工作流变得可重复，就不要再依赖长提示或反复来回。使用技能将指令打包成 SKILL.md 文件，以及 Codex 应一致应用的上下文和支持逻辑。技能在 CLI、IDE 扩展和 Codex 应用中均可使用。

每个技能应严格限定在一个任务上。从 2 到 3 个具体用例开始，定义清晰的输入和输出，并编写描述，明确说明技能做什么以及何时使用。包含用户实际会说的触发短语类型。

不要一开始就试图覆盖所有边缘情况。从一个代表性的任务开始，让它运行良好，然后将该工作流转化为技能，并在此基础上改进。仅当脚本或额外资产能显著提高可靠性时才包含它们。

一个很好的经验法则：如果你反复使用相同的提示或纠正相同的工作流，它很可能应该成为一个技能。

技能对于以下重复性工作特别有用：

• 日志分类
• 发布说明草稿
• 根据清单进行 PR 审查
• 迁移规划
• 遥测或事件摘要
• 标准调试流程

$skill-creator 技能是搭建技能第一个版本的最佳起点，然后使用 $skill-installer 技能在本地安装。技能最重要的部分之一是描述。它应该清楚地说明技能做什么以及何时使用。

提示

：个人技能存储在

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

技能创建和安装

Codex 应用技能 UI

8. 通过自动化在重复性工作上节省时间

一旦工作流稳定，你可以安排 Codex 在后台为你运行它。在 Codex 应用中，自动化让你选择项目、提示、频率和执行环境，用于重复性任务。

当某个任务对你来说变得重复时，你可以轻松地在 Codex 应用的自动化选项卡中创建自动化。你可以选择它在哪个项目中运行，运行什么提示（你可以调用技能），以及运行的频率。你还可以选择自动化是在专用的 git worktree 中运行，还是在你的本地环境中运行。了解更多关于 git worktrees 的信息。

好的候选包括：

• 总结最近的提交
• 扫描可能的 bug
• 起草发布说明
• 检查 CI 失败
• 生成站会摘要
• 按计划运行重复性分析工作流

一个有用的规则是：技能定义方法，自动化定义时间表。如果一个工作流仍需要大量调整，先将其转化为技能。一旦它变得可预测，自动化就会成为杠杆。

提示

：使用自动化进行反思和维护，而不仅仅是执行。回顾最近的会话，总结反复出现的痛点，并随着时间的推移改进提示、指令或工作流设置。

Codex 应用自动化创建

9. 通过会话控制在长时间运行的工作中保持有序

Codex 会话不仅仅是聊天历史。它们是工作线程，会积累上下文、决策和行动，因此良好管理它们对质量有很大影响。

在 Codex 应用 UI 中，管理多个线程最容易，你可以固定线程并创建 worktree。但如果你使用 CLI，以下斜杠命令特别有用：

• /experimental 切换实验性功能并添加到 config.toml
• /resume 恢复已保存的对话
• /fork 创建新线程，同时保留原始对话记录
• /compact 当线程变长时，获取早期上下文的摘要版本。注意，Codex 会自动为你压缩对话
• /agent 当你运行多个 Agent 并想在活跃 Agent 线程之间切换时使用
• /theme 选择语法高亮主题
• /apps 直接在 Codex 中使用 ChatGPT 应用
• /status 检查当前会话状态

每个独立的工作单元保持一个线程。如果工作仍然是同一个问题的一部分，通常留在同一个线程中更好，因为它保留了推理过程。只有当工作真正分支时才进行 fork。

提示

：

使用 Codex 的

多 Agent 工作流将限定任务从主线程中分离出来。让主 Agent 专注于核心问题，使用子 Agent 处理探索、测试或分类等任务。

10. 常见错误避免

初次使用 Codex 时的一些常见错误：

• 在提示中塞入持久规则，而不是将它们移到 AGENTS.md 或技能中
• 不让 Agent 看到自己的工作，即不提供如何最好地运行构建和测试命令的细节
• 在多步骤和复杂任务上跳过规划
• 在工作流被理解之前就让 Codex 拥有你计算机的完全权限
• 不使用 git worktree 就在同一文件上运行多个实时线程
• 在手动可靠之前就将重复性任务转化为自动化
• 与自己的工作进行并行使用 Codex，而不是将其视为需要逐步观察的东西

入门清单

1. 给 Codex 正确的目标、上下文、约束和完成条件
2. 对于困难任务，先让 Codex 规划
3. 创建初始的 AGENTS.md
4. 告诉 Codex 如何构建、测试、验证和审查
5. 设置匹配你工作流的配置默认值
6. 为高价值外部工具添加 MCP
7. 将重复工作流转化为技能
8. 一旦工作流稳定，使用自动化

你越是将你的工作流、标准和上下文转化为 Codex 可以使用的形式，你就越能看到 Agent 的真正能力。今天就开始吧！