Codex
手册

序 两根轴，不是一个开关

Preface

很多人用 Codex 的第一周，会在两个极端之间来回摆。

一种是被问烦了。它每改一个文件、每跑一条命令，都要停下来等你点头。干一个小活点了二十次确认，最后一气之下把权限全放开。

另一种是锁得太死。为了安全，你选了最保守的设置。结果它连装个依赖、跑个测试都做不了。你只好自己动手，那还要它干嘛。

两种情况的根源是同一个误解：把「权限」当成了一个开关。

Codex 的权限是两根独立的轴

这两根轴可以自由组合。「能写工作区、超出范围时才问你」是一种组合；「只能读、永远不问」是另一种。前者适合日常开发，后者适合放进 CI 让它做只读分析。

被问烦了，别急着把审批整个关掉，也别把沙盒一起放开。先给常用命令加精确的 rules，给必要目录加窄的 writable_roots。再试 auto_review 或 granular。never 排在最后。

锁得太死，该放宽的才是沙盒。一次放宽一个目录，或者一个开关。搞清楚这两根轴怎么组合，是用好 Codex 的前提。全书在 §04 把它讲透，取值总表在 4.1，症状对照在 4.13。

全书四段

Part 1 装上、登录、搞清楚计费，跑通第一个改动。

Part 2 是全书的重心：两根轴、AGENTS.md、上下文。读完这一段，你知道怎么让它在你划定的范围里放手干。

Part 3 讲扩展：技能、插件、Hooks、MCP、子智能体与并行。

Part 4 讲怎么把活交出去。包括云端、CI、四个实战案例，以及用配置文件统一团队。

怎么用这本书

关于内容来源

这是一份非官方社区手册。OpenAI 自己维护着官方中文文档，简体和繁体都有。这本书把同一批内容按学习顺序重新组织，并补上「为什么」。

写这本书时，我们拿 2026-09-04 的文档镜像，和 2026-10-13 的线上现状逐条比对。比出了 20 处已经失效的说法。事实核查时又找出十几处。其中最要紧的一条，连镜像抓取时就已经过期了。审批策略里有一档叫 untrusted。它在 CLI 0.149.0（2026-08-20）退役了，镜像里的文档还在教。§04 4.5 有专门的说明。

三条编写纪律

价格与模型只用官方页面。 官方没有给出明确数字的（比如各档用量的具体倍数），本书不写数字。

命令和配置项逐字取自官方文档。 已退役或已删除的东西，只作为「已失效」提醒出现，不教用法。比如 untrusted 和 codex mcp-server。

不编造经历。 书里的判断都有出处。

从第一个问题开始：Codex 到底有哪几种用法。

§01 Codex 是会动手的智能体，入口有好几个，规矩只有一套

What Codex Is, and Where You Use It

这一节讲三件事。Codex 到底是什么，它住在哪几个地方，管住它的权限规则长什么样。读完你能挑对入口，也知道后面各节为什么这么排。

1.1 它会自己动手，这个差别决定了后面所有事

先说一个最容易搞混的地方。Codex 不是更聪明的自动补全。

补全工具最坏的结果，是补错一行。你按一下 Esc，它就没了。Codex 不一样。它读你的仓库，改文件，跑命令，看输出，再决定下一步。你给的是目标，它交回来的是一批改动，外加一段说明。

官方对 CLI 的描述很直白。在终端里检查代码、做更改、运行命令，把重复的活自动化。注意几个动词，检查、更改、运行。后两个都会在你的机器上留下痕迹。

我喜欢用三层类比来记这件事。

• 补全像输入法。你敲一个字，它猜下一个字。
• 聊天像顾问。你问，它答，手要你自己动。
• Codex 像领了活的工程师。它自己去翻代码、改文件、跑测试，回来给你看结果。

三层的区别在于谁的手在动。到了第三层，你的角色变了。从现在开始，你是给指令和做验收的人，不是逐行敲代码的人。

这也解释了为什么官方文档把沙盒和审批放在很靠前的位置，本书也一样。手在你机器上动，就得先说清楚它能碰哪里、什么时候该停下来问你。这条线索我们放到 1.8 再拉出来，先看产品本身。

1.2 Codex 和 ChatGPT 是什么关系

现在的官方文档里，Codex 不再是一个孤立的产品。它是 ChatGPT 家族里的一种工作方式。在桌面应用和网页版里，你靠产品选择器选择。

重点看最后一行。写代码选 Codex，理由很实际。它会把 diff、命令输出、测试结果摆在你面前。这些正是你要核对的东西。Work 倾向于用非技术语言交付完整成果。Git 和 shell 命令这类细节，它会藏起来。

两者在桌面应用里的差别，官方列得很清楚。

还有一件和钱有关的事先记下。ChatGPT Work 和 Codex 共享用量、积分和限额。你在 Work 里做一份报告，扣的是同一个额度。怎么算，见 §02。

1.3 五个入口，跑的是同一套东西

Codex 有好几个界面。区别不在能力，在你人在哪里、改动落在哪里。

另外还有一类入口，挂在别的平台上。在 GitHub 的 PR 里评论 @codex review，是一种。在 CI 里用 openai/codex-action@v1，是另一种。还有 Slack 和 Linear 的集成。这些见 §10 10.7、10.8。codex-action 的用法在 10.5。

桌面应用：项目多、任务长的时候用

ChatGPT 桌面应用有 macOS、Windows 和 Linux 版本。Linux 目前是预览版。你在产品选择器里选 Codex，就进入开发者视图。

开一个 Codex 聊天时，要先选它在哪里跑。官方给了三种位置。

• 「Local」：直接在你当前的项目目录里干活。
• 「Worktree」：改动隔离在一个独立的 worktree 里。不碰你正在编辑的那个检出。
• 「Cloud」：在一个已发布的云端环境里，开一个独立的远程任务。

Local 和 Worktree 都跑在你自己的电脑上。界面上，用「Work in」菜单选「这台电脑」还是「云端」。对本地的 Git 项目，另有一个独立的 Worktree 控件。worktree 怎么用，见 §09。

CLI：本书的默认入口

在项目目录里敲 codex，就进了交互界面。它直接读你的本地仓库，跑你机器上已经装好的工具。模型、推理强度、权限，都由你选。

CLI 还有一个独有的用法：codex exec。它能不经人工交互跑完一件事，所以能进脚本和 CI。这是 §10 的主题。

本书默认用 CLI 当例子，原因只有一个。命令行的行为最容易写清楚，读者也最容易照着复现。你用桌面应用或 IDE，概念是一样的，只是按钮换了位置。

IDE 扩展：让改动出现在你看代码的地方

Codex 扩展适用于 VS Code、Cursor 和 Windsurf。VS Code Insiders 也一样。Xcode 和 JetBrains 系列 IDE 走各自的集成。

扩展最大的好处是上下文。你打开的文件、选中的代码，都能直接带进提示。官方说得对：Codex 从你正在看的代码开始，你少了很多重复交代的功夫。改动的 diff 也在编辑器里，你不用来回切窗口。

Codex Cloud：把活扔到云端

Codex Cloud（Codex 云端）让任务跑在隔离环境里。环境由 OpenAI 托管。你可以在网页、手机或桌面应用里发起和审阅。每个任务有自己的工作区，电脑睡着了也能继续。它新旧两版差别不小，下一小节单独讲。

1.4 云端这套已经换版，旧教程的说法要小心

如果你读过 2026 年 9 月之前的资料，会看到一套云端流程。用 setup 脚本装依赖，用 universal 镜像，机密只在设置阶段可用。这套现在叫 Codex Cloud (Legacy)。官方写的是「计划弃用」，没有给日期。

新版的关键词是「创建并发布环境」。具体步骤和新旧对比表，见 §10.7。

有三条规则，我觉得读者应该先记住。

• 云端必须用 ChatGPT 账号登录。API Key 登录用不了云端。
• 你电脑上的东西不会自动搬过去。本地文件、正在跑的进程、浏览器登录态、VPN 访问，都不会自动转给云端任务。它用的是环境里的文件和服务。
• 共享环境只给使用权。管理员共享给你的环境，你能用它开任务，但共享本身不给你编辑它的权限。

密钥怎么放、联网怎么开，见 §10.7。这里只提醒一句。旧教程里「机密进入智能体阶段前被移除」那套描述，属于 Legacy。新版的凭据分环境变量和 network secrets 两类。细节也在 §10.7。

1.5 手机端适合收尾，不适合起步

你可能见过「Codex 远程」这个名字。它现在改叫 Codex on mobile。官方文档的页面名换了，索引里的旧页面还能打开，内容一样。

它能做的事很具体。你在手机上启动任务、跟进度、批准请求、看改动和测试结果。任务本身跑在两个地方之一：云端，或者你已连接的 Mac、Windows 电脑。

连接电脑的步骤官方是这样写的。

1. 在电脑上打开 ChatGPT 桌面应用。进入「设置」里的「Connections」。选「Control this Mac or PC」。点 Set up 或 Add，再批准远程访问。
2. 用手机扫二维码，登录同一个 ChatGPT 账号和工作空间，批准连接。
3. 在 iOS 的 ChatGPT 应用里打开 Codex，选连接的电脑。如果你的应用还显示 Remote，就打开 Remote。

两条提醒。电脑要保持唤醒和在线，否则手机批准的请求没人接。可用性还取决于发布进度和工作空间设置。

我对手机端的判断是：它适合收尾，不适合起步。批准一条命令、看一眼 diff，很顺手。从零写需求，还是在电脑前更省心。

1.6 哪部分开源，哪部分不开源

OpenAI 以开源方式开发 Codex 的关键部分，代码在 GitHub 上。但「Codex 开源」这句话只对一部分成立。

重点看最后两行。你最常碰的三样东西里，CLI 是开源的，IDE 扩展和云端不是。官方的开源页没有列出桌面应用，所以我不把它当成开源组件。

有两个细节。

第一，许可证。我核实了三个仓库，三个都是 Apache-2.0。

• openai/codex
• openai/codex-security
• openai/codex-action

npm 上的 @openai/codex 也一样。openai/skills 的 README 说，许可证按单个技能算。各技能目录里有自己的 LICENSE.txt。plugins 和 codex-universal 的许可证我没核实到。用之前请自己看仓库里的 LICENSE。

第二，贡献方式。CLI 0.149.0 的发布说明写得明白。外部贡献应先走 issue 和设计讨论，不要直接提 PR。

报问题去对应仓库的 issue。提的时候写清楚你用的是哪个组件，比如 CLI、SDK、IDE 扩展或云端。再带上版本号。

1.7 看文档先看成熟度标签

读官方文档时，你会在功能旁边看到「实验性」「测试版」这类标签。它们告诉你这个功能能不能放心依赖。

这张表在本书里会反复用到。比如设备码登录是测试版，Codex Cloud (Legacy) 是计划弃用。codex app-server 命令，官方明确写了是实验性的，不支持生产负载。看到标签就想一下：这件事我敢不敢押在上面。

1.8 不管从哪个入口进，管它的都是两根轴

回到 1.1 留下的线索。Codex 能在你机器上动手，所以每个入口都要回答两个问题。

• 它能碰什么？哪些文件能写，能不能联网。这由沙盒决定。
• 它什么时候问你？越过边界的时候，是停下来等你点头，还是交给别人审，还是干脆不问。这由审批决定。

官方的说法很清楚：沙盒定义能访问哪些文件和网络资源，审批决定在什么时候暂停。两个控件一起工作，但互相独立。

最直观的证据在桌面应用里。官方说，换成「替我审批」只是换了谁来审批，沙盒的范围一点没扩大。机制见 §04 4.7。

各个入口把这两根轴放在不同的位置。

被问烦了和锁得太死这两种常见失败，序里讲过，症状对照见 §04 4.13。完整的组合矩阵在 §04 4.6。

1.9 按场景挑入口

先给结论，再给理由。

• 改自己电脑上的仓库：CLI 或 IDE 扩展。看你习惯待在终端还是编辑器。
• 同时管好几个项目，或任务要跑很久：桌面应用。
• 不想让它碰你正在改的分支：桌面应用的 Worktree 模式，见 §09。
• 要挂进流水线自动跑：codex exec 或 GitHub Action，见 §10。
• 想让它在你离开后继续跑：Codex Cloud。
• 人在路上，只想批准或看一眼：手机端。

登录方式也会影响你能用哪些入口。用 API Key 登录，CLI、SDK 和 IDE 扩展能用，云端功能用不了。这一点 §02 会讲透。

1.10 这一节的结论

Codex 是会自己动手的编码智能体。它和聊天、Work 同属一个产品家族，靠产品选择器区分。入口有桌面应用、CLI、IDE 扩展、Codex Cloud 和手机端。它们跑的是同一套规矩。

三个要带走的判断：

• 写代码选 Codex，别在聊天里贴代码让它猜。
• 云端已经换版。旧教程里的两阶段、机密只在设置阶段可用，说的是 Legacy。
• 管住它的是两根独立的轴，沙盒和审批。

本书的事实截至 2026 年 10 月 13 日。当时 CLI 的最新稳定版是 0.162.1，发布于 10 月 9 日。官方文档站已迁到 learn.chatgpt.com，细节见附录 D.3。

下一节，我们把它装上、登录，然后把计费讲清楚。

§02 装法随你挑，登录方式决定你怎么付钱

Install, Sign In, and Understand the Bill

这一节把 Codex 装上、登进去，再把计费和模型选择讲明白。四种装法装出来是同一个 codex。真正影响你钱包和功能的，是登录方式。

2.1 动手之前，先定两件事

装之前有两个决定，它们互相影响。

第一，用 ChatGPT 账号登录，还是用 API Key。前者走订阅额度，后者按 API 价格按量付费。第二，从哪个入口开始：CLI、桌面应用，还是 IDE 扩展。

我的建议很直接。个人开发者用 ChatGPT 账号，从 CLI 或桌面应用开始。要放进 CI 或共享环境的自动化，才用 API Key。理由 2.5 会讲：登录方式不只改账单，还改你能用的功能。

需要一个终端、一个 ChatGPT 账号或 API Key，以及 Git。走 npm 还要有 Node.js。

2.2 CLI 有四种装法，挑一种就好

官方给了四条路径，没写它们有功能差别。我的取舍标准是：机器上已经有谁，就用谁。没有偏好，就用官方页面排第一的独立安装程序。

# 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"

# 所有平台：npm
npm install -g @openai/codex

# macOS：Homebrew
brew install --cask codex

预期结果：命令跑完没有报错，终端里能找到 codex。以后升级，独立安装程序和 npm 都是把安装命令再跑一遍。Homebrew 用 brew upgrade --cask codex。

codex doctor

它检查安装、配置、认证、运行时、Git、终端、app-server 和线程清单。官方写的用途是提交支持问题前、排查安装故障时用。装完先跑一遍是我的建议，比等出问题再查省事。

2.3 Windows 有两条路，原生和 WSL2

原生路线：agent 在 PowerShell 里跑，用 Windows 沙盒。WSL2 路线：agent 在 Linux 环境里跑，用 Linux 沙盒。我的建议是默认走原生。只有两种情况才选 WSL2。需要 Linux 原生工具链，或者仓库本来就在 WSL2 里。

桌面应用默认用 Windows 原生的 agent。想让它跑在 WSL2 里，到设置里把 agent 切到 WSL，然后重启应用。不重启不生效。

桌面应用去 chatgpt.com/download 下载。或者用 winget 装：

winget install --id 9PLM9XGG6VKS -s msstore

官方建议同时装 Git、Node.js、Python 和 GitHub CLI。Git 最关键，审查面板和撤销都靠它。

Windows 沙盒：推荐 mxc

原生 Windows 有三种沙盒实现，推荐的是 mxc。桌面应用在个人账号下，设备支持时会自动优先用它。企业部署，或者单独用 CLI，要自己在 config.toml 里打开：

[features]
prefer_mxc = true

设备门槛、旧版回退和单次测试的命令，见 §04 4.10。官方推荐 Windows 11。沙盒怎么和审批搭配，见 §04。

WSL2 怎么装

# 在管理员 PowerShell 里
wsl --install
wsl

# 进入 WSL 之后
curl -fsSL https://chatgpt.com/codex/install.sh | sh
codex

官方明确写了三条。

• 仓库放在 Linux 家目录，比如 ~/code，别放 /mnt/c。跨文件系统更慢，符号链接和权限问题也更多。
• WSL1 不再支持。0.114 及以前能用，0.115 起 Linux 沙盒换成 bubblewrap。
• Windows 应用和 WSL 里的 CLI，默认互不共享。配置、登录缓存和会话历史都是如此。想共享，把 WSL 里的 CODEX_HOME 指到 Windows 的 .codex 目录。

2.4 桌面应用、Linux 预览版和 IDE 扩展

macOS 和 Windows 都有桌面应用。从 chatgpt.com/download 下载，打开后登录。想写代码，就在产品选择器里选 Codex。

Linux 桌面应用目前是预览版。官方支持的发行版如下，每个都有 x64 和 ARM64 两套包。

先用 uname -m 看架构。x86_64 是 x64，aarch64 或 arm64 是 ARM64。装好后从应用菜单打开，更新走系统包管理器。计算机使用（Computer Use）在预览版里还没有。

IDE 扩展适用于 VS Code、Cursor 和 Windsurf。VS Code Insiders 也一样。Marketplace 的条目 ID 是 openai.chatgpt。看不到侧边栏图标，就打开命令面板。运行 Codex: Open Codex Sidebar。Xcode 和 JetBrains 走各自的集成。在它们的 AI 聊天里选 Codex。

2.5 登录方式不只改变账单

Codex 支持两种登录方式。桌面应用、CLI 和 IDE 扩展在本地干活时都支持。用云端，只能用 ChatGPT 账号登录。

重点看「云端功能」那一行。选了 API Key，就放弃了 Codex Cloud。GitHub 代码审查也一样。这类功能依赖 ChatGPT 工作空间。登录方式不只是计费方式。

codex login

桌面应用在未登录界面选「继续登录」。IDE 扩展选「使用 ChatGPT 登录」。

printenv OPENAI_API_KEY | codex login --with-api-key

桌面应用选「使用其他方式登录」，IDE 扩展选「使用 API 密钥」。CI 这类程序化的工作流，官方明确建议用 API Key。同时提醒别在不受信任或公开的环境里，暴露 Codex 的执行能力。

登录信息会被缓存，CLI 和 IDE 扩展共用同一份。从任何一端退出，另一端下次启动也要重新登录。缓存位置有两种。一种是本地明文文件 ~/.codex/auth.json。另一种是操作系统自带的凭据存储区。用 cli_auth_credentials_store 选存哪里。

# file | keyring | auto | ephemeral
cli_auth_credentials_store = "keyring"

四个取值的意思如下。

• file：存成文件。
• keyring：存进系统凭据存储区。
• auto：优先用凭据存储区，不行再回退到文件。
• ephemeral：只放在当前进程的内存里。

服务器这类无头环境里，浏览器登录会卡住。本地网络挡住登录用的 localhost 回调时，也一样。官方首选设备码登录。它目前是测试版，要先在 ChatGPT 安全设置里启用。

codex login --device-auth

设备码用不了，备选有两个。

• 在有浏览器的电脑上登录后，把 ~/.codex/auth.json 复制过去。
• 或者用 SSH 转发 localhost:1455 回调端口。

命令在官方认证页。

云端还要求账号启用多重身份验证（MFA）。邮箱加密码登录的账号，必须先设 MFA 才能访问云端。

2.6 第一次进项目目录，会发生什么

登录之后，到项目目录里敲 codex。它会先检查这个目录有没有纳入版本控制，再给出不同的默认建议。

官方还提醒：视你的设置，Codex 可能一直以 read-only 启动。这会持续到你明确信任这个目录。信任可以走初次进入时的提示，也可以用 /permissions。「工作区」包括当前目录和 /tmp 这类临时目录。想看它算了哪些，输入 /status。

git init
git add -A
git commit -m "before codex"

Auto 等价于 --sandbox workspace-write --ask-for-approval on-request。前半句是沙盒，后半句是审批。你在 §01 见过这两根轴，§04 会拆开讲透。

2.7 计费：先看登录方式，再看套餐

先给结论。ChatGPT Work 和 Codex 共享用量。在 Work 里做一份幻灯片，和在 Codex 里改一个函数，扣的是同一个额度。

重点看 Pro 那一行。旧资料写「Pro 是 Plus 的 5 倍或 20 倍」，这个说法已经过期。现在 Pro 是三个价位。官方定价页没给三档各自的用量数字，我不替它编。你要比较，就去看官方的 Pro 说明页。官方还写了：Pro 套餐目前没有 5 小时限额，「目前」二字说明以后可能变。

Plus 和标准版 Business 有一张本地消息估计表，按每 5 小时算。Plus 的套餐卡片只写了 GPT-6.1 Sol 和 Luna。这张表里却有 Astra 一行。能不能选到 Astra，以你模型选择器里看到的为准。

重点看区间的宽度。同一个模型，上限是下限的十倍左右。官方说这只是估计，不是固定上限。任务大小、上下文、推理量都会影响。云端任务可能更耗额度，每周也可能另有限额。

我的建议：拿这张表比模型之间的相对成本，别拿它算一天能干几件事。Luna 比 Sol 大一个数量级，这个关系才有用。

速度档也会烧额度，而且按倍数烧。倍率和开关见 §06 6.8，这里不写数字。

订阅额度用完，可以买积分继续。官方给了标准速度下每百万 token 的积分费率。

倍数是我拿官方数字算的。输出一栏，Astra 的 1,250 是 Sol 的 5 倍。Luna 的 12.5 是 Sol 的二十分之一。结论就一句。任务描述得清楚就用 Luna，需要判断力才升到 Sol 或 Astra。选模型就是最大的省钱杠杆。

到顶了会怎样？一轮对话进行到一半到顶，这一轮可以跑完，但受公平使用限制。Plus 和 Pro 可以买额外积分，不用升级套餐。任何用户也可以用 API Key 多开几轮本地对话，按标准 API 价格付费。

用量面板在 chatgpt.com/codex/settings/usage。CLI 会话里输入 /status 能看剩余额度。

想让额度撑久，官方的建议有四条。

• 提示写精确。
• 素材只给相关的。
• AGENTS.md 控制得小。
• MCP 服务器只开需要的。

后两条每条消息都带着走，我建议先从它们查起，见 §05 和 §08。

2.8 模型怎么选

官方现在的推荐很明确。复杂的编码和智能体工作，用 GPT-6.1 Sol，前提是你的账号和客户端能用。目标清楚的重复任务，用 Luna。

GPT-6 Sol（gpt-6-sol）仍可选。官方拿它当 GPT-5.5 的替换。GPT-6.1 Sol 首发不含 Free 和 Go。它们用桌面应用里的 Luna。Enterprise 和 Edu 里它默认关闭，要管理员先启用。

模型迭代快，旧名字会失效。如果你的配置、脚本、定时任务里写死了模型名，按下表查一遍。

要搜的地方：工作空间默认值、托管配置、自定义智能体、定时任务和脚本。用 API Key 登录的 Codex 不受 GPT-5.4 退役影响。

各个入口的选法不一样。桌面应用和网页版 Work 用输入框下方的模型与推理控件。另有 Power 预设。往 Smarter 调，推理更深。往 Faster 调，更快更省。点 Advanced 才能指定具体模型。IDE 扩展用输入框下方的模型切换控件。CLI 里用 /model，或启动时加 --model（别名 -m）。

codex --model gpt-6.1-sol
codex exec -m gpt-6.1-sol "Review the current changes"

想固定默认模型，在 config.toml 里写一行。

model = "gpt-6.1-sol"

不写的话客户端用推荐模型。官方没写默认值叫什么。我只能确认 CLI 0.161.0 的发布说明提到一件事。GPT-6.1 Sol 成为了内置目录的默认模型。服务端默认值可能不同，以 /status 看到的为准。

推理强度越高，复杂任务的结果可能越好，但耗时更长、用的 token 更多。官方的做法是先用默认值，需要更深的规划再加。

档位从低到高，桌面、网页、IDE 和 CLI 的叫法略有不同。

• 桌面、网页、IDE：Light、Medium、High、Extra High。
• CLI：最低档叫 Low。

Light 或 Low 适合快而范围明确的任务。High 和 Extra High 适合多步骤、要权衡的难题。再往上还有 Max 和 Ultra，多数任务用不上。

Max 让模型对单个任务想得更久。Ultra 会调用子智能体，把能拆开的部分并行处理。Luna 最高到 Max，不含 Ultra。起步建议有三条。

• GPT-6.1 Sol 用客户端默认强度。
• Luna 从 High 开始。
• Astra 从 Light 开始（配置里写作 low）。

不同代模型的档位不严格对应，拿熟悉的任务试低一档再调。

CLI 里要看 Max 或 Ultra，先用 /model 选好模型。再选 More reasoning…。桌面应用里看不到 Ultra，就去设置的 Configuration。然后打开 Ultra in model picker slider。

2.9 这一节的结论

装法是口味问题，登录方式才是决策。ChatGPT 账号给你完整功能和订阅计费。API Key 给你按量付费，也让你失去云端。

三条要带走的判断：

• Pro 现在是三档，$100、$200、$500。「5 倍或 20 倍」已经作废。
• Work 和 Codex 共享用量。Luna 的积分费率只有 6.1 Sol 的二十分之一。
• 按官方安排，GPT-5.5 已在 2026 年 10 月 14 日退役。写死了模型名的配置，现在就查。

装好了，登进去了，也知道每次对话扣的是哪份额度。下一节，我们跑第一个真正的改动。

§03 第一个任务要小到一分钟能验收，提示要说清四件事

Your First Change, and How to State a Task

装好了，登进去了，现在让它真的改一个东西。这一节带你跑通第一个任务，讲清楚提示怎么写，再给你一张高频斜杠命令的速查表。

3.1 先挑对任务：改完一分钟内能看出对错

第一个任务的标准只有一条。改完你能在一分钟内看出对错。

别挑「重构这个模块」，也别挑「把测试覆盖率提上去」。这类任务它会干很久，改一大片。最后你面对几百行 diff，不知道从哪看起，只能凭感觉点接受。这一次你什么也没学到。

好的第一个任务，长得像下面这几个。文件名是示例，换成你自己项目里的。

• 给 src/utils/slug.ts 里的 slugify 补两个单元测试。只改测试文件。
• 核对 README 里的安装步骤。看它和 package.json 的 scripts 对不对得上。只改 README。
• 把某个文件里三处重复的错误处理提成一个函数，行为不变，跑一遍测试。

三个任务的共同点：范围小，边界写死，验收动作现成。后面所有的提示写法，都是围绕这三点展开的。

还有一条我想加：第一个任务最好别联网。本地的沙盒默认没有网络。装依赖、拉包、调外部接口这类命令需要联网。默认的按需审批下，它们通常会弹出审批。审批策略是 never 或你拒绝时，它们会直接失败，机制见 §04 4.9。

第一次就被打断好几回，很容易分不清是任务问题，还是权限问题。等你熟悉了审批提示，再碰联网的活。

如果你连项目都还不熟，有个比改代码更安全的第零步。官方 CLI 页面给的第一条提示就是让它介绍项目：

Tell me about this project

这一步只读不写，没有任何风险。它读完给你一个概览，你就知道它有没有理解对这个仓库。理解错了，后面别指望它改对。

3.2 开跑之前的三件小事

cd ~/your-project
git status

预期结果：输出里没有未提交的改动。有的话，先提交或者暂存。

codex

预期结果：进入交互界面，底部有输入框。装好后第一次运行会先让你登录，见 §02。

官方说明里，/status 会显示当前的模型、审批策略、可写目录和 token 用量。我建议每次开新项目先看一眼，确认它在你以为的地方工作。

预期结果：你能看到模型名、审批策略，以及可写目录里包含你的项目目录。默认的 Auto 是工作区可写加按需审批，这两个词 §04 会拆开讲。

如果你对这个仓库心里没底，可以换个更保守的起点。用只读沙盒启动，让它先给方案，你同意了再放开。

codex --sandbox read-only --ask-for-approval on-request

这条命令的前半句限定它只能读，后半句让它在需要越界时来问你。读不够用的时候，它会请求更多权限，你再决定给不给。想中途切换，随时输入 /permissions。

3.3 提示写四件事：改什么、别碰什么、怎么算完成、去哪看

官方对 Codex 提示的描述，只有一句话。这句话里有四件事。

• 说清你要的行为。
• 指出相关的代码或复现步骤。
• 保留重要的约束。
• 说明怎么验证改动。

我把它压成四个问题，每个问题对应一句话。官方指南的概述部分另有一种通用拆法，对照见附录 A.7。

重点看第三行。「怎么算完成」是四件事里最容易漏的。你不说，它就按自己的理解收工。你说了「跑 npm test，全部通过再告诉我」，它就有了可核对的出口。

下面是同一个任务的两种写法。

给 src/utils/slug.ts 里的 slugify 补单元测试。
覆盖两种情况：空字符串，和带重音的字符。
只改 src/utils/slug.test.ts，不要动实现文件。
写完运行 npm test，全部通过再告诉我。

帮我把 slug 相关的代码测一下，质量弄好一点。

第二种写法的问题，不在语气，在于它什么都没定。「测一下」是改哪里？「质量弄好」又怎么验收？这样的提示，它也许能交出东西，但你没法判断交得对不对。我认为，提示越短越要警惕，因为短往往意味着该定的事没定。

再记两个官方的小提示。

• 描述结果，不要罗列步骤。只有步骤本身重要时，才写步骤。否则给它留空间去搜索、比较、调整做法。
• 首条提示只是起点。可以用后续消息补上下文、纠正方向，不必一开始就写得完美。

任务有多个步骤时，先输入 /plan。官方说它会让 Codex 先调查、提出方案，再动手编辑。你认可了方案，再放它去改。

3.4 看它干活：有两个瞬间该停下来

发出提示后，你会看到它交替做几件事。读文件，提出改动，请求运行命令，看输出，再继续。大多数时候你只需要看着。有两个瞬间不要走神。

瞬间一：它请求批准的时候

默认的 Auto 下，Codex 在工作区里读文件、改文件、跑命令，都不用问你。它要问你的，主要是两类事：改工作区以外的文件，或者运行需要联网的命令。

看到审批提示，别习惯性回车。先看三样：它要干什么，为什么要干，范围是不是你预想的。这一步就是「审批决定它什么时候问你」落到你手上的样子。

顺带记一个官方写明的细节。可写目录里的 .git 仍然是只读保护的。.agents 和 .codex 目录也是。也就是说，默认设置下沙盒里的命令写不了 .git。git commit 这类要写 .git 的命令，多半要走审批才放行。官方没有单独写 commit，这是我按受保护路径推的。提交这一步，新手阶段我建议留给你自己做。

瞬间二：它给出改动的时候

这是你真正要审的东西。别只看它的文字总结，要看 diff 本身。

• CLI 里输入 /diff，能看到已暂存、未暂存和还没被 Git 跟踪的文件。
• 输入 /review，让 Codex 审一遍你当前的改动。重点看行为变化和缺失的测试。
• 桌面应用的 Codex 视图和 IDE 扩展里，有现成的差异视图。改动就摆在代码旁边。

看完之后，自己再核对一遍。

git diff
npm test

它跑的时候，你还能插话

Codex 工作中，你可以接着发消息，不用等它停。CLI 里按 Enter 是「引导」：消息加入当前这一轮，用来改方向或补信息。按 Tab 是「排队」：消息留到下一轮。桌面应用里的默认行为，在设置的 General 里改。

发现它走偏了，连按两次 Escape（输入框为空时）。可以回到上一条你的消息，改写后从那个点分叉出新的聊天。

验收清单：每次都过一遍

四项里，第二项最费脑子，也最不能省。你读不懂的改动，就不该留下。

3.5 追问比重写更省事

第一版结果不对，别急着删掉重写提示。官方的建议是把第一版当草稿，用后续消息补上下文、纠正方向。

代码任务里，我建议用这几句追问。它们都在逼它把隐含的东西说出来。

• 「你做了哪些假设？」
• 「有哪些信息你没拿到？」
• 「继续之前，先问我两个你最不确定的问题。」
• 「把这次改动缩小到只涉及测试文件。」
• 「给我两种做法，说明各自的代价，先不要动手。」

官方对这件事的态度很实在。如果它访问不了某项资料，或者完成不了任务的某一部分，就要求它明说。明确指出不足，比自信地猜测更便于补救。

3.6 同一个提示，三个入口怎么发

在 CLI 里，Codex 不会自动看到你的编辑器状态。点名文件这件事要你自己做，所以提示里写清文件路径，比任何技巧都管用。需要时，输入 /ide 能把 IDE 里打开的文件和选区带进下一条提示。

如果你从桌面应用起步，第一个任务这样走。

用 IDE 扩展的话更直接。打开 Codex 侧边栏，打开相关文件，选中要改的代码，再发提示。选区和打开的文件会一起带上。

3.7 高频斜杠命令速查

在 CLI 的输入框里敲 /，会弹出命令列表，继续打字可以过滤。Codex 工作时，你可以输入命令后按 Tab 排队，等这一轮结束再执行。下面是第一周用得最多的。

表里有一处容易踩的细节：/fast 是切换，再输一次就关掉。

开新聊天、续聊、分叉、压缩和看用量的命令，见 §06 6.2 至 6.4。全表见附录 A.5。

除了斜杠命令，输入框还有几个键盘习惯值得养成。

• 输入 @ 搜工作区里的文件，把路径加进提示。
• 行首加 !，直接运行本地 shell 命令，受当前的审批和沙盒约束。
• 按 Up、Down 找回草稿历史，按 Ctrl+R 搜提示历史。

3.8 四个值得抄的提示模板

下面四个模板，思路来自官方的 Codex 提示示例，措辞是我重写的。每个都套了前面的四件事。

模板一：先读懂，再动手

我需要弄清楚这个服务的请求流程。
读 @routes.ts 和 @handlers.ts，按编号列出一个请求从进来到返回的步骤。
再列出涉及的文件。先不要改任何东西。

为什么这么写：它只读不写，边界明确。要求「编号步骤加文件列表」，让你能逐条核对，而不是读一大段看着像对的叙述。

模板二：修 bug，带复现和约束

Bug：在设置页点保存，界面提示「已保存」，刷新后开关又复原了。
复现：
1. npm run dev 启动应用
2. 打开 /settings，切换「开启提醒」
3. 点保存，然后刷新页面
约束：不要改接口的返回结构；修复要尽量小，能补回归测试就补。
先在本地复现这个 bug，再给出补丁并运行检查。

为什么这么写：官方的说法是，复现步骤和约束，比一句高层描述重要得多。「先复现」这一步，能防止它对着一个并不存在的问题写补丁。

模板三：补测试，点名函数

给 @transform.ts 里的 invert_list 函数补测试。
覆盖正常路径，再加空列表、单元素这两个边界。
沿用同目录其他测试的写法。运行后把命令和结果贴给我。

为什么这么写：点名了函数和文件，还要求「沿用现有写法」，它就不会另起一套风格。最后一句要求贴出命令和结果，是在把「怎么算完成」落到可核对的证据上。

模板四：大任务先出方案

/plan 为这个服务写一份迁移方案：配置从环境变量改成读配置文件。
列出要改的文件、每处改动的风险，以及你打算怎么验证。
方案出来之前，不要修改任何文件。

为什么这么写：/plan 后面可以直接带提示，官方的示例也是这个用法。方案是你最便宜的一次纠偏机会。方向错了，在这里改一句话，比在几百行 diff 里返工划算得多。

3.9 第一次就翻车的几种情况

最后一行的撤销，用 Git 就够了。我的建议是：先看清楚会删什么，再动手。

git restore .          # 撤掉未暂存的修改
git clean -nd          # 先预览：哪些新文件会被删
git clean -fd          # 确认无误后，删掉它新建的文件

另外，范围小还有一个好处是省额度。你在 §02 看到了，用量取决于任务大小、上下文和推理量。一个收紧的任务，花的 token 往往比一个松散的少得多。

3.10 这一节的结论

第一个任务的成败，一半看你挑的任务，一半看提示里有没有这四句话。它们是改什么、别碰什么、怎么算完成、去哪看。其中「怎么算完成」最容易漏，也最有用。

三个要带走的习惯：

• 开跑前 git status 干净，进去先 /status。
• 审批提示别回车，先看它要干什么。diff 别只看总结，自己跑测试。
• 走偏了就分叉或撤销，别在一团乱麻上接着改。

你在这一节里批准过的每一次请求，背后都是一个选择。沙盒划了线，审批决定它什么时候来问你。下一节，我们把这两根轴拆开，讲透。

§04 沙盒决定它能碰什么，审批决定它什么时候问你

Two Axes: Sandbox and Approvals

Codex 的权限是两个互相独立的设置。分清它们各管什么，你就不会再在「天天点确认」和「什么都干不了」之间来回摆。

2026 年 8 月 20 日，CLI 0.149.0 退役了审批策略的第三档。这一档叫 untrusted。9 月 4 日抓取的文档镜像里，它还是第三档。权限这件事最怕照旧资料抄。所以这一节按 2026 年 10 月 13 日的现行取值，重新讲一遍。

4.1 先给结论：每个动作都要过两道关

Codex 要执行一个动作，比如改文件、跑命令、访问网络，会先过两道关。第一道是沙盒：这件事在划定的边界之内吗。它由操作系统强制执行，管文件能写到哪里、命令能不能联网。第二道是审批：不在边界内，要不要停下来，停下来问谁。

两个设置互不依赖，可以自由组合。动作这样走：

如果不在边界内，就轮到审批这根轴接手。on-request 停下来请求批准，默认由你批准，也可以交给审查智能体（见 4.7）。never 不弹审批，智能体只能留在现有边界里想办法。granular 按提示类别分别处理。各取值的细节见 4.4。

这个模型有一个最容易搞错的推论：never 不等于放开权限。它只是不再问你，沙盒该拦的照样拦。真想放开，要去动沙盒这根轴。

沙盒存在的意义，是让边界内的低风险命令不用你确认。所以被问烦了，第一反应别去关审批。先看看边界是不是划得太窄。

4.2 沙盒：三个取值，一个比一个宽

沙盒管的是命令，不只是内置的文件编辑。智能体跑的 git、包管理器、测试工具，都继承同一套边界。

重点看第三行。danger-full-access 拿掉的是整个边界，文件和网络一起放开。

官方两页对 read-only 下能不能跑命令的说法不一致。沙盒页写的是不经批准不能改文件，也不能跑命令；审批与安全页的组合表写的是可以在只读沙盒内读文件、跑命令。我不替官方下结论，拿不准就看实际弹出的提示。官方也没有单独写只读沙盒下的网络。它只说本地智能体默认关闭网络。联网开关 network_access 属于 workspace-write。

默认值按目录有没有纳入版本控制而定。在你确认信任这个目录之前，还可能先落在 read-only。细节见 §02 2.6。

「工作区」具体包含哪些目录，用 /status 看。别靠猜。

4.3 workspace-write 里还有三块只读区

即使在 workspace-write 下，可写目录里也有三个路径只读。它们递归生效：

• .git：不管它是目录还是 gitdir: ... 指针文件。如果是指针，解析出来的真实 Git 目录一起保护。
• .agents：当它是目录时。
• .codex：当它是目录时。

官方安全页列的受保护路径就是这三个。CLI 0.159.0（2026-09-29）的发布说明另写了一条。可写根目录下的 .aws 目录默认也受保护。理由是 AWS 配置可以指定会被执行的凭据助手。两处说法不一致，页面还没跟上，用到 AWS 配置目录时以实际行为为准。

智能体能改你的代码，改不了 Git 元数据。所以 git diff 和 git checkout 这条退路始终在。

副作用是 git commit 要写 .git，可能仍要走审批。官方没有单独写 commit，这是我按受保护路径推出来的。官方的建议是：想对特定命令放行或拦下，用 rules，见 4.8。

需要它碰工作区之外的目录，加 writable_roots，别把整个沙盒放开：

sandbox_mode = "workspace-write"

[sandbox_workspace_write]
writable_roots = ["/Users/YOU/.pyenv/shims"]  # 额外可写的目录，写具体路径
network_access = false                        # 联网是单独的开关，见 4.9
exclude_slash_tmp = false                     # false 表示 /tmp 仍然可写

4.4 审批：三个取值，管的是打断你的频率

never 对所有 --sandbox 取值都适用。可以简写成 -a never。搭配 read-only，它就是最安静也最无害的组合。

granular 是一个带五个开关的表格。开关为 true，该类提示照常弹给你。开关为 false，该类提示自动拒绝：

approval_policy = { granular = {
  sandbox_approval = true,       # 沙盒越界的提权请求，照常问我
  rules = true,                  # 命中 rules 里 prompt 决定的命令，照常问我
  mcp_elicitations = true,       # MCP 服务器发来的追问，照常问我
  request_permissions = false,   # request_permissions 工具的权限请求，直接拒绝
  skill_approval = false         # 技能脚本的审批，直接拒绝
} }

审批管的也不只是 shell。带副作用的应用和 MCP 工具调用，同样会触发审批。工具如果声明了「破坏性」注解，调用一定要审批。如果它同时声明了「只读」注解，只读优先。

还有一个旧值要避开：on-failure 已弃用。官方的指引是，交互式运行用 on-request，非交互式运行用 never。

4.5 untrusted 已退役：旧资料里的第三档别再用

有的教程写着审批有三档：untrusted、on-request、never。那份教程已经过期。untrusted 在 CLI 0.149.0（2026-08-20）退役。官方现在明确说，Codex 和 ChatGPT Work 都不再支持 approval_policy = "untrusted"。

官方给了两条迁移路径。

第一条，交互式使用，直接换成只读加按需审批：

codex --sandbox read-only --ask-for-approval on-request

第二条，想保留原来「命令一律先问」的严格感。做法是不写显式的 approval_policy。在用户级配置里给具体项目标记不受信任：

# ~/.codex/config.toml，注意是用户级，不是项目里的 .codex/config.toml
[projects."/path/to/project"]
trust_level = "untrusted"

这样命令需要审批，除非 rules 放行。代价是项目本地的配置、Hooks 和 rules 也一并不加载。CLI 0.150.0 的发布说明还写了一条。不受信任的项目不再提供项目级 AGENTS.md 指令。显式写 approval_policy = "on-request" 会盖掉它。受管环境的写法见 §12.6。

4.6 把两根轴摆进一张矩阵

三个沙盒取值乘三个审批取值，一共九格。真正常用的只有几格：

上面九格里的「常用、少用、少见」是我的判断，不是官方分类。官方明确给出的常用写法只有五条。我照它整理了一遍：

注意 --ask-for-approval 是交互式 codex 的旗标。codex exec 没有这个旗标。0.162.1 源码里，exec 的参数列表没有它。无头模式默认就不弹审批，所以 CI 里写 codex exec --sandbox read-only 就够了。官方的 CI 组合表把两个旗标并列写，exec 页没有交代这个差别。

最后一行最需要小心。官方也提醒过：开发容器提供不少保护，但挡不住所有攻击。在容器里用 danger-full-access，恶意项目仍可以带走容器里能拿到的一切。这包括 Codex 的凭据。只对可信仓库这样用，并且盯着它的行为。

4.7 审批可以交给审查智能体：自动审查（auto-review）

审批太吵，又不想一刀切成 never，还有一条路：换个人来审批。这是第三个设置，但不是第三根轴。它只改「谁来回答」，不改边界。官方的说法是：换审批人，不发权限。它不扩大 writable_roots，不打开网络，也不削弱受保护路径。

approval_policy = "on-request"
approvals_reviewer = "auto_review"   # 默认是 "user"

流程是这样的。主智能体在沙盒里干活，需要越界时发出请求。Codex 把请求交给一个独立的审查智能体，不再等你。放行，动作继续。拒绝，主智能体必须换一条实质上更安全的路，否则停下来问你。

它只审四类请求：

• 请求提权的命令。
• 被沙盒拦住的网络请求。
• 可写根之外的文件编辑。
• 按注解或配置需要审批的 MCP 与应用工具调用。

沙盒内本来就允许的动作不经过审查，所以 never 时审查无事可做。完全访问权限或 --yolo 下没有边界可越，也就不会产生需要审查的请求。Computer Use 的应用级审批仍然直接弹给你。

它在防什么

审查策略盯四类风险：

• 把私密数据或密钥发往不可信目的地。
• 探测凭据、令牌、cookie。
• 大范围或持久地削弱安全。
• 有不可逆风险的破坏性操作。

低风险和中风险，策略允许就放行。严重风险一律拒绝。高风险要有足够的用户授权。审查本身出错按拒绝处理，超时的话动作也不会执行。

被拒绝之后

显式拒绝和普通沙盒报错不一样。Codex 把审查理由交还给主智能体。它还追加一条更强的指令：不许绕路，不许间接执行，不许规避策略。

每个回合还有熔断。按当前开源实现，连续拒绝 3 次，当前回合就会中断。最近 50 次审查里拒绝 10 次，同样中断。确认是误伤，在 TUI 里输入 /approve。选一条最近被拒的动作，放行一次重试。放行只对那一次动作有效，重试仍要过审查。

代价与边界

审查会多调用模型，所以多花用量。管理员可以用 allowed_approvals_reviewers 限制。官方也承认它不是确定性的安全保证，会犯错。GPT-6 Astra 另带一层异步安全监控。详见官方 Agent approvals & security 页。

想减少审查次数，官方的建议值得照抄：先修边界，别教审查智能体永远放行噪音请求。加窄的 writable_roots。加精确的 rules 前缀，比如 ["cargo", "test"]。宽泛的 ["python"]、["curl"] 会把审查本想守的边界抹掉。

桌面端与 IDE 的权限菜单

桌面应用和 IDE 扩展里，输入框下方有权限控件。CLI 里输入 /permissions。菜单项和配置大致这样对应：

这张对照是我按官方沙盒页和权限模式页归纳的。官方明确写了的只有两条。完全访问权限就是 danger-full-access 加 never。替我审批的工作区边界，和请求审批相同。

可用的模式取决于应用版本、执行环境、本地配置和组织要求。没出现或被禁用，不一定是你配错了。「菜单里有」也不等于「当前聊天选中了」。

4.8 例外靠 rules，不靠放宽沙盒

工作流里总有几条命令必须出沙盒，比如 git push。正确做法是给这几条命令开例外，不是把整个沙盒放宽。这件事归 rules 管。官方标注它仍是实验功能，可能变化。

规则文件放在生效配置层旁边的 rules/ 目录里。比如 ~/.codex/rules/default.rules。语法是 Starlark，写起来像 Python：

# ~/.codex/rules/default.rules
prefix_rule(
    pattern = ["git", "push"],          # 必须是命令的精确前缀
    decision = "forbidden",             # allow / prompt / forbidden
    justification = "推送交给人来做，先在本地提交。",
    match = ["git push origin main"],   # 加载时校验：这条应该命中
    not_match = ["git status"],         # 加载时校验：这条不该命中
)

三种决定各管一种情况：

• allow：不弹提示，直接在沙盒外运行。
• prompt：每次先问。
• forbidden：不问，直接拒。

多条规则同时命中，取最严的：forbidden 高于 prompt 高于 allow。

改完要重启 Codex。想先测一条命令会得到什么决定，用 codex execpolicy check。

codex execpolicy check --pretty \
  --rules ~/.codex/rules/default.rules \
  -- git push origin main

预期结果：输出 JSON，列出最严的决定和命中的规则。

复合命令不会被钻空子。由 &&、||、;、| 串起来的简单命令，Codex 会拆开逐条比对。最严的生效。带重定向、变量替换、通配符的脚本不拆，整条当一次调用。

allow 规则的范围要窄，宽了等于把沙盒拆了。项目里 <repo>/.codex/rules/ 的规则只在项目被信任时才加载。见 §12.4。

AGENTS.md 里的「不要 push」是请求。rules 里的 forbidden 是执行前比对。两者的分工见 §05 5.6。

4.9 联网是单独的闸门

本地智能体默认关闭网络，沙盒里的命令默认连不上网。在 on-request 下，需要联网的命令会触发审批请求。批准的范围可能是这一次，也可能是整个会话，以弹窗给的选项为准。官方没写这一步是先试一次再问，还是直接问。

在 never 下没有人可问。命令仍在无网络的沙盒里跑，连不上就直接失败。workspace-write 想不被反复问，要单独把网络打开：

[sandbox_workspace_write]
network_access = true

打开之后，命令可以连任何地方，包括被提示注入诱导的地址。想限制目的地，再开网络代理：

[features.network_proxy]
enabled = true
domains = { "api.openai.com" = "allow", "example.com" = "deny" }

代理不会自己开启联网。它只约束「已经开着的网络」：

域名规则是白名单优先。精确主机只匹配自己。*.example.com 匹配子域名，不含 example.com 本身。**.example.com 两者都含。deny 永远压过 allow。全局 * 等于大范围联网，能写具体域名就别用。回环和私有网段默认拦截。

代理只管沙盒里命令的网络。下面这些都不走它，各有各的控制项：

• 网页搜索。
• 应用和连接器。
• MCP 连接。
• 浏览器与 Computer Use。
• 云端任务。
• 客户端自己的模型请求。

网页搜索是另一个口子

网页搜索可以单独控制，不需要给命令开网络：

web_search = "cached"   # 默认。读 OpenAI 维护的索引，不抓实时页面
# web_search = "indexed"  # 外部访问由搜索索引把关
# web_search = "live"     # 等同命令行 --search
# web_search = "disabled" # 关掉这个工具

一旦用了 --yolo 这类完全访问设置，搜索默认变成 live。网页内容一律当成不可信输入，提示注入就是从这里进来的。

云端的联网设置

云端环境的联网是另一套设置，新版的域名范围和凭据放法见 §10.7。旧版 Codex Cloud (Legacy) 的智能体阶段默认断网。可以按环境开，还能限制只允许 GET、HEAD、OPTIONS。官方旧页举过例子。issue 正文里藏一句命令，让智能体把最近的提交信息 POST 到外部地址。联网越宽，越容易出这类事。

4.10 三个系统，三种执行器

概念一样，底层实现和你要做的事不一样：

Linux 与 WSL2

sudo apt install bubblewrap   # Ubuntu / Debian
sudo dnf install bubblewrap   # Fedora

Codex 用 PATH 里找到的第一个 bwrap。找不到会退到自带的辅助程序。那要求系统允许非特权用户命名空间，建不了就在启动时警告。Ubuntu 24.04 上装了 bubblewrap 仍可能警告。要另外加载 AppArmor 配置，步骤见官方沙盒页。

Windows 原生

Windows 上推荐 mxc。它不需要管理员批准的安装，不加额外账户，也不动本地防火墙规则。桌面应用在设备支持时，对个人账户自动优先用它。CLI 和企业部署用下面的配置打开同样的行为。同时留一个旧版回退：

[features]
prefer_mxc = true

[windows]
sandbox = "elevated"   # 旧版回退，MXC 不可用时才用；也可写 "unelevated"

也可以显式写 windows.sandbox = "mxc"。但设备不支持时会直接失败。MXC 要求较新的系统。官方写明，微软在下面两个版本里引入了对应的进程隔离，仍在向设备推送：

• Windows 11 24H2：构建号 26100.9278。
• Windows 11 25H2：构建号 26200.9278。

CLI 0.162.0 起，可以单次测试，不改保存的设置：

codex -c windows.sandbox=mxc sandbox --include-managed-config --permission-profile :workspace -- cmd.exe /d /c echo MXC_OK

预期结果：输出 MXC_OK，退出码为 0。这条在 PowerShell 里跑。

有个限制：前台命令退出后，剩下的子进程会被终止。依赖后台常驻开发服务器的流程要重新测。机器不支持 MXC 时，旧版 elevated 是首选回退。它需要管理员批准的安装。

要用 Linux 工具链，或流程本来就在 WSL2 里，就选 WSL2。VS Code 扩展想让智能体留在 WSL2 里，加这条设置：

"chatgpt.runCodexInWindowsSubsystemForLinux": true

Docker 里沙盒起不来怎么办

在 Docker 这类容器里，沙盒可能起不来。宿主机或容器配置可能拦住 Codex 需要的命名空间或 seccomp 操作。官方的做法是先把容器本身配成你要的隔离边界。然后在容器里用 --sandbox danger-full-access。别让它再叠一层沙盒。官方还提供了带出站防火墙的 devcontainer 参考实现。

想看某条命令在沙盒下会怎样，用 codex sandbox，也叫 codex debug。子命令是 macos、linux、windows。具体参数以 codex sandbox --help 为准。

4.11 权限配置方案（Beta）：把文件和网络收进一个名字

sandbox_mode 加 sandbox_workspace_write 是老办法。新办法是权限配置方案（permission profile）。一个命名策略里，同时写文件规则和网络规则。官方标注为 Beta，可能变化。

内置三个：

• :read-only：本地命令只读。
• :workspace：允许写活动工作区和系统临时目录。
• :danger-full-access：去掉本地沙盒限制。

自定义的写在 [permissions.<名字>] 下。用 default_permissions 指定默认用哪个。优先用 extends 继承内置。.git、.codex 只读这类保护就自动带过来。:danger-full-access 不能被继承。

default_permissions = "project-edit"

[features]
network_proxy = true               # 要让下面的域名规则真正生效，必须开

[permissions.project-edit]
extends = ":workspace"

[permissions.project-edit.filesystem.":workspace_roots"]
"**/*.env" = "deny"                # 这类环境文件连读都不许

[permissions.project-edit.network]
enabled = true

[permissions.project-edit.network.domains]
"api.openai.com" = "allow"

网络代理的写法和 4.9 不同。权限配置方案里，域名写在方案下面，features.network_proxy 只当开关用。4.9 的表形式，则把开关和域名写在一起。两种写法都成立，别混着抄。

我的建议是先把两根轴用熟。真需要细规则时，再迁移过来。比如「工作区可写但 .env 不许读」，或者「只放行某几个域名」。

4.12 实操：三步把权限调到合适

# ~/.codex/review.config.toml  只读看代码，越界再问
sandbox_mode = "read-only"
approval_policy = "on-request"

# ~/.codex/ci.config.toml  无人值守，只读，绝不弹审批
sandbox_mode = "read-only"
approval_policy = "never"

codex --profile review

预期结果：用 review 这套配置启动。

4.13 症状对照：该动哪根轴

重点看第一行。「烦了就关审批」最顺手，但它绕开了真正的问题：边界划得对不对。

4.14 这一节的结论

我的推荐组合只有三个。日常用 workspace-write 加 on-request，一整天都别动它。看陌生仓库用 read-only 加 on-request。CI 用 read-only 加 never。想换别的组合之前，先问自己：我要放开的是边界，还是只是不想被问。

两根轴管的是它能做什么。但它每次开工都要重新认识你的项目：测试怎么跑，哪些目录不能碰。下一节讲 AGENTS.md，把这些规矩一次交代清楚。

§05 项目规矩写进 AGENTS.md，别再每次开场重讲一遍

AGENTS.md: Tell Codex the Rules Once

AGENTS.md 管「怎么干活」，两根轴管「能不能干」。这一节讲它去哪里找、怎么叠加、该写什么。还讲它和 rules、memories 怎么分工。

2026 年 8 月 26 日，CLI 0.150.0 改了一件事。不受信任的项目，不再提供项目级 AGENTS.md 指令。项目里的文件读不到时，先查项目有没有被信任。本节依据 2026 年 10 月 13 日的官方页面和 0.162.1 源码。加载顺序和 32 KiB 合并上限都对照过。

5.1 先给结论：AGENTS.md 是写给智能体的工作守则

设想第一天。你每次开场都要打一遍。这个项目用 pnpm，改完代码要跑测试，不要随便加生产依赖。第五天你开始烦。第十天你漏了一条，它给你装了个新包。

AGENTS.md 就是把这些话写进仓库，让 Codex 自己读。官方文档的说法是：Codex 在开始任何工作之前，先读 AGENTS.md。每个任务从一致的预期出发，不管你打开的是哪个仓库。

先把边界划清楚。AGENTS.md 是指令，不是权限。它能告诉 Codex「提交前跑 lint」。但它不能让 Codex 获得写某个目录的能力。后者归 §04 的两根轴管。

我用三个递进的类比来记这几样东西：

• AGENTS.md 是贴在工位上的工作守则，每次开工都看。
• rules 是门禁系统里的白名单，管哪些命令能出沙盒。
• memories 是同事自己记的笔记，有用，但不是制度。

5.6 会把这三样和技能放进同一张表里对比。

5.2 它怎么找文件：全局、项目、合并

Codex 启动时构建一条指令链。每次运行构建一次，在 TUI 里通常是每个会话一次。没有缓存，所以改完文件，重开会话就生效，不需要清任何东西。

第一层：全局

在 Codex 主目录下找。默认是 ~/.codex，设了 CODEX_HOME 就用那个。有 AGENTS.override.md 就读它，否则读 AGENTS.md。这一层只用找到的第一个非空文件。

第二层：项目

从项目根开始，一级一级往下走到当前工作目录。项目根默认是含 .git 的目录。每一级依次找三样：

• AGENTS.override.md。
• AGENTS.md。
• project_doc_fallback_filenames 里配置的备用文件名。

每个目录最多纳入一个文件。找不到项目根，只看当前目录。

项目根的标记可以改。project_root_markers = [".git", ".hg", ".sl"] 表示这几个都算。设成空数组 []，就以当前目录为根，不再往上找。

第三层：合并

从根往下依次拼接，中间用空行隔开。越靠近当前目录的文件，拼出来的位置越靠后，所以越近的规矩优先级越高。空文件会被跳过。合并后的总大小一到 project_doc_max_bytes 的上限，就不再往里加。默认是 32 KiB。

下面是一个仓库的样子：

~/.codex/AGENTS.md                    个人偏好，所有仓库共用
my-repo/
├── AGENTS.md                         仓库规矩，提交进版本库
└── services/
    └── payments/
        ├── AGENTS.md                 被忽略，因为同目录有 override
        └── AGENTS.override.md        支付服务的特殊规矩

从 services/payments 启动，Codex 先读全局文件。再读仓库根的 AGENTS.md。接着读 payments 的 override。override 在同一目录里取代 AGENTS.md，不是叠加。但它不影响更上层的文件，仓库根那份照样会读。

重点看第三行：子目录那份只写差异。它已经继承了上面两层，不用重复。

分层的顺序，我建议从上往下长。先只写仓库根那一份。哪块代码真有特殊规矩，再给它单开一个子目录文件。一上来就铺满每一层，只会让你在五个文件之间找「到底哪条生效」。

5.3 该写什么：能让它少走弯路的几类

官方给的清单很短：构建和测试命令，评审预期，仓库约定，目录专属指令。再往下，官方只强调一件事：保持精简。先写真正重要的，用得多了再补。

我的判断是，值得写的内容有三个特征。Codex 自己猜不出来，写错的代价不小，还会反复遇到。

• 跑什么命令。测试、lint、构建，尤其是跟惯例不一样的那种。
• 硬性红线。哪些文件是生成的不能手改，加依赖要先问，哪个目录别碰。
• 路由指引。官方提到一种情况：它找对了文件，但读了太多文档。这时在 AGENTS.md 里写清先看哪些目录，比让它自己摸省事。
• 评审标准。你在 PR 里重复提过的意见，写下来。

左边每一句都能照做、能检验。右边是正确的废话，占着篇幅，什么也没规定。

怎么写才有效？我自己的标准是四条：

• 写动作，不写态度。「提交前运行 pnpm lint」可执行，「注意代码质量」不可执行。
• 一条只讲一件事。拆开写，后面才好增删。
• 给出安全的做法。只说「不要手改生成文件」，不如再补一句「改 schema/ 后重新生成」。官方写代码审查规则时也是这个思路。说明要标记的行为，再说明安全的做法或例外。
• 可检验。写完能想出一个任务来验证它有没有被照做，就算合格。

还有一个容易忽略的成本。官方说明，Codex 会把有限的项目指引放进会话的第一轮。也就是说，AGENTS.md 写得越长，一开场占的上下文越多。这件事 §06 会接着讲。

也有不该写的。代码本身说得清的事，比如技术栈和目录结构，它会自己看。长篇架构介绍更没必要，32 KiB 上限不是给你写文档用的。官方建议用 pre-commit hook、linter、类型检查来强制执行。代码审查规则里也明说，格式和 lint 检查留给 CI。AGENTS.md 是提醒，不是执法。

5.4 动手：四步写出第一份 AGENTS.md

# AGENTS.md

## 构建与测试
- 改完代码运行 `pnpm test`，提交前再运行 `pnpm lint`。
- 装依赖用 pnpm，不要用 npm。

## 红线
- 新增生产依赖之前先问我。
- `src/generated/` 是生成文件，不要手改。改 `schema/` 后运行 `pnpm gen`。

## 找东西
- 接口定义在 `src/api/`，业务逻辑在 `src/services/`，不用全仓库搜索。

## Code Review Rules
- 数据库迁移必须带回滚脚本。

git add AGENTS.md
git commit -m "docs: add AGENTS.md"

codex --ask-for-approval never "Summarize the current instructions."

这里用 --ask-for-approval never，是因为这个问题不需要任何动作。不用弹审批。要验证子目录的覆盖，换个目录启动：

codex --cd services/payments --ask-for-approval never "List the instruction sources you loaded."

预期结果：先报全局文件，再报仓库根的 AGENTS.md。接着是 payments 的 override。

想看更细，可以让 TUI 写日志：codex -c log_dir=./.codex-log。然后查看 ./.codex-log/codex-tui.log。

5.5 嵌套、改名和代码审查：三个常见需求

临时覆盖，不删原文件

需要临时改全局规矩，建一个 ~/.codex/AGENTS.override.md。它存在时，基础文件被整体取代。删掉它，共享的规矩就恢复了。

仓库里已经有别的文件名

团队原来就有 TEAM_GUIDE.md，不用改名，把它登记到备用列表：

# ~/.codex/config.toml
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536     # 同时把合并上限从 32 KiB 提到 64 KiB

重启后，每个目录按这个顺序找：AGENTS.override.md、AGENTS.md、TEAM_GUIDE.md、.agents.md。不在列表里的文件名一律忽略。

想给自动化账号一套独立的指令，可以指定另一个主目录：

CODEX_HOME=$(pwd)/.codex codex exec "List active instruction sources"

预期结果：输出的是这个自定义 .codex 目录下的文件。

给 GitHub 代码审查写规则

GitHub 上的 Codex 代码审查，规则也写在 AGENTS.md 里。在离相关代码最近的那份里，加一节 ## Code Review Rules。仓库级检查放根目录，服务级检查放嵌套文件。每条写清楚两件事：要标记什么行为，安全的做法或例外是什么。格式和 lint 留给 CI。审查本身怎么用，见 §10 和 §11。

5.6 四样东西各管什么：AGENTS.md、rules、memories、skills

官方把这几样叫作「互补，不是竞争」。问题在于，新手容易把规矩塞错地方。我整理了一张对照表：

重点看前两行。「不要 git push」写在 AGENTS.md 里，是请你的智能体遵守。写成 rules 里的 forbidden，Codex 在执行前会拿命令前缀去比对。我的读法是：AGENTS.md 靠模型自觉，rules 靠规则引擎。真正不能出错的事，两处都写。

举个例子。「不要自己推送」这件事，可以在两边各写一份：

# AGENTS.md 里：告诉它为什么、该怎么做
- 完成后只在本地提交，推送由我来做。

# ~/.codex/rules/default.rules 里：执行前拦住
prefix_rule(pattern = ["git", "push"], decision = "forbidden",
            justification = "推送由人来做，先在本地提交。")

前者让它知道该怎么做，后者保证万一它忘了，也推不出去。示例里让它提交，提交会走一次审批，除非 rules 放行，见 §04 4.3。

memories 要点

本地 Codex 的 memories 默认关闭。桌面应用在「设置 > 个性化」里启用，也可以写配置：

[features]
memories = true

开启之后，Codex 会等聊天空闲一段时间。然后把合格的历史聊天，提炼成本地记忆文件。文件存在 ~/.codex/memories/。它会跳过活跃的或很短的会话，对生成的字段做密钥脱敏。更新在后台进行，所以聊天刚结束时，记忆不一定马上更新。

几条使用要点：

• 用 /memories 控制当前聊天能不能使用已有记忆、能不能成为未来记忆的来源。这个选择不改全局设置。
• 这些文件是生成出来的状态，可以查看，但别把手改当作主要控制手段。
• 不要往里存密钥。分享你的 Codex 主目录之前，先检查记忆文件。
• 官方明确说：团队必须遵守的规矩，放在 AGENTS.md 或随仓库提交的文档里。不要只靠 memories。

最后一条是这一节最该记住的话之一。memories 在你的机器上，同事看不到，换台电脑也没有。进了版本库的 AGENTS.md，所有人都读得到。

5.7 把 AGENTS.md 养成团队资产

写完不是结束。官方推荐把它当成反馈回路来养。Codex 对你的代码库做错了假设，就纠正它。再让它把纠正写进 AGENTS.md，这样下次会话自动继承。什么时候该更新，官方给了几个信号：

• 重复犯错。同一个错出现第二次，加一条规矩。
• 读得太多。文件找对了，但读了一堆不相干的文档，加路由指引。
• PR 反馈重复。同一条意见说第二遍，就该写下来。

纠正之后，直接让它自己写：

刚才你把迁移脚本放错了目录。请把「迁移脚本放在 db/migrations/」这条规矩
补进仓库根的 AGENTS.md，保持文件精简，不要重复已有的条目。

预期结果：Codex 修改 AGENTS.md。你看一眼 diff，确认没有多出废话，再提交。

在 GitHub 的 PR 里，直接评论 @codex add this to AGENTS.md。这会把更新委托给一个云端聊天。你还可以用定时任务定期检查有没有该补的规矩，见 §10。

AGENTS.md 还能影响协作方式。官方说明，Codex 可以按适用的 AGENTS.md 去派子智能体。技能里的指示同样适用。比如在里面写明「需要通读大量文件时，交给子智能体并返回摘要」。这样噪音就挡在主线程之外，见 §06 和 §09。

规矩写多了也会出问题。排错时对照这张表：

5.8 这一节的结论

我的建议是，今天就用 /init 搭一份，删到十来行，提交。以后每次你对它说「不是这样，应该这样」超过两遍，就让它把这条写进去。

规矩交代完了，还剩一个麻烦：同一个聊天聊得太久，它还是会变钝。下一节讲上下文，以及长任务该怎么组织。

§06 上下文是有限的，长任务靠定目标和拆分，不靠硬撑

Context and Long-Running Work

聊天拉长了会变钝，这是上下文的问题。这一节讲怎么看用量、怎么压缩、什么时候换新聊天。还讲怎么把一个要跑很久的任务组织好。

2026 年 9 月 22 日，CLI 0.156.0 给 /usage 加了分析面板。账号用量、token 总数、插件和技能的使用情况，都能在里面看。上下文用掉多少，也该每一轮都看得见。

6.1 先给结论：先问「该不该继续」，最后才调参数

聊到很长的时候，你会看到几种症状：

• 它忘了半小时前定的约定。
• 它把已经改好的地方又改回去。
• 它反复读同一个文件。

官方用两个词描述这件事。上下文污染：有用的信息被杂乱的中间输出淹没。上下文腐化：聊天被相关性低的细节填满，表现逐渐下降。探索笔记、测试日志、堆栈、命令输出，都算这类噪音。全留在主聊天里，要紧的需求和约束就被挤到角落了。

官方没有给出「聊多少轮会变钝」的数字，所以别信任何人报的固定轮数。该看的是你的聊天里堆了多少噪音。

处理的顺序，我的建议是下面这样。越靠上越便宜，越靠下越贵：

重点看顺序。多数人一遇到变钝就去调压缩阈值，其实问题常常出在第一行。

6.2 先看清用了多少

别凭感觉判断上下文满没满。CLI 里有三个入口：

• /status：当前模型、审批策略、可写目录和 token 用量。官方的说法是用它确认剩余的上下文容量。
• /statusline：交互式配置终端底部的状态栏。可选模型、上下文、限额、Git、token、会话等字段，并保存到 config.toml。
• /usage：账号级别的 token 用量。/usage daily、/usage weekly、/usage cumulative 直接打开对应视图。需要 Codex 服务账号登录。

我的建议是把上下文显示在状态栏里。这样每一轮你都看得见，不用等它出问题再去查。

6.3 压缩：能用，但要知道它在丢什么

压缩是把前面的轮次换成一份摘要，腾出上下文。官方的描述是：Codex 用简洁的摘要替换较早的轮次。这样释放上下文，同时保留关键细节。

手动压缩

长对话之后输入 /compact，Codex 会请你确认是否总结目前的聊天。预期结果：较早的轮次被一份摘要取代，上下文占用下降。

自动压缩

历史逼近阈值时，Codex 会自动压缩。相关配置有三个：

# ~/.codex/config.toml
# 不设就用模型默认值。要调，先用 /status 看实际窗口，再定数字
# model_auto_compact_token_limit = <token 数>
model_auto_compact_token_limit_scope = "total"   # 默认。另一个取值是 body_after_prefix

如果你想改压缩时用的提示词，有 compact_prompt 可以内联覆盖。文件形式的 experimental_compact_prompt_file 标注为实验性。Hooks 里还有 PreCompact 和 PostCompact 两个事件。可以在压缩前后插入自己的动作，见 §07。

6.4 开新聊天：比压缩便宜，也比压缩可靠

一个任务干完就开新的，别在一个聊天里连着做三件不相干的事。这是最简单的办法，也最容易被低估。

它能这么轻松，前提是关键约定已经写在 AGENTS.md 里。新聊天不用重讲，这就是 §05 值得先做的原因。

几个细节：/clear 和 Ctrl+L 在任务运行中不可用。codex resume 的 --last 默认只在当前工作目录里找，加 --all 才跨目录。当前目录和聊天保存的目录不一样时，Codex 会问你用哪个。tui.resume_cwd 可以固定这个选择。侧聊不能嵌套，评审模式里也不能开。

桌面应用里，每个聊天都有自己的上下文、消息、结果和目标。想并行做两件事，就开两个聊天，别塞进一个。

6.5 把噪音挪出主聊天：子智能体

要读的东西实在太多时，别让主聊天去读。让它派子智能体去读，只把结论带回来。官方的思路是：主智能体守住需求、决策和最终输出。子智能体去做探索、跑测试、分析日志。它们返回摘要，不返回原始输出。

在 CLI 里直接说就行：

用子智能体分别从安全风险、测试缺口、可维护性三个角度审查这个分支。
三个都完成后，按类别汇总发现，每条带上文件引用。

预期结果：Codex 派出几个子智能体并行去读，最后在主聊天里给你一份汇总。运行中用 /subagents 查看并切换本会话的子智能体线程。官方命令页还写了 /agent。但 0.162.1 的源码里，这个命令已经改名为 /agents，打开的是智能体指挥中心。

代价要算清。每个子智能体各自调用模型和工具。所以子智能体工作流，比同等的单智能体运行更耗 token。我的判断是，先用在以读为主的任务上：探索、测试、分流、总结。官方在长任务页提醒，别让两个聊天改同一批文件，我认为子智能体同理。具体怎么配，见 §09。

6.6 长任务：用 /goal 把「做完」定义清楚

一个要跑很多步的任务，官方的建议是：给它明确的结果、约束和完成标准。并把相关工作放在同一个聊天里。让它用同一份上下文选择下一步、判断何时完成。

桌面应用、CLI、IDE 扩展里，都用 /goal 进入目标模式。你输入的目标文本既是第一条提示，也是完成标准。

目标要写哪三样

重点看第三行。目标要让它能自己检验进度，所以验证不是可选项。一个写得过关的目标长这样：

/goal 把 api/ 目录下所有回调风格的函数改成 async/await。
保持对外行为不变，不新增依赖。
pnpm test 和 pnpm lint 全部通过，并在 docs/migration.md 里记录每一处改动。

目标文本不能为空，最长 4,000 个字符。内容更长，就把细节放进文件，让目标指向那个文件。

结果还说不清的时候，先用 /plan。让 Codex 先访谈你、找出约束。再整理成带可衡量标准的目标，用 /goal 启动。Codex 已经在干活时，/plan 暂时不可用。

跑起来之后怎么管

最重要的一条，是启动目标不会给它更大的权限。它仍然受同一套沙盒和审批策略约束，需要决定时照样暂停。配了自动审查的话，独立的审查智能体可以评估符合条件的请求，但边界不会因此扩大。

这直接把 §04 接了过来。长任务最怕的是跑到一半卡在审批上，没人应答。有两种想法，我不推荐第二种。第一种，开工前就把边界想清楚。补窄的 writable_roots，加精确的 rules 前缀，再考虑 auto_review。第二种，为了不被打断直接上 never 加完全访问。官方说，自动审查改善了长时间运行的智能体工作的默认状态。但它不是确定性的安全保证。

6.7 让长任务不用你盯着：并行、不休眠、通知

并行

每个聊天各管各的上下文和目标。可以同时跑，但别让两个聊天改同一批文件。需要并行改代码，用 worktree 给每个聊天一份独立的检出，见 §09。

别让电脑睡着

本地长任务最怕机器休眠。桌面应用里，设置中打开 Prevent sleep while running。Mac 就会保持唤醒。CLI 里对应的是实验性功能。输入 /experimental 勾选它，或者在配置里写 features.prevent_idle_sleep。官方标注它是实验性的，默认关闭。

通知：不同界面各有各的开关

CLI 的内置通知可以只订阅你关心的事件：

[tui]
notifications = ["agent-turn-complete", "approval-requested"]  # 也可以写 true 表示全开
notification_method = "auto"          # auto / osc9 / bel，auto 优先用 OSC 9，不支持就退到响铃
notification_condition = "unfocused"  # 默认。终端失焦才通知；写 "always" 则始终通知

通知想送到别处，比如桌面弹窗、聊天 webhook、CI 通知。用 notify 运行一个外部程序：

notify = ["python3", "/path/to/notify.py"]

程序会收到一个 JSON 参数。目前支持的事件只有 agent-turn-complete。常用字段有 type、thread-id、turn-id、cwd、input-messages 和 last-assistant-message。

6.8 速度：用额度换时间

Fast 和 Ultrafast 是用更多额度换更快的速度。选哪个取决于你是不是坐在旁边等。

表里的「倍」是相对 Standard 速度的用量倍率。官方说，GPT-6 Astra 的 Ultrafast 生成 token 更快。最快可达 Standard 的 8 倍。用 API Key 的话，走的是 API 的 token 计价。ChatGPT 的积分倍率不适用。

Ultrafast 在 Pro $500 档里先扣包含的用量，用完再扣积分。其他自助套餐，即便购买了积分，上线时也没有 Ultrafast。Enterprise 里默认关闭，要工作空间管理员为选定用户或整个工作空间开启。

我的判断是，Fast 适合你在旁边等的短任务，不适合跑一整夜的长任务。长任务开了 Fast，只是用 2.5 倍的速度烧额度，而你本来就不在等。可以用 /statusline 把当前是不是 Fast 显示在状态栏里。

6.9 这一节的结论

我的建议是养成一个习惯：每个任务一个聊天，每个聊天一个目标。目标写完整，约定写进 AGENTS.md，进度靠通知看，不靠盯。

你反复用到的做法，比如固定的评审流程、固定的发布步骤，值得打包起来重复用。下一节讲技能、插件与 Hooks。

§07 技能管流程，插件管分发，Hooks 管拦截

Skills, Plugins and Hooks

AGENTS.md 交代的是项目规矩。这一节讲三种让 Codex 多会一件事的办法。它们是技能、插件，以及在固定节点替你跑脚本的 Hooks。

7.1 三样东西各管一段：流程、分发、拦截

每周都要对 Codex 说同一段话，比如发布说明按什么格式写。说到第三遍，就该把它存起来了。Codex 给了三个存放的地方，名字听着差不多，管的事完全不同。

区别在谁说了算。技能是建议，模型可以选，也可以不选。Hooks 是机关，事件到了就触发。插件只是包装盒。

回到全书的主线。这三样东西没有一样能绕开沙盒和审批。官方的说法是，插件功能经由 Codex 主机运行时。适用的就是这台主机的沙盒和审批策略。技能带的脚本也一样。granular 审批写法里有个 skill_approval。它专管技能脚本的审批提示，见 §04。

7.2 技能就是一个目录，门面是 description

技能的最小形态是一个文件夹，里面有一份 SKILL.md。完整一点的长这样。

my-skill/
├── SKILL.md          必需：指令和元数据
├── scripts/          可选：可执行脚本
├── references/       可选：参考文档
├── assets/           可选：模板、资源
└── agents/
    └── openai.yaml   可选：外观、调用策略、依赖

SKILL.md 必须有 name 和 description，其余都可选。

渐进式披露，以及 2% 的预算

Codex 不会把所有技能的全文塞进上下文。它先只拿每项技能的名称、描述和文件路径。决定用哪一项之后，才去读完整的 SKILL.md。官方把这叫渐进式披露。

这个初始列表有预算。预算是模型上下文窗口的 2%，窗口大小不明时是 8,000 个字符。技能装多了，Codex 先缩短描述，再多就省略一部分并给出警告。

所以技能不是装得越多越好。三十个用不上的技能，可能把你真正需要的那个挤出列表。description 的开头也最值钱。描述被缩短时丢的是后半截，官方建议把关键场景和触发词放在最前面。上下文用量怎么看，见 §06 6.2。

两种触发方式

• 显式调用：在 CLI 或 IDE 扩展里运行 /skills。也可以输入 $ 再选技能。ChatGPT 里对应的符号是 @。
• 隐式调用：你没点名，但任务对上了某项技能的 description。Codex 自己选。

隐式调用全凭 description。写它的时候，要像给同事写一句「什么情况下该来找我」。

好描述有三个要素：什么时候用，输入输出是什么，什么时候不用。最后一条最容易漏，却最能减少误触发。我的建议是先写「不该用」那一句，再写「该用」的。

7.3 动手写一个技能：PR 描述

下面的例子是我编的演示，换成你自己的任务就行。

第 3 步的技能文件，完整写出来是这样。

---
name: pr-description
description: 当用户要求为当前分支写 PR 描述时使用。输入是当前分支相对主干的提交和 diff，输出是固定三段的描述。不要用于写 commit message，也不要用于代码审查。
---

按下面的步骤写 PR 描述。

1. 运行 git log 和 git diff，对比当前分支与主干，列出改动的文件和提交。
2. 输出三段：做了什么、为什么做、怎么验证。
3. 「怎么验证」只写你确实运行过的命令。没运行过就写「未验证」。
4. 不要修改任何文件，只输出描述文本。

每一步都是祈使句，输入输出都写明了。第 3 条专门堵一个常见毛病：把没跑过的测试写成已通过。这也是官方最佳实践的方向：一个技能只做一件事。

第 5 步的配置如下。allow_implicit_invocation 默认是 true。设成 false 后，Codex 不再隐式调用它。$pr-description 这样的显式调用照常可用。

# pr-description/agents/openai.yaml
policy:
  allow_implicit_invocation: false

7.4 技能放在哪里，决定谁能用到它

Codex 从六类位置读取技能。在仓库里，它从当前目录向上扫描到仓库根。每一级的 .agents/skills 都看。

同名技能不会合并。两个同名的都会出现在选择器里，所以命名别撞车，尤其是个人技能和仓库技能之间。想临时停用某个技能，又不想删。就在 ~/.codex/config.toml 里写下面的配置。改完重启 Codex。

[[skills.config]]
path = "/path/to/skill/SKILL.md"
enabled = false

想装别人写好的技能，在 Codex 里用内置安装器。例如装精选技能 linear：

$skill-installer linear

官方的定位是，这条路适合本地试验，要分发自己的技能请用插件。我的建议是分层放。个人偏好进 $HOME/.agents/skills。团队流程进仓库根目录，跟着代码一起评审、一起回滚。

7.5 技能够用就别上插件，要发给别人才上

技能解决「我和我的仓库」，插件解决「别人怎么装上我这一套」。还在迭代个人流程，先写技能。出现下面任何一种情况，再考虑插件。

• 要把两个以上技能捆在一起发。
• 技能要连外部服务，得带上 MCP 服务器的配置。
• 想让网页版和手机端的 ChatGPT 也能用。独立技能只在桌面应用、CLI 和 IDE 扩展里可用。插件里的技能还能用在网页版和手机端。

按现行的官方页面，插件可以包含技能、MCP 服务器、浏览器扩展和 Hooks。旧文档的措辞不同。9 月 4 日的中文镜像写「连接器」。ChatGPT 网页端的构建页面写「应用」。三个名字大体指同一类东西，但官方没有专门说明它们的关系，读文档时别被名字绊住。MCP 本身见 §08。

插件目前有明确的界面边界。IDE 扩展不支持插件。桌面应用里打开「插件」标签页，搜索、看详情、点加号安装。CLI 里输入 /plugins 打开插件浏览器。它按市场分组。选中已安装的插件，按 Space 启用或停用。使用时，可以直接描述任务让 Codex 自己选。桌面应用和网页版里还可以用 @ 点名某个插件或它带的技能。CLI 里怎么点名插件，官方没写。

有一个细节容易踩。官方文档说，安装之后要开新聊天，随附的技能和工具才可用。CLI 0.154.0 的更新说明提到，已有会话能识别新装插件的工具。但文档没改口，我还是建议开新聊天。另外，API Key 登录时，只能管理受支持的 OpenAI 精选插件。

7.6 打包自己的插件：别指望一条命令搞定

另外，learn.chatgpt.com 现行的「构建插件」页面已经改了。它面向 ChatGPT 网页端，是无代码流程。做法是在聊天里 @ Plugin Creator，用对话建插件。这和 Codex 本地的文件式打包是两回事。

做给 Codex 用的插件，看官方开发者站的「打包你的插件」一页。地址是 developers.openai.com/plugins。learn.chatgpt.com 的插件页也把打包和市场的细节指向那里。现行写法如下。我的判断是，只给自己用的话，先别急着手写插件，技能够了。

my-first-plugin/
├── plugin.json
└── skills/
    └── hello/
        └── SKILL.md

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "my-first-plugin",
  "version": "1.0.0",
  "description": "Reusable greeting workflow"
}

根目录的 plugin.json 是可移植的入口。插件名用 kebab-case。可移植包会自动从 skills/ 发现技能，清单里不用写 skills 字段。extensions.com.openai 下放 OpenAI 专有的展示信息。Hooks 设置也放在这里。旧的 .codex-plugin/plugin.json 仍作为兼容回退保留。镜像里教的就是这种。

做好的插件要登记到一份市场目录，插件浏览器才能列出它。市场是一份 JSON。仓库级是 .agents/plugins/marketplace.json。个人级是 ~/.agents/plugins/marketplace.json。source.path 相对市场根目录解析，要以 ./ 开头。

{
  "name": "local-repo",
  "plugins": [
    {
      "name": "my-plugin",
      "source": { "source": "local", "path": "./plugins/my-plugin" },
      "policy": { "installation": "AVAILABLE", "authentication": "ON_INSTALL" },
      "category": "Productivity"
    }
  ]
}

改完重启 ChatGPT 桌面应用，插件就会出现在市场里。CLI 里也有一组 codex plugin marketplace 命令。它们管理市场来源。

codex plugin marketplace add owner/repo --ref main
codex plugin marketplace list
codex plugin marketplace upgrade
codex plugin marketplace remove marketplace-name

来源可以是 GitHub 简写、Git 地址或本地目录。--ref 用来钉住版本。官方开发者站说，这些命令服务于编写和搭目录，安装和测试本地插件要用桌面应用。

CLI 命令参考另有 codex plugin add、list、remove。它们管已配置市场里的插件。/plugins 浏览器也能装。两处口径不完全一致，在 CLI 里装本地插件之前请先实测。

要按仓库启用或停用某个插件，就用项目的 .codex/config.toml。里面写 [plugins."my-plugin@local-repo"]。把 enabled 设成 true 或 false。项目配置只在受信任的项目里加载，见 §12.4。发布给整个工作空间需要管理员权限，见 §12。

7.7 Hooks：在循环的固定点上插一段你自己的脚本

Hooks 让你在智能体循环的特定时刻运行脚本或 MCP 工具。官方列的用途有这些。

• 把对话发到你自己的日志系统。
• 拦住不小心贴进提示的 API Key。
• 一轮对话停下时跑自定义检查。

十二个事件，分四个时机

重点看 PreToolUse 和 PermissionRequest。它们正好落在全书那两根轴上。我认为这两个事件最值得先学。

PreToolUse 在工具调用前运行，可以拒绝，也可以改写输入。PermissionRequest 只在 Codex 即将向你申请审批时运行。它可以批准、拒绝，或不表态让弹窗照常出现。多个 hook 里只要有一个拒绝，就是拒绝。也就是说，PermissionRequest 是审批这根轴的程序化版本。

配置放在哪，以及先信任再运行

Codex 认两种写法。一种是独立的 hooks.json。另一种是 config.toml 里的 [hooks] 表。常用的位置有四个。

• ~/.codex/hooks.json
• ~/.codex/config.toml
• <repo>/.codex/hooks.json
• <repo>/.codex/config.toml

多个来源的 Hooks 会全部加载，不会互相替换。仓库里的 Hooks 只在项目 .codex/ 层被信任时才加载。

这是 Hooks 最关键的安全设计。非托管的 hook 必须经你审查和信任才能运行。Codex 把信任记在这条 hook 当前定义的哈希上。新增的、改过的 hook 都会标为待审查。信任之前一律跳过。

在 CLI 里用 /hooks 查看来源、审查、信任或停用。有个选项叫 --dangerously-bypass-hook-trust。它能让一次调用跳过信任要求。官方定位是给已在 Codex 之外审查过来源的一次性自动化用。我的建议是日常别碰。

写第一个 hook：拦住强制推送

先在 <repo>/.codex/hooks.json 放配置。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "/usr/bin/python3 \"$(git rev-parse --show-toplevel)/.codex/hooks/block_force_push.py\"",
            "statusMessage": "Checking Bash command"
          }
        ]
      }
    ]
  }
}

命令里用 git rev-parse --show-toplevel 取仓库根。这是官方推荐的写法，因为 Codex 可能从子目录启动。再写脚本。每个命令型 hook 都会在 stdin 收到一个 JSON 对象。Bash 的命令文本在 tool_input.command。

#!/usr/bin/env python3
import json
import sys

event = json.load(sys.stdin)
command = event.get("tool_input", {}).get("command", "")

# 这行是关键：匹配到就输出拒绝决定
if "git push --force" in command or "git push -f " in command:
    print(json.dumps({
        "hookSpecificOutput": {
            "hookEventName": "PreToolUse",
            "permissionDecision": "deny",
            "permissionDecisionReason": "仓库规定：禁止强制推送。",
        }
    }))

sys.exit(0)

预期结果：下次 Codex 想强制推送，调用被拒绝，原因文字回到模型那里。第一次会提示有新 hook 待审查，要先去 /hooks 里信任它。拒绝还有两种写法。

• 旧式：{"decision": "block", "reason": "…"}
• 以退出码 2 结束，并把原因写到 stderr

退出码 0 且无输出，就当成功放行。

另外两个常用事件，和几条细则

Stop 在一轮对话要结束时运行。它有个反直觉的设定。返回 decision: "block" 的效果是让 Codex 继续干。这一轮并没有被拒绝。你给的 reason 会变成一条新的用户提示，比如「测试没过，再跑一遍」。

输入里的 stop_hook_active 表示这一轮是否已被续过。我的建议是脚本里一定读它，续过一次就别再续，否则容易写出停不下来的循环。这是我的推断，官方没讲这个用法。

UserPromptSubmit 在你的提示发出前运行。输入里有 prompt。返回 decision: "block" 可以拦下它。扫描 API Key 的用途，靠的就是它。

• matcher 是正则，但只有部分事件认它。工具类事件按工具名过滤，SessionStart 按启动来源过滤。UserPromptSubmit、Stop、Interrupt 会忽略它。
• 覆盖有限。Shell 命令和 apply_patch 能被拦截。MCP 工具和其他本地函数工具也能。托管的 WebSearch 不能。
• 后台运行。加 "async": true 就不等它。但后台 hook 拦不住任何操作。策略逻辑必须用同步 hook。
• 输出别太长，更别带密钥。给模型看的输出默认约 2,500 个 token。超出部分会存到临时目录，只给模型头尾预览。

Hooks 默认开启。要整体关掉，就改 config.toml。在 [features] 下写 hooks = false。管理员可以在 requirements.toml 里定义托管 Hooks。用户停不掉，Codex 也不负责分发其中的脚本。托管约束的总览见 §12.6，细节以官方管理员文档为准。

7.8 装第三方扩展之前，先查这六件事

技能是文本，插件是包，Hooks 是会自动执行的命令。装别人的，等于把别人的指令和代码放进自己的循环。官方没有专讲第三方扩展审查的一页。下面这张清单，是我把各页零散的规则收拢起来整理的。

最后一行的配置长这样，不用改插件清单，就能管住它带来的 MCP 服务器。writes 的意思是，没标成只读的工具都要弹窗。

[plugins."sample@test".mcp_servers.sample]
enabled = true
default_tools_approval_mode = "prompt"   # 可取 auto / prompt / writes / approve
enabled_tools = ["read", "search"]       # 允许列表，只开放你认可的工具

我有两点个人判断。第一，Hooks 的风险比技能高一个量级。技能要经过模型判断，脚本还要走审批。Hooks 是事件一到就执行的命令。它只靠「信任过那一版哈希」这一道关。所以我会把每一行命令连同它调用的脚本读完。第二，进了团队仓库的技能和 Hooks，应该和代码一样走评审。它们本来就在仓库里，评审成本不高。

有一件事官方文档没有说明。陌生仓库自带的 .agents/skills，在未受信任的项目里会不会照常加载？我没找到答案。保险的做法很简单。打开陌生仓库之前，先看一眼它的 .agents/ 和 .codex/ 目录。

7.9 这一节的结论

三样东西，三种分工。技能存流程，插件管分发，Hooks 做拦截。我的建议按这个顺序用。

• 先把重复三遍以上的事写成技能，放进仓库共享。
• 真有分发需求，再包成插件。
• 确实需要「每次都发生」的检查，才上 Hooks。

下一节讲 MCP。先讲怎么把 Jira、Sentry、Figma 这些外部工具接进 Codex。再讲接进来之后审批怎么管。

§08 MCP 工具走审批这道闸，沙盒的网络代理管不到它们

MCP: Connecting Your Tools

Codex 能看到你的仓库，但看不到你的工单、日志和设计稿。这一节讲怎么用 MCP 把它们接进来，以及接进来之后该怎么管。

8.1 先分清四种「接法」

MCP 是模型上下文协议。它给 Codex 一组可以调用的工具。Codex 能自己去查工单、翻日志、读设计稿，不用等你复制粘贴。

文档里和 MCP 沾边的东西有四样，很容易混。

最后一行是旧资料里最容易踩的坑。8.9 会专门讲。

8.2 两种服务器形态，三种认证方式

Codex 支持两类 MCP 服务器。

• STDIO 服务器：作为本地进程运行，由一条命令启动，支持环境变量。大多数开源 MCP 服务器是这一种。
• Streamable HTTP 服务器：通过地址访问。支持 Bearer Token、OAuth。对受信任的第一方服务器，还能直接使用当前 ChatGPT 会话认证。

OAuth 这一项支持两种注册方式。它们是客户端 ID 元数据文档（CIMD）和动态客户端注册（DCR）。细节放在 8.5。我的判断是，接公司内部系统优先选 Streamable HTTP。因为令牌过期时，标头 helper 可以现取新的。

还有一个对服务器作者有用的细节。Codex 会读取服务器初始化时返回的 instructions 字段。它被当作适用于整个服务器的指引。官方建议用它写跨工具的流程、约束和速率限制。还建议让前 512 个字符能独立看懂。因为 Codex 决定怎么用这个服务器时，最先看到的就是这一段。

8.3 接第一个 MCP 服务器：三条路，同一份配置

配置都存在 config.toml 里。默认是 ~/.codex/config.toml。也可以放项目级的 .codex/config.toml，但只对受信任的项目生效。桌面应用、CLI 和 IDE 扩展共享这份配置，配一次，三边都能用。

ChatGPT 网页版不读本地的 Codex 配置。它只能用插件提供的远程 MCP 工具。

下面用 Context7 走一遍 CLI 的路。它是一个免费的开发者文档 MCP 服务器。

codex mcp add context7 -- npx -y @upstash/context7-mcp

另外两条路。

• 桌面应用：设置，MCP 服务器，添加服务器。填名称，选 STDIO 或 Streamable HTTP，给命令或地址。保存后点重启。
• IDE 扩展：齿轮菜单里选 MCP 服务器，流程一样，最后重启扩展。

列表里会标出哪些已启用、哪些需要 OAuth 登录。需要时点「身份验证」。

我的偏好是先用 CLI 命令把服务器加进去。再打开 config.toml，看它写成了什么样。这样你不用背字段，也知道每个字段从哪来。我还建议一次只接一个服务器，跑通再加下一个，出问题时好定位。

8.4 config.toml 里的关键字段

每个服务器一个 [mcp_servers.<名称>] 表。STDIO 和 HTTP 两种形态的字段不同。

重点看 http_headers_helper。公司内部的令牌通常有有效期，写死在静态标头里迟早过期。让 helper 命令每次现取就行。

Codex 会缓存 helper 返回的标头。同源请求返回 401 或 403 时，它会刷新一次。值有变化才重试。注意它只支持从本地环境发起的 HTTP 连接。stdio 服务器和经由远程执行环境的连接不行。

除了这些，还有一组通用选项，下面是它们在一个示例里的样子。

[mcp_servers.tracker]
url = "https://mcp.example.com/mcp"          # 示例地址，换成你自己的
bearer_token_env_var = "TRACKER_TOKEN"       # 令牌从环境变量里取
startup_timeout_sec = 20                     # 启动超时，默认 10
tool_timeout_sec = 45                        # 单次工具调用超时，默认 60
required = false                             # 设 true 则该服务器初始化失败时，启动或恢复会话直接失败
enabled_tools = ["search_issues", "get_issue"]   # 工具允许列表
default_tools_approval_mode = "prompt"       # 默认审批方式

几个选项补充说明。enabled 设成 false 可以停用服务器而不删配置。disabled_tools 是拒绝列表。它在 enabled_tools 之后生效。tools.<工具名>.output_token_limit 是工具级选项。它能给某个工具的输出单独设一个 token 预算。工具名我用的是虚构的，实际名字以服务器公开的为准。

官方默认的启动超时只有 10 秒。用 npx 的服务器首次运行要现拉包。我估计容易超时。这是我的推断，官方文档没写。遇到启动失败，先把 startup_timeout_sec 调大试试。

8.5 需要登录的服务器：OAuth 怎么走

支持 OAuth 的服务器要先登录。命令是 codex mcp login <服务器名>。CLI 0.161.0（2026 年 10 月 7 日）起，会话里也能直接登录。命令是 /mcp login <名称>，不必退出。

大多数情况下你不用管注册细节。Codex 默认自动选择。授权服务器声明支持 CIMD，且回调地址是受支持的回环地址，就用 CIMD。否则在能用时退回 DCR。如果你手里已经有预先注册好的客户端，就在添加时带上它的 ID。

codex mcp add example --url https://mcp.example.com --oauth-client-id my-client

命令会打印一条回调地址，你要把它原样登记到对方的授权服务器。某一次登录的注册方式可以强制指定。选项是 --oauth-client-registration。取值是 cimd 或 dcr。这个选择只对当次登录有效，不写进配置。

CLI 0.158.0（9 月 28 日）起，支持需要客户端密钥的服务器。命令是 codex mcp add --oauth-client-secret。它要和 --url、--oauth-client-id 一起用。

在远程开发机上登录时，回调地址要对得上。官方提供了两个全局设置。

• mcp_oauth_callback_url
• mcp_oauth_callback_port

它们可以指定自定义回调路径，或固定监听端口。这部分规则很细，我没有逐条验证过。真遇到时，去读官方 MCP 页面的 OAuth 一节。

8.6 管住它：MCP 的闸门是审批，不是沙盒

这一节是本书主线在 MCP 上的落点，所以要说透。

官方在审批与安全页面里写明了边界。命令网络代理只管本地命令沙盒里的脚本、程序和子进程。哪些连接不走它，§04 4.9 列过了。MCP 服务器连接就是其中之一。

翻成人话：命令的网络关得再死，Codex 到 MCP 服务器的连接也不受影响。官方在权限页里说得更直白。本地和远程的 MCP 服务器用自己的进程或传输。要靠 mcp_servers 配置和托管的服务器白名单来管。所以在 MCP 这条路上，沙盒那根轴管不到。我的理解是，落到日常，能管住 MCP 的有两样。一样是审批这根轴里按工具设的审批方式。另一样是你自己配的白名单。

第一道闸：按工具设审批方式

每个服务器可以设 default_tools_approval_mode。单个工具可用 tools.<工具名>.approval_mode 覆盖。取值四种。我不会给任何陌生服务器直接开 approve。

auto 的确切行为，官方没有展开，我不敢替它解释。我的做法是：服务器级默认设成 prompt。再把确认只读的几个查询类工具，逐个设成 approve。这样新增工具时默认要问你，不会悄悄放行。

还有一条兜底规则。如果工具声明了破坏性标注，它的调用始终需要审批。但如果这个工具同时声明了只读标注，以只读标注为准。注意这是靠服务器自报的标注，一个不老实的服务器可以谎报。所以标注只能当参考，不能当担保。

第二道闸：只暴露需要的工具

enabled_tools 是允许列表。disabled_tools 是拒绝列表。我的建议是能用允许列表就别用拒绝列表。拒绝列表只能挡你已经知道的工具，服务器升级后新增的工具它挡不住。

审批策略本身怎么影响 MCP

• approval_policy 有个 granular 写法。里面有 mcp_elicitations 一项。设成 true，MCP 服务器发来的征询提示就能弹给你。设成 false，这类提示会被自动拒绝。
• 自动审查（auto-review）只评估那些已经需要审批的动作。其中包括有副作用的应用和 MCP 工具调用。想让某个敏感 MCP 工具被审查智能体看到，要把它配成需要审批。never 下审查无事可做，别指望它兜这个底。机制见 §04 4.7。

接之前，先问三件事

• 它是谁的进程？STDIO 服务器是在你机器上运行的进程。codex mcp add x -- npx -y 某个包。这等于同意在本地跑一个第三方包。装之前看一眼维护者。
• 它返回的内容可信吗？工单标题、日志内容、网页正文都可能夹带「忽略之前的指令」这类话。MCP 工具返回的是数据，不是指令。网站工具那一页对此说得很直白，我认为这条对所有 MCP 服务器同样适用。
• 配置从哪来？项目级的 .codex/config.toml 跟着仓库走。它只在受信任的项目里加载。一个你刚克隆下来的陌生仓库，不该有权在你机器上启动进程。别为了省事就把项目随手标成受信任，见 §12.4。

团队层面还有一道闸。管理员可以在托管配置里设置 mcp_servers 批准清单。只有名称和身份都匹配的服务器才会被启用。STDIO 看命令，HTTP 看地址。清单存在但为空，则所有 MCP 服务器都被禁用。托管约束的总览见 §12.6，细节以官方管理员文档为准。

8.7 想让 MCP 少吃上下文

MCP 工具的描述和调用结果都会占上下文。官方给了两个现成的旋钮，我觉得值得知道。

• tools.<工具名>.output_token_limit 是工具级选项。它给单个工具的输出设上限，覆盖模型默认的截断预算。
• enabled_tools 只开放要用的工具。一个服务器暴露几十个工具，而你只用其中三个，剩下的就是白占位置。我会先把允许列表收到三五个工具，不够再加。

上下文怎么看、满了怎么办，见 §06。

另有全局设置 mcp_optional_startup_grace_ms。它控制 Codex 在启动阶段构建初始工具目录时，等可选服务器多久。默认 1000 毫秒。需要等服务器完整启动再开始，就把它设成 0。这时每个服务器按自己的 startup_timeout_sec 等。

8.8 网站工具（WebMCP）：让网页直接递工具给智能体

这个功能的官方页面名叫「网站工具」。它是 ChatGPT 对 WebMCP 标准提案的实现。通过它，网站可以在日常界面之外，直接向智能体提供一组预定义的操作。你和智能体看的是同一个实时页面、同一个登录会话。

它和 MCP 的区别，官方的说法是这样。MCP 把 AI 应用连到本地或远程服务器。工具可以独立于网页存在，比如调接口管记录。

WebMCP 则是网站把自己的能力当工具递出来。智能体访问页面时自己发现，不用另装服务器。适合你和智能体要看同一样东西的场景，比如编辑画布或看仪表盘。一个网站可以两种都支持。

使用上有几个门槛，都来自官方页面。

• 只在 ChatGPT 桌面应用的内置浏览器里工作。ChatGPT Work 和 Codex 都能发现并使用。
• 需要把桌面应用更新到最新版。企业版工作空间里，管理员要通过工作空间策略允许「网站工具」。Edu 工作空间里不可用。
• 对模型有要求。页面目前写的是用 GPT-5.6 Sol 或 GPT-6 Sol。它还说 GPT-5.6 Luna 目前禁用了 WebMCP。这一句比推荐模型的更新慢。页面没有提到 GPT-6.1 Sol 和 GPT-6 Astra。也没有说 GPT-6 Luna 的情况。所以我无法替你判断。

用的时候，在内置浏览器里打开网站，让智能体帮忙。地址栏里的「网站工具」按钮能展开看这个页面提供了哪些工具。工具属于提供它的页面，页面关闭或跳转后可能消失。没有合适的工具时，智能体还可以用普通的浏览器能力。

安全方面，页面把话说得很重：网站提供的工具定义和调用结果都是不可信内容。工具名字或者它自称只读，都不是证明。内置浏览器会在每次调用前做一次安全审查。发消息、付款、删除数据、改权限这类操作后果重大。它们仍然走正常的网站访问和确认策略。你可以在「设置 > 浏览器 > 权限」里关掉「启用站点工具」。

如果你是网站开发者，页面也教了怎么加。现阶段内置浏览器只支持 WebMCP 接口的一部分。声明式 API（用 HTML 表单属性定义工具）不支持。iframe 里注册的工具也不支持。必须在顶层页面用 JavaScript 注册。官方的只读示例如下。

if (typeof document.modelContext?.registerTool === "function") {
  await document.modelContext.registerTool({
    name: "get_page_title",
    description: "Read the title of the current page.",
    inputSchema: {
      type: "object",
      properties: {},
      additionalProperties: false,
    },
    annotations: { readOnlyHint: true },   // 声明只读
    execute: async () => ({ title: document.title }),
  });
}

官方给开发者的建议有这些。

• 输入收窄。
• 写明副作用。
• 返回足够的信息，让人能验证结果。
• 沿用应用已有的认证、授权和输入校验。
• 对不支持 WebMCP 的浏览器保留正常界面。

你也可以直接让 Codex 帮你给应用加 WebMCP。要求它复用现有逻辑和权限。我认为这一项对普通使用者的价值还早，对做 Web 应用的开发者更近。

8.9 把 Codex 当 MCP 服务器？这条路已经封了

官方原先那页的 MCP 工具参考，现在不再受支持。Agents SDK 示例也一样。如果你有集成是靠启动这两个命令之一工作的，升级 Codex 之前必须先迁移。我的建议是，读旧教程时看到 codex mcp-server，那一段直接跳过。

官方给的替代方案是 Codex app server。它用于需要认证、对话历史、审批和流式智能体事件的集成。我只说三件事，教程不在这一节。

• app server 使用自己的 JSON-RPC 协议。它不是 MCP 服务器，也不是 MCP 客户端的直接替代品。迁移要改成按它的协议调用，不再走 MCP 工具调用。
• app-server 命令目前是实验性的，官方明确说不支持生产负载。
• 如果你要做的是自动化作业或接进 CI，改用 Codex SDK。这是官方在 app server 页面里的建议，见 §10。

被删掉的只是「把 Codex 当服务器」这个方向。Codex 作为客户端连接外部 MCP 服务器，一切照旧。仍然用 codex mcp 管理。

8.10 这一节的结论

接 MCP 不难，难的是接完之后心里有数。MCP 工具不在沙盒的网络代理管辖之内，能管它的是审批方式和工具白名单。我的做法归成四条。

• 服务器级默认设 prompt，只给确认只读的工具开 approve。
• 用 enabled_tools 白名单，只暴露要用的工具。
• 令牌放环境变量，不写进配置文件。用 bearer_token_env_var。或者用 http_headers_helper。
• 别把陌生仓库标成受信任，陌生的 npx 包先看维护者。

下一节讲子智能体、worktree 与并行。怎么让多个 Codex 同时干活，又不让它们互相踩脚。

§09 并行先解决隔离：子智能体继承沙盒，worktree 隔开文件，云端隔开整台机器

Subagents, Worktrees and Parallel Work

一个 Codex 不够用的时候，有三种办法让更多的 Codex 同时干活。这一节讲它们各自隔离到哪一层，权限从哪里来，以及什么时候该用哪一种。

9.1 三种并行，隔离的程度完全不同

很多人想到并行，第一反应是快。其实要先回答的是：几个 Codex 同时动手，会不会互相踩脚，权限又怎么算。我认为选哪一种，先看你要隔离什么，再看你愿意多配多少东西。

三者可以叠着用，比如在一个 worktree 里再派几个子智能体做只读调查。

9.2 子智能体的第一价值是保护主线程，不是提速

官方讲子智能体，先讲的是上下文。你在主聊天里定需求、约束和决策。如果探索笔记、测试日志、堆栈跟踪这些噪声也灌进来，聊天会越来越不可靠。这类问题官方叫上下文污染和上下文腐化，含义见 §06 6.1。我认为这是理解子智能体的关键。

子智能体的做法是把脏活挪出主线程，只把摘要带回来。主智能体守着需求、决策和最终输出，子智能体并行去探索、跑测试、读日志。能独立并行的活，才顺带变快。

适用范围官方说得很清楚。起步先用在以读为主的任务上，比如探索、测试、问题分流和总结。以写为主的并行要更小心，多个智能体同时改代码会冲突，协调成本也会上升。还有一笔账要算。每个子智能体都有自己的模型调用和工具调用。所以比同等的单智能体运行更费 token。我的建议是第一次尝试就从审查和探索这类只读任务开始。

9.3 怎么让 Codex 派子智能体

当前版本的 Codex 默认开启子智能体工作流。但只在你直接要求，或适用的 AGENTS.md、技能指令里写了要求时才派。所以最稳妥的做法是你亲口说。用「开两个智能体」「每点一个智能体」这类直白的话。

好的委派提示要交代三件事：怎么分工，要不要等全部完成，最后返回什么。我的建议是把这三件事写进每一条委派提示。

Review this branch with parallel subagents. Spawn one subagent for security risks, one for test gaps, and one for maintainability. Wait for all three, then summarize the findings by category with file references.

这是官方示例，三件事都在里面。按风险类别拆三个，wait for all three，按类别汇总并带文件引用。多个智能体同时跑时，Codex 会等所有结果就绪，再返回一份汇总。

跑起来以后怎么看、怎么管，各个界面不一样。

• CLI：用 /subagents 切换并查看正在运行的智能体线程。官方命令页仍写 /agent。想调整方向、停掉某个、关掉已完成的线程，直接对 Codex 说。
• 桌面应用：从主线程里的活动入口打开子智能体线程。查看它的工作和返回给主聊天的摘要。
• IDE 扩展：后台智能体面板可用时，展开能看状态、停止子智能体、打开线程。

另外，模型页面提到 Ultra 推理档位会用子智能体并行处理复杂任务的各部分。官方的口径是多数任务不需要 Max 或 Ultra。GPT-6 Luna 最高只到 Max，不含 Ultra。想用 Ultra，在 CLI 里用 /model 选模型。再选「More reasoning…」。我的建议是先靠明确的委派提示，别一上来就开 Ultra。

9.4 子智能体继承你的沙盒，这一条要记牢

回到全书的主线。子智能体不是自带权限的新角色，它继承你当前的沙盒策略。我的判断是，这是并行里最容易被忽略的一条。在桌面应用和 IDE 里，它继承的是输入框下方选定的权限模式。所以要在委派之前，先为父级这一轮选对模式。

CLI 里有两个细节更值得知道。

• 非活动线程也会弹审批。即使你正盯着主线程，子智能体线程发出的审批请求也会冒出来。浮层会标出来源线程的名字，按 o 可以先打开那个线程，再决定批准、拒绝还是回答。
• 父级的临时设置会被重新应用。Codex 在启动子智能体时，会重新应用父轮次的实时运行时覆盖。其中包括你在会话里用 /permissions 改的设置，以及 --yolo。官方特意注明，这对自定义智能体文件里写了不同默认值的情况同样成立。

第二条的后果很实际。别指望在子智能体的配置文件里写 read-only。这兜不住一个 --yolo 的父会话。想让子智能体受限，先把父会话的权限收紧。官方同时说，你可以为单个自定义智能体覆盖沙盒配置，比如明确让它只读。两句话放在一起，我的理解是文件里的设置是默认值，会话里临时改的设置优先。我没有逐项验证各种组合，写进自动化之前请先实测。

还有一种情形会让人措手不及。在非交互式流程里，或任何弹不出新审批的场合，需要新审批的动作会直接失败。错误传回父级工作流。所以 codex exec 里跑子智能体，权限要事先配好。沙盒怎么选，见 §10.1。

要在子智能体启动和结束的节点插自己的脚本，用 Hooks，见 §07。它有 SubagentStart 和 SubagentStop 两个事件。

9.5 自定义智能体：窄而有主见

Codex 内置三个智能体。

• default 是通用后备。
• worker 偏执行，用于实现和修复。
• explorer 偏只读探索。

想要自己的，写一份独立的 TOML 文件。个人的放 ~/.codex/agents/。项目的放 .codex/agents/。每个文件定义一个智能体，必须有三项。

• name
• description
• developer_instructions

文件里还可以写别的 config.toml 键，比如这些。

• model
• model_reasoning_effort
• sandbox_mode
• mcp_servers
• skills.config

没写的会从父会话继承。如果自定义智能体与内置的同名，比如也叫 explorer，你的优先。

下面是一个只读的 PR 审查智能体，改自官方的 PR 审查示例。它是你自己定义的智能体，和 §04 的自动审查不是一回事。官方也说，好的自定义智能体要窄而有主见。我倾向于一个智能体只干一件事。描述写到一看就知道何时该派它。

# .codex/agents/reviewer.toml
name = "reviewer"
description = "PR reviewer focused on correctness, security, and missing tests."
model = "gpt-6.1-sol"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"
developer_instructions = """
Review code like an owner.
Prioritize correctness, security, behavior regressions, and missing test coverage.
Lead with concrete findings, include reproduction steps when possible, and avoid style-only comments unless they hide a real bug.
"""

文件里的 sandbox_mode = "read-only" 只是默认值。按 9.4 的说法，有两种情形会盖过它。一种是父会话用了 --yolo。另一种是在会话里用 /permissions 改过权限。Codex 启动子智能体时，会重新应用父轮次的设置。文件里写的 read-only 就兜不住。

模型怎么挑，官方的建议是：大多数任务从 gpt-6.1-sol 起步。前提是你的账号或工作空间有权限，没有就选你能用的。gpt-6-luna 用于快速、范围窄、可重复或大批量的轻活。推理强度方面，显式指定 GPT-6 Luna 时先试 high。指定 GPT-6 Astra 时先试 low。再按任务调整。你什么都不配，子智能体就继承父级的模型和推理强度。

全局设置放在 config.toml 的 [agents] 下。

未设置上限时，默认值由 Codex 自己选，官方没有写具体数字。旧名字 agents.max_threads 仍可作为别名。我会把上限显式写出来，官方示例里用的是 8 和 6。

9.6 worktree：每个聊天一份独立检出

worktree（官方中文页译作「工作树」）让同一个项目能运行多个聊天。它们互不干扰。这个功能建立在 Git worktree 之上，所以项目必须是 Git 仓库。每个 worktree 有自己的一份全部文件，共享同一个 .git 元数据。所以可以并行检出不同分支。

官方页面讲的是桌面应用里的做法，分四步。

可以把本地检出当前台，worktree 当后台。移交会处理 Git 操作，让聊天在两边安全移动。下次交回去，还回到原来的 worktree。

这里有一条 Git 本身的限制。同一个分支只能在一个地方被检出。你在 worktree 上建了分支 feature/a，本地就没法再检出它。硬检出会收到下面这类错误。

fatal: 'feature/a' is already used by worktree

想在本地看，就用移交把聊天移过去，别硬在两边同时检出。我觉得这是 worktree 最容易让新手卡住的地方。

几条会影响日常使用的细节

• 位置。受管 worktree 默认建在 $CODEX_HOME/worktrees。起点是所选分支的 HEAD。如果选的是带本地改动的分支，未提交改动也会一并应用。位置可在设置的 Worktrees 里改。
• 被忽略的文件不会跟着走。移交走的是 Git，所以 .gitignore 里的文件不会自动带过去。想带上 .env 这类文件，就写一份 .worktreeinclude。放在仓库根目录。按 .gitignore 的写法列出要复制的路径。
• 清理。默认保留最近 15 个 Codex 管理的 worktree。有置顶聊天、进行中聊天或永久 worktree 的不会被自动删。删除前会先存快照，重新打开对应聊天可以选择恢复。
• 永久 worktree。想要长期存在的环境，从侧边栏项目的三点菜单创建，不会被自动删除，可以开多个聊天。日常任务我建议用默认的受管 worktree。

# .worktreeinclude
.env
.env.local
config/secrets.json

官方命令参考把斜杠命令 /worktree 列在 IDE 扩展和桌面应用的输入框命令里。它的作用是在新的 Git worktree 里运行当前聊天。CLI 的内置命令表里还没有它。CLI 一侧的进展要看更新说明，脉络如下。

• CLI 0.154.0（2026 年 9 月 9 日）加入了两项实验性功能。它们是 --worktree 和 /worktree。
• 0.156.0（9 月 22 日）起，worktree 支持默认启用。
• 0.162.0（10 月 8 日）又加了一组工具。用来创建和列出受管 Git worktree。

这些命令的具体参数和行为，官方文档页没有展开，我只敢写到这里。另外，定时任务在 Git 仓库里，可以跑在专用的后台 worktree 上。见 §10。

9.7 本地环境：给新 worktree 装好依赖

worktree 在另一个目录里运行。所以你没提交进仓库的依赖和文件，它可能没有。本地环境解决这件事。我会把 setup 脚本当成用 worktree 的前置条件。它只在 ChatGPT 桌面应用的 Codex 里可用，在应用设置里配置。生成的文件存在项目根目录的 .codex 文件夹中。可以提交进 Git 与团队共享。

• Setup 脚本：Codex 在新聊天创建新 worktree 时自动运行。用来装依赖、做首次构建。比如 npm install 加 npm run build。平台不同可以分别写 macOS、Windows、Linux 版本。
• Actions：把常用任务（启动开发服务器、跑测试）做成应用顶栏上的按钮。它们在集成终端里运行。我觉得它对个人项目是锦上添花。

9.8 Codex Cloud：隔开的是整台机器

Codex Cloud 在云端跑编码任务，你的电脑睡着了，任务也能继续。可以在网页、手机或桌面应用里用。使用云端必须用 ChatGPT 账号登录，API Key 登录不行，见 §02。

下面这些内容，都放在 §10.7 讲。

• 新旧版的对比表
• 新版建环境的流程
• 凭据：环境变量与 network secrets
• 联网设置，§04 4.9 另有简述

这里补一条细节：network secret 的 Key 要与直接变量不同。我的判断是，新项目直接按新版来，不必再碰 Legacy。

规格与限制

表后面有几条限制。任务保存的 VM 状态最长保留 7 天。时间从你最后一次开始对话轮次，或恢复任务之后算起。官方云端环境页的「当前限制」列了四项暂不支持。

• 计算机使用
• 浏览器使用
• GitLab
• 自托管的 GitHub Enterprise Server

但 8 月 19 日的更新说明和官方的 GitLab 页写着另一回事。GitLab 在 Codex cloud 里有测试版。自托管和 Dedicated 的 GitLab 也提到了。两页说法不一致，官方没有解释，用 GitLab 之前请先自己试一次。

仓库里的技能在云端任务里可用，但你本机的个人技能不会同步上去。所以要给云端用的技能，放进仓库，见 §07。

CLI 里也能用云端。

• codex cloud 打开交互式选择器。
• codex cloud exec 直接提交任务。
• codex cloud list 列出最近的云端聊天，适合脚本使用。

IDE 扩展和桌面应用的输入框里还有三个斜杠命令。CLI 的内置命令表里没有它们。

• /cloud 把当前聊天放到云端。
• /cloud-environment 选环境。
• /local 回到本地。

9.9 按场景选：该用哪一种并行

我的取舍是：能用子智能体解决的，先别开 worktree。能在本地 worktree 解决的，先别上云端。隔离每升一层，配置成本就多一截，凭据和联网要管的东西也多一截。

9.10 这一节的结论

并行的钱要花在隔离上。子智能体继承父会话的沙盒，worktree 隔开代码副本，云端隔开整台机器。三种方式的权限来源不同，所以出问题的地方也不同。

• 子智能体：小心父会话的临时权限被一路继承。
• worktree：小心被忽略的密钥文件被复制。
• 云端：小心凭据和联网的范围。

• 派子智能体前，先把父级这一轮的权限模式选对。我的建议是三种方式别一次全上。
• 显式设置 agents.max_concurrent_threads_per_session。别让 token 消耗失控。
• 新版云端环境是「创建并发布」，旧版 Legacy 的细节见 §10.7。

下一节讲怎么把 Codex 交出去。先讲非交互模式、GitHub Action、SDK 和自动化。再讲 CI 里密钥和权限怎么放。

§10 没人盯着的时候，边界要在启动前定死

Cloud, CI and Non-interactive Mode

Codex 离开终端之后，审批这根轴就没人接了。这一节讲脚本、CI、云端和定时任务里的做法。先收紧沙盒、凭据和网络，再放手让它跑。

2026 年 10 月 14 日，GPT-5.5 从所有套餐退役。写死了它的脚本和定时任务，偏偏没人盯着，最容易漏改。换成什么，见 §02 2.8。这一节讲的就是这类没人盯着的活。

10.1 无人值守时，只剩沙盒这根轴能用

前面几节你都坐在终端前。Codex 想越界，会停下来问你，这一步就是审批（见 §04）。CI 里没有你，问了也没人答。

所以无人值守只有一种可行做法：沙盒收到刚好够用，审批干脆不触发。官方说，--ask-for-approval never 适用于所有 --sandbox 模式。Codex 会在你设定的限制内尽力执行。

这是 codex 主命令的参数，codex exec 的官方参数表里没有它。我对照 0.162.1 的源码，无头模式下它默认就是不问审批。官方审批页的组合表也说，非交互运行用 codex exec --sandbox workspace-write。限制设多大，启动前一次定下，启动后没有第二次机会。

重点看第三行。官方说只在受控环境里用，举的例子是隔离的 CI 运行器或容器。我的理解是，你的开发机和多人共用的 runner 都不算。

10.2 先选路，再动手：六条自动化路线

Codex 有六种方式脱离你的键盘干活。它们跑的地方不同，凭据放的地方也不同。

云端功能一律要 ChatGPT 登录。官方定价页写明，API 密钥路线没有云端功能，GitHub 代码审查也在其中。

Slack 和 Linear 的集成不在这六条路线里。Slack 在这一节只出现在定时任务的触发源里，见 10.8。Linear 集成目前还依赖 Legacy 云端，见 10.7。

我的上手顺序是先开 @codex review，再写两三个 codex exec 小脚本。要进 GitHub 工作流时换 Action，SDK 和云端留到真有需要。

10.3 codex exec：把 Codex 当成会读写管道的命令

codex exec（也可写成 codex e）不开 TUI，跑完就退出。运行期间进度流到 stderr。只有最终的智能体消息打到 stdout，所以重定向和管道都很干净。

codex exec "generate release notes for the last 10 commits" | tee release-notes.md

# 指令你来写，管道内容只当上下文
npm test 2>&1 \
  | codex exec "summarize the failing tests and propose the smallest likely fix" \
  | tee test-summary.md

# 整段提示都来自 stdin
cat prompt.txt | codex exec -

它默认在只读沙盒里跑。要改文件，显式写 --sandbox workspace-write。老的 --full-auto 已弃用，会打警告。

受控自动化里有三个顺手的开关。--ephemeral 不在磁盘留会话记录。--ignore-user-config 不读 $CODEX_HOME/config.toml。这样运行器上遗留的个人配置，就带偏不了行为。--ignore-rules 跳过用户和项目的 execpolicy .rules。

另外，MCP 服务器配了 required = true。它初始化失败时，codex exec 会报错退出，不会少个工具硬跑。

要让程序读输出，加 --json。stdout 就变成 JSON Lines 事件流。事件含 thread.started、turn.completed、turn.failed、item.*、error 等。只要最终消息，用 -o <path>。下游要稳定字段，用 --output-schema 约束成 JSON Schema。

codex exec "Extract project metadata" \
  --output-schema ./schema.json \
  -o ./project-metadata.json

两阶段流水线可以用 codex exec resume --last "..." 接着上一次跑。运行位置必须是 Git 仓库，这是防破坏性改动的保护。CI 里代码本来就是检出的，用不着 --skip-git-repo-check。

还有一条 codex review 专做非交互审查。目标在 --uncommitted、--base、--commit 里三选一。也可以直接给一段自定义提示。

10.4 CI 里放密钥：先问谁读得到它

自动化最容易出事的是密钥，不是提示词。官方的态度很明确：API 密钥更容易预配和轮换，是自动化的合适默认选择。

放法只看一句话。工作流如果会检出或运行由仓库控制的代码，别把密钥设成作业级环境变量。这里的密钥指 OPENAI_API_KEY 或 CODEX_API_KEY。同一作业里的构建脚本、测试、依赖钩子，或者被入侵的 Action，都读得到它。

CODEX_API_KEY=<api-key> codex exec --json "triage open bug reports"

上面这条把密钥只放在一次调用前。Codex 访问令牌是较新的一条路。它在管理控制台创建，用环境变量 CODEX_ACCESS_TOKEN 传入。官方同时说明：平台 API 密钥能满足需求就继续用它。公开 CI、来自 fork 的 PR、共用机器都可能让令牌暴露给工作空间之外的人。我没在真实工作空间里用过它，这里只转述官方页面。

用 ChatGPT 账户的 auth.json 跑 CI，官方放在「高级」里。它要求 cli_auth_credentials_store = "file"。几条规矩我建议当硬规则。令牌不提交、不贴工单、不在聊天里发。不要在并发作业或多台机器之间共用同一份。Codex 会自己刷新并写回文件，持久运行器上别每次都用原始密钥覆盖它。公开和开源仓库不要走这条路。

10.5 GitHub Action：把权限拆成两个作业

openai/codex-action@v1 会装好 Codex CLI。你提供 API 密钥时，它会启动 Responses API 代理。之后按你给的权限跑 codex exec。

运行器用 Linux 或 macOS。Windows 必须设 safety-strategy: unsafe。调用前先检出代码。

真正管权限的是三个输入。sandbox 取 workspace-write、read-only 或 danger-full-access。选能完成任务的最窄一档。action 的 README 把它标成旧写法。新工作流推荐 permission-profile，取值是 :read-only、:workspace。它还是 Beta，要 CLI 0.138.0 以上。两个输入互斥。

safety-strategy 默认 drop-sudo，跑 Codex 前移除 sudo。这一步对该作业不可逆，保护内存里的机密。allow-users 与 allow-bots 限制谁能触发。默认只有有写权限的用户能跑。prompt 和 prompt-file 二选一，同时给会报错。

官方有句提醒我很认同。它说的是 safety-strategy 的 read-only 取值。取值一共有 drop-sudo、unprivileged-user、read-only、unsafe 四个。这个取值能阻止 Codex 改文件、用网络。但 Codex 运行时仍带着提升的权限，别只靠它保护机密。沙盒管 Codex 能碰什么，safety-strategy 管运行器上的机密。两层各管各的。

下面是官方的 PR 审查示例。不看提示词，看权限怎么分。Codex 所在的作业只有 contents: read。发评论的作业才有写权限。两边只通过一个作业输出传话。

name: Codex pull request review
on:
  pull_request:
    types: [opened, synchronize, reopened]

jobs:
  codex:
    runs-on: ubuntu-latest
    permissions:
      contents: read               # 这行是关键：Codex 所在的作业只读
    outputs:
      final_message: ${{ steps.run_codex.outputs.final-message }}
    steps:
      - uses: actions/checkout@v5
        with:
          ref: refs/pull/${{ github.event.pull_request.number }}/merge
          fetch-depth: 0
          persist-credentials: false   # 不把令牌留在检出目录里

      - name: Run Codex
        id: run_codex
        uses: openai/codex-action@v1
        with:
          openai-api-key: ${{ secrets.OPENAI_API_KEY }}
          prompt-file: .github/codex/prompts/review.md
          output-file: codex-output.md
          sandbox: read-only           # 我加的一行：审查只需要读，官方示例没写

  post_feedback:
    runs-on: ubuntu-latest
    needs: codex
    if: needs.codex.outputs.final_message != ''
    permissions:
      issues: write
      pull-requests: write           # 写权限只给发评论的作业，它拿不到 API 密钥
    steps:
      - name: Post Codex feedback
        uses: actions/github-script@v7
        with:
          github-token: ${{ github.token }}
          script: |
            await github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.payload.pull_request.number,
              body: process.env.CODEX_FINAL_MESSAGE,
            });
        env:
          CODEX_FINAL_MESSAGE: ${{ needs.codex.outputs.final_message }}

官方示例没写 sandbox。action.yml 和 README 都写明了一件事。两个沙盒输入都留空时，action 退回旧的 workspace-write。所以我自己显式补了一行 read-only。

另有一个官方没点明的风险，是我从示例结构读出来的。prompt-file 来自被检出的代码。检出的若是 PR 合并后的内容，提示文件就握在 PR 作者手里。对外开放的仓库上线前请自己验证。

把这个结构推到「修 CI」，就是 §11 案例三的两作业方案。拿到密钥的作业改不了仓库，能改仓库的作业看不到密钥。

10.6 SDK：把 Codex 嵌进自己的程序

脚本写不动的需求用 SDK。TypeScript 版是 npm install @openai/codex-sdk。它要 Node.js 18 以上，只在服务端用。核心是 startThread()、run()、resumeThread()。

Python 版是 pip install openai-codex。它要 Python 3.10 以上，已有稳定版。它通过 JSON-RPC 控制本地 app-server。

Python 版把沙盒做成预设，每一轮都能换。预设有 Sandbox.read_only、Sandbox.workspace_write、Sandbox.full_access。官方例子正好演示：先写，再用只读审自己的 diff。

from openai_codex import Codex, Sandbox

with Codex() as codex:
    thread = codex.thread_start(sandbox=Sandbox.workspace_write)
    thread.run("Make the requested change.")
    # 同一线程，下一轮收回写权限：审查只读
    review = thread.run("Review the diff only.", sandbox=Sandbox.read_only)

传给 run(...) 的沙盒，对这一轮和之后的轮次都生效。所以收权限的那一步别漏。官方示例用 gpt-6.1-sol。它注明这得是你账号可用的模型，不然省略 model。

10.7 Codex Cloud：新版和 Legacy 别混着用

云端有两套说法，旧文章几乎都在讲老的那套。

新版在网页或桌面应用里建。选 Work in > Cloud，打开 Select environment。再选 Create environment。手机端只能用已发布的环境，不能新建。

测好的配置记在两个字段里。Install script 装依赖。Start skill 写怎么启动服务、怎么确认就绪。保存只存配置，发布才会冻结预备好的文件系统给新任务用。

每个新任务拿到自己的工作区。改环境走 Edit 再 Republish，旧任务不受影响。官方提醒：重要的东西要提交，保存状态替代不了版本控制。VM 状态能保留多久，见 §09 9.8。

云端没有人点审批，边界靠两样东西：这台 VM 能连哪些域名，凭据以什么形式进去。凭据分两种。环境变量原样传给程序。

网络机密要填 Key、Value 和 Allowed domains。程序只拿到占位符，代理在放行的域名上换成真值。这只对 HTTPS 的 443 端口生效，真实凭据不会落进本地进程或文件。你自己的凭据放进 Personal vault，共享环境只共享「需要哪些值」。

联网要打开 Allow Codex to access internet。再在 Allow domains 里选预设：

• Package managers
• Custom domains only
• All (unrestricted)

官方提醒：放行一个域名，不等于给了你在那个服务里的凭据。连内网目前只支持 Tailscale。暂不支持哪些功能，见 §09 9.8。GitLab 的两页官方说明互相矛盾，那里也有交代。

命令行也能碰云端。codex cloud exec 直接提交任务。codex cloud list --json 列出最近的云端聊天，供脚本读取。codex cloud exec 的提示词可以省略，省略就交互式询问。--env 必填，--attempts 取 1 到 4、默认 1。

10.8 GitHub 代码审查与定时任务

很多旧教程说，要先配好云端才能用代码审查。现在的前提改了，要三样：

• 已连接 Codex 的 GitHub 仓库。
• 代码审查设置页的权限（chatgpt.com/settings/code-review）。
• 想让它守仓库规矩时，要有 AGENTS.md。

官方还说明，云端审查不用你创建或管理云端环境。

开启很简单。在设置页选仓库，打开 Review code 下的 Automatic review。想自动审，就去 Personal preferences。开 Automatic review，再用 Review trigger 选时机。

手动就在 PR 评论里写 @codex review，等它先点个眼睛表情，再发审查。它在 GitHub 里只标 P0 和 P1，评论留给真正的风险。审查规则写进离代码最近的 AGENTS.md。标题固定叫 ## Code Review Rules。

## Code Review Rules

### Experiment cohorts

- Do not filter treatment comparisons on post-exposure behavior, including conversion or retention.
  Safe path: build cohorts from assignment or exposure; report conversion as an outcome.

官方建议先写两三条，每条说清要拦什么、为什么、安全做法是什么。格式和 lint 这类机械检查留给 CI。规则只是引导，替代不了测试、分支保护和必需的审批。

有一处要留意。@codex fix the P1 issue 会起一个 Legacy 云端聊天。任何不是 review 的 @codex 提及也一样。审查走新路，让它动手改仍走 Legacy。Security Review 还在研究预览阶段。触发用 @codex security review。

定时任务在桌面应用里可以作用于本地项目，英文叫 Scheduled tasks。文档路径和页内锚点里还留着 automations 旧称。它们在项目目录或隔离的 worktree 里跑。CLI 和 IDE 扩展没有管理界面，只能帮你先写好、测好提示。

符合条件的套餐上，网页端和手机端的任务还能由事件触发。事件来源有 Gmail、Slack、GitHub。这种触发不能和时间表混用。

安全上看这几句。定时任务用你的默认沙盒设置无人值守地跑。组织策略允许时，它用 approval_policy = "never"。管理员禁止，就回退到你所选权限模式的审批行为。

read-only 下，改文件和联网的调用都会失败。workspace-write 下，工作区外的修改和联网失败。个别命令可用规则放行，写法见 §04 4.8。完全访问风险最高，它可能不问你就改文件、跑命令、联网。我的建议是从最窄开始，缺什么再补。

另外，GPT-5.5 已在 2026 年 10 月 14 日退役。定时任务里写死它的要换掉，替换对照见 §02 2.8。

10.9 这一节的结论

无人值守的核心只有一句：先定边界，再放手。审批轴在 CI 里等于关掉，保护全压在沙盒和凭据上。

• 脚本用 codex exec，默认只读。要写再加 --sandbox workspace-write。
• 密钥只给需要它的那一次调用，别设成作业级环境变量。
• GitHub 上用 openai/codex-action@v1。让拿密钥的作业没有写权限。
• 云端分清新版和 Legacy，凭据优先用网络机密，联网从紧放。
• 代码审查的前提是已连接 GitHub 仓库。规则写进 ## Code Review Rules。

下一节 §11 把这些拆成四个案例。提 PR 前自审，摸清陌生仓库，让 CI 失败自己修，再把团队规范固化下来。

§11 四个案例，都先定权限再写提示词

Four Hands-on Cases

提 PR 前自审、摸清陌生仓库、让 CI 失败自己修、把团队规范固化下来。每个案例按场景、权限、提示词、为什么这么写、验收来走。

11.1 四个案例的共同骨架

下面的场景都用「假设你要……」来写。它们是按官方文档的步骤推演出来的，不是我的亲身战绩。操作步骤和命令以官方文档为准，提示词是示例，改成你自己的路径和约束再用。

每个案例我都先回答同一个问题：这次让 Codex碰什么、什么时候问你。这就是全书那两根轴。提示词是软的，沙盒是硬的，所以权限永远写在提示词前面。

提示词本身，我用 §03 3.3 讲的四件事来检查。官方对 Codex 提示的描述，是说清你要的行为，指出相关的代码或复现步骤。还要保留重要的约束，并说明怎么验证改动。§03 把它压成四个问题：改什么、别碰什么、怎么算完成、去哪看。后面每个提示词，你都能按这四个问题逐句对上。

重点看「谁在场」这一列。有人在场的两个案例，都从只读起步。没人在场的那个，所有边界都得提前写进工作流文件。

11.2 案例一：提 PR 前，先让它审一遍

场景

假设你写完一个「支付重试」功能，测试全绿，但心里清楚有几处是赶出来的。提交之前想有人再看一遍，又不想占同事的时间。

权限

只读就够了。官方对 /review 的描述是这样的。Codex 启动一个专门的审查器，读选定的差异。它报告按优先级排序的发现，不改你的工作目录。保险起见还是显式限死。

git status
git diff --stat        # 先心里有数：这次动了多少
codex --sandbox read-only

进了会话，输入 /review。CLI 里会给出几个范围。可以对照基准分支审查，也可以审查未提交的更改或某个提交。还能自定义审查指令。

官方写明，IDE 扩展里的 /review 只在 Git 仓库里出现。CLI 那段没单独说。我建议都在 Git 仓库里用。

提示词

预设是通用的。你知道风险在哪，就直接点名。官方文档里的写法是在 /review 后面直接带关注点。

/review 对照 main 审查当前分支，重点看三件事：
1. src/payment/ 下新加的重试逻辑，会不会造成重复扣款
2. 有没有把错误吞掉、只打日志的地方
3. 新增的两个依赖，许可证和体积

格式和命名不用提，那些 lint 会管。
每条发现给出文件和行号，并写清在什么输入下会出问题。

要注意，/review 后面带的文字走的是「自定义审查指令」那一档。我对照 0.162.1 的源码，带参数的 /review 会按自定义指令发起审查。它并不会同时选中「对照基准分支」那个预设。所以示例里的 main 是写在指令里的文字，由审查器自己去比。

非交互的 codex review 更严。--uncommitted、--base、--commit 和自定义提示互相排斥，只能选一个。

为什么这么写

• 三个关注点点名了行为和位置，审查器不用在整个仓库里瞎看。
• 排除 lint 管的东西。官方的 GitHub 审查建议里也有同样一条：机械检查留给 CI，别占审查的注意力。
• 要触发条件。「在什么输入下出问题」这句能立刻筛掉一半「理论上可能」的泛泛结论。这是我的判断，不是官方原话。

验收

别把审查结果当结论。它不知道那段怪代码是三年前为绕线上问题写的。每条发现，你自己打开它指的文件行号，按它说的输入走一遍。

想让它顺手改，我的建议是审和改分成两步。官方说明，让 Codex 应用它找到的修复时，你原有的沙盒和审批设置照常生效。所以只读会话里它不会直接动手改，这是设计使然。

先审完，挑出真要改的几条。用 /permissions 放宽权限，再让它改这几条。改完重跑一次 /review，确认问题消失。边审边改的坏处是 diff 一变，你分不清哪些是原来的问题、哪些是新引入的。

推送之后，GitHub 上还有第二遍。在 PR 评论里写 @codex review。它按仓库 AGENTS.md 里的 ## Code Review Rules 审，只标 P0 和 P1。本地一遍看你的改动，云端一遍看仓库的规矩，两遍互补。前提是仓库已连接 Codex，见 §10 10.8。

三个入口审的是同一件事，区别在谁来触发、读哪份规则。我的建议是自查在前，GitHub 在后。非交互那条，等你想把审查塞进脚本再用。

顺带三个设置。config.toml 里的 review_model 可以让 /review 用和当前会话不同的模型。

在桌面应用里，把 Code review 选成 Detached。入口是 Settings > General。IDE 扩展把 chatgpt.reviewDelivery 设成 detached。这样审查就会另开聊天，不占主线程的上下文。

审查范围别给太大，「审一下整个仓库」只会得到泛泛而谈。

11.3 案例二：摸清一个陌生代码库

场景

假设你被派去在一个从没碰过的 billing 模块里加功能。老办法是读两天代码、再问人。现在先让 Codex 替你跑一遍，把「这个仓库长什么样」变成一份能核对的笔记。

权限

只读，而且要显式指定。

cd ~/some-unfamiliar-repo
codex --sandbox read-only

clone 下来的仓库当然有 Git，所以 Codex 多半会推荐 Auto。判断规则见 §02 2.6。这一次我们主动往回收一格。

理由有两个。你还不知道哪些脚本有副作用，npm run setup 说不定会往数据库里灌数据。另外，探索阶段本来就不该产生改动。一旦它改了东西，你就分不清「本来如此」和「它改的」。沙盒是硬的，提示词里再写一句「不要改文件」是软的，两层都留着。

提示词

分三轮。第一轮要一张地图。

我第一次接触这个仓库。请只读地探索，不要改任何文件。

给我：
1. 这个项目是干什么的，一段话
2. 入口在哪：可执行文件、服务启动点、主要命令
3. 目录职责表：每个顶层目录一行
4. 数据从哪进来、到哪去（外部依赖、数据库、队列、第三方 API）
5. 怎么跑测试，怎么本地起服务
6. 你觉得最容易出问题的三个地方，以及原因

每条结论都带文件路径。不确定的地方明确写「没找到」，不要猜。

第二轮把细看的线索拆开并行。官方说明，子智能体要你明确要求才会开，或者由 AGENTS.md、技能里写明。

官方写明它们继承当前的沙盒策略。它们还会重新应用父轮次的 --yolo 和 /permissions 改动。官方没有单独写 --sandbox read-only 这种启动标志。我的理解是同样沿用，所以你从只读起步，它们也只读（细节见 §09）。

用并行子智能体深入这三条线，每条一个，跑完汇总：
1. 认证与鉴权：请求从入口到拿到用户身份，每一层做了什么
2. 数据库访问：用了什么 ORM 或驱动，事务边界在哪，有没有裸 SQL
3. 测试：怎么组织的，哪些模块覆盖好，哪些几乎没有

每个智能体只返回结论和文件引用，不要贴大段代码。

并行不是免费的。官方明说，子智能体流程比同等的单智能体多耗 Token。探索大仓库通常值。但先用 agents.max_concurrent_threads_per_session 把并发框住。

第三轮才带着真问题问，而且先不要写代码。你也可以用 /plan 让它先提方案。

我要在 services/billing 里加「订单退款后自动作废关联发票」。
先不要写代码，告诉我：
1. 现有退款流程走哪几个文件，从哪个函数进入
2. 发票在哪里创建，有没有现成的作废接口
3. 这两条流程现在有没有耦合
4. 如果要加，你会改哪几个文件，为什么是这几个
5. 有哪些事代码里看不出来、我应该先问原作者

为什么这么写

第一轮最后那句「不确定就写没找到」，我建议每次都加。没有它，模型倾向给一个听起来合理的答案，你一眼分不出真假。第三轮的第 5 问最值得留。比如代码里有条 TODO 写着「等某某上线后删」，但没人告诉你某某是什么。这就是你该去问人的地方。

验收

• 抽查两个目录。自己打开看一眼，五分钟的事。对上了，剩下的结论才敢用。
• 把结论存下来。/init 能在当前目录生成 AGENTS.md 脚手架。但只读沙盒下写文件要先过审批或放宽权限。这是我的推断，官方的 /init 说明没讲权限。先用 /permissions 放宽，生成后让它精简，只留测试命令、起服务方式、目录职责和几个坑。
• 探索完用 /new 在同一个 CLI 会话里开个新聊天，把结论当输入再动手。探索会往上下文里堆很多文件内容（见 §06）。

别一上来就说「帮我改 X」。它会边猜边改，你得到一堆看起来对、实际没走通的代码。先探索，再动手，这两步要分开。

11.4 案例三：让 CI 的失败自己修好

场景

假设你的主 CI 工作流叫 CI，偶尔因为快照没更新、类型对不上这类小事变红。你想让它失败后自动试修一次：修得好就开个 PR 等你看，修不好就什么也不发生。

权限：关键在结构，不在提示词

这套方案安全，是因为它把三样东西彻底拆开了。

两个作业之间只传一个补丁构件。拿到密钥的作业改不了仓库，能改仓库的作业看不到密钥。官方给的理由很直接。作业级环境变量里的密钥，构建脚本、测试、依赖钩子都读得到。被入侵的 Action 也一样。这套结构的来龙去脉见 §10。

name: Codex auto-fix on CI failure

on:
  workflow_run:
    workflows: ["CI"]
    types: [completed]

jobs:
  generate_fix:
    if: ${{ github.event.workflow_run.conclusion == 'failure' }}
    runs-on: ubuntu-latest
    permissions:
      contents: read                  # 这个作业只读
    outputs:
      has_patch: ${{ steps.diff.outputs.has_patch }}
    steps:
      - uses: actions/checkout@v5
        with:
          ref: ${{ github.event.workflow_run.head_sha }}
          fetch-depth: 0
          persist-credentials: false

      - uses: actions/setup-node@v4
        with:
          node-version: "20"

      - name: Install dependencies    # 装依赖在 Codex 之前，这一步看不到密钥
        run: |
          if [ -f package-lock.json ]; then npm ci; fi

      - name: Run Codex
        uses: openai/codex-action@v1
        with:
          openai-api-key: ${{ secrets.OPENAI_API_KEY }}   # 密钥只出现在这一步
          sandbox: workspace-write    # 我加的一行：它要改文件，官方示例没写，显式写出更稳
          prompt: |
            The CI workflow "${{ github.event.workflow_run.name }}" failed for commit
            ${{ github.event.workflow_run.head_sha }}.

            Run `npm test --silent` to reproduce the failure. Identify the minimal
            change needed to make the tests pass, implement only that change, and
            run `npm test --silent` again.

            Do not refactor unrelated files.

      - name: Create patch artifact
        id: diff
        run: |
          git add -N .
          git diff --binary HEAD > codex.patch
          if [ -s codex.patch ]; then
            echo "has_patch=true" >> "$GITHUB_OUTPUT"
          else
            echo "has_patch=false" >> "$GITHUB_OUTPUT"
          fi

      - name: Upload patch artifact
        if: steps.diff.outputs.has_patch == 'true'
        uses: actions/upload-artifact@v4
        with:
          name: codex-fix-patch
          path: codex.patch
          if-no-files-found: error

  open_pr:
    runs-on: ubuntu-latest
    needs: generate_fix
    if: needs.generate_fix.outputs.has_patch == 'true'
    permissions:
      contents: write                 # 写权限在这里，但这个作业没有 OPENAI_API_KEY
      pull-requests: write
    steps:
      - uses: actions/checkout@v5
        with:
          ref: ${{ github.event.workflow_run.head_sha }}
          fetch-depth: 0

      - uses: actions/download-artifact@v4
        with:
          name: codex-fix-patch

      - name: Apply Codex patch
        run: git apply --index codex.patch

      - name: Open pull request
        env:
          GH_TOKEN: ${{ github.token }}
          FAILED_HEAD_BRANCH: ${{ github.event.workflow_run.head_branch }}
          FAILED_HEAD_SHA: ${{ github.event.workflow_run.head_sha }}
          RUN_ID: ${{ github.event.workflow_run.run_id }}
        run: |
          branch="codex/auto-fix-$RUN_ID"

          git config user.name "github-actions[bot]"
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
          git switch -c "$branch"
          git commit -m "Auto-fix failing CI via Codex"
          git push origin "$branch"

          {
            echo "Codex generated this patch after CI failed for \`$FAILED_HEAD_SHA\`."
            echo
            echo "Review the changes before merging."
          } > pr-body.md

          gh pr create \
            --base "$FAILED_HEAD_BRANCH" \
            --head "$branch" \
            --title "Auto-fix failing CI via Codex" \
            --body-file pr-body.md

这是 Node.js 项目的写法，换技术栈就改安装和测试命令。官方另有一份 Codex GitHub Action 安全指南，上线前建议读一遍。另外，action 的 sandbox 输入现在被官方标成旧写法。README 推荐新工作流用 permission-profile: ":workspace"，两者互斥。两个都不给时，action 本来就退回 workspace-write。

提示词别直接在 CI 里调。我的建议是先在本地用 codex exec --sandbox workspace-write "..." 把同一段提示跑通。看它对一个真实的失败会怎么改，满意了再搬进工作流。CI 里每调一次都要等一轮，本地试错便宜得多。

为什么这么写

提示词只有几句话，每一句都在防一种具体的跑偏。

• 先复现。让它自己看到失败，不凭报错猜。
• 最小改动，只实现这个改动。防止它顺手「优化」一圈，给你一个五百行的 PR。
• 改完再跑一遍。让它自己验证，而不是口头声称。
• 不要重构无关文件。缺了它，自动修 CI 会变成自动重构仓库。

配置上有三个取舍。safety-strategy 保持默认的 drop-sudo。别为了省事改成 unsafe。

allow-users 和 allow-bots 默认只放有写权限的用户。工作流再挂了别的触发方式时，要检查这一项。如果提示词里要拼进 PR 标题、提交消息、议题正文，先清洗，官方明确提醒了提示注入。

验收

别让它自动合并。这个流程的产出是一个 PR，不是一次直接推送，这是故意的。审这个 PR 时问三件事。

• 它改的是问题本身，还是把断言改宽、加个 skip 让测试闭嘴？
• 改动范围有没有超出失败的那个点？
• 如果失败本来是环境问题（依赖版本、缓存），它是不是在代码里打了补丁绕过去？

第三种最隐蔽。下面这几类仓库，我的建议是别用这个方案：

• 涉及认证、加密、权限的安全敏感代码。
• 测试时好时坏的仓库。它会去修一个不存在的 bug。
• 公开或开源仓库。尤其别走 ChatGPT 账户认证那条路，官方明确不推荐。

11.5 案例四：把团队规范固化下来

场景

假设团队里有一批没写下来的约定。改了 api/ 要同步 docs/api/。internal/ 不许被外部包引用。新依赖要先过安全组。新人来一次讲一遍，评审时再提醒一遍。现在要让这些约定变成 Codex 每次都会读到的东西。

权限：四层，按顺序上

别一次全上。每一层都能单独见效，出了问题也好回退。

前三层跟着代码走，谁 clone 谁拿到。第四层走管理员渠道，性质完全不同。

提示词与文件

第一层最便宜，不改任何人的权限，当天见效。内容写命令和红线，不写项目介绍。Codex 自己看得出你是个微服务项目。红线要具体到路径，「注意代码质量」没有任何作用。

# AGENTS.md

## 怎么跑

- 测试：`make test`（不是 `npm test`，我们有额外的 fixture 准备步骤）
- Lint：`make lint`，提 PR 前必须过

## 红线

- 不要修改 `gen/` 下的任何文件，那是 protobuf 生成的
- 不要在 `internal/` 之外引用 `internal/` 的包
- 加新的生产依赖前先问我

## Code Review Rules

### Internal package boundaries

- Do not import `internal/` packages from outside the module.
  Safe path: expose the needed behavior through `pkg/` with an explicit interface.

最后那一节是 §10 讲过的 GitHub 审查规则。它放在最贴近相关代码的 AGENTS.md 里。长度要控制。

AGENTS.md 官方页说，合并后的指令体积默认到 32 KiB 就停止加入。高级配置页却写成每个文件读多少。两页说法不一致。总之写太长会被截断，等于把后面的指令扔掉。

审查规则官方建议先写两三条，写法见 §10 10.8。再拿一个有代表性的 PR 用 @codex review 试，噪音大的规则就收窄或删掉。

第二层放仓库级默认设置和命令规则。注意规则目前仍标着实验性。

# .codex/config.toml
approval_policy = "on-request"
sandbox_mode    = "workspace-write"

[sandbox_workspace_write]
network_access = false

# .codex/rules/default.rules
prefix_rule(
    pattern = ["git", "push"],
    decision = "prompt",                     # 推送前必须有人确认
    justification = "推送到远端前需要人确认",
    match = ["git push origin main"],        # 内联单元测试：这条应当命中
    not_match = ["git status"],              # 这条不应命中
)

规则文件的 match 和 not_match 会在加载时校验，能提前发现写错的规则。多条规则同时命中，取最严的那个决定。

这里用 prompt，不用 §04 4.8 示例里的 forbidden。因为团队允许推送，只要求人确认。

为什么这么分

第二层有个绕不开的前提：只有项目被信任，Codex 才加载 .codex/ 这一层。所以团队成员 clone 之后，要先确认信任这个项目，配置才会生效。这一句得写进 README。

另外，项目里的 .codex/config.toml 改不了 openai_base_url、model_provider 这类敏感键。信任怎么判断、哪些键会被忽略，完整说明见 §12 12.4。

第三层把重复流程做成技能。写 description 时说清楚什么时候用、什么时候不用，因为它决定技能何时被选中。技能列表有预算，所以仓库技能要精简，别把每个小操作都做成一个。预算见 §07 7.2。

第四层最后碰。官方写明，本地配置的值和强制规则冲突时，客户端会回落到兼容的值并通知用户。强制线要是在摸清大家怎么用之前就下发，换来的多半是一堆被回落的设置。同事们还会摸不着头脑。先跑通前三层，再定强制线。

验收

找一个没参与配置的同事。让他 clone 仓库，装好 Codex，跑一个典型任务，你在旁边看。会话里用 /status 对一下生效的模型、审批策略和可写根目录。他卡在哪，哪里就是你没写清的地方。这比你自己再读一遍配置有用得多。

如果有人反映「我这儿行为不一样」，多半是项目没被信任。如果配置写了没生效，翻 §12 12.1 的优先级表。命令行标志的优先级最高，会盖过仓库配置。

11.6 这一节的结论

四个案例的共同点，是动手之前先把权限定死。

• 自审用只读，审和改分成两步，最后让 GitHub 上的审查再补一遍。
• 探索陌生仓库用只读，三轮问法：地图、并行细看、带着真问题问。
• CI 自动修靠两作业结构：拿密钥的不能写，能写的没有密钥，产出只到 PR。
• 团队规范四层按顺序上，最后才碰强制线。

第四个案例里反复出现的 config.toml 和 requirements.toml，下一节 §12 会讲透。那一节也是全书的收束。

§12 配置写进文件，团队才真的统一了

Configuration Files and Team Rollout

前十一节讲的是怎么用。这一节讲怎么把用法固化成文件，再让整个团队跑在同一套边界里。它也是全书的收束。

12.1 配置有七层，谁在后面谁说了算

Codex 从好几个地方读配置。你的个人默认值在 ~/.codex/config.toml。项目覆盖放在仓库里的 .codex/config.toml。CLI 和 IDE 扩展共用同一套配置层。

官方现在列的是七层，从高到低如下。旧教程常写六层，漏的是第 5 层云端托管默认值。

重点看第 2 层和第 5 层的位置。仓库配置排在用户配置前面。所以团队写进仓库的默认值，会盖过你自己的 ~/.codex/config.toml。但你敲的命令行标志永远排第一。

还有一条要分清：这七层说的是默认值。能让用户改不动的，是另一套约束，叫 requirements.toml。后面 12.6 再讲。官方的原话大意是，约束限制行为，配置提供默认。

12.2 config.toml 里值得先设的几项

配置项有几百个，常改的就那么几个。我按「先管边界，再管体验」的顺序挑。

两处最容易踩旧坑。第一，approval_policy 的 untrusted 已在 CLI 0.149.0 退役。遗留设置可能让客户端起不来，见 §04 4.5。第二，model_reasoning_effort 不再是固定的五个值，而是一个字符串。能填什么由你选的模型决定。max 和 ultra 能不能用，取决于模型、套餐、客户端和设置。

模型本身，不写 model 就用推荐模型。要写，就写你账号能用的。官方示例是 gpt-6.1-sol，并明确提醒它需要账号或工作空间有权限。

# ~/.codex/config.toml
sandbox_mode    = "workspace-write"   # 先定边界：只能写工作区
approval_policy = "on-request"        # 再定何时问你
web_search      = "cached"            # 默认值，写出来是为了让团队看得见

[sandbox_workspace_write]
network_access = false                # 联网要显式打开

[shell_environment_policy]
inherit = "core"                      # 只传一小撮核心变量
ignore_default_excludes = false       # 默认是 true；设成 false 才会自动剔除名字含 KEY、SECRET、TOKEN 的变量

[shell_environment_policy.filters]
"AWS_*" = "exclude"
"AZURE_*" = "exclude"

[agents]
max_concurrent_threads_per_session = 6   # 框住子智能体并发，见 §09

这份配置里最值得抄的是 shell_environment_policy。它管的是 Codex 传给它所启动命令的环境变量。ignore_default_excludes 默认是 true。意思是默认不自动过滤名字里带 KEY、SECRET、TOKEN 的变量。很多人以为默认就会过滤，其实不会。

Windows 沙盒见 §04 4.10。

12.3 配置方案：同一台机器上切换场景

不同的活要不同的默认值。与其每次敲一长串标志，不如存成配置方案。

做法是在 ~/.codex/ 下建 名字.config.toml。再用 --profile 名字 选它。Codex 先读 ~/.codex/config.toml，再把方案文件叠在上面。所以方案里只写要改的几项。文件里直接写顶层键，不要套 [profiles.名字]。名字可以含字母、数字、连字符和下划线。

# ~/.codex/readonly_quiet.config.toml
approval_policy = "never"
sandbox_mode    = "read-only"

codex --profile readonly_quiet
codex exec --profile readonly_quiet "review this change"

只想改一次的，用 -c 或 --config。值按 TOML 解析，拿不准就加引号，别让 shell 按空格拆开。

codex --config sandbox_workspace_write.network_access=true
codex --config 'shell_environment_policy.include_only=["PATH","HOME"]'

注意 include_only 是旧的数组写法，官方示例里还在用。新配置写 [shell_environment_policy.filters] 表（见 12.2）。同一层配置里别把两种写法混用，Codex 会拒绝。

配置方案正好对上 §10 的 CI 场景。把「只读、不审批」做成一个方案。CI 脚本里一个 --profile 就带上全部边界，不用在每条命令上重复写。

12.4 受信任项目是一次真实的安全判断

Codex 只在你信任某个项目时，才加载它的 .codex/ 层。把项目标成不受信任，项目本地的配置、hooks 和规则会被整层跳过。用户级和系统级的照常加载。

想想为什么。.codex/config.toml 是跟着仓库走的。如果 clone 一个陌生仓库就自动加载它的配置，对方有三样东西可以塞给你。一是会在本地起进程的 MCP 服务器。二是在特定时机跑命令的 hooks。三是放宽沙盒外命令的规则。所以「要不要信任这个项目」是一次真实的判断，别一路回车过去。

信任状态写在用户配置里。

# ~/.codex/config.toml
[projects."/path/to/project"]
trust_level = "trusted"        # 或 "untrusted"

还有一批键，项目里的 .codex/config.toml 设了也没用。官方列了这些：

• openai_base_url
• chatgpt_base_url
• apps_mcp_product_sku
• model_provider
• model_providers
• notify
• profile
• profiles
• experimental_realtime_ws_base_url
• otel

Codex 会忽略它们，启动时打警告。它们涉及凭据去向、认证和本机通知，得放在用户级配置里。

trust_level = "untrusted" 还有第二个用途。想保留更严的命令审批，就在用户配置里给该项目写它。做法与代价见 §04 4.5。

12.5 建议线、默认线、强制线

团队级的东西，要分清三条线。放的地方不同，能不能被用户改也不同。

注意建议线的能力上限。官方的说法是，仓库配置能给默认设置和可复用工作流。它授不了工作空间、模型、平台 API 或已连接系统的访问权限。「让新人 clone 完就能用 Codex」办不到，那是账号和席位的事。

12.6 requirements.toml：唯一有强制力的一层

它约束的是安全相关的设置：

• 审批策略、审批人、自动审查策略。
• 沙盒模式、权限配置方案。
• 网页搜索模式。
• 托管 hooks。
• 用户能启用哪些 MCP 服务器。
• 能用哪些插件市场来源。

功能标志也能在 [features] 下钉死，省略的功能键不受约束。

用户的配置和强制规则冲突时，本地客户端会回落到兼容的值，并通知用户。它不会让用户的设置悄悄生效。

怎么送到设备上

官方列了四个来源，按优先级从低到高：

• 系统文件。Unix 上是 /etc/codex/requirements.toml。Windows 上是 %ProgramData%\OpenAI\Codex\requirements.toml。
• 云端配置包里的 Agent Security 要求。
• 旧式 managed_config.toml 里被客户端重新解释成要求的字段。
• macOS 的托管偏好（MDM）。键是 com.openai.codex:requirements_toml_base64。

高优先级的覆盖低优先级的标量和列表，表按键合并。规则、hooks、文件系统限制这类要求有各自的合并行为。别假设所有字段合并方式一样，以官方参考为准。

云端这一路有前提：用户用 ChatGPT 登录支持的套餐。这时受支持的本地客户端会拿到工作空间关联的强制要求。这些要求在管理控制台的 Agent Security 里管理。拿不到有效缓存、请求又失败时，客户端会报错，不会悄悄不带这层要求就启动。这个设计我认为是对的，宁可起不来也别带着漏洞起。

写什么

官方给的一个云端示例，同时限制了审批、沙盒，并要求 shell 入口先确认：

allowed_approval_policies = ["on-request"]
allowed_sandbox_modes = ["read-only", "workspace-write"]

[rules]
prefix_rules = [
  { pattern = [{ any_of = ["bash", "sh", "zsh"] }], decision = "prompt", justification = "Require explicit approval for shell entry points" },
]

这一份只放行 on-request 和两档沙盒。never 与 danger-full-access（包括 --yolo）都进不来。

官方托管配置页的示例写的是 allowed_approval_policies = ["untrusted", "on-request"]。页面自己解释了：这里的 untrusted 只用来放行「由不受信任项目推导出的更严策略」。它不能再被直接选作 approval_policy。别把它读成还能写 approval_policy = "untrusted"。

Codex 0.138.0 起，官方更推荐用权限配置方案来写。不要围绕旧的沙盒模式设计新部署：

default_permissions = ":workspace"

[allowed_permission_profiles]
":read-only" = true
":workspace" = true
# ":danger-full-access" 没写，所以被拒绝

这张白名单是完整名单。设成 true 的放行，省略或设成 false 的一律拒绝。以后版本新增的内置方案也一样。

有两个落地陷阱。0.137.0 及更早的客户端会直接忽略 allowed_permission_profiles 和托管的 default_permissions。所以整个车队升级完再下发。部署白名单之前，还要把旧的 sandbox_mode 和 [sandbox_workspace_write] 从配置里清掉。混合版本期间，可以暂时保留 allowed_sandbox_modes 当兼容约束。

还有几个单点开关，一行一个。allow_appshots = false 关 Appshots。allow_remote_control = false 关设备远程控制。要在浏览器和桌面端全面关掉计算机使用，得把相关的功能键一个个关：

[features]
browser_use = false
browser_use_full_cdp_access = false
browser_use_external = false
in_app_browser = false
computer_use = false

托管 hooks 和 MCP 清单也属于这类约束。托管 hooks 定义在 requirements.toml 里，用户停不掉。Codex 也不负责分发其中的脚本，见 §07。MCP 服务器用 mcp_servers 批准清单约束。名称和身份都匹配才启用，STDIO 看命令，HTTP 看地址。清单存在但为空，所有 MCP 服务器都被禁用，见 §08。

旧式托管默认：managed_config.toml

它设的是客户端启动时的起始配置。启动时会盖过用户的 config.toml 和命令行的 --config。运行期间用户仍可以改，下次启动再被覆盖。位置是 Unix 上的 /etc/codex/managed_config.toml。Windows 上是 ~/.codex/managed_config.toml。

macOS 上还能通过 MDM 下发。在 com.openai.codex 域下用 config_toml_base64。这条线是遗留路径。新部署我建议先看云端托管默认和 requirements.toml。

12.7 管理员上线：先分清六条边界

官方的管理员上线指南有八步。顺序可以照着走，但核心是先认清：这是六条互相独立的边界。

我的排期建议是这样。第一步给每条边界指定负责人。第二步配好工作空间访问和身份，用一个有目标权限的成员测登录。第三步下发本地运行时要求，用上一节的权限方案白名单。

第四步把仓库配置、规则和技能提交进 .codex 或 .agents。第五步才碰云端。Codex Cloud 对企业工作空间默认关闭，已经开了的从 Legacy 沿用。

权限也分开管。「在云端使用 Codex」给使用者。「管理工作空间环境」只给创建和编辑共享环境的人。

之后是插件与连接器的审查，再接治理与观测。官方区分了几个出口：

• 工作空间分析：看交互式报表。
• Analytics API：做程序化的汇总。
• Compliance API：查审计记录。
• 用量上限与支出控制：管积分消耗。

最后一步是验证。拿有代表性的身份，各测一次「应该放行」和「应该拦下」的操作。把生效的设置和结果记下来。

12.8 Codex Security 是另一条产品线

官方文档里有个容易和权限系统混淆的名字，Codex Security。它是一个找漏洞、确认漏洞、修漏洞的应用安全智能体。它不是 Codex 自己的沙盒和审批。

它有三种用法。在桌面应用里装 Codex Security 插件，侧边栏出现 Security 工作台。在终端和 CI 里，用公开的 @openai/codex-security 包。比如 npx @openai/codex-security --help。第三种是 Codex Security Cloud。它还在研究预览阶段，扫描已连接的 GitHub 仓库，在 Codex Cloud 里跑。

PR 上的深度安全审查，是 §10 10.8 提到的 @codex security review。想看沙盒、审批、网络控制和管理员设置？回到官方的 Agent approvals & security 页。别在这条线上找。

12.9 全书收束：边界先定，剩下交给它

全书只有一条主线：沙盒决定它能碰什么，审批决定它什么时候问你。两根轴各管各的，别把它们当成一个开关。

回头看这十二节，每一节其实都在这两根轴上做事。§01 到 §03 把它装上、跑通。§04 把两根轴讲透。§05 到 §06 解决它做事时知道什么。

§07 到 §09 扩展它能做什么，同时守住扩展带来的新边界。§10 把它交出去，没人盯着时只剩沙盒和凭据。§11 用四个案例演示怎么从权限出发。这一节把所有边界写进文件，让整个团队共用。

最后一行最容易被忘。这本书的事实核对到 2026 年 10 月 13 日，CLI 稳定版是 0.162.1。审批取值在 2026 年 8 月变过。模型在 2026 年 10 月 14 日又换了一批。产品每周都在变。

我的建议是把官方 changelog（learn.chatgpt.com/docs/changelog）当成例行检查。每次升级 CLI 前看一眼，比读任何教程都管用。文档站迁移的来龙去脉，见附录 D.3。

正文到这里结束。接下来是四个附录：A 收命令和提示词，B 对齐术语，C 按症状排错，D 记录版本时间线。剩下的事，交给你下一次打开 Codex。

附录 A 命令与提示词速查：要抄的那一行都在这

Appendix A · Commands and Prompts Cheat Sheet

不翻章节也能找到启动标志、斜杠命令和提示词模板。每条后面的 §NN 是展开讲的地方。

A.1 这页怎么用

先说一条原则。这里只收官方文档里查得到的写法。当前 CLI 稳定版是 0.162.1（2026-10-09）。斜杠命令还在不断增加。你装的版本里多出来的命令，以 TUI 里输入 / 弹出的列表为准。

A.2 启动标志：权限、模型、目录

第一行是起点，第五行是误区。很多人以为 -a never 是「放开」，其实它只是「不问」。

A.3 登录与子命令

A.4 codex exec：脚本与 CI

codex exec 默认跑在只读沙盒里。要让它改文件，必须显式放开。完整用法见 §10 10.3。

A.5 会话里的斜杠命令

这一节是全书斜杠命令的总表。会话管理类命令的细讲在 §06 6.4，第一周必用的在 §03 3.7。先看每天都会用的。

再看管理与扩展类。

最后是云端与 worktree 类。官方命令页把这四条列在 IDE 扩展的命令表里。CLI 里有没有，以你版本里输入 / 弹出的列表为准。

A.6 键盘与深链接

桌面应用的快捷键可以搜索、改绑。入口是 Settings > Keyboard Shortcuts。下面是我认为最常用的一组。

CLI 里还有三个键值得记。Codex 工作时，Enter 是引导当前轮次。Tab 是把消息排队，留给下一轮。写长提示时按 Ctrl+G。它会打开 VISUAL 或 EDITOR 指定的外部编辑器。

桌面应用还保留了 codex:// 深链接，适合做团队文档里的「一键开聊」。最常用的是下面这个形式，注意查询值要先编码。

codex://threads/new?prompt=<编码后的提示>&path=<本地目录的绝对路径>

链接只会把提示填进输入框，不会自动发送。prompt、path、originUrl 至少要带一个。否则链接什么也不做。

A.7 提示词模板

官方提示词指南的概述部分，把一条好提示拆成四样东西。它们是目标、上下文、输出、边界。短任务一句话就够，大任务才需要四样齐全。§03 引的是同一份指南里专讲 Codex 的那一句。它的内容是：说清行为，指出代码或复现步骤，保留约束，说明怎么验证。表的最后一列，把两套说法对上了号。

括号里是要你替换的部分。

通用骨架

目标：（要的结果，写结果，不写步骤）
上下文：先看 @（路径）。背景是（一两句）。
输出：先给方案，再给改动，最后列出你跑过的验证命令和结果。
边界：不改公共 API，不动 gen/ 目录。动手前先把计划发给我。

展开见 §03 3.3。

摸清陌生仓库（只读）

用 --sandbox read-only 启动。最后那句「没找到就直说」不能省，它能减少听起来合理的编造。展开见 §11 11.3。

我第一次接触这个仓库。请只读地探索，不要改任何文件。
给我：这个项目是干什么的（一段话）、入口在哪、目录职责表（每个顶层目录一行）、
数据从哪进来、到哪去、怎么跑测试、怎么本地起服务、最容易出问题的三个地方，以及原因。
每条结论都带文件路径。不确定的地方明确写「没找到」，不要猜。

修 bug

复现步骤和约束，比对问题的概括描述有用得多。展开见 §03 3.8 模板二。

Bug：在设置页点保存，界面提示「已保存」，刷新后开关又复原了。
复现：npm run dev → 打开 /settings → 切换「开启提醒」→ 点保存 → 刷新页面。
约束：不要改接口的返回结构；修复要尽量小，能补回归测试就补。
先在本地复现这个 bug，再给出补丁并运行检查。

写测试

给 @transform.ts 里的 invert_list 函数补测试。
覆盖正常路径，再加空列表、单元素这两个边界。
沿用同目录其他测试的写法。运行后把命令和结果贴给我。

展开见 §03 3.8 模板三。

提 PR 前自审

先只读审，再切到可写改。审和改分开，diff 才看得清。展开见 §11 11.2。

/review 重点看边界情况和安全问题。格式和命名不用提，那些 lint 会管。
每条发现给出文件和行号，并写清在什么输入下会出问题。

先计划，再立目标

/plan
我们要把 auth 子系统拆成 token 解析、会话加载、权限判断三块。
约束：对外行为不变，公共 API 稳定。请先问清楚你需要知道的，再给分里程碑的迁移计划。

/goal
完成里程碑 1：拆分完成，现有测试全部通过，没有新增循环依赖。

这是两条消息，分两次发。目标要写成它能自己验证的样子：预期结果、约束、验证三项都要有。展开见 §03 3.8 模板四和 §06 6.6。

让 GitHub 上的 PR 被审

@codex review
@codex review for security vulnerabilities and security concerns

这两句是在 PR 评论里发的，不是在终端里。前提是仓库已连接 GitHub，详见 §10 10.8。

CI 里自动修失败

三句话各防一种跑偏：先复现，只做最小改动，改完再跑一遍。最后一句最重要。展开见 §11 11.4。

CI 工作流「CI」在提交（sha）上失败了。
运行 npm test --silent 复现失败，找出让测试通过所需的最小改动，只实现这个改动，
然后再跑一次 npm test --silent。不要重构无关的文件。

把命令输出直接喂给它

npm test 2>&1 \
  | codex exec "总结失败的测试，并给出最小的可能修复" \
  | tee test-summary.md

展开见 §10 10.3。

让它起草 AGENTS.md

根据刚才的探索，起草一份放在仓库根目录的 AGENTS.md。
写：怎么跑测试、怎么起本地服务、目录职责、三条最容易踩的坑。
控制在 60 行以内。代码能看出来的不用写，不要写架构介绍。

展开见 §05 5.4。

让 GitHub 审查读到你的规则

写在最贴近相关代码的 AGENTS.md 里，格式和 lint 留给 CI。展开见 §05 5.5 和 §10 10.8。

## Code Review Rules

- 不要在模块外部引用 internal/ 下的包。
  安全做法：通过 pkg/ 暴露一个带明确接口的入口。

A.8 这一附录的结论

命令会随版本变，写法的骨架不会变。一条权限命令永远回答两个问题：能碰什么，什么时候问。记住这个，新命令一眼就能归位。

下一个附录是术语表，把上面反复出现的名词逐个对一遍。

附录 B 术语表：同一件事，别再叫出三个名字

Appendix B · Glossary

官方文档、旧教程和界面菜单对同一个概念的叫法不一样。这里一次对齐，并标出在哪一节讲透。

B.1 先对齐三个菜单名

写成 like_this 的是配置键、命令行取值或命令，可以原样搜索。界面里的中文名以官方译名为准。

桌面应用和 IDE 扩展把两根轴合成了菜单项，CLI 把它们拆开写。对照关系如下。

在 CLI 里用 /permissions 切换。更改审批人不会扩大沙盒范围，这一点官方写得很明确。这张对照是我按官方沙盒页和权限模式页归纳的。官方明确写了的只有两条。完全访问权限就是 danger-full-access 加 never。替我审批和请求审批的边界相同。每个菜单项的完整对照见 §04 4.7。

B.2 两根轴与安全

B.3 指令、配置与上下文

B.4 扩展与协作

B.5 运行形态与交付

B.6 模型、计费与成熟度

B.7 这一附录的结论

这些词里最容易混的是三对。沙盒和审批、配置方案和权限配置方案、项目信任和审批档。每一对都能追溯到同一个源头，一个管能力，一个管打断。

下一个附录是排错手册，按症状而不是按功能组织。

附录 C 常见问题与排错：先查这四处，再查别的

Appendix C · FAQ and Troubleshooting

按症状组织，每行给出原因和处理。覆盖登录、权限、配置、扩展、上下文、额度和 CI。

C.1 先做四步诊断

codex --version        # 版本：CLI 与桌面应用内置版本可能不同
codex login status     # 身份：ChatGPT 账号还是 API Key
# 进入会话后输入 /status，核对工作区包含哪些目录、剩余额度
echo $CODEX_HOME       # 配置层：不是默认值，你改的可能不是生效的那份

我的判断是，多数「它怎么不听话」的问题，根子在这四处之一。先对症状，再翻功能文档。下面的表按这个顺序排。

C.2 安装、登录与版本

C.3 权限、沙盒与网络

C.4 指令、配置与 Hooks

C.5 扩展、MCP 与子智能体

C.6 上下文、会话与长任务

C.7 额度与模型

C.8 云端、GitHub 与 CI

C.9 求助前先收集这些

• 版本：codex --version。再说明你用的是 CLI、IDE 扩展还是桌面应用。
• 会话记录在 $CODEX_HOME/sessions。默认是 ~/.codex/sessions。已归档的在 archived_sessions。
• macOS 应用日志的目录如下。~/Library/Logs/com.openai.codex/年/月/日
• 反馈：在会话里输入 /feedback，可以附上当前会话。提交后会给你一个会话 ID。已知问题先去 GitHub 的 openai/codex 议题里搜。

C.10 这一附录的结论

排错的顺序比具体命令重要。先版本，再身份，再权限，最后才是配置和扩展。顺序反了，你可能在 MCP 超时上耗很久，最后发现是项目没被信任。

最后一个附录是版本时间线与来源，用来核对本书每个事实的出处。

附录 D 版本时间线与参考来源

Timeline and Sources

本书素材镜像抓取于 2026-09-04。这里补齐此后到成稿日的变化，并列出每一类事实的出处。

D.1 官方更新日志（09-04 之后）

D.2 Codex CLI 稳定版（09-04 之后）

另有两个更早的关键节点。CLI 0.149.0（2026-08-20）退役了 untrusted 审批策略。gpt-5.4 与 gpt-5.4-mini 于 2026-08-31 退役，现建议换 gpt-6-sol 或 gpt-6-luna。两件事都发生在本书素材镜像抓取之前，但镜像里的文档当时还没改。

D.3 本书的素材构成

D.4 写作中发现的已失效说法

写作前逐条比对出 20 处，事实核查时又找出十几处。影响最大的几条，本书一律按右栏写：

D.5 未能核实、需要你自己确认的

• 各套餐的具体用量倍数与额度。官方页面没有给出完整数字
• Plus 能否用 GPT-6 Astra。定价页的套餐卡片没列，用量表却有 Astra 一行
• read-only 下网络是否一定关闭。官方只明说 workspace-write 默认关网
• 云端是否支持 GitLab。云端环境页列为不支持，更新日志和 GitLab 页写 Beta
• mxc 下会不会出现 1385 错误。官方排错页写的是旧版 elevated 的情况
• 部分组件的许可证。CLI 为 Apache-2.0；技能按单个技能各自声明；openai/plugins、openai/codex-universal 未核实

D.6 免责声明

本书为非官方社区手册，与 OpenAI 无隶属关系，不代表官方立场。

内容仅供学习参考。在公司代码库中使用 Codex 前，请遵守你所在组织的安全与合规规范。沙盒与审批的配置尤其要按规范来。

产品功能、套餐与价格以 OpenAI 官方最新说明为准。文档：learn.chatgpt.com/docs