OpenAI Codex 是个"一个 agent 跨 CLI / IDE / App / 云"的编程助手——零配置也能用,但要在大型代码库里稳定产出,清晰的提示和一点点工程化设置会带来质的差别。这篇把官方的 best-practices 整理成中文,并在文末附上与 Claude Code 最佳实践的对照(很多理念是同构的,你可以横向迁移)。
一、第一步就用好:上下文与提示
Codex 即使在极简设置下也有价值,但好的提示在大代码库里会显著提升可靠性。官方推荐每条提示包含四个要素:
- 目标(Goal):要改什么、建什么?
- 上下文(Context):相关的文件、文件夹、文档、示例或报错——用
@提及。 - 约束(Constraints):规范、架构、安全要求、约定。
- 完成标准(Done when):什么算完成?比如"测试通过"“bug 解决”。
另外要按任务复杂度选推理档位:scoped 小任务用 Low,复杂改动用 Medium/High,超长的 agentic 工作用 Extra High。在 Codex App 里还能用语音听写更快地输入上下文。
二、难任务先规划,再写代码
复杂或含糊的任务,先规划再动手。三种方式:
- Plan 模式:用
/plan或Shift+Tab切换,让 Codex 先收集上下文、提澄清问题,再开始实现。 - Agent 访谈:让 Codex 反过来问你,把模糊想法逼成具体需求。
- PLANS.md 模板:进阶工作流,用一个文件管理多步骤工作。
三、用 AGENTS.md 把指导沉淀成可复用
AGENTS.md 是面向 agent 的 README,会自动载入上下文。一份好的 AGENTS.md 应包含:
- 仓库结构、重要目录
- 项目怎么跑起来
- 构建 / 测试 / lint 命令
- 工程约定、PR 规范
- 约束与禁止项
- 完成标准与验证方法
用 /init 可以在当前目录生成起步模板。AGENTS.md 文件分多个层级:全局(~/.codex/AGENTS.md)、仓库根目录(AGENTS.md)、子目录级(AGENTS.md)——Codex 会从项目根目录一路读到当前工作目录,越近的文件越具体。
进阶一点,每个目录里还可以放 AGENTS.override.md:Codex 会优先读取它,没有时才读同级的 AGENTS.md。如果你的团队已有其他说明文件名,可以用 project_doc_fallback_filenames 配置 fallback 名称;同时注意项目说明默认有 project_doc_max_bytes 上限(官方默认 32 KiB),太长会被截断,所以更推荐按目录拆小、保持主文件精简。
强调一句话:“一份简短而准确的 AGENTS.md,比一份充满含糊规则的长文件有用得多。” 当反复出现同类错误,就让 Codex 做个复盘(retrospective),据此更新指导。
这条和 Claude Code 把 CLAUDE.md “当代码维护、狠心精简"的理念完全一致——臃肿是大忌。
四、配置:让偏好跨会话一致
配置用来建立跨会话、跨界面的持久偏好,推荐三层结构:
- 个人默认:
~/.codex/config.toml - 仓库特定:
.codex/config.toml - 一次性覆盖:命令行参数
配置项涵盖模型选择、推理强度、sandbox 模式、审批策略、profiles、MCP 设置,也包括 project_doc_fallback_filenames、project_doc_max_bytes 这类项目说明文件加载规则。原则是:从默认权限起步,默认保持审批和 sandbox 收紧,只在信任的仓库或明确需要的工作流里逐步放宽。把环境搭对(正确的工作目录、写权限、模型默认值、工具/连接器)能从源头避免质量问题。
五、用测试和 review 提升可靠性
Codex 的工作流不该止于"生成代码”,还要验证:
- 写或更新测试
- 跑测试套件
- 执行 lint 和格式化检查
- 确认行为符合需求
- review diff,找 bug 和回归
/review 命令支持多种 review 模式:对照基分支的 PR 式 review、未提交改动 review、commit review、自定义 review 指令。团队可以维护一个 code_review.md、在 AGENTS.md 里引用它,让 Codex 应用一致的 review 标准。接上 GitHub Cloud 还能自动 review PR——官方提到 OpenAI 内部 100% 的 PR 都用 Codex review。
六、用 MCP 接入外部上下文
MCP(Model Context Protocol)把 Codex 连到外部工具和系统,省去手动复制信息。什么时候该上 MCP:
- 上下文在仓库之外
- 数据频繁变化
- 用工具比"复制一堆说明"更合适
- 可复用的集成能让多人/多项目受益
Codex 支持 STDIO 和 Streamable HTTP(带 OAuth)两种 server,在 App 里 Settings → MCP servers 添加,或 CLI 里 codex mcp add。
注意官方的告诫:“只在真正解锁某个工作流时才加工具”,别一上来把所有能连的服务都连上。
七、把重复活儿做成 skill
Skill 把指令打包成可复用的工作流,跨 CLI / IDE / App 通用。设计原则:
- 单一职责:一个 skill 干一件事
- 清晰的输入输出,配 2~3 个具体用例
- 描述性标题,点明用途和适用场景
- 写用户真正会说的触发短语
适合做成 skill 的场景:日志排查、发布说明起草、PR review、迁移规划、遥测汇总、调试流程。用 $skill-creator 这个 skill 能脚手架出初版,迭代期间存本地。存放位置:$HOME/.agents/skills(个人)、.agents/skills(团队仓库)。
关键还是描述:“它应该说清这个 skill 做什么、什么时候用。”
八、用 automation 调度重复工作
当工作流稳定下来,就可以在 Automations 标签里做后台定时调度:指定项目、提示(里面调用 skill)、执行节奏。适合:提交摘要、bug 扫描、发布说明、CI 失败检查、站会汇总、可复用分析。
一句话点透二者关系:“skill 定义方法,automation 定义节奏。” 而且 automation 不只是执行任务,还支持复盘维护——回看会话、找摩擦点、迭代改进。
九、用会话控制管理长任务
会话会不断累积上下文和决策,管理得好对质量影响很大。CLI 关键命令:
| 命令 | 作用 |
|---|---|
/resume |
恢复保存的对话 |
/fork |
保留记录的同时分叉出一条新线 |
/compact |
把前面冗长的上下文总结压缩 |
/agent |
在多个并行 agent 线程间切换 |
/status |
查看当前会话状态 |
/experimental |
开关实验特性 |
/apps |
在 Codex 内访问 ChatGPT apps |
/theme |
调语法高亮 |
原则:一条线程对应一个完整的工作单元,真正分叉时才 /fork。把有边界的任务(探索、测试、排查)交给 subagent,让主 agent 保持专注。
十、八个常见误区
| 误区 | 正解 |
|---|---|
| 把持久规则塞进提示里 | 写进 AGENTS.md 或 skill |
| 对 agent 藏着构建/测试命令细节 | 明确告诉它怎么跑 |
| 多步任务跳过规划 | 先 /plan |
| 过早授予全部权限 | 从默认权限起步,先保持收紧,再按需放宽 |
| 多条活跃线程改同一批文件却不用 worktree | 用 git worktree 隔离 |
| 把不可靠的工作流也自动化 | 先让流程稳定再上 automation |
| 事事盯着、不敢放手 | 善用并行 |
| 一个项目一条线程(而非一任务一线程) | 按任务拆线程,避免上下文劣化 |
小结与对照
Codex 的最佳实践可以浓缩成一条主线:把"一次性的提示"逐步沉淀为"可复用的工程资产"——好提示(四要素)→ 先规划 → AGENTS.md 固化规则 → 配置统一偏好 → 测试/review 把关 → MCP 接外部 → skill 封装 → automation 调度 → 会话控制收尾。
如果你也在用 Claude Code,会发现两者理念高度同构,概念几乎一一对应:
| 主题 | Codex | Claude Code |
|---|---|---|
| 项目级持久指令 | AGENTS.md |
CLAUDE.md(也读 AGENTS.md) |
| 先想后做 | /plan 模式 |
plan 模式 |
| 权限/隔离 | sandbox + 审批策略 | 六种权限模式 |
| 上下文压缩 | /compact |
/compact、/clear |
| 隔离探索 | subagent | subagent |
| 并行隔离 | git worktree | --worktree |
| 可复用工作流 | skill | skill |
| 接外部工具 | MCP | MCP |
关于
关注我获取更多资讯
