TransCrab
← 返回

Codex 最佳实践

2026-03-12 · 原文链接

如果你刚开始使用 Codex，或者刚接触编码代理，这份指南会帮你更快拿到更好的结果。它覆盖了在 CLI、IDE 扩展 和 Codex 应用 中让 Codex 更高效的核心习惯：从提示与规划，到验证、MCP、技能和自动化。

当你把 Codex 从“一次性助手”改成“可长期配置和打磨的队友”来使用时，它的效果最好。

一个实用的思路是：先给对任务上下文，用 AGENTS.md 存放长期有效的指导，按你的工作流配置 Codex，用 MCP 连接外部系统，把重复工作沉淀成技能，再把稳定流程自动化。

强力起步：上下文与提示

即使你的提示词不完美，Codex 也已经足够强，能产生实际价值。很多时候，你只做最少准备就把一个难题交给它，也能得到不错的结果。清晰的 prompting 不是“有用”的前提，但它确实会让结果更可靠，尤其是在大型代码库或高风险任务里。

如果你在大型或复杂仓库中工作，最大的突破点是给 Codex 正确的任务上下文，并明确你希望它如何完成。

一个好的默认提示结构是包含四件事：

这样能帮助 Codex 保持范围聚焦、减少主观假设，产出更容易评审的结果。

根据任务难度选择推理等级，并实际测试哪种设置最适合你的流程。不同用户、不同任务的最佳配置并不相同。

为了更快提供上下文，你可以在 Codex 应用里用语音听写，把想做的事直接说给 Codex，而不是全靠手打。

如果任务复杂、含糊、或难以准确描述，先让 Codex 做计划，再开始写代码。

下面几种方式都很好用：

使用 Plan 模式： 对大多数用户来说，这是最简单也最有效的选项。Plan 模式会让 Codex 先收集上下文、提出澄清问题，再形成更扎实的执行计划。可用 /plan 或 Shift+Tab 切换。

让 Codex 先“采访”你： 如果你有一个模糊想法，但不知道怎么描述清楚，让 Codex 先问你问题。告诉它要挑战你的假设，把模糊想法先变成可执行内容，再写代码。

使用 PLANS.md 模板： 对更高级流程，你可以配置 Codex 按 PLANS.md 或执行计划模板来处理长周期或多步骤工作。详情见 execution plans guide。

当某种提示模式验证有效后，下一步就是别再手动重复它。这正是 AGENTS.md 的价值所在。

可以把 AGENTS.md 理解成面向代理的开放格式 README。它会自动载入上下文，也是你和团队在仓库里固化 Codex 工作方式的最佳位置。

一个好的 AGENTS.md 应覆盖：

CLI 里的 /init 斜杠命令可以快速在当前目录脚手架出一个起始版 AGENTS.md。这会是很好的起点，但你应该按团队真实的构建、测试、评审和发布流程做调整。

你可以在不同层级放置 AGENTS.md：放在 ~/.codex 的全局 AGENTS.md 用于个人默认，仓库级文件用于共享规范，子目录里更具体的文件用于局部规则。离当前目录更近且更具体的文件优先级更高。

务求实用。短小且准确的 AGENTS.md，比冗长但模糊的规则清单更有价值。先写基础内容，只有当你观察到重复错误时，再追加新规则。

如果 AGENTS.md 越写越大，保持主文件精简，并把规划、代码评审、架构等任务细则拆到独立 markdown 文件后再引用。

当 Codex 在同一件事上犯错两次时，让它做一次复盘，然后更新 AGENTS.md。这样沉淀出来的指导会始终贴近真实摩擦点。

配置是让 Codex 在不同会话和不同界面保持一致行为的核心手段之一。比如，你可以配置模型默认值、推理强度、沙箱模式、审批策略、profiles 和 MCP 设置。

一个不错的起步模式是：

config.toml 用于定义长期偏好，比如 MCP 服务器、profiles、多代理配置和实验特性。你可以直接编辑，也可以让 Codex 帮你改。

Codex 自带操作系统级沙箱能力，你主要可以控制两个关键旋钮：审批模式和沙箱模式。审批模式决定 Codex 在何时请求你批准命令；沙箱模式决定 Codex 是否能在目录中读写，以及代理可访问哪些文件。

如果你刚开始用编码代理，先用默认权限。默认情况下把审批和沙箱收紧，只有在信任仓库或明确场景确实需要时，再放宽权限。

注意：CLI、IDE 和 Codex 应用共享同一套配置层。更多信息见 sample configuration。

尽早把 Codex 配到你的真实环境。很多“质量问题”本质其实是“配置问题”：比如工作目录错了、没有写权限、模型默认不对、或者工具/连接器缺失。

别止步于“让 Codex 改代码”。你应该要求它在需要时补测试、运行相关检查、确认结果，并在你接受前先评审自己的改动。

Codex 可以帮你跑完整闭环，但前提是它知道什么叫“好结果”。这些标准可以来自你的提示，也可以来自 AGENTS.md。

这可以包括：

在 Codex 应用里切换 diff 面板，可以直接在本地 review changes。点击具体行可提交反馈，反馈会作为下一轮 Codex 的上下文。

这里一个很实用的命令是 /review，它提供几种代码评审方式：

如果你和团队有 code_review.md 文件，并在 AGENTS.md 中引用，Codex 也可以按这套规范执行评审。对于想在不同仓库和贡献者间保持评审一致性的团队，这是非常强的模式。

Codex 不该只负责“写代码”。在正确指令下，它还可以帮你 测试、检查和评审。

如果你在用 GitHub Cloud，可以配置 Codex 为你的 PR 执行 code reviews for your PRs。在 OpenAI 内部，Codex 会评审 100% 的 PR。你可以开启自动评审，或在需要时 @Codex 触发响应式评审。

用 MCP 接入外部上下文

当 Codex 需要的上下文不在仓库内时，就该用 MCP。这样 Codex 可以直接连接你已经在用的工具和系统，你不必再把实时信息反复复制粘贴进提示词。

Model Context Protocol（MCP）是把 Codex 连接到外部工具和系统的开放标准。

以下场景适合使用 MCP：

Codex 同时支持带 OAuth 的 STDIO 和 Streamable HTTP 服务器。

在 Codex 应用中，进入 Settings → MCP servers 可查看自定义与推荐服务器。很多情况下，Codex 也可以帮你安装所需服务器，你只需要开口提。你也可以在 CLI 中使用 codex mcp add 命令，通过名称、URL 等参数添加自定义服务器。

只在工具能真正解锁工作流时再接入，不要一开始就把你所有工具都接上。先从 1～2 个能明确消除你高频手工循环的工具开始，再逐步扩展。

当某个流程开始可重复时，不要再依赖长提示或反复来回沟通。用 Skill 把这套方法打包成 SKILL.md、上下文和配套逻辑，让 Codex 稳定复用。技能可跨 CLI、IDE 扩展和 Codex 应用生效。

每个技能尽量只做一件事。先定义 2～3 个具体用例，写清输入和输出，并在描述里明确“这个技能做什么、何时使用”，还要包含用户真实会说的触发语句类型。

别一上来就覆盖所有边界情况。先用一个代表性任务跑通流程，再把它沉淀成技能并持续改进。只有当脚本或附加资产确实提升可靠性时再加入。

一个经验法则：如果你总在复用同一段提示，或总在纠正同一类流程，它大概率就该变成一个技能。

技能尤其适合这些重复任务：

$skill-creator 技能是脚手架第一个技能版本的最佳起点，而 $skill-installer 技能可用于本地安装。技能中最关键的部分之一是描述：它必须明确这个技能做什么、何时使用。

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

当流程稳定后，你可以把它调度为后台定时任务。在 Codex 应用中，automations 允许你为重复任务选择项目、提示词、执行频率和执行环境。

一旦某件事对你来说开始重复，就可以在 Codex 应用的 Automations 页面创建自动化。你可以选择运行在哪个项目里、运行什么提示（也可以调用技能）、以及运行频率。你还可以选择让自动化在独立 git worktree 中运行，或直接在本地环境运行。更多见 git worktrees。

常见的高价值候选包括：

一个很实用的规则是：技能定义“方法”，自动化定义“时间表”。如果流程还需要大量人工引导，先把它打磨成技能；一旦可预测，自动化就会成为真正的效率放大器。

自动化不只用于执行，也适合做复盘和维护。定期回顾近期会话，汇总重复摩擦点，并持续优化提示、指令和工作流配置。

Codex 会话不只是聊天记录，它是会持续累积上下文、决策和动作的工作线程，所以线程管理质量会显著影响结果质量。

Codex 应用里的线程管理最轻松，因为你可以 pin 线程并创建 worktree。如果你在用 CLI，这些 slash commands 特别实用：

为每个“连贯工作单元”维护一个线程。如果工作仍属于同一个问题，通常留在同一线程更好，因为它保留了完整推理脉络。只有在工作真正分叉时再 fork。

使用 Codex 的 multi-agent 工作流，把边界清晰的工作从主线程卸载出去。让主代理专注核心问题，把探索、测试、分诊等任务交给子代理。

初次使用 Codex 时，常见误区有：