Codex 蓝皮书：从安装到实战的全链路使用指南

非官方开源指南 · 持续更新版
写给开发者、独立开发者和 AI 工具重度用户的 OpenAI Codex 使用手册。

本书的事实基础主要来自 openai/codex 仓库在 2026-09-03 的源码——命令定义、配置字段、沙箱与审批模式、斜杠命令及其官方描述，都是从实现里直接读出来的，而不是凭记忆写的。

Codex 迭代很快，安装方式、模型名称、额度、入口位置和命令参数都可能变化。涉及具体功能和价格时，请以 Codex 官方文档、codex --help 和你账号实际显示为准。

阅读入口

• 在线阅读（本书网页版）
• Markdown 原稿
• Codex 官方文档 · openai/codex 源码

0. 使用说明

0.1 重要声明

• 本资料为非官方指南，不代表 OpenAI 官方文档。
• 所有功能以官方文档和你本地的 Codex 实际版本为准。
• 书中的命令、配置键名、枚举值都标注了来源，建议边读边用 codex --help 和 /status 在自己的终端里验证一遍。
• Codex 是滚动发布的。遇到命令不存在，第一反应先 codex update。

0.2 这份指南适合谁

• 完全没用过 Codex，但想系统上手的人。
• 会写代码，但不知道怎么把编码代理接进真实项目的人。
• 已经用过 Cursor、Copilot、Claude Code，想搞清楚 Codex 工作流差异的人。
• 想把 Codex 接进 CI/CD、做自动化的人。
• 需要在受控沙箱里跑 AI 代理、对权限边界有要求的团队。

不适合：想找"一句提示词生成完整 SaaS"的银弹的人。本书讲的是把 AI 当成一个需要交接上下文、需要验收、需要留下工程规范的协作者。

0.3 阅读路线

一句话建议：先花 30 分钟把第二篇跑通，再回来读第三篇。没有跑过一次真实会话，第三篇的所有概念都会显得抽象。

第一篇：先搞懂 Codex 是什么

1.1 四个入口，别搞混

"Codex"是一个产品家族的名字。你实际接触到的是四个形态，能力和场景差别很大。

本书的重心是 Codex CLI，因为它是四者中门槛最陡、能力最全、也最容易用错的一个。云端部分见 3.9。

四者共享同一套账号和额度：用 ChatGPT 账号登录，Plus / Pro / Business / Edu / Enterprise 计划都包含 Codex 用量；也可以用 API key，但需要额外配置。

1.2 心智模型：代理循环

Codex CLI 不是补全工具，也不是聊天框。它的工作方式是代理循环：

你给一个目标
  → 它自己决定读哪些文件、跑什么命令
  → 观察结果
  → 决定下一步
  → …直到任务完成，或者需要你拍板

这带来两个直接后果，也是理解后面所有章节的前提：

1. 你不需要手动喂上下文。 不用把文件粘进对话框。说"这个项目的鉴权逻辑在哪"，它会自己去搜。
2. 你必须管权限。 因为它真的会执行 rm、git push、npm install。这就是 Codex 把沙箱和审批策略做成两个独立正交维度的原因（见 3.3）——这是 Codex 相比同类工具最有工程感的设计。

1.3 Codex 和 Cursor / Copilot 有什么不同

核心差异不在模型，而在交互形态。

1.4 Codex 和 Claude Code 的对照

两者形态最接近，很多人会同时用。这张对照表能省掉不少迷惑：

Codex 内置了 /import 命令，官方描述是 "import setup, this project, and recent chats from Claude Code"。从 Claude Code 迁过来的话，这是第一条该敲的命令。

1.5 上下文窗口：唯一真正稀缺的资源

会话里的一切都占地方：系统指令、AGENTS.md、工具定义、你的每一句话、它读过的每个文件、每条命令的输出。

窗口快满时会触发自动压缩——早期对话被摘要，腾出空间继续。压缩是有损的。Codex 把这件事做成了可配置项：

• model_context_window — 显式声明上下文窗口大小（token）
• model_auto_compact_token_limit — 触发自动压缩的用量阈值
• model_auto_compact_token_limit_scope — 阈值算全量上下文，还是只算当前压缩窗口里携带前缀之后的部分

三条实操纪律：

1. 一个会话干一件事。 做完就 /new 或 /clear，别在一个会话里从改 Bug 一路聊到重构架构。
2. 别让它读不需要读的东西。 "把整个 logs/ 目录读一遍"是在烧上下文，正确做法是让它 grep。
3. 重要约定写进 AGENTS.md，不要只在对话里说。 压缩之后，只在对话里说过的话不保证还在。

用 /status 可以随时查看当前会话配置和 token 用量。

第二篇：安装、配置与环境准备

2.1 系统要求

来自 docs/install.md：

注意 Windows 是通过 WSL2支持的。原生 Windows 上有安装脚本，但官方把 WSL2 列为受支持环境。

2.2 安装

官方安装脚本（推荐）

macOS / Linux：

curl -fsSL https://chatgpt.com/codex/install.sh | sh

Windows PowerShell：

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

安装器默认从 https://releases.openai.com/codex 下载，元数据或资源不可用时回落到 GitHub Releases。想强制走 GitHub Releases：

curl -fsSL https://chatgpt.com/codex/install.sh | CODEX_INSTALLER_USE_RELEASES_OPENAI_COM=false sh

包管理器

npm install -g @openai/codex     # npm
brew install --cask codex        # Homebrew

手动下载二进制

从 最新 GitHub Release 取对应平台的包：

解压出来的可执行文件名里带平台后缀（如 codex-x86_64-unknown-linux-musl），自己重命名成 codex。

验证与升级

codex --version
codex update        # 升级到最新版
codex doctor        # 诊断安装、配置、认证、运行时健康状况

codex doctor 是被低估的命令。配置不生效、认证有问题、沙箱起不来，先跑它。

2.3 登录

codex

首次运行选 Sign in with ChatGPT。推荐用 ChatGPT 账号登录，这样 Codex 用量走你的 Plus / Pro / Business / Edu / Enterprise 计划。

也可以用 API key，但需要额外配置。相关的配置项：

命令：

codex login       # 管理登录
codex logout      # 清除已存储的认证凭证

会话内用 /logout 退出登录。

2.4 第一次会话

cd /path/to/your/project
codex

建议按这个顺序走一遍：

这个项目是做什么的？

主入口在哪里？解释一下目录结构

给主文件加一个 hello world 函数

/diff

把改动提交上去，写一条描述清楚的 commit message

跑完这五步，你就已经用过核心循环了：探索 → 理解 → 修改 → 检查 → 交付。

也可以带初始提示直接启动：

codex "解释一下这个代码库"

2.5 沙箱与审批：最该先搞懂的一件事

这是 Codex 的核心设计，也是它和同类工具差别最大的地方。沙箱和审批策略是两个正交的维度：

• 沙箱决定"命令能碰到什么"——文件系统和网络的边界。
• 审批策略决定"什么时候来问你"。

沙箱模式（sandbox_mode）

源码 codex-rs/protocol/src/config_types.rs 的 SandboxMode 枚举：

审批策略（approval_policy）

源码 codex-rs/protocol/src/protocol.rs 的 AskForApproval 枚举：

granular 下可以逐项配置（GranularApprovalConfig）：

字段为 true 表示该类请求会呈现给你；为 false 表示自动拒绝而不是弹给你。

组合起来用

两个维度组合出实际的工作姿态：

会话里用 /permissions 交互式选择"Codex 被允许做什么"，用 /status 查看当前生效的设置。

⚠️ danger-full-access + never 是全放行组合，只应该在容器、虚拟机或一次性环境里用。不要在你的日常开发机上这么配。

相关命令

/permissions          选择 Codex 被允许做什么
/elevate-sandbox      设置提权的 agent 沙箱
/sandbox-add-read-dir <绝对路径>    让沙箱能读某个目录

codex sandbox <命令>   # 在 Codex 提供的沙箱里跑一条命令

最后那条很实用：可以拿来单独验证某个命令在沙箱里到底能不能跑通。

2.6 命令速查

Shell 命令

来自 codex-rs/cli/src/main.rs 的子命令定义：

常用全局参数：

codex -c key=value            # 临时覆盖任意配置项
codex -c log_dir=./.codex-log # 开启 TUI 明文日志

斜杠命令

以下命令名和描述直接来自 codex-rs/tui/src/slash_command.rs 的 description()，是官方原文的中译。

会话管理

干活

配置

环境与界面

其他

部分命令受功能开关控制，不一定出现在你的 / 菜单里（如 /plan、/apps、/plugins、/usage、/goal、/personality）。看不到就用 /experimental 或 codex features 查一下。

2.7 推理投入档位

ReasoningEffort 枚举（codex-rs/protocol/src/openai_models.rs）：

none · minimal · low · medium（默认）· high · xhigh · max · ultra · persistent

用 /model 同时选模型和这个档位。

档位不是越高越好——它是在同一个模型里拿 token 花费换思考深度。编码和长周期任务对它敏感，简单改动、格式调整这类任务在低档位上质量往往不掉。先在默认 medium 上跑，觉得不够再往上提，而不是一上来就拉满。

具体有哪些模型可选、各自定位如何，随版本变化很快。用 /model 看你账号当前实际可选的列表，不要照抄任何文章里写死的模型名——包括本书。

2.8 配置文件在哪

Codex 的配置以 TOML 为主，位于 CODEX_HOME（默认 ~/.codex/）：

/debug-config 会打印出配置层级和各项的来源，排查"我明明配了却不生效"时用它。

第三篇：核心能力详解

选错机制会很别扭。先看这张决策表：

最重要的判断准则：AGENTS.md 是事实，Skill 是流程，Hook 是规则，沙箱是边界。如果 AGENTS.md 里出现了"第一步……第二步……"，那它应该是个 Skill；出现了"每次都必须……"，那它应该是个 Hook；出现了"绝对不许碰……"，那它应该是沙箱或 execpolicy。

3.1 AGENTS.md：项目指令

AGENTS.md 是一个普通的 Markdown 文件，Codex 在会话开始时读它。它是你把"要反复解释的东西"写下来的地方。

发现规则

来自源码 codex-rs/core/src/agents_md.rs 的文件头注释，这套规则值得完整理解：

1. 确定项目根：从当前工作目录向上走，直到找到 project_root_markers 里配置的标记。未配置时默认标记是 .git。找不到标记就只考虑当前工作目录；标记列表设为空则禁用向上遍历。
2. 收集：从项目根一路向下到当前工作目录（含两端），把途中每一个 AGENTS.md 都收集起来，按这个顺序拼接。
3. 不越过项目根：向上遍历到项目根就停。

这套规则的实际含义：monorepo 里可以分层写。仓库根放全局约定，packages/web/AGENTS.md 放前端专属约定；在 packages/web/ 下启动 Codex，两份都会加载，且子目录的排在后面（更靠近你的指令后被读到）。

相关常量与配置：

project_doc_fallback_filenames 默认是空的。想让 Codex 也读 CLAUDE.md 或 .cursorrules，得自己配：

toml project_doc_fallback_filenames = ["CLAUDE.md", ".cursorrules"]

生成初稿

/init

官方描述是 "create an AGENTS.md file with instructions for Codex"。它会分析代码库生成一份初稿，你再往上加它推不出来的东西。

写出真正被遵守的指令

AGENTS.md 是作为上下文注入的，不是强制配置。写法直接影响遵守率。

篇幅：32 KB 是硬上限，但别贴着上限写。控制在 200 行以内，越长越稀释。

具体：写能被验证的指令。

✅ 用 2 空格缩进
✅ 提交前跑 `pnpm test`
✅ API handler 放在 `src/api/handlers/`

❌ 代码要格式化好
❌ 记得测试
❌ 保持文件组织有序

一致：两条规则互相矛盾时，模型可能随机挑一条。定期清理过期和冲突的条目。

一份能用的 AGENTS.md 模板

# 项目名

一句话说清这个项目是干什么的。

## 构建与测试

- 安装依赖：`pnpm install`
- 开发服务器：`pnpm dev`（跑在 3000 端口）
- 单元测试：`pnpm test`
- 提交前必须通过：`pnpm lint && pnpm typecheck && pnpm test`

## 目录约定

- `src/api/handlers/` — HTTP 路由处理
- `src/domain/` — 纯业务逻辑，不允许 import 任何 IO 模块
- `src/infra/` — 数据库、外部服务客户端

## 约定

- 用 2 空格缩进，不用 tab。
- 新增依赖前先问，这个项目刻意保持依赖精简。
- 数据库改动必须配 migration 文件，不要直接改 schema.sql。

## 已知坑

- `src/legacy/report.ts` 有一套自己的日期处理，不要用 date-fns 去"统一"它，
  下游有三个报表依赖它现在的时区行为。
- CI 上 `test:e2e` 偶发超时，重跑一次通常就好，不要改超时阈值。

注意最后一节。"已知坑"往往是整份 AGENTS.md 里价值最高的部分——那是模型从代码里推不出来的东西。

AGENTS.override.md

个人的、不该进版本库的偏好放这里：你的沙箱地址、你偏好的测试数据、你个人的调试习惯。记得加 .gitignore。

3.2 配置分层与 Profile

Codex 的配置是分层的，这是它面向团队和企业的设计。/debug-config 会显示"配置层级与需求来源"，正是为了排查多层叠加后的最终值。

常用配置项

从 codex-rs/config/src/config_toml.rs 的 ConfigToml 定义摘出最常用的：

模型与上下文

model = "..."                                # 模型
review_model = "..."                         # /review 用的模型
model_provider = "..."                       # 从 model_providers 里选
model_context_window = 400000                # 上下文窗口（token）
model_auto_compact_token_limit = 300000      # 触发自动压缩的阈值

权限

sandbox_mode = "workspace-write"             # read-only | workspace-write | danger-full-access
approval_policy = "on-request"               # untrusted | on-request | granular | never
default_permissions = ":read-only"           # 冒号开头是内置档，其他名字从 [permissions] 解析

[sandbox_workspace_write]
# workspace-write 模式下的细化配置

项目指令

project_doc_max_bytes = 32768
project_doc_fallback_filenames = ["CLAUDE.md"]

其他常用

notify = ["notify-send", "Codex"]            # 通知用的外部命令
tool_output_token_limit = 20000              # 工具输出进上下文的 token 预算
background_terminal_max_timeout = 300000     # 后台终端输出轮询窗口，默认 5 分钟
allow_login_shell = true                     # 是否允许模型请求 login shell
mcp_optional_startup_grace_ms = 1000         # 建工具目录时等可选 MCP 的宽限期
cli_auth_credentials_store = "auto"          # file | keyring | auto

Profile：一组配置的具名快照

profile = "safe"          # 默认用哪个

[profiles.safe]
sandbox_mode = "read-only"
approval_policy = "untrusted"

[profiles.yolo]
sandbox_mode = "danger-full-access"
approval_policy = "never"

也支持 profile-v2：$CODEX_HOME/<name>.config.toml 是一个独立的具名配置文件。

临时覆盖

codex -c sandbox_mode=read-only
codex -c model_auto_compact_token_limit=200000
codex -c log_dir=./.codex-log

-c key=value 可以覆盖任意配置键，适合一次性实验，不用改文件。

企业侧：requirements.toml

管理员可以用 requirements.toml 施加硬性约束，这一层的优先级高于用户和项目配置。一个具体例子（来自 docs/config.md）：

allow_managed_hooks_only = true

设成 true 后，用户、项目、会话级的 hook 配置会被忽略，只允许 requirements 和 managed config 层的托管 hook。

⚠️ 这个开关只在 requirements.toml 里有效，写进 config.toml 不会启用托管专属模式。

3.3 沙箱的细节

2.5 讲了模式选择，这里讲边界本身。

workspace-write 是日常最常用的模式：可以改工作区内的文件，具体范围由 [sandbox_workspace_write] 配置。需要让沙箱额外读某个目录时：

/sandbox-add-read-dir /absolute/path

想单独验证一条命令在沙箱里能不能跑通：

codex sandbox <你的命令>

这条命令很适合在配沙箱规则时做验证，比在会话里反复试省事得多。

execpolicy 是更细的一层：它用规则描述哪些命令直接放行、哪些必须询问、哪些直接拒绝。untrusted 审批策略正是靠它工作的——"命令都要审批，除非有 execpolicy 规则显式放行"。

3.4 Skills：把重复流程变成一条斜杠命令

Skill 是一个带 YAML 前置元数据的 SKILL.md。官方描述："use skills to improve how Codex performs specific tasks"。

格式

来自官方样例（codex-rs/skills/src/assets/samples/）：

---
name: skill-creator
description: Create or update a Codex skill with appropriately scoped instructions and any needed supporting resources.
metadata:
  short-description: Create or update a skill
---

# Skill Creator

正文：Codex 调用这个技能时该怎么做。

字段：

description 怎么写

这是决定技能能不能被正确触发的关键。看官方 imagegen 技能的写法——它把「什么时候用」和「什么时候不要用」都写了：

Generate or edit raster images when the task benefits from AI-created bitmap visuals... Use when Codex should create a brand-new image, transform an existing image... Do not use when the task is better handled by editing existing SVG/vector/code-native assets...

"Do not use when" 和 "Use when" 一样重要。 只写前者，技能会在不该触发的场合被拉进来。

官方给的写作原则

skill-creator 技能本身就是一份技能写作指南，几条原则值得直接搬用：

• 假设 Codex 本来就有能力。 只写会改变它决策、或改善它产出的信息。删掉通用建议、重复指令、臆想的边界情况，以及不能实质澄清任务的例子。
• 保住用户意图和范围。 技能应该支持所请求的任务，而不是替用户改选型、扩大作业范围、改动无关配置，或暗示可以做额外的外部操作。
• 具体程度要匹配风险。 多种做法都合理时，给模型选择空间；只在正确性、安全性、权限或流程确实脆弱时，才用详细步骤、确定性脚本或绝对化措辞。

存放与使用

项目技能放 .codex/skills/<name>/SKILL.md。会话里：

/skills

3.5 Plan 模式与长任务

Plan 模式（/plan）让 Codex 先给方案再动手。切进去之后它不改代码，只输出计划，你审完再放行。

/plan 给用户注册加邮箱验证

目标（/goal）用于长任务：设置或查看一个长期目标，让 Codex 在多轮之间保持方向不漂移。

/goal 把整个 API 层从 callback 迁移到 async/await，保持测试全绿

Side 对话（/side 或 /btw）在临时分叉里开一段旁支对话——你想问一个跟当前任务无关的问题，又不想污染主线上下文时用它。问完回到主线，主线上下文不受影响。

这三个配合起来是长任务的标准姿势：/goal 定方向 → /plan 出方案 → 干活 → 中途有疑问用 /side 问 → /compact 控制上下文 → /review 验收。

3.6 MCP：把外部系统接进来

MCP（Model Context Protocol）是把 Codex 连到外部工具、数据库、API 的开放标准。

管理

codex mcp        # 管理外部 MCP 服务器

/mcp             列出已配置的 MCP 工具
/mcp verbose     看详情

配置

MCP 服务器配在 config.toml 的 [mcp_servers] 表里。从 McpServerConfig 定义看，每个服务器支持的字段相当细：

enabled_tools / disabled_tools 这对组合很实用：一个 MCP 服务器往往暴露几十个工具，全塞进上下文既浪费又容易误触发。只开你真正要用的那几个。

OAuth 相关的全局配置：

mcp_oauth_credentials_store = "auto"    # keyring | file | auto（默认）
mcp_oauth_callback_port = 8080          # 不设则用系统分配的临时端口
mcp_oauth_callback_url = "..."          # 自定义回调 URI

反向：把 Codex 当 MCP 服务器

codex mcp-server

这会把 Codex 自己作为一个 MCP 服务器通过 stdio 暴露出去——别的 MCP 客户端就能把 Codex 当成一个工具来调用。

⚠️ 不要把 token 明文写进入库的配置里。

3.7 Hooks：确定性的自动化

AGENTS.md 和 Skill 都是建议，模型可能遵守也可能不遵守。Hook 是保证：它在生命周期的固定节点执行，跟模型怎么想没关系。

/hooks          查看和管理生命周期 hooks

判断准则：如果一件事必须在某个精确时刻发生（每次编辑后格式化、每次提交前跑检查），写 Hook，不要写进 AGENTS.md。

企业侧可以用 requirements.toml 里的 allow_managed_hooks_only = true 强制只允许托管 hook，屏蔽用户和项目级的 hook 配置（见 3.2）。

3.8 会话管理

Codex 把会话当成可以持久化、可以分叉、可以归档的一等对象。

分叉是被低估的能力。你走到一半想试一条不同的路线，又不想丢掉当前状态——/fork 出一份，两边独立往前走。

会话历史写在 ~/.codex/history.jsonl，由 history 配置项控制写不写、写什么。

3.9 云端与自动化

非交互执行

codex exec "跑一遍测试并总结失败原因"
codex e "..."                              # 别名

codex exec 是脚本和 CI 里的入口。它默认 RUST_LOG=error，消息直接内联打印，不需要另开文件盯日志。

有个专门的开关：codex exec 的 --skip-git-repo-check（源码 codex-rs/exec/src/cli.rs 里还有 不加载 $CODEX_HOME/config.toml 的选项，认证仍走 CODEX_HOME）——在 CI 里跑时值得关注这类参数，用 codex exec --help 看当前版本的完整列表。

代码审查

codex review        # 非交互跑一次代码审查

/review                    审查当前改动
/review 只看 src/api 下的改动    支持内联参数

review_model 配置项可以给审查单独指定模型——审查和写代码对模型的要求不完全一样，分开配是合理的。

/auto-review 用于批准某次自动审查拒绝的一次重试。

Codex Cloud

codex cloud         # 实验性：浏览 Codex Cloud 任务并把改动应用到本地

云端形态（chatgpt.com/codex）适合派发能并行的、不需要你盯着的任务。本地和云端之间的桥梁就是 codex cloud 和 codex apply：

codex apply         # 把 Codex 产出的最新 diff 以 git apply 应用到本地工作区
codex a             # 别名

Cloud 部分的官方文档在 developers.openai.com/codex/cloud。本书对云端的覆盖不如本地深入——写作时该域名不可达，云端章节只依据 CLI 侧的接口反推，请以官方文档为准。

3.10 日志与排查

codex doctor                      # 一站式体检
codex -c log_dir=./.codex-log     # 开启 TUI 明文日志
tail -F ./.codex-log/codex-tui.log

Codex 是 Rust 写的，遵循 RUST_LOG 环境变量：

RUST_LOG=debug codex

TUI 默认把诊断记录在有界的本地存储里；显式设置 log_dir 才会生成明文日志文件。

会话内的排查命令：

第四篇：标准工作流

工具讲完了，这一篇讲怎么用。大部分人用不好 Codex，不是因为不知道有哪些功能，而是因为把它当搜索引擎用——一次问一句，拿到答案就走。

4.1 从需求到交付的五步链路

探索 → 计划 → 实现 → 验证 → 交付

每一步都有明确的产出物和明确的失败信号。

第一步：探索

目标：让 Codex 建立起对相关代码的理解，让你确认它理解对了。

先把沙箱压到只读，这样它想改也改不了：

codex -c sandbox_mode=read-only

在动手之前，先看一下这个项目里用户注册是怎么走的。
从入口路由开始，把涉及的文件和它们的职责列出来。先不要改任何东西。

产出物：一份文件清单 + 数据流描述。

失败信号：它开始猜测。看到"通常这类项目会……"、"一般来说……"这种措辞，说明它没找到真东西。这时候要给更具体的线索。

第二步：计划

目标：拿到一份你能审的方案，而不是一堆已经写好的代码。

/plan 给用户注册加邮箱验证

Plan 模式下 Codex 只出方案不动手。追加要求：

说清楚：要改哪些文件、每个文件改什么、需要新增哪些文件、
数据库要不要动、有哪些你不确定的地方。

这一步是整个流程里投入产出比最高的。 五分钟审方案，能省掉半小时审一个方向就错了的 diff。

审方案时重点看三件事：

1. 它有没有漏掉你知道但没说的约束？（漏了就补进 AGENTS.md，而不是只在对话里说）
2. 它列的"不确定的地方"你能不能现在就回答掉？
3. 改动范围是不是超出了你的预期？超出了就明确划界。

长任务额外加一步：

/goal 邮箱验证功能完整上线，含迁移、测试和文档

第三步：实现

切到可写沙箱：

/permissions

选 workspace-write。然后：

按这个方案实现。每完成一个文件停一下告诉我，我要看着走。

或者放手：

按这个方案实现，全部做完再告诉我。

选择标准：改动局限在你熟悉的代码里 → 放手；碰到你不熟或者风险高的地方 → 分步。

中途要不要打断？ 如果它走偏了，打断并说清楚哪里偏了。不要用"不对，重来" ——它会丢掉已经做对的部分。用"第 2 步做错了，X 应该是 Y，其他保留"。

第四步：验证

这是最容易被跳过、也最不该跳过的一步。

/diff

先自己扫一眼 diff，再让它验证：

跑测试和 lint，把真实输出贴给我。

注意措辞："把真实输出贴给我"。不加这句，它可能会说"测试通过了"而没真跑。

然后用独立的审查通道：

/review

/review 走的是独立的审查流程（还能用 review_model 配单独的模型），比在同一个上下文里问"你觉得你写得对吗"可靠得多——后者有明显的自我确认偏误。

验证清单：

• [ ] /diff 自己扫过一遍
• [ ] 测试跑了，输出贴出来了
• [ ] Lint / typecheck 过了
• [ ] /review 跑过，问题都处理了
• [ ] 改动真的解决了原始问题（不是绕过了它）
• [ ] 没有引入新的依赖（除非你批准过）
• [ ] 边界情况：空输入、超长输入、并发、失败重试

第五步：交付

把改动提交，commit message 按项目的约定写。
然后 push 到一个新分支并开 PR，PR 描述里说清楚改了什么、为什么、怎么验证的。

交付之后还有一步：如果这次会话里有任何"我又解释了一遍"的时刻，把那条解释写进 AGENTS.md。这是让下一次更省力的唯一办法。

4.2 提示词模板库

以下模板可以直接存成 Skill，变成 /命令。

理解陌生代码

我要改 <功能>。在动手之前：
1. 找到相关的入口点
2. 画出从入口到数据落库的调用链
3. 列出这条链路上任何看起来不寻常的地方（自定义逻辑、注释里的警告、绕过标准做法的写法）
先不要改任何东西。

定位 Bug

现象：<具体描述，包含实际输入和实际输出>
期望：<期望输出>
复现步骤：<步骤>

先找到根因再改。找到之后先告诉我根因是什么，我确认后你再动手。
不要在没有确认根因的情况下"试着修一下"。

最后一句很重要。没有它，模型的默认倾向是快速给出一个看起来合理的修改。

重构

重构 <目标>，约束：
- 外部行为完全不变，现有测试必须全绿
- 不新增依赖
- 一次只做一类改动，先做 <A>，做完让我看，再做 <B>

开始前先告诉我你打算怎么拆这几步。

写测试

给 <模块> 补测试。要求：
- 覆盖正常路径、边界情况、错误路径
- 用项目现有的测试工具和风格（先看一下已有的写法）
- 不要为了覆盖率写没有意义的断言
写完把测试跑一遍，贴输出。

代码审查

/review 重点看：正确性 bug（给出具体触发条件）、
重复实现了已有能力的地方、明显的性能问题。
每条给出 文件:行号。不确定的标注"不确定"。
不要提风格问题，lint 会管。

4.3 反模式清单

❌ 一个会话干所有事

上下文被无关内容填满，压缩后早期的关键约定丢失，模型开始犯低级错误。

改法：一个任务一个会话，/new 是你最好的朋友。临时插问用 /side。

❌ 把约定只在对话里说

"记住我们这个项目不用 lodash" —— 说了，当场生效了，压缩之后没了。

改法：写进 AGENTS.md。判断标准：这条约定下次会话还需要吗？需要就写进去。

❌ 一上来就 danger-full-access + never

图省事把两个维度都拉满，等于把沙箱这层设计白白扔掉。

改法：从 workspace-write + on-request 开始，被问烦了再往下调，而不是反过来。真要全放行，进容器。

❌ 不看方案直接批准

Plan 模式给了方案，扫一眼觉得"差不多"就批了。然后花二十分钟 review 一个方向就错了的 diff。

改法：审方案的时间应该和审 diff 的时间相当。

❌ 相信"测试通过了"这句话

改法：永远要求"把真实输出贴出来"，并且自己 /diff 扫一遍。

❌ 在没有 Git 保护的情况下放手让它干

改法：动手前先 commit 或者建分支。有了 Git 兜底，你才敢放宽权限。

❌ 用模糊的纠正

"不对"、"这样不行"、"重新弄一下"。模型不知道哪里不对，会随机改一个方向，经常把对的部分也一起改掉。

改法：具体到哪一步、哪个文件、哪个判断错了，以及正确的是什么。

❌ MCP 服务器全量接入

一个 MCP 服务器暴露几十个工具，全塞进上下文既浪费又容易误触发。

改法：用 enabled_tools 只开你真正要用的那几个。

❌ 在陌生仓库里直接放宽权限

别人的仓库里可能有 .codex/skills/ 带着你没看过的指令，也可能有指向不知道什么服务的 MCP 配置。

改法：clone 之后先用 read-only 跑，看看 .codex/、AGENTS.md 和 MCP 配置里有什么，再决定放宽到哪一档。

4.4 一条实用的自检

每次会话结束前问自己三个问题：

1. 这次有没有哪句话我上次也说过？ → 写进 AGENTS.md。
2. 这次有没有哪套流程我以后还会走一遍？ → 做成 Skill。
3. 这次有没有哪件事本来就不该让模型自己决定？ → 写成 Hook，或者收紧沙箱。

坚持一个月，你的 AGENTS.md 和 .codex/ 会变成整个项目最有价值的资产之一。

第五篇：实战案例库

五个案例，从易到难。建议每个都真的跑一遍，光看是学不会的。

案例一：三十分钟读懂一个陌生仓库

第一步：锁死权限，让它只能看

cd the-unfamiliar-repo
codex -c sandbox_mode=read-only

我第一次看这个项目。请按顺序回答：
1. 它是做什么的？
2. 怎么跑起来？怎么跑测试？
3. 目录结构里每个顶层目录的职责
4. 主要的数据流：请求进来之后经过哪些层
5. 有没有明显不寻常的地方（自定义框架、绕过标准做法的写法、注释里的警告）

先不要改任何东西。

只读沙箱在这里不只是安全措施——它还消除了"它会不会偷偷改了什么"这个疑虑，让你能放心让它自由探索。

第二步：验证它的理解

不要直接信。挑一个结论去验证：

你说鉴权在 middleware/auth.py 里做。把那个文件的关键部分贴出来，
指出具体是哪几行完成了鉴权。

贴不出来或者对不上，说明前面的结论是猜的。

第三步：固化成 AGENTS.md

/init

然后补充它推不出来的部分：

在 AGENTS.md 里加一节"已知坑"，把你刚才发现的不寻常之处写进去。
不要写从代码里一眼能看出来的东西。

第四步：找一个小切口练手

在这个项目里找一个小的、低风险的改进点：
一个缺失的错误处理、一个没覆盖的边界情况、一处明显的重复代码。
列出候选，说明每个的风险等级。

从最低风险的开始，走一遍完整的五步链路。

案例二：给一个脚本加上生产级的健壮性

场景：一个"能跑但不健壮"的定时脚本——直接 requests.get，直接按下标取字段，没有超时、没有重试、没有错误处理。API 抖动一次，定时任务就红一次。

这是最能体现编码代理价值的场景：改动小、边界多、容易漏。

读一下 crawler.py。这个脚本每天由 CI 跑一次，
目前任何网络抖动或 API 返回格式变化都会让它直接崩掉。

给它加上生产级的健壮性：
1. HTTP 请求加超时
2. 失败重试，指数退避，最多 3 次
3. 校验响应结构，缺字段时给出清晰的错误信息而不是 KeyError
4. 结构化的日志输出，让 CI 日志里能看出发生了什么
5. 失败时以非零退出码结束，这样 CI 才会标红

约束：
- 只用标准库和已有依赖，不要新增依赖
- 保持现有的输出格式和文件名不变

先给我方案，我确认后再动手。

为什么这么写：

• 说清楚运行环境（"每天由 CI 跑一次"）—— 这决定了错误处理策略是重试而不是弹窗。
• 逐条列出要求 —— 比"让它更健壮"具体得多。
• 明确约束 —— 没有"不加依赖"这条，它很可能给你引入一堆库。
• 先要方案 —— 你能在写代码前就发现方向问题。

验收：

现在验证：
1. 正常路径还能跑通吗？跑一次，贴输出。
2. 把 URL 改成一个不存在的域名，确认重试逻辑生效、最终以非零码退出。
   验证完把 URL 改回来。
3. 确认输出文件的格式和之前完全一致。

第 2 条是关键。健壮性代码最容易出的问题就是"错误路径从来没被跑过"。

案例三：把 Codex 接进 CI

场景：让 Codex 在 CI 里自动跑代码审查或例行检查。

核心是 codex exec——非交互执行，输出内联打印。

codex exec "审查本次改动，列出正确性问题，每条给出 文件:行号"

在 CI 里用的几个要点：

一个最小示例：

name: Codex Review
on:
  pull_request:
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0          # review 需要能对比 base
      - name: 安装 Codex
        run: curl -fsSL https://chatgpt.com/codex/install.sh | sh
      - name: 跑审查
        env:
          # 认证凭证放 secrets，不要写进仓库
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        run: |
          codex exec \
            -c approval_policy=never \
            -c sandbox_mode=read-only \
            "审查本次 PR 相对 origin/main 的改动，列出正确性问题"

⚠️ 认证方式和环境变量名请以 codex login --help 和官方认证文档为准——这一块随版本变化，本书不保证长期准确。

为什么用 read-only：审查不需要写权限。给最小权限是 CI 里的基本纪律。

案例四：用 Profile 管理多套工作姿态

场景：你在同一台机器上做不同性质的工作——改自己的项目、审别人的 PR、在一次性容器里跑批量任务。每种场景该给的权限完全不同。

在 ~/.codex/config.toml 里：

# 默认用最保守的
profile = "review"

[profiles.review]
# 审代码：只读，不该改任何东西
sandbox_mode = "read-only"
approval_policy = "untrusted"

[profiles.dev]
# 日常开发：能改工作区，模型自己决定什么时候问
sandbox_mode = "workspace-write"
approval_policy = "on-request"

[profiles.longtask]
# 长任务：能改，少打断
sandbox_mode = "workspace-write"
approval_policy = "never"
model_auto_compact_token_limit = 250000

[profiles.container]
# 一次性容器里：全放行
sandbox_mode = "danger-full-access"
approval_policy = "never"

用的时候：

codex -c profile=dev
codex -c profile=longtask

这个案例的价值在于把"我现在在做什么性质的事"变成一个显式选择，而不是每次靠临时改配置或者靠记性。默认值设成最保守的那个——忘记切换时，损失最小。

验证生效：

/status
/debug-config

案例五：写一个属于你的 Skill

场景：你发现自己第三次在粘同一段说明了。

从对话到 Skill 的最短路径：

把我们刚才走的这套流程做成一个 Skill，放在项目的 .codex/skills/ 下。

流程是：<用两三句话复述刚才做了什么>

description 里要同时写清楚什么时候用、什么时候不要用。

一个真实可用的例子：发版前检查

.codex/skills/preflight/SKILL.md：

---
name: preflight
description: 发版前的完整检查清单。Use when 用户准备合并到主分支、打 tag 或发布版本时。Do not use when 只是想跑一下测试，或者还在功能开发中途——那些场景直接跑对应命令更快。
metadata:
  short-description: 发版前检查
---

# 发版前检查

依次执行并报告每一项的**真实结果**，任何一项失败就停下来告诉我，不要继续往下跑。

1. 确认工作区干净（`git status --short` 为空）
2. `pnpm lint` 通过
3. `pnpm typecheck` 通过
4. `pnpm test` 通过——贴出真实输出，不要只说"通过了"
5. 检查相对主分支的 diff 里没有：调试用的 console.log、被注释掉的代码块、
   TODO/FIXME 标记、硬编码的 URL 或密钥
6. 如果 diff 里改了公开 API，确认 README 或文档也同步更新了

全部通过后，给我一份适合放进 release notes 的改动摘要。

## 注意

- 只报告，不要自己去修。发现问题交给我决定怎么处理。
- 第 5 项用 `git diff` 检查，不要凭印象。

这个 Skill 用到了本书讲过的几条原则：

• description 同时写了 use when 和 do not use when —— 触发准确度的关键
• "贴出真实输出" —— 防止模型口头声称通过
• "只报告，不要自己去修" —— 明确划定范围，符合官方"保住用户意图和范围"的原则
• "用 git diff 检查，不要凭印象" —— 把容易出错的一步固定成确定性操作

写完之后验证：

/skills

确认它出现在列表里，然后实际跑一次，看它是不是真的按步骤走、真的贴了输出。

附录

附录 A：速查表

沙箱模式

审批策略

granular 的五个开关：sandbox_approval、rules、skill_approval、request_permissions、mcp_elicitations。true = 呈现给你，false = 自动拒绝。

推理投入档位

none · minimal · low · medium（默认）· high · xhigh · max · ultra · persistent

常用配置项

model = "..."
review_model = "..."
model_context_window = 400000
model_auto_compact_token_limit = 300000

sandbox_mode = "workspace-write"
approval_policy = "on-request"
default_permissions = ":read-only"

project_doc_max_bytes = 32768                    # 默认 32 KB
project_doc_fallback_filenames = ["CLAUDE.md"]   # 默认空
project_root_markers = [".git"]                  # 默认 .git

tool_output_token_limit = 20000
background_terminal_max_timeout = 300000         # 默认 5 分钟
allow_login_shell = true
cli_auth_credentials_store = "auto"              # file | keyring | auto
mcp_oauth_credentials_store = "auto"
mcp_optional_startup_grace_ms = 1000

profile = "dev"
[profiles.dev]
sandbox_mode = "workspace-write"

[mcp_servers.example]
enabled = true
required = false
startup_timeout_sec = 10
enabled_tools = ["search", "fetch"]

文件位置

~/.codex/config.toml              主配置
~/.codex/<name>.config.toml       具名 profile（profile-v2）
~/.codex/history.jsonl            会话历史
requirements.toml                 企业硬性约束（优先级最高）

./AGENTS.md                       项目指令（入库）
./AGENTS.override.md              本地覆盖（gitignore）
.codex/skills/<name>/SKILL.md     项目技能

该用哪个机制

Skill 前置元数据

---
name: my-skill
description: 做什么。Use when <触发场景>。Do not use when <不该触发的场景>。
metadata:
  short-description: 列表里显示的短描述
---

附录 B：从 Claude Code 迁过来

第一条该敲的命令：

/import

官方描述："import setup, this project, and recent chats from Claude Code"。

手动对照的话：

最大的心智差异是权限模型：Claude Code 是一个维度（权限模式），Codex 是两个正交维度（沙箱 × 审批）。习惯了前者的人容易只调审批策略而忘了沙箱还卡着，或者反过来。配完用 /status 确认两边都对。

附录 C：常见问题

Q：AGENTS.md 写了但它不遵守。

AGENTS.md 是作为上下文注入的，不是强制配置，没有严格遵守的保证，指令越模糊越容易被忽略。排查顺序：

1. /status 看当前会话配置。
2. 确认文件位置在发现路径上——从项目根（默认由 .git 标记）到当前工作目录之间。不在这条路径上的 AGENTS.md 不会被加载。
3. 确认没超 project_doc_max_bytes（默认 32 KB）。
4. 把指令写得更具体（"用 2 空格缩进" 优于 "格式化好"）。
5. 找冲突指令——多层 AGENTS.md 说了相反的话，模型可能随机挑一条。
6. 如果这件事必须在某个时刻发生，改成 Hook。AGENTS.md 管不了这个。

Q：我的 AGENTS.md 在子目录里，没被读到。

发现规则是"从项目根向下到当前工作目录"。你在仓库根启动 Codex，packages/web/AGENTS.md 不会被加载；你 cd packages/web 再启动，根和子目录两份都会加载。用 /cd 也能在会话中切换。

Q：它总在问我要不要执行命令，很烦。

调 approval_policy。on-request → never 是最直接的办法。但先想清楚：你是想少被问（调审批），还是想让它能做更多事（调沙箱）？这是两件事。

Q：它说没权限做某事，但我已经设了 approval_policy = "never"。

never 只是"不问你"，不是"给权限"。它仍然被沙箱卡着。要放开能力，改 sandbox_mode。这是两个维度最常见的混淆点。

Q：怎么让沙箱能读工作区外的目录？

/sandbox-add-read-dir /absolute/path

Q：MCP 服务器起不来 / 工具太多。

• 起不来：/mcp verbose 看详情；调大 startup_timeout_sec；关键服务器设 required = true 让问题暴露出来而不是静默降级。
• 工具太多：用 enabled_tools 白名单只开你要的。

Q：某个斜杠命令我这里没有。

部分命令受功能开关控制（/plan、/apps、/plugins、/usage、/goal、/personality 等）。用 /experimental 或 codex features 查。也可能是版本太老，codex update。

Q：会话历史存在哪？能关吗？

~/.codex/history.jsonl，由 history 配置项控制写不写、写什么。

Q：在别人的仓库里用 Codex 安全吗？

先用 read-only 跑，看清楚这几处再决定放宽：

• AGENTS.md 里写了什么指令
• .codex/skills/ 里有哪些技能
• MCP 配置指向哪些服务

Q：Skill 触发不了 / 触发太频繁。

description 写得不够。把「Use when」和「Do not use when」都写清楚——只写前者，技能会在不该触发的场合被拉进来。

Q：配置改了没生效。

/debug-config

它会显示配置层级和各项来源。注意 requirements.toml 的优先级高于用户和项目配置——企业环境里配置被覆盖是常见原因。

结语

Codex 和同类工具最大的差别，是它把"能做什么"和"什么时候问你"拆成了两个独立的旋钮。这个设计一开始会让人觉得多余，用久了会发现它恰好对应了真实工作里的两种不同焦虑：怕它闯祸，和嫌它啰嗦。这两件事本来就该分开调。

本书讲的所有机制，最终都指向同一件事：把你脑子里的项目知识，变成机器可读的形式，留在仓库里。

AGENTS.md 是你的项目常识，Skill 是你的操作手册，Hook 是你的红线，沙箱是你的物理边界，MCP 是你的外部接口。它们加起来，本质上是一份给 AI 协作者的入职文档——而它恰好对人类新同事也一样有用。

从今天开始，每次会话结束前问自己一遍第 4.4 节的三个问题。一个月之后回头看，你会发现改变的不只是 AI 的输出质量，还有你自己对项目的理解深度。

关于本书的事实来源：命令列表、配置字段、枚举值、AGENTS.md 发现规则、斜杠命令及其描述，均取自 openai/codex 仓库 2026-09-03 的源码实现。云端（Codex Cloud / Web）部分覆盖较浅，因为写作时官方文档站不可达。涉及模型名称、价格、账号能力时，请以官方文档和你账号实际显示为准。

License：本项目采用 MIT License 开源。

贡献：欢迎提 issue 和 PR 补充内容、纠正错误。Codex 更新很快，任何一处过时的描述都值得被指出来。