by smallnest

Codex CLI 最佳实践：从入门到精通

Codex CLI 最佳实践：从入门到精通

OpenAI Codex CLI 是一款运行在终端中的 AI 编程智能体，采用 Rust 编写，主打高性能与高度可配置性。但工具再强，用不好也是白搭。这篇文章不是参考文档——它是一份实战经验总结，告诉你怎么把 Codex 用出最大价值。

一、心态转变：别把 Codex 当一次性助手

这是最重要的一条。OpenAI 官方说得明白：当你不再将 Codex 视为一次性的助手，而是将其视为一个可以随着时间推移不断配置和改进的队友时，它的效果会最好。

具体来说，这条演进路径是这样的：

  1. 给正确的任务上下文 — 每次对话的基础
  2. 用 AGENTS.md 做长期指导 — 不再重复啰嗦
  3. 配置 Codex 匹配你的工作流 — 省去每次手动设置
  1. 通过 MCP 连接外部系统 — 让 Codex 看到代码库之外的世界
  2. 把重复工作沉淀为技能 — 一次定义，反复调用
  3. 将稳定流程自动化 — 让机器干机器该干的事

二、写好提示词：四要素法则

Codex 已经足够强大，即使提示词不够完美也能产出有用结果。但在大型代码库或高风险任务中，清晰的提示词是可靠性的保障。

一个好的提示词应包含四个部分：

要素 说明 示例
目标 你想要改变什么或构建什么？ "为用户注册接口添加邮箱验证"
上下文 哪些文件、文件夹与此任务相关？ "参考 src/auth/register.ts 和 @docs/api-spec.md"
约束 必须遵守的规则和约定？ "遵循现有错误处理模式，使用 Zod 验证"
完成条件 什么标志着任务完成？ "所有测试通过，新接口返回正确状态码"

这种结构能让任务聚焦、减少臆测、产出更易审查的成果。

推理强度的选择

最强推理并不总是最好的选择。根据任务难度匹配推理级别：

  • 低：快速、范围清晰的任务（改个变量名、修个 typo）
  • 中/高：复杂改动或调试（跨模块重构、排查并发 bug）
  • 极高：长时间运行的代理式任务（从零搭建项目、大规模迁移）

三、困难任务先规划

当任务复杂、模糊或难以描述时，先让 Codex 制定计划再编码。这是新手最容易忽略的一步。

三种规划方式，从简到繁：

方式一：Plan 模式（最推荐）

输入 /plan 或按 Shift+Tab 切换。Plan 模式允许 Codex 在实现之前收集上下文、提出澄清问题、制定更完善的计划。

方式二：让 Codex 面试你

如果你对想要的东西只有一个粗略想法，先让 Codex 向你提问：

"我对这个功能有个大致想法，但你先问我问题，搞清楚再写代码。"

方式三：PLANS.md 模板

对于高级工作流，在 PLANS.md 中定义执行计划模板，处理耗时更长或步骤更复杂的任务。

四、AGENTS.md：写给 Agent 的 README

当某个 Prompt 奏效后，不要反复手动输入，写进 AGENTS.md。

AGENTS.md 是面向 Agent 的项目说明书，会自动加载进上下文。用 /init 命令在当前目录生成基础版，然后根据项目实际情况编辑。

应该写什么

一份实用的 AGENTS.md 通常包含：

  • 仓库结构与关键目录 — 让 Codex 知道代码在哪
  • 如何运行项目 — 构建和启动命令
  • 测试与 lint 命令 — 验证标准
  • 工程规范 — PR 期望、代码风格
  • 约束与禁止模式 — "不要用 any 类型"
  • 完成标准与验证步骤 — 怎么算做完了

多层级管理

AGENTS.md 可以在多层级目录中同时存在，各司其职：

位置 用途
~/.codex/AGENTS.md 个人默认设置
项目根目录 AGENTS.md 仓库共享标准
子目录 AGENTS.md 局部规则

保持简洁

一份简短准确的 AGENTS.md 比一份充斥着模糊规则的长文件更有用。 先从基础规则入手，在发现重复出现的错误后才添加新规则。如果文件变得过大，将细节拆到单独的 Markdown 文档里。

如果 Codex 犯了两次同样的错误，你可以要求它回顾并更新 AGENTS.md。

五、权限与沙箱：先紧后松

Codex 的安全模型包含两个维度：

  • 审批模式：决定何时需要用户确认命令
  • 沙箱模式：决定目录访问与文件权限

沙箱策略

策略 说明 适用场景
read-only 只读访问 代码审查、分析
workspace-write 可写工作区 日常开发（推荐）
danger-full-access 完全访问 受控环境的批量操作

实操建议

新手先保持权限偏紧，在明确需要后，仅对受信任的仓库或特定工作流放宽权限。

1
2
3
4
5
6
7
8
# 日常开发推荐：全自动 + 工作区写入
codex --full-auto --sandbox workspace-write "重构 auth 模块"

# 代码审查：只读模式
codex --sandbox read-only "审查 src/ 目录的代码质量"

# CI/CD 场景：非交互模式 + JSON 输出
codex exec --json "运行测试并修复失败的用例"

绝对不要做的事

永远不要将 --full-auto 与 --dangerously-bypass-approvals-and-sandbox（--yolo）组合使用。 需要额外目录权限时，用 --add-dir 而非 danger-full-access。

六、斜杠命令：高效交互的核心

掌握斜杠命令是提高效率的关键。按用途分为五类：

会话与流程控制

命令 用途 最佳实践
/new 新建会话 每个独立任务开新会话，避免上下文污染
/undo 撤销上一步 Codex 理解错意时快速回退
/compact 压缩历史 对话过长变慢时使用（Codex 也会自动压缩）
/fork 分叉会话 探索性想法独立出去，不影响主线
/resume 恢复会话 继续昨天的工作
/exit / /quit 退出程序 —
/logout 登出账号 切换 OpenAI 账号时

配置与权限

命令 用途 最佳实践
/approvals 设置权限模式 支持 Auto（建议）、Read Only、Full Access
/model 切换模型 简单任务用 mini 省钱，复杂架构用 o1
/status 查看状态 Token 用量、剩余上下文、权限模式
/mcp 管理 MCP 工具 调试外部工具连接
/experimental 切换实验特性 写入 config.toml，永久生效

上下文与记忆

命令 用途 最佳实践
/init 生成 AGENTS.md 项目必做！这是 Codex 的"项目记忆"
/mention 将文件加入上下文 Codex 找不到文件时显式提及
/diff 查看 Git 变更 提交前最后检查
/compact 压缩历史 上下文过长时释放 Token

动作与高级功能

命令 用途 最佳实践
/review 代码审查 多种模式：PR 式、未提交变更、指定提交
/plan Plan 模式 复杂任务先规划，Shift+Tab 切换
/goal 长时域目标模式 设定持久目标，Codex 持续推进直到完成
/skills 浏览技能 探索和安装实验性技能
/agent 多代理切换 子代理负责辅助任务
/theme 选择语法高亮主题 —
/apps 在 Codex 内使用 ChatGPT apps 直接调用 ChatGPT 应用

/goal：让 Codex 自己跑起来

这是 2026 年 5 月 Codex 0.128.0 版本新增的最重要的功能。OpenAI 总裁 Greg Brockman 的原话是："codex now has a built in Ralph loop++"。

以前的痛点：你给 Codex 一个指令，它处理一轮就停下。你再输入"继续"、"跑测试"、"修一下失败用例"……一轮一轮推，人成了最慢的节点。

/goal 的改变：你给 Codex 一个持久目标，它会把目标保存下来，自己一轮接一轮往下推进，直到完成、暂停、预算用完或卡住——真正实现无人值守。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 创建目标
/goal 迁移这个包到新 API 版本，并验证所有调用

# 查看当前目标状态（状态、耗时、Token 用量）
/goal

# 暂停
/goal pause

# 恢复
/goal resume

# 清空目标
/goal clear

目标有五种状态：active → paused / achieved / unmet / budget_limited

/goal 的四层机制

这不只是一个提示词模板，而是一整套目标生命周期管理：

  1. 持久化层 — 目标作为独立状态存起来，与对话历史分离。/compact 不会破坏目标状态，关掉终端后 codex resume 还能续上
  2. 完成审计 — 每轮结束后自动注入审计提示词，要求模型用真实证据而非"感觉做完了"来判定完成
  3. Token 预算软停止 — 预算耗尽时不会粗暴中断，而是总结进度、列出剩余工作后停下
  4. 生命周期控制 — 创建/暂停/恢复/清空由用户控制，模型只能标记"完成"

/goal 适用与不适用场景

适合用 /goal：

  • 重复性 + 持续性的批量任务（批量修 bug、批量生成测试）
  • 覆盖式任务（QA 完整流程、安全扫描、类型严格化）
  • 明确的工程任务（迁移模块、按规格文档实现功能）
  • 基于规格文档的实现（Spec-Driven Development）

不要用 /goal：

  • 单轮就能完成的小任务 — 杀鸡用牛刀，更慢更费 Token
  • 说不清"完成长什么样"的探索性任务 — 没有验收标准，Codex 会幻想目标
  • 需要用户不断决策的任务 — 产品决策、UX 偏好，Agent 替不了人
  • 破坏性、不可回滚的操作 — 风险会被放大
  • Plan 模式下 — 已知 Issue #20656：Plan 模式下 goal 不会自动延续

/goal 提示词的五段式黄金模板

/goal 对提示词的要求比普通对话高一个数量级。如果用模糊词（"全部"、"彻底"、"清理一下"），审计清单根本建不起来。

1
2
3
4
5
6
7
8
9
10
11
12
13
/goal <一句话描述目标>
Scope: <作用范围 — 改哪些文件/子系统，其他不要碰>
Constraints:
- <硬性约束 1 — 比如"不要修改数据库 schema">
- <硬性约束 2 — 比如"保持现有公开 API 不变">
Done when:
1. <可验证的产物 1 — 引用具体文件名或命令>
2. <可验证的产物 2>
3. <可验证的产物 3>
Stop if:
- <机械可识别的停止条件 1 — 比如"需要新依赖">
- <机械可识别的停止条件 2 — 比如"需要修改禁止列表中的文件">
Use a token budget of <N> tokens for this goal.

每一段的要点：

  • Objective：避开虚词。"全部"、"彻底"、"improve" 无法映射成清单，会让审计失效
  • Scope：画边界。Codex 是会扩散的，你不画它就乱跑
  • Constraints：硬性规则，违反就停。约束要"可机械识别"
  • Done when：验收清单。每条引用具体文件路径或命令（npm test 比"测试通过"明确）
  • Stop if：停止条件。比 Done when 更重要——防止 Codex 钻牛角尖或越界
  • Token budget：必给。没设预算 = 没有软停止 = 万一跑飞只能眼睁睁看着烧 Token

启用 /goal

/goal 是实验性功能，默认关闭。在 ~/.codex/config.toml 中添加：

1
2
[features]
goals = true

保存后重启 Codex 即可。

七、自定义 Slash 命令：杀手级功能

这是 Codex 与其他终端 Agent 的核心差异之一。你只需创建一个 Markdown 文件就能定义自己的斜杠命令。

怎么做

在 ~/.codex/prompts/ 目录下创建 Markdown 文件：

1
2
3
4
5
6
7
8
9
<!-- ~/.codex/prompts/security-audit.md -->
# Security Audit

请扫描当前代码库，查找以下漏洞：
1. SQL 注入
2. 硬编码的密钥
3. XSS 漏洞

并生成一份 Markdown 报告。

重启 Codex 后，输入 /security-audit 即可自动执行这套流程。

适合做成自定义命令的场景

  • 安全审计、代码规范检查
  • 项目初始化模板
  • 发布前的检查清单
  • 定格式的文档生成

八、MCP：让 Codex 连接外部世界

当所需的上下文信息位于代码库之外时，使用 MCP。它允许 Codex 连接到你已使用的工具和系统，无需不断复制粘贴。

什么时候该用 MCP

  • 所需上下文存在于代码库之外（Slack 讨论、Jira 任务）
  • 数据变化频繁（部署状态、监控指标）
  • 希望跨用户或项目保持一致的集成

配置 MCP 服务器

1
2
3
4
5
6
7
8
9
10
11
# 列出已配置的 MCP 服务器
codex mcp list

# 添加 stdio 类型的 MCP 服务器
codex mcp add my-server -- npx -y @my/mcp-server

# 添加 HTTP 类型的 MCP 服务器
codex mcp add my-http --url https://example.com/mcp

# 删除服务器
codex mcp remove my-server

九、技能（Skills）：把重复工作模式化

一旦工作流程变得可重复，不要再依赖冗长的提示或反复的沟通。用技能将指令、上下文和逻辑打包到 SKILL.md 文件中。

技能设计原则

  • 每项技能只做一件事 — 不要做大而全的"万能技能"
  • 先列出 2-3 个具体用例 — 明确定义输入和输出
  • 包含用户实际会用的触发短语 — 方便调用
  • 先跑通再迭代 — 不要一开始就考虑所有极端情况

经验法则

如果你不断重复使用相同的提示词或纠正相同的工作流程，它就应该成为一项技能。

适合做成技能的场景：

  • 日志分类与模式识别
  • 起草发布说明
  • 按检查清单进行 PR 评审
  • 迁移规划
  • 监控数据汇总
  • 调试流程

技能存放位置

位置 用途
$HOME/.agents/skills 个人技能
仓库内 .agents/skills 共享技能

十、Agent 友好型 CLI：给 Codex 造专用工具

这是 Codex 团队成员 Nick Baumann 分享的实战心得，也是高级用法中最有价值的一条。

核心思路

MCP 连接器解决了"能不能访问"的问题，但原始数据往往过于庞大且杂乱。更好的做法是把常用操作封装成一个带参数、输出 JSON、有帮助文档的 CLI 命令。

Codex 本身就擅长用命令行——它会搜索、加 flag 筛选、把上一个命令的结果串到下一个命令里，不需要你教它怎么调。

Agent 友好型 CLI 的特征

  • 支持搜索和缩小范围
  • 支持重试和管道输出
  • 能写入大文件
  • 有 --help 文档
  • 能根据上一步结果生成下一步命令

Nick Baumann 的三个实战案例

CLI 工具 解决的问题 做法要点
codex-threads Codex 会话存档噪音多，直接读又慢又乱 本地建索引，支持搜索、定位、读取历史会话
slack-cli Slack 频道中找不到过往技术决策讨论 搜索定位具体消息链，一条命令拿到结果
typefully-cli 不想每次让 Codex 重新学 API 让 Codex 读 API 文档编译出 Rust CLI，只暴露常用操作

核心原则：如果你发现自己反复在给 AI 喂同一类乱糟糟的数据，那就别再解释了，给它造个命令。

Codex 官方提供了 cli-creator 技能帮你用 Codex 自己造 CLI。

十一、会话管理：每个任务一个线程

Codex 会话不仅是聊天记录，它们是随着时间推移积累上下文、决策和行动的工作线程。妥善管理会话对质量有重大影响。

核心原则

  • 每个连贯的工作单元保持一个线程 — 同一问题保留推理过程
  • 工作真正分支时才分叉 — 用 /fork 创建新线程
  • 上下文膨胀时压缩 — 用 /compact 做摘要
  • 使用 multi-agent 拆出边界清晰的任务 — 主代理专注核心问题，子代理负责探索、测试

会话相关命令

1
2
3
4
5
6
7
8
9
10
11
# 恢复最近会话
codex resume --last

# 恢复指定会话
codex resume <SESSION_ID>

# 搜索所有目录的会话
codex resume --last --all

# 分叉最近会话为新线程
codex fork --last

十二、自动化：稳定之后再上

当你发现某个任务开始重复，可以在 Codex 的 Automations 页创建自动化。选择运行项目、执行 prompt（可以调用技能）和执行节奏。

适合自动化的任务

  • 总结最近提交
  • 扫描潜在 bug
  • 起草发布说明
  • 检查 CI 故障
  • 定期运行可重复的分析流程

重要原则

技能定义方法，自动化定义节奏。 如果工作流程仍然需要大量人工干预，先做成技能，稳定后再自动化。

自动化不仅用于执行，也用于反思和维护——回顾最近的会话，总结反复出现的问题，持续改进提示、说明或工作流设置。

十三、配置文件：持久化你的偏好

配置可以确保 Codex 在不同会话和界面上行为一致。

配置文件层级

文件 用途
~/.codex/config.toml 个人默认配置
.codex/config.toml 仓库级配置
命令行参数 临时覆盖

常见配置项

  • 默认模型
  • 推理强度
  • 沙箱模式
  • 审批策略
  • MCP 服务器
  • 配置文件（Profile）
  • 多代理设置

命令行常用启动方式

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
# 带初始提示启动
codex "帮我分析这个项目"

# 附加图片（多模态）
codex -i screenshot.png "这个 UI 有什么问题？"

# 加载配置文件
codex --profile work

# 使用本地开源模型
codex --oss

# 启用网络搜索
codex --search

# 设置工作目录
codex --cd /path/to/project

# 授予额外目录写入权限
codex --add-dir /path/to/data

# 非交互模式（CI/CD）
codex exec --json "运行测试并生成报告"

十四、测试与 Review：不只是生成代码

使用 AI Agent 不要停留在生成代码这一步。要求它创建测试、运行检查、确认结果，并在接受更改之前审查变更。

常见验证步骤

  1. 编写或更新测试
  2. 执行相关测试套件
  3. 检查 lint、格式化或类型检查
  4. 确认行为符合需求
  5. 评审 diff，排查回归或风险模式

/review 的多种模式

  • 针对基础分支进行 PR 式审查
  • 审查未提交的变更
  • 审查指定提交
  • 自定义审查指令

如果你和团队有一个 code_review.md 文件并在 AGENTS.md 中引用，Codex 可按该指南进行评审——这对保持团队审查行为一致性非常有效。

十五、常见错误清单

错误 正确做法
把持久规则塞进提示里 移到 AGENTS.md 或技能中
没让 Agent 看到构建和测试命令 写进 AGENTS.md
复杂任务不做规划 先用 /plan 制定方案
还没理解流程就给全部权限 先紧后松，逐步放开
在同一文件上并行运行多个线程 使用 git worktree 隔离
流程还不稳定就做成自动化 先做成技能，稳定后再自动化
把 Codex 当需要逐步盯着执行的工具 让它做你的并行队友
一个项目只用一个线程 每个任务一个线程，避免上下文膨胀
/goal 用模糊词写目标 用五段式模板，确保目标可被映射成审计清单
/goal 不设 Token 预算 必须设 Token budget，否则跑飞无法软停止
Plan 模式下用 /goal 先退出 Plan 模式，再启动 /goal
单轮小任务用 /goal 杀鸡用牛刀，直接用普通 prompt 更快更省

总结：Codex 使用成熟度模型

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
Level 1：基础使用
  └─ 正确写提示词（四要素），选对推理强度

Level 2：项目管理
  └─ AGENTS.md + 配置文件，让 Codex 理解项目

Level 3：工具扩展
  └─ MCP 连接外部系统 + 自定义斜杠命令

Level 4：工作流沉淀
  └─ 技能化重复任务 + Agent 友好型 CLI

Level 5：长时域自主
  └─ /goal 持久目标 + Spec-Driven Development + Token 预算治理

Level 6：自动化运维
  └─ 稳定流程自动化 + 持续反思改进

核心心法：Codex 不是更强的搜索引擎，而是一个需要你持续培养的队友。你投入在配置、技能和工作流上的时间，会在后续每一次交互中复利回报。而 /goal 让这个队友终于能"打持久战"了——但前提是你得给它一个可被审计的目标。