中文 | English

如果你刚开始使用 Codex，或者刚开始接触 coding agents，这份指南会帮助你更快获得更好的结果。它覆盖了让 Codex 在 CLI、IDE 扩展 和 Codex app 中更有效的核心习惯，内容从提示与规划一直延伸到验证、MCP、skills 和 automations。

当你不再把 Codex 当成一次性助手，而是把它当成一个会随着时间被你持续配置和改进的队友时，它的效果最好。

一个有用的理解方式是：先提供正确的任务上下文，用 AGENTS.md 承载耐久指导，用配置让 Codex 贴合你的工作流，用 MCP 连接外部系统，把重复工作打包成 skills，并把稳定的工作流自动化。

强势起步：上下文与提示

即使你的提示并不完美，Codex 也已经足够强大，能够发挥价值。你经常可以只用很少的准备就把一个困难问题交给它，并得到很强的结果。清晰的 prompting 不是获得价值的前提，但它确实会让结果更可靠，尤其是在更大的代码库里，或者在风险更高的任务上。

如果你在一个大型或复杂的仓库里工作，最大的提升点就是给 Codex 提供正确的任务上下文，并明确说明你希望它完成什么。

一个很好的默认模式是在提示里包含四件事：

• Goal： 你想改什么或构建什么？
• Context： 这个任务相关的是哪些文件、目录、文档、示例或报错？你也可以用 @ 提到某些文件作为上下文。
• Constraints： Codex 需要遵守哪些标准、架构、安全要求或约定？
• Done when： 在任务完成之前，哪些条件必须成立，例如测试通过、行为发生变化，或者 bug 不再复现？

这会帮助 Codex 保持边界、减少假设，并产出更容易审查的工作。

根据任务难度选择推理强度，并测试什么设置最适合你的工作流。不同的用户和不同的任务，最适合的设置并不相同。

• 对更快、边界明确的任务使用 Low
• 对更复杂的改动或调试使用 Medium 或 High
• 对长时、agentic、强推理任务使用 Extra High

为了更快提供上下文，你可以尝试在 Codex app 中使用语音听写，把你想让 Codex 做什么直接说出来，而不是打字。

困难任务先规划

如果任务复杂、含糊，或者很难描述清楚，先让 Codex 规划，再开始写代码。

下面几种方式都很好用：

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

让 Codex 先采访你： 如果你大致知道自己想要什么，但不确定怎么准确描述，可以先让 Codex 向你提问。告诉它挑战你的假设，把模糊的想法变得具体之后再写代码。

使用 PLANS.md 模板： 对更高级的工作流，你可以配置 Codex 在更长或多步骤的任务中遵循 PLANS.md 或 execution-plan 模板。更多细节请参见 execution plans guide。

用 AGENTS.md 复用指导

一旦某种提示模式有效，下一步就是不要再手动重复它。这正是 AGENTS.md 的作用所在。

把 AGENTS.md 看作是面向 agents 的开放格式 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 app 里通过 Settings → Configuration → Open config.toml 打开）
• 把仓库特定行为保存在 .codex/config.toml 中
• 只在一次性场景里使用命令行覆盖（如果你使用 CLI）

config.toml 是你定义耐久偏好的地方，例如 MCP servers、profiles、多 agent 设置和 feature flags。你可以直接编辑它，也可以让 Codex 帮你更新。

Codex 自带操作系统级的沙箱机制，并有两个你可以控制的关键旋钮。Approval mode 决定 Codex 何时会请求你的许可来运行命令，sandbox mode 决定 Codex 是否能在目录里读写，以及 agent 可以访问哪些文件。

如果你刚开始使用 coding agents，请从默认权限开始。默认让 approval 和 sandboxing 保持严格，只在需求明确之后，再针对受信仓库或特定工作流放宽权限。

请注意，CLI、IDE 和 Codex app 共享同一套配置层。更多信息见 sample configuration 页面。

尽早让 Codex 贴合你的真实环境。很多质量问题其实都是 setup 问题，比如工作目录不对、缺少写权限、默认模型错误，或者缺少工具和 connectors。

通过测试与审查提升可靠性

不要只停留在让 Codex 做出改动。还要让它在需要时创建测试、运行相关检查、确认结果，并在你接受之前审查工作。

Codex 可以为你执行这个循环，但前提是它知道“好”长什么样。这些指导既可以来自 prompt，也可以来自 AGENTS.md。

这可以包括：

• 为改动编写或更新测试
• 运行正确的测试套件
• 检查 lint、格式化或类型检查
• 确认最终行为符合请求
• 审查 diff，查找 bug、回归或有风险的模式

在 Codex app 中切换 diff 面板，可以直接在本地 review changes。点击具体行即可提供反馈，这些反馈会作为上下文注入下一轮 Codex 交互。

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

• 按 base branch 做 PR 风格审查
• 审查未提交改动
• 审查某个 commit
• 使用自定义审查说明

如果你和团队有一个 code_review.md 文件，并在 AGENTS.md 里引用它，Codex 在审查时也能遵循这份指导。对于想让审查行为在不同仓库和贡献者之间保持一致的团队来说，这是很强的模式。

Codex 不应该只生成代码。在正确指导下，它也能帮你测试、检查和审查代码。

如果你使用 GitHub Cloud，可以把 Codex 配置成对你的 PRs 运行代码审查。在 OpenAI 内部，Codex 会审查 100% 的 PR。你既可以启用自动审查，也可以在 @Codex 时触发按需审查。

用 MCP 获取外部上下文

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

Model Context Protocol，也就是 MCP，是一个把 Codex 连接到外部工具和系统的开放标准。

在以下情况下使用 MCP：

• 所需上下文存在于仓库之外
• 数据变化频繁
• 你希望 Codex 使用工具，而不是依赖粘贴进来的说明
• 你需要跨用户或跨项目可复用的集成

Codex 同时支持 STDIO 和 Streamable HTTP 服务器，并支持 OAuth。

在 Codex App 中，前往 Settings → MCP servers 可以查看自定义和推荐的服务器。很多时候，Codex 还能帮助你安装所需服务器，你只需要开口即可。你也可以在 CLI 中使用 codex mcp add 命令，通过名称、URL 和其他细节添加自定义服务器。

只在工具真正解锁了现实工作流时才添加它们。不要一开始就把所有你用过的工具都接进来。先从一两个能明确消除你经常重复的手工环节的工具开始，然后再逐步扩展。

把可重复工作打包成 skills

一旦某个工作流开始变得可重复，就不要再依赖长 prompt 或反复往返说明。使用 Skill 把 Codex 需要稳定应用的说明、SKILL.md 文件、上下文和辅助逻辑打包起来。Skills 可跨 CLI、IDE 扩展和 Codex app 使用。

让每个 skill 聚焦于一件事。先从 2 到 3 个具体用例开始，定义清晰的输入和输出，并把 description 写成“这个 skill 做什么、何时使用它”。同时写进用户真的会说出来的触发短语类型。

不要试图一开始就覆盖所有边界情况。先从一个代表性任务开始，把它跑通，然后再把那个工作流沉淀成 skill，并在之后持续改进。只有在脚本或额外资产能提升可靠性时，才把它们加进去。

一条很好的经验法则是：如果你反复重用同一个 prompt，或者反复纠正同一条工作流，那它大概率应该成为一个 skill。

Skills 对以下重复任务尤其有用：

• 日志分诊
• release note 起草
• 按检查清单做 PR 审查
• migration 规划
• telemetry 或 incident 总结
• 标准化调试流程

$skill-creator skill 是构建 skill 第一版的最佳起点。先把第一版保留在本地迭代。等它准备好广泛共享时，再把它打包成 plugin。一个 skill 最重要的组成部分之一就是 description。它应该说明 skill 做什么，以及何时使用它。

个人 skills 存储在 $HOME/.agents/skills 中，共享团队 skills 则可以提交到仓库内的 .agents/skills。这对新同事入职特别有帮助。

为重复工作使用 automations

一旦某个工作流稳定下来，你就可以安排 Codex 在后台按计划运行它。在 Codex app 中，automations 允许你为重复任务选择项目、prompt、节奏和执行环境。

当某项任务开始反复出现时，你可以在 Codex app 的 Automations 标签页里创建一条 automation。你可以选择它运行在哪个项目里、使用什么 prompt（你可以调用 skills），以及运行频率。你也可以选择 automation 是在独立 git worktree 中运行，还是在本地环境中运行。更多信息请参见 git worktrees。

好的候选任务包括：

• 总结最近的 commits
• 扫描潜在 bug
• 起草 release notes
• 检查 CI failures
• 生成 standup summaries
• 在计划任务里运行可重复的分析工作流

一个有用的规则是：skills 定义方法，automations 定义日程。如果一个工作流仍然需要大量人工引导，先把它做成 skill。等它变得可预测后，automation 才会成为真正的倍增器。

不要只用 automations 来执行，也要用它们来反思和维护。回顾最近的 sessions，总结重复摩擦点，并持续改进 prompts、instructions 或工作流设置。

用 session controls 组织长时工作

Codex sessions 不只是聊天历史。它们是随着时间积累上下文、决策和操作的工作线程，因此管理方式会显著影响质量。

Codex app UI 让 thread 管理最简单，因为你可以 pin threads，也可以创建 worktrees。如果你使用 CLI，这些 slash commands 特别有用：

• /experimental 用于切换实验功能并把设置写入 config.toml
• /resume 用于恢复已保存的对话
• /fork 用于在保留原始 transcript 的同时创建新 thread
• /compact 用于在线程变长时生成较早上下文的摘要。注意，Codex 也会自动压缩对话
• /agent 用于在并行运行 agents 时切换当前活动 agent thread
• /theme 用于选择语法高亮主题
• /apps 用于在 Codex 中直接使用 ChatGPT apps
• /status 用于检查当前 session 状态

为每个连贯的工作单元保留一个 thread。如果工作仍属于同一个问题，通常继续待在同一个 thread 会更好，因为它保留了推理轨迹。只有当工作真的分叉时，再去 fork。

使用 Codex 的 subagent 工作流，把有边界的工作从主线程卸载出去。让主 agent 保持对核心问题的聚焦，而把探索、测试或分诊等任务交给 subagents。

常见错误

刚开始使用 Codex 时，有一些常见错误需要避免：

• 把耐久规则全部塞进 prompt，而不是迁移到 AGENTS.md 或 skill 中
• 没有给出如何最好地运行构建和测试命令的细节，导致 agent 看不到自己的工作结果
• 在多步骤和复杂任务上跳过规划
• 在还没理解工作流之前，就把对你电脑的全部权限交给 Codex
• 在不使用 git worktrees 的情况下，让 live threads 同时操作同一批文件
• 在工作流还不够可靠时，就把它做成 automation
• 把 Codex 当成必须逐步盯着看的东西，而不是和你自己的工作并行使用
• 每个项目只保留一个 thread，而不是每个任务一个 thread，这会导致上下文膨胀，并随着时间推移让结果变差