概述
如果你是 Codex 或编码智能体的新手，本指南将帮助你更快地获得更好的结果。它涵盖了在 CLI、IDE 扩展 和 Codex 应用 中提高 Codex 效率的核心习惯，包括提示词、规划、验证、MCP、技能和自动化。
Codex 在你将其视为可以随时间配置和改进的队友时效果最佳，而不是一次性的助手。
一个实用的思考方式：从正确的任务上下文开始，使用 AGENTS.md 提供持久指导，配置 Codex 以匹配你的工作流，使用 MCP 连接外部系统，将重复工作转化为技能，并自动化稳定的工作流。
良好的首次使用：上下文和提示词
即使你的提示词不够完美，Codex 也已经足够强大以提供价值。你通常可以用最少的设置将难题交给它，仍然获得良好的结果。清晰的提示词不是获得价值的必要条件，但它确实能让结果更可靠，特别是在大型代码库或高风险任务中。
如果你在大型或复杂的仓库中工作，最大的突破是给 Codex 正确的任务上下文和清晰的工作结构。
一个好的默认做法是在提示词中包含四个要素：
| 要素 | 说明 |
|---|---|
| 目标 (Goal) | 你试图改变或构建什么？ |
| 上下文 (Context) | 哪些文件、文件夹、文档、示例或错误与此任务相关？可以使用 @ 提及特定文件作为上下文。 |
| 约束 (Constraints) | Codex 应遵循哪些标准、架构、安全要求或约定？ |
| 完成标准 (Done when) | 任务完成前应该满足什么条件，例如测试通过、行为改变或 Bug 不再复现？ |
这有助于 Codex 保持范围清晰、减少假设，并产生更容易审查的工作。
根据任务的难度选择推理级别，并测试哪种设置最适合你的工作流。不同用户和任务适合不同的设置：
- Low（低）：适合更快、范围明确的任务
- Medium（中）或 High（高）：适合更复杂的更改或调试
- Extra High（极高）：适合长时运行、智能体化、推理密集的任务
为了更快地提供上下文，可以尝试在 Codex 应用中使用语音听写来口述你想让 Codex 做什么，而不是打字输入。
困难任务先规划
如果任务复杂、模糊或难以描述清楚，让 Codex 在开始编码前先进行规划。
以下几种方法效果很好：
使用规划模式 (Plan Mode)
对于大多数用户来说，这是最简单、最有效的选项。规划模式让 Codex 收集上下文、提出澄清问题，并在实施前制定更强大的计划。使用 /plan 或 Shift+Tab 切换。
让 Codex 采访你
如果你对自己想要什么有大致想法但不知道如何描述清楚，让 Codex 先向你提问。告诉它挑战你的假设，将模糊的想法转化为具体的东西，然后再编写代码。
使用 PLANS.md 模板
对于更高级的工作流，你可以配置 Codex 遵循 PLANS.md 或执行计划模板，用于长时运行或多步骤的工作。更多详情参见执行计划指南。
使用 AGENTS.md 使指导可复用
一旦某个提示词模式有效，下一步就是停止手动重复它。这就是 AGENTS.md 的用武之地。
将 AGENTS.md 视为智能体的开放式 README。它会自动加载到上下文中，是编码你和你的团队希望 Codex 在仓库中如何工作的最佳场所。
一个好的 AGENTS.md 应涵盖：
- 仓库布局和重要目录
- 如何运行项目
- 构建、测试和检查命令
- 工程约定和 PR 期望
- 约束和禁止事项
- “完成”的含义以及如何验证工作
CLI 中的 /init 斜杠命令是在当前目录快速生成入门 AGENTS.md 的命令。这是一个很好的起点，但你应该编辑结果以匹配你的团队实际构建、测试、审查和发布代码的方式。
你可以在不同级别创建 AGENTS.md 文件：
- 全局：
~/.codex中的个人默认设置 - 仓库级：共享标准
- 子目录：更具体的本地规则
如果当前目录附近有更具体的文件，该指导优先。
保持实用性。一个简短、准确的 AGENTS.md 比充满模糊规则的长文件更有用。从基础开始，只有在注意到重复错误后才添加新规则。
如果 AGENTS.md 开始变得太大，保持主文件简洁，并引用任务特定的 markdown 文件来处理规划、代码审查或架构等事项。
当 Codex 两次犯同样的错误时，让它进行回顾并更新 AGENTS.md。指导保持实用性并基于真实的摩擦。
配置 Codex 以保持一致性
配置是使 Codex 在会话和界面之间表现更一致的主要方式之一。例如，你可以设置模型选择、推理工作量、沙箱模式、审批策略、配置文件和 MCP 设置的默认值。
一个好的起始模式是：
- 将个人默认设置保存在
~/.codex/config.toml（Codex 应用：设置 → 配置 → 打开 config.toml） - 将仓库特定行为保存在
.codex/config.toml - 仅在一次性情况下使用命令行覆盖（如果你使用 CLI）
config.toml 是你定义持久偏好的地方，如 MCP 服务器、配置文件、多智能体设置和功能标志。你可以直接编辑它或让 Codex 为你更新。
Codex 内置操作系统级沙箱，有两个关键控制旋钮：
- 审批模式 (Approval mode)：决定 Codex 何时请求你运行命令的权限
- 沙箱模式 (Sandbox mode)：决定 Codex 是否可以在目录中读写以及智能体可以访问哪些文件
如果你是编码智能体的新手，从默认权限开始。默认保持审批和沙箱严格，然后仅在受信任的仓库或特定工作流需要时才放宽权限。
注意 CLI、IDE 和 Codex 应用都共享相同的配置层。更多信息参见示例配置页面。
尽早为真实环境配置 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 连接到你已经使用的工具和系统，这样你就不必不断将实时信息复制粘贴到提示词中。
Model Context Protocol（MCP）是连接 Codex 到外部工具和系统的开放标准。
使用 MCP 的场景：
- 需要的上下文存在于仓库之外
- 数据频繁变化
- 你希望 Codex 使用工具而不是依赖粘贴的指令
- 你需要跨用户或项目的可重复集成
Codex 支持 STDIO 和 Streamable HTTP 服务器与 OAuth。
在 Codex 应用中，前往设置 → MCP 服务器查看自定义和推荐的服务器。通常，Codex 可以帮助你安装所需的服务器。你只需要提出要求。你也可以在 CLI 中使用 codex mcp add 命令添加自定义服务器，包括名称、URL 和其他详细信息。
仅在工具解锁真实工作流时才添加工具。不要一开始就连接你使用的每个工具。从一两个明显消除你经常做的手动循环的工具开始，然后从那里扩展。
将重复工作转化为技能
一旦工作流变得可重复，停止依赖长提示词或重复的来回对话。使用技能将指令打包到 SKILL.md 文件中，Codex 应一致应用的上下文和支持逻辑。技能在 CLI、IDE 扩展和 Codex 应用中都能工作。
让每个技能只专注于一项工作。从 2-3 个具体用例开始，定义清晰的输入和输出，并编写描述说明技能做什么以及何时使用它。包括用户实际会说的触发短语类型。
不要试图一开始就覆盖所有边缘情况。从一个代表性任务开始，让它运行良好，然后将该工作流转化为技能并持续改进。仅在脚本或额外资产能提高可靠性时才包含它们。
一个好的经验法则：如果你不断重用相同的提示词或纠正相同的工作流，它可能应该成为一个技能。
技能特别适用于重复性工作，如：
- 日志分类
- 发布说明起草
- 针对检查清单的 PR 审查
- 迁移规划
- 遥测或事件摘要
- 标准调试流程
$skill-creator 技能是搭建技能第一个版本的最佳起点。在迭代时保持第一个版本为本地版本。当它准备好广泛分享时，将其打包为插件。技能最重要的部分之一是描述。它应该说明技能做什么以及何时使用它。
个人技能存储在 $HOME/.agents/skills，共享的团队技能可以检入仓库中的 .agents/skills。这对新团队成员入职特别有帮助。
使用自动化处理重复工作
一旦工作流稳定，你可以安排 Codex 在后台为你运行它。在 Codex 应用中，自动化让你选择项目、提示词、执行频率和执行环境来运行重复性任务。
一旦任务对你来说变得重复，你可以在 Codex 应用的自动化选项卡中创建自动化。你可以选择它运行的项目、运行的提示词（可以调用技能）以及运行频率。你还可以选择自动化是在专用 git worktree 中运行还是在本地环境中运行。了解更多关于 git worktrees 的信息。
良好的自动化候选任务：
- 总结最近的提交
- 扫描可能的错误
- 起草发布说明
- 检查 CI 失败
- 生成站会摘要
- 按计划运行可重复的分析工作流
一个有用的规则是：技能定义方法，自动化定义时间表。如果工作流仍需要大量指导，先将其转化为技能。一旦它可预测，自动化就成为力量倍增器。
将自动化用于反思和维护，而不仅仅是执行。审查最近的会话，总结重复的摩擦，并随时间改进提示词、指令或工作流设置。
使用会话控制组织长时运行的工作
Codex 会话不仅仅是聊天历史。它们是随时间积累上下文、决策和动作的工作线程，因此管理好它们对质量有很大影响。
Codex 应用 UI 使线程管理最容易，因为你可以固定线程并创建 worktrees。如果你使用 CLI，这些斜杠命令特别有用：
| 命令 | 用途 |
|---|---|
/experimental | 切换实验性功能并添加到 config.toml |
/resume | 恢复保存的对话 |
/fork | 创建新线程同时保留原始记录 |
/compact | 当线程变长时，对早期上下文进行摘要。注意 Codex 会自动为你压缩对话 |
/agent | 当你运行并行智能体时，在活动的智能体线程之间切换 |
/theme | 选择语法高亮主题 |
/apps | 在 Codex 中直接使用 ChatGPT 应用 |
/status | 检查当前会话状态 |
每个连贯的工作单元保持一个线程。如果工作仍然是同一问题的一部分，保持在同一线程通常更好，因为它保留了推理轨迹。仅在工作真正分支时才分叉。
使用 Codex 的子代理工作流将限定的工作从主线程卸载。保持主代理专注于核心问题，使用子代理处理探索、测试或分类等任务。
常见错误
首次使用 Codex 时应避免的一些常见错误：
| 错误 | 正确做法 |
|---|---|
| 在提示词中过载持久规则 | 将它们移入 AGENTS.md 或技能 |
| 不让智能体看到它的工作 | 提供如何最好地运行构建和测试命令的详细信息 |
| 在多步骤和复杂任务上跳过规划 | 使用规划模式 |
| 在理解工作流之前给 Codex 计算机的完全权限 | 从默认权限开始，逐步放宽 |
| 不使用 git worktrees 在同一文件上运行实时线程 | 使用 worktrees 隔离工作 |
| 在手动可靠之前将重复任务转化为自动化 | 先手动验证，再自动化 |
| 将 Codex 视为必须逐步监视的东西 | 将其与你自己的工作并行使用 |
| 每个项目使用一个线程而不是每个任务一个线程 | 每任务一线程，避免上下文膨胀 |
总结
| 实践 | 核心要点 |
|---|---|
| 提示词 | 目标、上下文、约束、完成标准四要素 |
| 规划 | 复杂任务先用 Plan Mode 或 PLANS.md |
| AGENTS.md | 持久指导，仓库级配置 |
| 配置 | config.toml 保持一致性 |
| 测试审查 | 让 Codex 测试、检查、审查自己的工作 |
| MCP | 连接外部工具和系统 |
| 技能 | 将重复工作打包为 SKILL.md |
| 自动化 | 稳定工作流后台自动运行 |
| 会话管理 | 每任务一线程，合理使用子代理 |
原文来自 OpenAI Developers 文档