Codex 入门最佳实践「OpenAI官方」

最近很多朋友从cc转向codex，有很多人问我究竟怎么用codex，其实我觉得不用看任何资料视频，OpenAI官方就有最好的使用指南和case

传送门：

https://developers.openai.com/codex

从今天开始，我会挑选一些日常中普通人可能最需要的codex功能分享给大家

今天这篇来也是自在OpenAI官方的Codex使用最佳实践指南，适合小白从整体上入门codex，当然了不是说你要照着一条一条去做，做到心理有数也是好的。

核心观点只有一句话：把Codex当成需要持续配置和改进的队友，而不是一次性的助手。

还没安装codex（Mac上的体验是最好的，很多功能也是从Mac第一时间支持的），看这里：

https://chatgpt.com/zh-Hans-CN/codex/

具体怎么做？拆开来说。

第一件事：给任务提供完整上下文

Codex本身已经足够强，即使提示词不完美，也能给出不错的结果。但如果你在大型或复杂代码库里工作，给它足够的任务上下文，是解锁更好效果的关键。

一个好的提示词应该包含四个要素：

目标，也就是你想改变或构建什么；上下文，哪些文件、文档、示例或报错信息与当前任务相关，可以用@直接提及具体文件；约束条件，Codex需要遵循哪些标准、架构要求或规范；完成标志，任务结束的判断依据是什么，比如测试通过、行为改变、Bug不再复现。

推理强度也要根据任务难度来选。简单任务用低强度，复杂任务或调试用中高强度，长时间的推理密集型任务用最高强度。

另外，在Codex应用里，可以直接用语音输入来描述你想做什么，比打字快得多。

第二件事：复杂任务先规划再动手

如果任务复杂、模糊或者难以描述清楚，让Codex在开始写代码前先做规划。

有三种方式可以用：

方式一是Plan模式，这是最简单也最有效的选项。Plan模式让Codex先收集上下文、提出澄清问题，再制定更完善的计划。通过 /plan 或 Shift+Tab 切换。

方式二是让Codex来问你。如果你有个模糊的想法但不知道怎么描述，让Codex先采访你，挑战你的假设，把模糊的想法变成具体的需求，然后再写代码。

方式三是使用PLANS.md模板，适合更复杂的多步骤工作流。

第三件事：把好用的提示词沉淀到AgentS.md

一个提示词模式一旦跑通，就不要反复手动重复它。这正是AGENTS.md的用处。

把AGENTS.md理解为一个面向AI Agent的README文件。它会自动加载到上下文里，是告诉Codex如何在你的代码库里工作的最佳载体。

一份好的AGENTS.md应该涵盖：仓库结构和重要目录、项目启动方式、构建、测试和Lint命令、工程规范和PR要求、约束条件和禁止事项、任务完成的标准和验证方式。

CLI里的 /init 命令可以快速生成一个初始的AGENTS.md，作为起点，但需要根据团队的实际工作方式进行编辑。

AGENTS.md支持多层级：放在 ~/.codex 里的是个人全局默认配置，放在仓库根目录的是团队共享标准，放在子目录里的是局部规则，越具体的文件优先级越高。

保持简洁很重要。一个简短准确的AGENTS.md，比一个充满模糊规则的长文件更有用。从基础内容开始，发现Codex反复犯同一个错误时，让它做复盘，然后更新AGENTS.md。

如果AGENTS.md越来越大，可以保持主文件简洁，把规划、代码审查、架构等具体内容分别放到独立的markdown文件里，在主文件里引用即可。

第四件事：通过配置保持行为一致性

配置是让Codex跨会话、跨场景表现稳定的主要手段。可以配置的项目包括默认模型、推理强度、沙箱模式、审批策略、配置文件和MCP设置。

推荐的配置方式：

个人默认配置放在 ~/.codex/config.toml（在Codex应用里通过设置→配置→打开config.toml访问），仓库专属配置放在 .codex/config.toml，命令行覆盖只用于临时情况。

Codex有两个关键的权限控制项：审批模式决定Codex在执行命令前是否需要你的确认，沙箱模式决定Codex能读写哪些目录和文件。

刚开始使用编程Agent时，建议从默认权限开始，保持审批和沙箱设置较为严格，等你熟悉工作流之后，再对可信任的仓库或特定场景适当放开权限。

CLI、IDE插件和Codex应用共享同一套配置层。很多质量问题其实是配置问题，比如工作目录不对、缺少写权限、模型默认值不合适、缺少必要工具或连接器。

第五件事：让Codex测试并审查自己的代码

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

Codex可以完成这个完整的循环，前提是它知道什么叫好的结果。这个标准可以来自提示词或AGENTS.md。

具体包括：为改动编写或更新测试、运行相应的测试套件、检查Lint、格式化或类型检查、确认最终行为符合需求、审查diff是否存在Bug、回归或风险模式。

在Codex应用里，可以切换diff面板直接查看本地改动，点击具体的行可以提供反馈，这些反馈会作为上下文传入下一轮对话。

斜杠命令 /review 提供了几种代码审查方式：对比基础分支的PR式审查、审查未提交的改动、审查某个commit、使用自定义审查指令。

如果团队有 code_review.md 文件并在AGENTS.md里引用它，Codex在审查时也会遵循那些规范。这是让审查行为在多个仓库和贡献者之间保持一致的有效模式。

如果你使用GitHub Cloud，还可以设置Codex自动审查PR。OpenAI内部100%的PR都经过Codex审查，可以选择自动触发或者@Codex手动触发。

第六件事：用MCP连接外部系统

当Codex需要的上下文在代码库之外时，用MCP来连接。这样Codex就能直接访问你已经在用的工具和系统，不需要把实时信息反复复制粘贴到提示词里。

MCP，即模型上下文协议，是一个将Codex与外部工具和系统连接的开放标准。

适合用MCP的场景：所需上下文在代码库之外、数据频繁变化、想让Codex直接调用工具而不是依赖粘贴的说明、需要跨用户或项目可重复集成。

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

在Codex应用里，进入设置→MCP服务器可以查看自定义和推荐的服务器，Codex通常可以帮你安装所需的服务器，直接问它就行。在CLI里也可以用 codex mcp add 命令添加自定义服务器。

接入工具要有节制，只在能真正打通某个工作流的时候才加。从一两个能明确减少手动操作的工具开始，再逐步扩展。

第七件事：把可复用的工作流打包成技能

当一个工作流变得可重复时，就不要再依赖长提示词或反复来回了。把它做成Skill，打包进SKILL.md文件里，Codex会持续应用这套指令、上下文和支撑逻辑。技能在CLI、IDE插件和Codex应用里都能用。

每个技能只做一件事。从2到3个具体用例开始，定义清晰的输入和输出，描述要写清楚这个技能做什么以及什么时候用它，要包含用户实际会说的触发短语。

不需要一开始就覆盖所有边缘情况。先让一个典型任务跑通，再把它做成技能并持续优化。只在能提升可靠性的时候才加入脚本或额外资产。

如果你发现自己一直在复用同一个提示词或反复纠正同一个工作流，那它就应该变成一个技能。

技能特别适合这些场景：日志分析、发布说明起草、对照清单的PR审查、迁移规划、遥测或事故摘要、标准调试流程。

/skill-creator 技能是搭建第一个技能初版的最佳起点。先在本地迭代，准备好了再打包成插件分享。技能描述是最重要的部分，它要说清楚这个技能做什么以及什么时候用它。

个人技能存放在 $HOME/.agents/skills，团队共享技能可以提交到仓库里的 .agents/skills 目录，对新成员上手很有帮助。

第八件事：稳定的工作流交给自动化

一旦某个工作流稳定了，就可以让Codex在后台定时执行它。在Codex应用的自动化标签页里，可以选择项目、提示词、执行频率和运行环境。

可以调用技能作为提示词，还可以选择在独立的git工作树还是本地环境里运行。

适合自动化的任务包括：汇总近期提交、扫描潜在Bug、起草发布说明、检查CI失败、生成每日站会摘要、定时运行可重复的分析工作流。

有一个区分方式：技能定义方法，自动化定义时间表。如果一个工作流还需要大量人工引导，先把它做成技能，等它变得可预测了，自动化才能真正发挥放大效果。

自动化不只是执行，也可以用来做回顾和维护，比如定期审视最近的会话、总结反复出现的问题，然后持续优化提示词、指令或工作流设置。

第九件事：管理好长期运行的会话

Codex的会话不只是聊天记录，而是积累了上下文、决策和操作的工作线程，管理好它们对质量影响很大。

Codex应用里可以固定线程和创建工作树。如果用CLI，以下斜杠命令很实用：

/experimental 切换实验性功能并写入config.toml；/resume 恢复保存的对话；/fork 创建新线程同时保留原始记录；/compact 在线程过长时生成早期上下文的摘要版本（Codex也会自动压缩对话）；/agent 在并行运行多个Agent时切换活跃的Agent线程；/theme 选择语法高亮主题；/apps 在Codex里直接使用ChatGPT应用；/status 查看当前会话状态。

一个建议：每个连贯的工作单元保持一个线程。如果工作还是同一个问题的延续，待在同一个线程里通常更好，因为它保留了推理轨迹。只有当工作真正分叉时才fork。

可以用子Agent工作流把有边界的任务从主线程里分出去，让主Agent专注于核心问题，用子Agent处理探索、测试或分类这类任务。

最后：几个常见错误

刚开始用Codex时，有几个坑值得注意：

把持久性规则堆进提示词里，而不是放进AGENTS.md或技能；没有告诉Agent如何运行构建和测试命令，导致它看不到自己的工作结果；跳过多步骤复杂任务的规划阶段；还没搞清楚工作流就给Codex开放了完整权限；在同一批文件上并行运行多个会话却没用git工作树；在任务还不稳定的时候就把它变成自动化；像监工一样盯着Codex一步步执行，而不是让它并行工作；用一个线程对应一个项目而不是一个线程对应一个任务，导致上下文膨胀、效果变差。

把Codex用好，本质上是一套工程化的习惯养成过程：上下文给够，规范写进文件，重复的事情变成工具，稳定的工具交给自动化。