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