翻译 | OpenAI Codex 官方最佳实践指南

本文翻译自 OpenAI 官方文档 Codex Best Practices。
补充内容来源：@jxnlco 推文 — Getting the most out of Codex

概述

本指南涵盖了在 CLI、IDE 扩展和 Codex 应用中使用 Codex 的有效习惯。核心理念是：**”少把它当作一次性的助手，多把它当作一个你可以持续配置和改进的队友。”**

推荐的渐进路径：从提供良好的任务上下文开始，使用 AGENTS.md 进行持久化指导，为你的工作流配置 Codex，通过 MCP 连接外部系统，将重复性工作打包为 Skills，最后将稳定的工作流自动化。

延伸阅读 — 大多数开发者最初把编码智能体用于代码：检查仓库、生成 diff、跑测试、开 PR。但计算机上的大量工作本身就由代码介导：执行 shell 命令、浏览网页、调用 API、导出文档、响应事件、触发自动化。随着这些能力对 Codex 开放，它越来越不像狭义的”编码助手”，而更像一个完成计算机工作的系统。

良好的首次使用：上下文与提示词

即使没有完美的提示词，Codex 也能交付不错的结果，但清晰的提示词能在大型代码库或高风险任务中提升可靠性。

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

  • 目标（Goal） — 你想要改变或构建什么
  • 上下文（Context） — 相关的文件、文件夹、文档、示例或错误信息（使用 @ 提及）
  • 约束（Constraints） — 需要遵循的标准、架构、安全要求或惯例
  • 完成条件（Done when） — 完成时应该满足什么条件（测试通过、行为变更、Bug 修复）

推理级别

根据任务复杂度选择：

  • Low — 更快，适用于范围明确的任务
  • Medium 或 High — 复杂的变更或调试
  • Extra High — 长时间运行的、需要深度推理的智能体任务

Codex 应用中的语音输入可以加速上下文的传递。

复杂任务先规划

对于复杂或模糊的任务，让 Codex 先规划再编码。

三种方式：

  1. Plan 模式 — 使用 /plan 或 Shift+Tab 切换。Codex 会收集上下文、提出澄清问题，并在实施前制定计划。

  2. 采访式方法 — 让 Codex 先向你提问，挑战你的假设，将模糊的想法转化为具体方案。

  3. PLANS.md 模板 — 对于高级工作流，配置 Codex 按照执行计划模板来处理多步骤工作。

引导（Steering）与排队（Queuing） — 在 Codex 执行任务时，你有两种干预方式。引导是在当前步骤完成前打断它、纠正方向，比如在审查网页时说”把这个缩小”、”这两个元素间距不对”。排队则不打断当前任务，而是追加下一步，比如”做完之后把预览链接发到 Slack 给审查者”。引导改变 Codex 正在做的事，排队改变接下来该做的事。

使用 AGENTS.md 让指导可复用

AGENTS.md 是一个”面向智能体的开放格式 README”，会自动加载到上下文中。它记录了你希望 Codex 在仓库中如何工作。

应该包含的内容：

  • 仓库布局和重要目录
  • 如何运行项目
  • 构建、测试和 lint 命令
  • 工程惯例和 PR 期望
  • 约束和禁止事项
  • 完成定义和验证步骤

关键实践：

  • 在 CLI 中使用 /init 生成初始 AGENTS.md
  • 在不同层级放置文件：全局（~/.codex）、仓库级别、或子目录级别
  • 离当前目录更近的文件优先级更高
  • 保持简短准确，而非冗长模糊
  • 当 Codex 重复犯同一个错误时，让它做复盘（retrospective）并更新 AGENTS.md
  • 如果文件变得太大，保持主文件精简，引用特定任务的 markdown 文件

配置 Codex 以保持一致性

配置层级：

  • 个人默认配置：~/.codex/config.toml
  • 仓库级行为：.codex/config.toml
  • 命令行覆盖：用于一次性场景（仅 CLI）

关键控制项：

  • 审批模式（Approval mode） — Codex 何时请求运行命令的权限
  • 沙箱模式（Sandbox mode） — 智能体可以读写哪些文件

对新手的建议：默认保持审批和沙箱收紧，仅对受信任的仓库或特定工作流放宽。

配置在 CLI、IDE 和 Codex 应用之间共享。许多质量问题源于配置问题，如错误的工作目录、缺少写入权限或错误的模型默认值。

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

不要只让 Codex 做变更——还要让它：

  • 编写或更新测试
  • 运行相关测试套件
  • 检查 lint、格式化或类型检查
  • 确认最终行为符合请求
  • 审查 diff 中的 Bug、回归或风险模式

审查选项

/review 斜杠命令提供：

  • 对比 base 分支审查（PR 风格）
  • 审查未提交的变更
  • 审查某个 commit
  • 自定义审查指令

团队可以维护一个 code_review.md 文件，从 AGENTS.md 中引用，以保持一致的审查行为。GitHub Cloud 集成支持自动 PR 审查——OpenAI 使用 Codex 审查他们 100% 的 PR。

侧边面板（Side Panel）

侧边面板让工作产物紧贴在产生它的对话旁边，无需导出切换上下文。支持直接在产物上做标注（Annotations），标注会留在工作循环内。

Annotations — 文档和幻灯片可以在产生它的线程旁边打开，直接审查和修改

Sheets in Codex — 侧边面板中可以直接审查电子表格和数据表

内置浏览器让 Codex 可以检查渲染后的页面、控制它、并直接在审查的界面上响应标注。特别适合：index.html 轻量静态产物、Storybook UI 审查、Remotion Studio 程序化动画、基于浏览器的幻灯片、数据应用分析工作流。

浏览器侧边面板 — 网页既是输出也是控制界面

使用 MCP 获取外部上下文

MCP（Model Context Protocol，模型上下文协议）将 Codex 连接到外部工具和系统。

何时使用 MCP：

  • 上下文存在于仓库之外
  • 数据频繁变化
  • 你希望 Codex 使用工具，而非依赖手动粘贴的指令
  • 你需要跨用户或项目的可重复集成

Codex 支持 STDIO 和 Streamable HTTP 服务器（带 OAuth）。通过应用中的 Settings → MCP servers 或 CLI 中的 codex mcp add 进行配置。

建议：从一两个能消除手动循环的工具开始，然后再扩展——不要一次性接入所有工具。

工具与触达范围 — 当线程有了连续性，下一个问题就是它能作用于什么。Codex 可以逐层向外扩展：

  • $browser — 侧边面板中的内置浏览器，检查和标注网页
  • @chrome — 依赖用户登录状态的 Chrome 工作流
  • @computer — 只能通过桌面 GUI 完成的工作

Slack、Gmail、Calendar 之所以重要，是因为许多重要任务最初以消息、收件箱项目或日程问题的形式出现，然后才变成代码。

将重复性工作转化为 Skills

Skills 将指令、上下文和支持逻辑打包到一个 SKILL.md 文件中，可在 CLI、IDE 和应用中一致地使用。

Skill 设计原则：

  • 每个 Skill 专注于一项工作
  • 从 2-3 个具体用例开始
  • 定义清晰的输入和输出
  • 编写描述，说明 Skill 做什么以及何时使用
  • 包含用户实际会说的触发短语
  • 仅在能提升可靠性时才添加脚本或资源

适合做成 Skill 的场景：

  • 日志分类
  • Release Notes 起草
  • 按清单进行 PR 审查
  • 迁移规划
  • 遥测或事件摘要
  • 标准调试流程

使用 $skill-creator 生成第一个版本。个人 Skills 放在 $HOME/.agents/skills；团队共享 Skills 放在仓库中的 .agents/skills。

使用 Automations 处理重复性工作

当工作流稳定后，通过 Codex 应用中的 Automations 标签页将其调度为后台运行。配置项目、提示词（可调用 Skills）、执行频率和执行环境（专用 git worktree 或本地）。

适合自动化的场景：

  • 汇总最近的 commits
  • 扫描潜在 Bug
  • 起草 Release Notes
  • 检查 CI 失败
  • 生成站会摘要
  • 按计划运行可重复的分析

核心原则：**”Skills 定义方法，Automations 定义调度。”** 如果工作流仍需要引导，先将其做成 Skill。也可以将 Automations 用于反思和维护——审查会话、总结摩擦点、持续改进配置。

线程自动化示例 — 固定线程很有用，但它们仍然等待用户回来。线程自动化可以每隔几分钟或几小时检查一次，持续运行直到满足条件。例如一个”参谋长”线程每 30 分钟运行一次：

“每 30 分钟检查 Slack 和 Gmail 中需要我关注的未回复消息。帮我排列优先级。如果有人问我问题，尽可能深入研究答案并起草回复，但不要发送。”

当用户回来时，收集上下文的昂贵工作往往已经完成——人类仍然决定什么被发送。

使用会话控制组织长期工作

会话会随时间积累上下文、决策和操作。

有用的 CLI 斜杠命令：

  • /experimental — 切换实验性功能
  • /resume — 恢复已保存的对话
  • /fork — 创建新线程，保留原始记录
  • /compact — 压缩早期上下文（也会自动触发）
  • /agent — 在并行的 agent 线程间切换
  • /theme — 选择语法高亮主题
  • /apps — 在 Codex 中使用 ChatGPT 应用
  • /status — 检查当前会话状态

会话管理原则：

  • 每个连贯的工作单元一个线程
  • 如果工作属于同一个问题，留在同一个线程中（保留推理轨迹）
  • 仅在工作真正分叉时才使用 fork
  • 使用子智能体工作流将有界工作（探索、测试、分类）从主线程中卸载

Goals — 有明确终点的长期任务

Goals 是更长期运行的 Codex 任务，具有智能体可以持续推进的明确终点。

一个弱目标是”实现这个 Markdown 文件中的计划”；一个强目标有可衡量的成功标准。例如，工程师可以将内部工具从 Python 迁移到 Rust——新实现在单元测试通过之前不算完成。

Goal 结合了持续执行与验证器。用户定义结果、停止条件和判断是否在接近目标的信号。有用的验证器包括：

  • 测试套件
  • 基准测试
  • Bug 复现
  • 验证矩阵
  • 必须持续通过的端到端工作流

有雄心很重要，但没有验证就只是一个愿望。

共享记忆（Shared Memory）

长期运行的线程在共享单个对话之外的记忆时会变得更有用。一种持久模式是将持久线程锚定在 Obsidian vault 中——一个纯文件文件夹，易于检查、编辑、移动和长期保存。

1
2
3
4
5
6
vault/
├── TODO.md
├── people/
├── projects/
├── agent/
└── notes/

在顶层，AGENTS.md 可以定义 Codex 如何更新该工作空间。一个实用的配置：

  • 将 ~/vault 视为持久工作记忆
  • 优先使用规范笔记而非笔记蔓延
  • 明确路由 TODO、人员、项目、每日摘要和草稿笔记
  • 保留决策、阻塞项、负责人、日期和有用链接
  • 如果没有有意义的变化，不要搅动 vault

重要的上下文不应该只存在于对话记录中。把它写在下一个线程能接续的地方。

常见错误

错误做法 正确做法
在提示词中堆积持久性规则 写入 AGENTS.md 或 Skills
不提供构建/测试命令导致智能体无法验证 在 AGENTS.md 中写清楚
复杂任务跳过规划直接开干 先用 Plan 模式规划
在理解工作流之前就授予完整权限 默认收紧，按需放开
在同一文件上运行多个活跃线程 使用 git worktree 隔离
手动都没跑通就自动化 先手动验证可靠，再配置 Automation
盯着 Codex 一步步执行 让它并行运行，你去做别的事
每个项目只用一个线程 每个任务一个线程（避免上下文膨胀）

原文链接：OpenAI Codex Best Practices
推文来源：@jxnlco — Getting the most out of Codex