Agent 架构文档 · Markdown
OpenAI Codex Agent 架构全景讲解
以 Agent 的生命脉络 为主线，讲清楚 OpenAI Codex 这一整套编程 agent 生态： 一份配置（AGENTS.md）+ 一个 Rust 内核（codex rs）+ 三种壳（CLI / IDE / Cloud）+ 一颗大脑 （gpt 5.x codex 系列），是怎么被定义、被唤起、怎么思考、怎么记忆、怎么开口、怎么协作的。 适合：刚被 Ch
以 Agent 的生命脉络 为主线，讲清楚 OpenAI Codex 这一整套编程 agent 生态： 一份配置（AGENTS.md）+ 一个 Rust 内核（codex-rs）+ 三种壳（CLI / IDE / Cloud）+ 一颗大脑 （gpt-5.x-codex 系列），是怎么被定义、被唤起、怎么思考、怎么记忆、怎么开口、怎么协作的。
适合：刚被 ChatGPT 那个 "Codex" tab 弄糊涂的新人 / 想把 codex CLI 接进 CI 的工程师 / 在做 agent 架构横评的研究者。
2026-06-08 官方复核补丁：npm
@openai/codexlatest 为0.137.0，GitHub release 为rust-v0.137.0（2026-06-04）。Codex manual 已覆盖 CLI / IDE / App / Web / GitHub Action / SDK / App Server / Subagents / Hooks / Memories / Plugins。本文 2026-04 的模型名、slash command、subagent 默认上限等细节按历史快照阅读，当前口径见official-update-check-2026-06-08.md。
#目录
- 写在前面：项目身份消歧 + 三个核心矛盾 0.5. 一张图看懂：Codex = Model + Harness
- Agent 是什么 —— Profile + Subagent + AGENTS.md
- Agent 怎么活起来 —— 一次调用的完整链路
- Agent 怎么思考 —— Agent Loop / Approval / Sandbox 三联体
- Agent 怎么行动 —— apply_patch / shell / MCP / Web
- Agent 怎么记忆 —— context / AGENTS.md / 多 turn / compaction
- Agent 怎么开口 —— TUI / IDE / App / Cloud / GitHub Action
- Agent 的外脑 —— gpt-5-codex 家族与 Responses API
- 关键设计权衡（架构师视角）
- 附录：组件地图、关键概念、源码索引、一句话总结
#零、写在前面：项目身份消歧 + 三个核心矛盾
"Codex" 这三个字在 OpenAI 历史上至少被回收使用过四次，先把名字钉死。
#0.1 "Codex" 到底指什么 —— 必须先消歧
下面四个东西经常被混为一谈，本文只讲后三个：
| 名字 | 时代 | 形态 | 状态 |
|---|---|---|---|
| Codex 模型（旧） | 2021，GPT-3 衍生的 code-davinci-002 | 代码补全模型，被 GitHub Copilot 用作底座 | 2023 年退役，与本文无关 |
openai/codex 仓库 |
2025-04 起 | Apache-2.0 开源仓库，最初用 TypeScript，2025 下半年起用 Rust 重写为 codex-rs |
本文主角的"地基" |
Codex CLI（@openai/codex） |
2025-04 起 | 命令行 agent，对标 Claude Code / Aider | 本文主角 |
| Codex Cloud / Codex App | 2025-05 起 | ChatGPT 内的 "Codex" tab + macOS/Windows 桌面 App，跑在 OpenAI 云沙箱里 | 本文主角 |
外加一些子产品：
- Codex IDE Extension：VS Code / Cursor / Windsurf / JetBrains 插件，本质是 codex-rs 的图形外壳。
- Codex GitHub Action（
openai/codex-action@v1）：把codex exec包成 CI 任务。 - Codex SDK：把 codex-rs 当库引用，用 Agents SDK 做二次开发。
- codex-mini / gpt-5-codex 家族：与 CLI 配套的模型分支（详见第七章）。
一句话定位：本文讲的 "Codex" 是 OpenAI 2025-2026 推出的、以 openai/codex 仓库为核、以 ChatGPT 订阅为账本、以 Rust 内核 + 多端壳层为形态的编程 agent 生态。
#0.2 三个核心矛盾
| 矛盾 | OpenAI 的回答 |
|---|---|
| agent 要敢动手，但用户要安全 | sandbox（能不能做）× approval（要不要问）双轴解耦，workspace-write + on-request 设为 --full-auto 默认，danger-full-access + never 才是真 yolo |
| 本地交互要快、云端任务要长 | 本端用 codex-rs（无 GC、毫秒级响应、Bubblewrap/Seatbelt 强隔离）；长任务推到 Codex Cloud，跑在 OpenAI 自家 sandbox 容器里，PR 形式回流 |
| 多端要一致，但 IDE/CLI/Cloud 各有形态 | 内核统一在 codex-rs 的 core/ crate；外面套不同壳（TUI / VS Code 插件 / JetBrains 插件 / 云端 worker / GitHub Action），共享同一份 ~/.codex/config.toml 与 AGENTS.md |
每章会反复回到这三个矛盾，看具体设计如何回应。
#零·五、一张图看懂：Codex = Model + Harness
业界视角：Anthropic / Cursor / Codex / Aider / Cline 共享同一档底座模型，但实际行为差距巨大。 差的不是模型，是"模型之上的外壳（Harness）"——指令、工具、基础设施、可观测性四层共同决定 agent 的真实能力上限。
套到 Codex 上特别贴：gpt-5-codex 家族是 Model，codex-rs 内核 + 多端壳层 + sandbox/approval 双轴 是 Harness。同一份内核装进 CLI / IDE / App / Cloud / GH Action 五种壳，行为却差很多——区别就来自 这层 harness 的具体配置。下文按"4 层 + 8 支柱"反向索引本文档每个章节。
#0.5.1 四层 Harness 结构
┌──────────────────────────────────────────────────────────────────────┐
│ Agent = Model (gpt-5-codex 家族) + Harness (codex-rs) │
└──────────────────────────────────────────────────────────────────────┘
┌──────────────────────────────────────────────────────────────────────┐
│ ① 指令层 │ AGENTS.md 多层级合并（用户/项目/嵌套目录） → §1.4 / §5.2 │
│ │ Profile (~/.codex/config.toml) 运行预设 → §1.2 │
│ │ Subagent developer_instructions → §1.3 │
│ │ Codex product prompt + 训练期 system prompt → §5.1 │
├──────────────────────────────────────────────────────────────────────┤
│ ② 能力层 │ apply_patch 私有结构化 diff（招牌菜） → §4.2 │
│ │ shell（sandbox 内执行） → §4.3 │
│ │ multi_tool_use.parallel 批处理 → §3.1 / §4.1 │
│ │ MCP servers（stdio + HTTP，含 OAuth） → §4.4 │
│ │ web_search / apps / skills → §4.5 │
├──────────────────────────────────────────────────────────────────────┤
│ ③ 基础设施│ Sandbox：bwrap (Linux) / seatbelt (macOS) → §3.3 │
│ │ Approval policy（untrusted/on-request/never）→ §3.2 / §3.4 │
│ │ codex app-server 双进程 + 本地 socket → §2.1 │
│ │ SQLite session（resume / fork / side） → §5.3 │
│ │ Responses API + server-side compaction → §5.4 / §7.3 │
│ │ OpenAI 云 sandbox 容器（Cloud 长任务） → §2.2 │
├──────────────────────────────────────────────────────────────────────┤
│ ④ 可观测 │ codex exec --json JSONL 事件流 → §2.1 / §6.1 │
│ │ /status 显示 token 用量 + session 配置 → §6.4 │
│ │ Cloud 任务有完整 PR + 容器日志 → §2.2 │
│ │ ⚠ 本地 CLI 无 cost 看板 / 跨 session 聚合缺位 │
└──────────────────────────────────────────────────────────────────────┘
#0.5.2 八支柱对照表
| # | Harness 支柱 | 一句话定义 | Codex 的实现 | 对应章节 |
|---|---|---|---|---|
| 01 | FS + Git | state 必须活在 context 之外 | AGENTS.md 走 git + 嵌套目录覆盖；apply_patch 直接落盘；workspace-write sandbox 把 .git 子路径回贴只读 |
§1.4 / §4.2 / §3.3 |
| 02 | Bash 通用工具 | "随用随装"，避免 token 爆炸 | shell 工具 + MCP stdio/HTTP 按需挂；codex sandbox 子命令独立试边界；untrusted 模式维护"已知安全只读命令"白名单 |
§4.3 / §4.4 |
| 03 | 沙箱 + 子工具 | 行动可隔离 + 可自检 | sandbox × approval 双轴正交（3×4 矩阵）；bwrap/seatbelt 物理隔离；codex execpolicy 干跑策略 |
§3.2 / §3.3 / §3.4 |
| 04 | 记忆 + 搜索 | 跨 turn / 跨 project 拿历史 | 无官方向量记忆——AGENTS.md 人工维护 + SQLite session resume/fork + 走 MCP 接外部记忆 server | §5.2 / §5.3 / §5.5 |
| 05 | 对抗 Context Rot | 长对话也别糊 | /compact 触发 Responses API 的 type=compaction + encrypted_content（server-side stateful 压缩，非 sliding window 截断） |
§5.4 |
| 06 | 长程执行 | 多 phase 任务不跑偏 | Plan Mode 新开 fresh context 做规划；model_reasoning_effort=high 提升单 turn 思考深度；Cloud 模式跑超长 task 以 PR 形式回流 |
§3.1 / §6.4 / §2.2 |
| 07 | Hooks 强制层 | 失败转成永久规则 | approval policy 支持 granular 表配置（sandbox_approval / rules / mcp_elicitations / request_permissions / skill_approval 等子开关分别决定何时提示）+ /hooks 生命周期 hook + AGENTS.md 让规则永久化（人工 PR）；旧 on-failure 模式已弃用 |
§3.2 |
| 08 | 规划 + 工具选择 | 别什么都试，先想再调 | Prompting Guide 鼓励 "proactively gather context, plan, implement, test"；subagent 默认 opt-in + max_depth=1 浅层并发；/plan 命令显式切规划 |
§3.1 / §1.3 / §6.4 |
#0.5.3 当前架构的短板（按 Harness 视角看出来的）
Codex 的指令层 / 能力层 / 基础设施层都打磨得很扎实，但 可观测性层在本地 CLI 形态上偏弱， 而且分布不均——Cloud 端可观测性完备（PR + 容器日志 + UI 历史），CLI/IDE 端却薄。文档现状：
- ✅ 有：
codex exec --jsonJSONL 事件流（CI 可解析）、/status即时面板、Cloud 任务完整记录 - ❌ 缺：本地 CLI 无 cost 透明度——
--json里有 usage 但没有按 task / 按 profile / 按 subagent 聚合的看板， ChatGPT 订阅模式下用户更难感知额度消耗节奏 - ❌ 缺：本地 agent loop 没有跨 session 持久记忆——SQLite session 只存对话，没有任务级别的"学到了什么"沉淀，
每次
codex启动等于 fresh start；AGENTS.md 需要人工维护这部分认知（参 §8.4 这是个有意决策但代价真实） - ❌ 缺：approval 模式之间切换不显式——
--full-auto/--yolo/--dangerously-bypass-...这些 flag 一旦传入， 整个 session 就锁定，没有逐 tool / 逐工作区动态切档的运行时提示；用户容易在不同壳之间携带错误的默认 trust 级别
server 或基于 codex exec --json 二次开发。Harness 的"The Ratchet 方法论"（每一次失败 → 一条永久规则）在 Codex 里
只能落到 AGENTS.md，且必须走 git PR review——这是优点也是吞吐瓶颈。
#一、Agent 是什么 —— Profile + Subagent + AGENTS.md
在 Codex 里，"一个 agent" ≠ 一个静态 persona，而是 (模型 + sandbox + approval + 工具白名单 + AGENTS.md) 这一组运行时参数 + 一份工程记忆。
#1.1 Codex 没有"APC"，但有四层身份描述
┌──────────────────────────────────────────────────────────────────────────┐
│ 本次 codex 调用的 effective agent │
├──────────────────────────────────────────────────────────────────────────┤
│ ① 二进制：codex / codex exec / codex app / codex mcp-server │
│ ↓ 决定主循环骨架、是否带 TUI、是否出 PR │
│ ② Profile（~/.codex/config.toml） │
│ ↓ model / approval_policy / sandbox_mode / mcp_servers / 默认行为 │
│ ③ Subagent (~/.codex/agents/*.toml or .codex/agents/*.toml) │
│ ↓ developer_instructions + 可覆盖的 model / sandbox / mcp / skills │
│ ④ AGENTS.md（项目级 + 用户级 + 嵌套目录级） │
│ ↓ 工程记忆，每轮 prompt 拼接进 system / developer 区 │
└──────────────────────────────────────────────────────────────────────────┘
四层叠在一起才构成"这次跑的是哪个 Codex"。这种切法的代价是：身份不像 APC 那样可以一次性 SELECT 出来，调试时得拼起来看；好处是分层清晰，工程记忆（AGENTS.md）走 git，运行参数（profile）走本地配置，模型选择（subagent）按任务切换。
#1.2 Profile —— 顶层默认值
~/.codex/config.toml 里每个 [profiles.<name>] 段就是一份"运行预设"，用 --profile / -p 选择：
# ~/.codex/config.toml（示意，字段以官方文档为准）
model = "gpt-5.5"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
[profiles.review]
model = "gpt-5.4"
sandbox_mode = "read-only"
approval_policy = "never"
[profiles.yolo]
sandbox_mode = "danger-full-access"
approval_policy = "never"
[mcp_servers.fs]
command = "npx"
args = ["@modelcontextprotocol/server-filesystem", "."]
[mcp_servers.github]
url = "https://api.example.com/mcp"
bearer_token_env_var = "GH_MCP_TOKEN"
字段语义官方在 developers.openai.com/codex/config-basic 与仓库 docs/config.md 里有完整列表，本文只挑跨章节会反复用到的：
model—— 默认模型（详见第七章）。approval_policy——untrusted/on-request/never（详见第三章）。sandbox_mode——read-only/workspace-write/danger-full-access（详见第三章）。mcp_servers.<name>—— 挂 MCP server，stdio 用command/args/env，HTTP 用url/bearer_token_env_var（详见第四章）。project_doc_max_bytes—— AGENTS.md 注入上限，默认 32 KiB（详见第五章）。cli_auth_credentials_store—— 登录凭据存哪：file/keyring/auto（详见第六章）。
#1.3 Subagent —— 任务级人格
Codex 的 subagent 是 2026 年才稳定的能力，不是默认开启，需要在 prompt 里显式触发（"spawn one agent per ..."）。定义文件位置：
- 用户级：
~/.codex/agents/*.toml - 项目级：
.codex/agents/*.toml
最小定义：
# .codex/agents/reviewer.toml
name = "reviewer"
description = "PR reviewer for correctness and security"
developer_instructions = """
Review code like an owner. Focus on correctness, security, and tests.
Never modify files. Output a structured report.
"""
model = "gpt-5.4"
model_reasoning_effort = "high"
sandbox_mode = "read-only"
# mcp_servers = [...] 省略字段会从 parent 继承
# skills.config = ...
全局并发与深度由 [agents] 段控制：
[agents]
max_threads = 6 # 同时活的 subagent 线程数，默认 6
max_depth = 1 # 嵌套层数，默认 1（subagent 不能再 spawn subagent）
job_max_runtime_seconds = 1800
内置 agent（按官方实现约定，名称可能随版本调整，待核实精确清单）：default（你 codex 直接对话的那个）、worker（subagent 默认壳）、explorer（专注代码搜索）。
关键边界：subagent 继承父 session 的 sandbox/approval，并继承运行时覆盖（比如父进程开了 /yolo，子进程也是 yolo）。这个设计是双刃剑：方便，但 yolo 会传染。
#1.4 AGENTS.md —— 工程记忆
AGENTS.md 是 Codex 的"项目说明书"，位置和优先级：
合并顺序（从前到后拼接，靠近 cwd 的文件覆盖更早的）：
1. ~/.codex/AGENTS.override.md
2. ~/.codex/AGENTS.md
3. <git_root>/AGENTS.override.md
4. <git_root>/AGENTS.md
5. <git_root>/<sub_dir>/AGENTS.md
...
N. <cwd>/AGENTS.md
每个目录最多取一个文件；先找 .override.md 再找 AGENTS.md；
默认上限 project_doc_max_bytes = 32 KiB，超出就停止追加。
合并结果在每次 run 启动时拼接一次，注入到 system/developer 上下文。
/init 会扫描当前仓库结构、生成一个 AGENTS.md 脚手架（构建命令、测试命令、目录约定），让你接着改。
关键认知：AGENTS.md 是让人 review 给 LLM 看的文档，而不是 LLM 自己存的记忆。Codex 不会自己往里写。这点和 Claude Code 的 CLAUDE.md / Cursor 的 .cursorrules 思路一致 —— 但 Codex 的"嵌套目录级 + override"是它特有的层级设计。
#二、Agent 怎么活起来 —— 一次调用的完整链路
从你按下回车，到 Codex 在工作区里改完文件、敲完测试、把 patch 推到屏幕上，每一步都能拆开看。
Codex 至少有 本地 CLI 和 Cloud agent 两条主链路，必须分开讲。
#2.1 本地 CLI 模式 —— codex / codex exec
这是日常 90% 的使用形态。命令行启动后，整体链路是：
┌────────────────────────────────────────────┐
│ 终端用户 │
└──────────────────┬─────────────────────────┘
│ codex / codex exec "<task>"
▼
┌─────────────────────────────────────────────────────────────────┐
│ codex 二进制 (codex-rs/cli + tui|exec) │
│ │
│ 1) 加载 ~/.codex/config.toml + profile + subagent toml │
│ 2) 扫描 AGENTS.md 链 → 拼成 effective system/developer prompt │
│ 3) 起 SQLite session 状态库（~/.codex/sessions/...） │
│ 4) 选认证：ChatGPT OAuth token | OPENAI_API_KEY │
│ 5) 选 transport：直接 Responses API，或经本地 proxy │
└────────────────────┬─────────────────────────┬──────────────────┘
│ │
▼ ▼
┌──────────────────────────────┐ ┌────────────────────────┐
│ Responses API (OpenAI 云) │ │ 本地 sandbox 执行器 │
│ gpt-5.x-codex / 推理 │ │ bwrap / seatbelt │
│ tool_calls 序列 │ │ apply_patch / shell │
└─────────────┬────────────────┘ └──────────┬─────────────┘
│ stream events │ 工具结果
▼ ▼
┌────────────────────────────────────────────────────────┐
│ agent loop (codex-rs/core) │
│ while not done: │
│ resp = responses.stream(input + tools) │
│ for tool_call in resp.tool_calls: │
│ if needs_approval(tool_call): ask_user() │
│ tool_result = sandbox.run(tool_call) │
│ input.append(tool_result) │
│ if resp.final_message: break │
└────────────────────────────────────────────────────────┘
几个值得点名的设计：
- App-server 双进程：
codex实际上分成 TUI 进程 +codex app-server后台进程，两者用本地 socket / WebSocket 通信。这样 IDE 插件和 TUI 可以共享同一个 server，开多个前端不用重复登录。--listen/--ws-auth等 flag 就是给这层用的。 codex exec≡ 头模式：去掉 TUI、把所有事件以 JSONL 输出到 stdout（--json），方便 CI 解析。-o/--output-last-message把最后一条消息单独写文件，常用来做 PR 评论体。codex resume/codex fork：会话状态存在本地 SQLite，可以在新 shell 里 resume；fork 会复制一份对话另起分支（分支不会污染原 session）。
#2.2 Cloud agent 模式 —— chatgpt.com/codex + Codex App
云端跑的 Codex 是另一条链路，不在本地起进程：
┌─────────────────────────────┐
│ 浏览器 / Codex 桌面 App │
│ （ChatGPT 账号已登录） │
└──────────────┬──────────────┘
│ 提交 task：仓库 + branch + prompt
▼
┌────────────────────────────────────────────────────────────┐
│ ChatGPT.com / Codex 后端 │
│ - 配置环境（哪个 repo、setup 步骤、要装的工具） │
│ - 决定本次 task 是否允许联网 │
│ - 排队 → 拉起一个云 sandbox 容器 │
└──────────────┬─────────────────────────────────────────────┘
│
▼
┌────────────────────────────────────────────────────────────┐
│ OpenAI 自家云 sandbox 容器（cloud environment） │
│ - clone 仓库到指定 branch │
│ - 跑 setup script（你预设的 install/test） │
│ - 启 codex 进程，执行 task，多 turn 工具调用 │
│ - 结束后产出 diff、测试报告、（可选）创建 PR │
└──────────────┬─────────────────────────────────────────────┘
│
▼
┌────────────────────────────────────────────────────────────┐
│ GitHub PR / ChatGPT UI 里的"Apply diff"按钮 │
│ 本地用 `codex apply <task-id>` 把 diff 拉回来 │
└────────────────────────────────────────────────────────────┘
要点：
- 并发是云端的核心卖点：可以同时开十几个 task，每个跑在独立容器里，"weeks of work in days" 的口径是为这个场景准备的。本地 CLI 的 subagent 是 in-process 并行，云端是跨容器并行，两层并行不是一回事。
- 联网控制：云沙箱默认可以根据配置开/关公网。开启网络是高危选项，因为这意味着 LLM 可以让 sandbox 访问你的私有 npm 源、SSH key（如果你显式注入）。
- 回流方式：要么云端直接开 PR（GitHub App 集成），要么用
codex apply <task-id>把 patch 拉到本地工作区，再人工 review。 - 认证一致性：Cloud 任务消耗的是你的 ChatGPT 订阅额度，不是 API Key 钱包；这一点在第六章再展开。
#2.3 GitHub Action 模式 —— openai/codex-action@v1
CI 模式本质上是把 codex exec 包了一层：
# .github/workflows/autofix.yml（示意）
- uses: openai/codex-action@v1
with:
openai-api-key: ${{ secrets.OPENAI_API_KEY }}
prompt-file: .github/prompts/autofix.md
codex-args: "--full-auto --sandbox workspace-write"
action 内部做的事：装 CLI 二进制 → 启 Responses API proxy（如果给了 API key）→ 用 GitHub runner 自带的 ubuntu sandbox 跑 codex exec。所以 GitHub Action 的安全边界其实是 GitHub runner 容器 + Codex sandbox 两层叠加。
#三、Agent 怎么思考 —— Agent Loop / Approval / Sandbox 三联体
"思考" 在 Codex 里被显式拆成三件事：模型在 Responses API 里推理（loop），何时停下来问人（approval），物理上能动什么（sandbox）。
#3.1 Agent Loop —— Responses API 之上的 while
OpenAI 把 Codex 的主循环写得相当朴素，每一轮叫做一个 turn：
# 伪码，按 OpenAI "Unrolling the Codex agent loop" 文档复述
input_items = [system_prompt, agents_md, user_message]
while True:
resp = client.responses.stream(
model=model,
instructions=developer_prompt,
tools=available_tools, # apply_patch / shell / web_search / mcp.* / ...
input=input_items,
)
for event in resp:
if event.type == "tool_call":
if needs_approval(event.tool_call):
ok = ask_user(event.tool_call)
if not ok: continue
result = sandbox.execute(event.tool_call)
input_items.append(tool_result_item(event.tool_call, result))
elif event.type == "message_final":
return event.content
if context_too_long(input_items):
input_items = compact(input_items) # 见 §5.4
几个要点：
- 基于 Responses API 而非 Chat Completions：Responses API 原生支持
tools、流式 reasoning、tool 结果回灌。Codex 是 OpenAI 自家 dogfooding 它的 Responses API 的最佳示范。 - rich tool 序列：单个 turn 内可以连续触发多次 tool_call（读文件、跑测试、再 apply_patch），不是 ReAct "一思一动" 那种单步。
- "持续动作"风格：Codex Prompting Guide 明确鼓励模型 "proactively gather context, plan, implement, test, and refine without waiting for additional prompts"，所以默认风格是 long-running、少打断。
- 并行工具调用：通过
multi_tool_use.parallel把多个独立的读操作打包成一个 batch；config 里supports_parallel_tool_calls = true控制开启。
#3.2 Approval policy —— "什么时候停下来问"
四种 approval 模式，是与"做什么"无关的元控制：
| 模式 | 行为 |
|---|---|
untrusted |
只允许"已知安全"的只读命令自动跑；写、网络、未知命令一律弹出 |
on-request |
沙箱内的事自动做；要越界（写工作区外、联网、destructive MCP）才问 |
never |
不弹窗。沙箱限制依然生效；超出沙箱直接报错而非询问 |
<granular table> |
不用字符串而用表配置，单独开关 sandbox_approval / rules / mcp_elicitations / request_permissions / skill_approval 等子项 —— 给企业策略做细粒度裁剪 |
旧版的 on-failure（命令失败再问）已经被官方明确标记为 deprecated（"use on-request for interactive runs or never for non-interactive runs"），新会话里不要再用。
关于"reviewer subagent 自动评审"的产品形态：本文写作时（2026-04）官方文档没有把它包装成一个独立的 approval mode 名称（早期博客出现过的
auto_review拼写未在 config reference 中保留），实际能力对齐的是/review命令 + reviewer subagent 模板，需要用户显式调用。（待核实：后续版本是否会重新引入单独 mode）
#3.3 Sandbox mode —— "物理上能做什么"
三档 sandbox，与 approval 正交：
| 模式 | 文件读 | 文件写 | 命令执行 | 网络 |
|---|---|---|---|---|
read-only |
全盘 | 禁止 | 默认禁止（除非 approval 放行） | 禁止 |
workspace-write（默认） |
全盘 | 仅 cwd 及 --add-dir 列出的目录；.git/.codex 子路径再次只读 |
沙箱内任意 | 默认禁止 |
danger-full-access |
全盘 | 全盘 | 任意 | 任意 |
物理实现按 OS 分流（来自 codex-rs/linux-sandbox/README.md 与 docs）：
- macOS：
sandbox-exec -p <profile>（Seatbelt），profile 名对应--sandbox模式。 - Linux：默认走 Bubblewrap（
bwrap）。关键 flag：--ro-bind / /整个根 fs 只读绑定- 写区域用
--bind <root> <root>单点放开 .git、.codex子目录在写区里用--ro-bind再次回贴只读--unshare-user、--unshare-pid、--unshare-net拆 namespace- 配
PR_SET_NO_NEW_PRIVS+ seccomp 网络过滤 - 符号链接攻击：在 first-missing-or-symlink 处用
/dev/nullmount 阻断
- Linux fallback：Landlock 路径仍保留（
features.use_legacy_landlock = true），但只在 bwrap 不可用时才用。 - Windows：PowerShell 下用 Windows Sandbox；或者 WSL2 走 Linux bwrap 路径。
- Cloud：OpenAI 自家容器 sandbox，这层的实现细节没有公开。
#3.4 sandbox × approval 的组合矩阵
合在一起看就清晰了：
│ approval=never │ on-request │ untrusted
─────────────────────┼────────────────┼────────────┼──────────
sandbox=read-only │ 静默只读 │ 越界询问 │ 写命令必问
sandbox=workspace-w. │ ★ 真 yolo'lite │ ★★ 默认推荐 │ 复杂场景
sandbox=danger-full │ ★ 真 yolo │ 命令外问 │ 命令外问
--full-auto 这个 flag 等价于 sandbox_mode = workspace-write + approval_policy = on-request，是 OpenAI 推荐的本地默认。要"什么都不问、什么都能做"必须显式 --dangerously-bypass-approvals-and-sandbox（别名 --yolo）—— 名字起得这么长就是劝退。
#四、Agent 怎么行动 —— apply_patch / shell / MCP / Web
把 LLM 的"想动手"翻译成"能动手"，靠的是工具集。Codex 的工具家族不大，但每件都打磨过。
#4.1 工具全景
┌───────────────────────── Codex 工具栈 ─────────────────────────┐
│ │
│ 内置（codex-rs 直接实现） │
│ ├─ apply_patch 代码 diff 应用，私有结构化语法 │
│ ├─ shell 沙箱内执行命令 │
│ ├─ multi_tool_use.parallel 并行批处理工具调用 │
│ └─ plan / planning Plan Mode 用的轻量 todo 工具 │
│ │
│ 扩展（通过 MCP 协议接入） │
│ ├─ stdio MCP servers 本地起进程，npx/python/... │
│ ├─ HTTP MCP servers URL + bearer，OAuth 走 codex mcp login │
│ └─ codex 自己也能当 MCP server（codex mcp-server） │
│ │
│ 能力（视配置开启） │
│ ├─ web_search Responses API 自带的搜索工具 │
│ ├─ image_input -i/--image 喂图片 │
│ ├─ image_gen $imagegen skill 生成图 │
│ ├─ apps / connectors composer 里 $ 触发，第三方应用接入 │
│ └─ skills .codex/skills 下的可复用脚本 │
└────────────────────────────────────────────────────────────────┘
#4.2 apply_patch —— Codex 的"招牌菜"
LLM 直接写文件最容易翻车（位置错、缩进错、覆盖意外内容）。Codex 的解法是 训练模型只输出一种特定 diff 语法，client 端用 codex-rs/apply-patch crate 严格解析后再写盘：
*** Begin Patch
*** Add File: hello.txt
+Hello world
*** Update File: src/app.py
*** Move to: src/main.py
@@ def greet():
-print("Hi")
+print("Hello, world!")
*** Delete File: obsolete.txt
*** End Patch
- 包络：
*** Begin Patch...*** End Patch - 三种文件操作：
*** Add File:/*** Update File:/*** Delete File: - 改名：
*** Move to: <new-path>（与 Update 联用） - Hunk 头：
@@，可附 class/method 名@@ def greet(): - 行前缀：
+（新增）/-（删除）—— 注意：和标准 unified diff 相反，Add File 里所有正文都用+起头 - 上下文规范：每个 hunk 默认 3 行 above + 3 行 below；3 行不够定位时就堆
@@锚点 - 路径必须是相对路径，不允许绝对路径
模型层这个 tool 在 Responses API 里也对外开放（叫"Apply Patch"），任何用 Responses API 的人都能复用同一份 grammar。OpenAI 还在 cookbook 里给了一份 Python 参考实现。
#4.3 shell —— 沙箱执行
shell 就是把模型给的命令丢进当前 sandbox 跑。不展开太多细节，但提两件容易踩坑的事：
- shell 本身没有"trusted command set"：这套白名单藏在 approval 层（
untrusted模式才会用）。untrusted模式下 Codex 维护一个公开的"已知安全只读命令"列表（ls / cat / grep / git status / ...），命中才自动跑。 codex execpolicy：可以独立评估你写的 rule 文件，干跑一遍看哪些命令会被放行/拦截，做企业策略时很有用。codex sandbox子命令：可以让你在不启动 LLM 的情况下，单独用沙箱跑一条命令试试边界。调试 sandbox 配置的利器。
#4.4 MCP —— 第二个 ecosystem 入口
Codex 是 Anthropic MCP 协议的"早期采用者"之一。两类 transport：
# stdio：本地起进程
[mcp_servers.fs]
command = "npx"
args = ["@modelcontextprotocol/server-filesystem", "."]
env = { TZ = "UTC" }
# streamable HTTP：远端 URL
[mcp_servers.linear]
url = "https://mcp.linear.app/v1"
bearer_token_env_var = "LINEAR_TOKEN"
http_headers = { "X-Workspace" = "acme" }
enabled_tools = ["create_issue", "get_issue"]
disabled_tools = ["delete_issue"]
startup_timeout_sec = 10
tool_timeout_sec = 60
亮点：
enabled_tools/disabled_tools同时存在时，allowlist 先生效再 denylist 过滤，做最小权限暴露。- OAuth 流程：
codex mcp login <name>走浏览器授权回调，可配mcp_oauth_callback_port/mcp_oauth_callback_url（远程开发场景常用）。 - Codex 也能当 MCP server：
codex mcp-server把 Codex 自己暴露成 MCP，让别的 agent（Claude Code / Cursor / 自己开发的 agent）通过 MCP 调用 Codex 当一个 sub-tool。这一步其实把整个生态拓扑反转了 —— Codex 既是 host 也是 server。 supports_parallel_tool_calls = true显式开启某 server 的并行调用（字段位于[mcp_servers.<name>]段下，确切默认值待核实）。
#4.5 Web search / Apps / Skills
这一组是体验层小工具，列一下：
- Web search：Responses API 自带，CLI 用
--search或/-popup 切换 cached / live 模式。 - Apps（Connectors）：在 composer 里输
$弹出第三方应用列表（Linear / Notion / Stripe 等 OpenAI 认证的官方 connector）。云端 task 触发时 connector 凭据由 ChatGPT 平台托管。 - Skills：仓库根的
.codex/skills/目录里放可复用的 prompt / 脚本片段，用$skill_name触发。$imagegen就是一个内置 skill。
#五、Agent 怎么记忆 —— context / AGENTS.md / 多 turn / compaction
Codex 把"记忆"拆成四层：单轮 prompt、AGENTS.md 工程记忆、多 turn 历史、compaction 总结。再多就只能靠工具临时检索。
#5.1 单轮 prompt 的"四件套"
每次 turn 开始，Codex 会拼出大致这样的输入（按官方 "Unrolling the Codex agent loop" 复述）：
┌───────────────── instructions（system / developer 区） ─────────────────┐
│ - OpenAI 训练时的 system prompt（不可见） │
│ - Codex 的 product prompt（"You are a senior engineer ..."） │
│ - merged AGENTS.md（用户级 + 项目级 + 嵌套目录级） │
│ - subagent 的 developer_instructions（如果是 subagent thread） │
│ - profile 注入的 personality / tone │
└──────────────────────────────────────────────────────────────────────────┘
┌───────────────── tools ─────────────────┐
│ apply_patch / shell / multi_tool / mcp.* │
│ MCP 暴露的工具（按 enabled_tools 过滤） │
└─────────────────────────────────────────┘
┌───────────────── input items 序列 ──────────────────┐
│ 用户消息、历史 tool_call、历史 tool_result、附件... │
└──────────────────────────────────────────────────────┘
#5.2 AGENTS.md —— 唯一"可写持久记忆"是给人看的
第 1.4 节已经讲过位置和合并顺序，这里强调三件事：
- 不会被 LLM 自动改写。Codex 不会偷偷往 AGENTS.md 里塞东西。
/init只在没有时主动生成一份骨架。 - 嵌套覆盖意味着你可以在
monorepo/services/foo/AGENTS.md写 foo 服务的特殊规则，离 cwd 越近权重越高。 - 32 KiB 上限很有限。塞不下时 OpenAI 推荐拆到子目录，而不是堆一个超大文件。
#5.3 多 turn 的 session 状态
session 状态存在本地 SQLite（路径由 sqlite_home 或 CODEX_SQLITE_HOME 控制）：
codex resume列出最近 session，挑一个继续。codex fork把当前 session 当 parent 拷一份新分支，原 session 不动。/new在同一个 CLI 进程内开新对话，不退出 process。/side临时开一个独立"小窗口"问个简短问题（fresh context），不污染主线 thread。
#5.4 Compaction —— 长任务的内存管理
context window 会爆。OpenAI 的策略不是 sliding window 截断，而是 结构化压缩：
/compact命令显式触发：把当前可见对话（含 tool_call/tool_result）替换成一个type=compaction的特殊 input item。- 这个 item 里有一段
encrypted_content：服务端可读的、不可在客户端展示的"压缩态"，保留模型的潜在理解状态而不是简单总结。 - 之后的 turn 会基于这个 compaction item 继续，token 消耗显著下降。
这种"server-side stateful compaction"是 Responses API 提供的能力，本质上是把 LLM 的 KV 状态以加密形式存在 OpenAI 后端，CLI 只持有引用。代价是这部分上下文你无法导出/迁移到别的 provider；好处是它不再受客户端 token 计数影响。
#5.5 没有外挂记忆系统
划重点：Codex 没有官方的向量库 / 长期记忆服务。"长期记忆"的常见做法是：
- AGENTS.md 写死规则（人工维护）
- MCP 接一个外部记忆 server（mem0、Letta、vector DB 等）
- 项目里直接放 markdown 文档，让 Codex 用
shell+rg/cat现读
这是个明显与 ChatGPT memory 功能不同的产品决策：编程 agent 默认不要"猜你的偏好"，要"读你写下来的规则"。
#六、Agent 怎么开口 —— TUI / IDE / App / Cloud / GitHub Action
同一个 codex-rs 内核，外面套五种壳。每种壳的 UX 边界不一样，但权限模型、配置、记忆是同一份。
#6.1 五种壳并列
┌────────────┬─────────────────────────────────────────────────┬────────────────────┐
│ 壳 │ 形态 │ 计费来源 │
├────────────┼─────────────────────────────────────────────────┼────────────────────┤
│ codex (TUI)│ Ratatui 全屏终端，approval 对话框、diff 染色 │ ChatGPT 订阅 / API │
│ codex exec │ 头模式，JSONL 输出，给 CI/脚本用 │ 同上 │
│ Codex App │ macOS/Windows 桌面，多 worktree 多 task 并行 │ ChatGPT 订阅 │
│ IDE Ext │ VS Code/Cursor/Windsurf/JetBrains 插件 │ ChatGPT / API / JB │
│ Cloud │ chatgpt.com/codex 网页 + 云沙箱 │ ChatGPT 订阅 │
│ GH Action │ openai/codex-action@v1，runner 内跑 codex exec │ API key（必须） │
└────────────┴─────────────────────────────────────────────────┴────────────────────┘
注意这里"壳"区别只是输入/输出 + 触发方式；核心 agent loop 都是 codex-rs/core（云端 worker 也是同一份内核，只是部署在 OpenAI 容器里）。这种"内核统一、壳层多样"的形态，使得 AGENTS.md / config.toml / MCP server 配置在所有壳里通用。
#6.2 TUI 重点交互
codex 主界面用 Ratatui（Rust TUI 框架）写，关键交互：
- 左/中/右三栏（不同版本会变）：会话列表 / 对话流 / 文件树/diff 预览
- 每个 tool_call 出现 approval 卡片：可以一次性 trust 该命令、单次 allow、reject。
- diff 染色：apply_patch 的 hunk 直接渲染成 +/- 着色 unified diff，回车确认应用。
- Ctrl+G：跳到 prompt editor（多行编辑）。
/-popup：第 6.4 节列的 slash 命令。--no-alt-screen：禁用 alt-screen，方便日志滚屏 + 跨终端复制。
#6.3 IDE 插件层
VS Code 系（VS Code / Cursor / Windsurf）：从 VSIX/Marketplace 装，sidebar 形态，approval 模式也分 Chat（只对话）/ Agent（受沙箱约束）/ Agent (Full Access)（约等于 yolo）。
JetBrains 系（IntelliJ / PyCharm / WebStorm / Rider 2025.3+）：嵌进现有 JetBrains AI chat panel，三种登录方式 —— JetBrains AI 订阅、ChatGPT 账号、OpenAI API Key 三选一。这种"嵌入现有 AI 面板"的取舍意味着 JetBrains 集成牺牲了一些 Codex 专属 UX（比如 fork/side），换来与 JetBrains AI 其它功能的一致性。
无论 VS Code 还是 JetBrains，底层都通过本地 codex app-server 进程通信，所以你在 IDE 里 approve 的事 CLI 也能看见，反之亦然。
#6.4 Slash 命令速查（CLI）
按官方 /codex/cli/slash-commands 列：
按官方 developers.openai.com/codex/cli/slash-commands 列（2026-04 现状）：
| 分组 | 命令 | 用途 |
|---|---|---|
| 核心 | /model |
切模型 + 推理强度 |
| 核心 | /fast |
切 Fast 服务档（gpt-5.3-codex-spark 等支持） |
| 核心 | /personality |
切交互人格（friendly / pragmatic / none） |
| 核心 | /plan |
Plan Mode：新开 fresh context 做规划 |
| 核心 | /permissions |
调 approval / sandbox |
| 核心 | /approve |
重试被拒动作 |
| 核心 | /status |
显示 token 用量、session 配置 |
| 文件/代码 | /diff |
显示 git diff（含未追踪文件） |
| 文件/代码 | /mention |
把文件附进对话 |
| 文件/代码 | /copy |
复制最后一条输出 |
| 文件/代码 | /review |
让 Codex 评审当前 working tree |
| 会话控制 | /clear |
清屏 + 开新对话 |
| 会话控制 | /new |
同一进程内开新对话 |
| 会话控制 | /fork |
当前对话 fork 一支 |
| 会话控制 | /side |
起一个临时 ephemeral side thread（不污染主线） |
| 会话控制 | /resume |
列出历史 session 选一继续 |
| 配置/外观 | /keymap |
重映射 TUI 快捷键 |
| 配置/外观 | /vim |
切 Vim 模式 |
| 配置/外观 | /theme |
切语法高亮主题 |
| 配置/外观 | /statusline |
配置底栏显示项 |
| 配置/外观 | /title |
配置终端窗口标题 |
| 配置/外观 | /raw |
切 raw scrollback 模式 |
| 工具/集成 | /agent |
切换活动 agent thread（subagent 用） |
| 工具/集成 | /mcp |
列出已连接的 MCP servers/tools |
| 工具/集成 | /apps |
浏览/插入第三方 connector |
| 工具/集成 | /plugins |
浏览/管理 plugin |
| 工具/集成 | /skills |
应用任务专用 skill |
| 工具/集成 | /hooks |
review 生命周期 hook |
| 维护 | /init |
在当前目录生成 AGENTS.md 脚手架 |
| 维护 | /compact |
压缩当前可见对话以释放 token |
| 维护 | /experimental |
实验特性开关 |
| 维护 | /goal |
设任务目标（experimental） |
| 维护 | /memories |
配置记忆行为 |
| 维护 | /feedback |
把日志发回维护者 |
| 维护 | /logout |
登出 |
| 维护 | /quit / /exit |
退出 |
注意官方文档当前列表里 没有 /yolo —— 早期博客提到的 yolo 命令已经被合并到 /permissions（要 yolo 必须用启动 flag --dangerously-bypass-approvals-and-sandbox）。/side 与 /theme 在 2026-04 文档里仍然存在，与早期博客一致。/hooks 是 codex 端的"生命周期 hook"概念（与 sandbox 内的 shell 工具不同），可以用来挂 pre/post 工具回调（待核实详细 schema）。
#6.5 认证与计费的两张面孔
Codex 的"账本"很特别：
- ChatGPT 账号登录（推荐）：浏览器 OAuth，回调 token 存
~/.codex/auth.json或 OS keyring（由cli_auth_credentials_store控制）。所有 CLI/IDE/App/Cloud 用法都从你 ChatGPT 订阅的额度里扣，不另收 API token 费。Plus / Pro / Business / Edu / Enterprise 都行（甚至 Free/Go 有少量额度）。token 自动续期。 - OpenAI API Key 登录（可选）：从 platform 控制台拿
OPENAI_API_KEY，按标准 API 费率计费（Responses API 价格，gpt-5.4 $1.5 / 1M input、$6 / 1M output 那一档；75% prompt cache 折扣可叠加）。CI 里只能用这种方式。 - JetBrains AI 订阅（仅 JetBrains IDE）：第三种通道，账单挂在 JetBrains 侧。
这种"个人订阅当 agent 钱包"的玩法，使得 Codex 是少数 不用搞清 API 计费就能起步的编程 agent 之一 —— 这点对采纳曲线影响巨大。
#七、Agent 的外脑 —— gpt-5-codex 家族与 Responses API
Codex 的"思考能力"不在仓库里，而在 OpenAI 后端的几个专用模型里。
#7.1 模型矩阵（截至 2026-04）
字段以官方 developers.openai.com/codex/models 为准；具体推荐档可能随时调，下面是当前官方推荐表：
| 模型 | 定位 | 默认场景 |
|---|---|---|
| gpt-5.5 | 复杂编码 + computer use + 知识工作 + research workflow | 当前推荐默认（ChatGPT 登录可用时） |
| gpt-5.4 | 编码 + 增强推理 + agentic workflow | 5.5 不可用时回退 |
| gpt-5.4-mini | 快速、便宜的小模型 | subagent / 简单任务 / 速度优先 |
| gpt-5.3-codex | 上一代旗舰 coding | legacy 兼容 |
| gpt-5.3-codex-spark | text-only research preview，近实时迭代 | ChatGPT Pro 用户专享，研究预览 |
| gpt-5.2 | 通用前代 | 兜底 |
要点：
-codex后缀模型是经过 coding-specific 后训练的版本，相对通用 5.x 在 apply_patch 格式、tool sequencing、长 horizon 任务上更稳。-mini是为 subagent / 高并发场景准备的：subagent 默认会用 mini 档以省钱省时间，主线对话才用大模型。-spark是低延迟实验型号，思想类似 Anthropic Haiku 或 Cerebras 加速版本：贴近 IDE 内联补全场景。- 历史名："codex-mini" 是 2025 年早期的产品名，现在被
gpt-5.x-mini系列吸收；"codex-1" 是 cloud agent 首发用的内部命名，已经被 5.x 系列替换。
#7.2 推理强度档位
每个模型可以指定 model_reasoning_effort = low / medium / high：
- 低档：响应快、可能跳步
- 高档：思考更长、可能多 turn 自我反思
- 在 IDE 里可以一键切；CLI 里
/model一并设置；profile / subagent toml 里可锁定。
OpenAI 在 cookbook 里建议："简单任务 low、复杂重构 high、长 horizon 任务 high"。
#7.3 Responses API —— 不是 Chat Completions
Codex 的所有调用都走 Responses API，不是老的 Chat Completions。差别：
- 原生
tools描述、原生 streaming reasoning event、原生tool_call/tool_resultitem 类型 instructions字段独立于input，对应 system/developer prompt- 支持
type=compaction、encrypted_content等 stateful item（见 §5.4） - 内置
web_search工具直接 enabled
简言之：Responses API 是一个"为 agent loop 设计的 API"，Codex 是它的官方 reference impl。
#7.4 OSS / 自托管模型
--oss flag 提示存在跑开源/自托管模型的路径（用兼容 OpenAI API 的 server，比如 vLLM、Ollama、Together），但官方明确：apply_patch 格式是给 gpt-5-codex 训练过的，跑别的模型时质量会显著下降。这条路目前还更像"实验性"。
#八、关键设计权衡（架构师视角）
五条核心取舍，每条按"问题 / 回答 / 启发"三段式。
#8.1 为什么 Rust 重写？把 TS 版本几乎抛弃？
问题：原版 Codex CLI 用 React + TypeScript + Node 写的，启动要 Node 22+，长 running agent 进程要 GC、要驻留内存。装一次得拖 200MB 的 node_modules。
回答：2025 年中开始重写到 Rust（codex-rs/），到 2026 年初已经占代码 95%+。npm i -g @openai/codex 现在装的是 thin wrapper，下载对应平台的 Rust 单二进制。原 TypeScript 版仍维护到 Rust 达 parity 为止，专门做 sec patch。
启发：当 agent 进程要长时间常驻、要操作 sandbox、要做 IPC（app-server 双进程）时，GC 语言不是好选择。Rust 在这里做对了三件事 —— 启动毫秒级、内存占用可控、sandbox 系统调用细粒度可控（直接调 bwrap/seatbelt）。这条路其它 agent 也在跟（zed、Aider 部分模块、Continue 部分模块），是个明显趋势。
#8.2 为什么是双轴（sandbox × approval）而不是单轴？
问题：单轴 trust level（"yolo / careful / paranoid"）听起来简单，但实际上"信任"既包含 能做什么（沙箱），也包含 什么时候问（审批），把这俩绑死会损失大量场景。
回答：拆成两轴：sandbox 决定物理边界，approval 决定何时打断人。workspace-write + on-request 是日常默认；read-only + never 是 review 用；danger-full-access + never 是 yolo（且名字劝退）。
启发：复杂权限系统里，永远不要把"能力"和"审批"绑成一个 enum。Goalfy 的多 turn 调度里也踩过类似坑。这套双轴的代价是用户要理解两个概念，但带来的灵活性远大于成本。
#8.3 为什么云和本地不是同一个进程？
问题：很多 agent 厂在纠结："本地 CLI 怎么也支持云端长任务？"答案要么是把 CLI 跑在云容器里（费时费钱），要么是搞混合模式（复杂）。
回答：Codex 直接拆成两套部署：本地 codex-rs 跑短交互、云 sandbox 跑长任务。但 共享同一份 agent loop 实现（codex-rs/core）。差异只在外层：本地有 TUI、云端有 GitHub PR 集成。codex apply <task-id> 把云端结果拉回本地 review。
启发：本地 vs 云端不是"哪个更好"的二选一，而是 不同 task latency / 不同安全模型 的两类工作。把它们做成同一个内核 + 不同部署，比硬塞同一个壳更优雅。
#8.4 为什么 AGENTS.md 不让 LLM 自己写？
问题：很多 agent 产品（Claude memory、ChatGPT memory、Cursor memory）都让 LLM 自动维护"记忆"。Codex 偏偏不这么做。
回答：AGENTS.md 是一个走 git、要 review、给团队共享的工程文档。/init 只生成骨架，后续修改全靠人。LLM 想加规则，就在对话里说，由人决定是否落进 AGENTS.md。
启发：编程场景下，"agent 自己学习偏好" 反而是反模式 —— 你不希望昨天偶然说一句 "用 tabs"，就让 codex 永远按 tab 写。规则要审计、要 PR review。把记忆做成 markdown 文件 + 嵌套层级，是把 git workflow 直接套到 agent memory 上，是个非常 "developer-native" 的决定。
#8.5 为什么 OAuth + ChatGPT 订阅，而不是逼用户掏 API key？
问题：开发者用 API key 很自然；但绝大多数 ChatGPT Plus 用户已经付了 $20/月，再让他们注册 platform、绑信用卡、买 API token 就是再上一道坎。
回答：CLI 默认走 ChatGPT OAuth，访问 token 落 ~/.codex/auth.json（或 OS keyring），自动续期。同一份订阅在 CLI / IDE / Cloud / App 里都能花。API key 留给 CI 等无头场景。
启发：对个人开发者 friction 越低越好，对企业则要可审计。Codex 这种"个人用订阅、CI 用 API key"的双轨制是个非常聪明的工程决策 —— 它把"个人付费意愿"和"企业合规需求"两条路分开走，互不阻挡。
#8.6 （加一条）为什么 subagent 默认要显式触发？
问题：很多 agent 框架（AutoGen / CrewAI）默认让 supervisor 自动 spawn workers，但实际用下来工作流调试极难、token 烧得飞快。
回答：Codex 的 subagent 必须在 prompt 里显式说"开 N 个 agent 做 X"（即"spawn one agent per …"句式），由模型生成对应 spawn 工具调用。agents.max_threads = 6 是官方文档里写明的默认值；max_depth 默认 1（subagent 不能再 spawn subagent，待二次核实是否可调）。这些默认值都很保守。
启发：multi-agent 不是"层数越多越好"。把 spawn 行为做成 opt-in + 浅层 的策略，配合 Plan Mode 让用户能预览计划，比"自动 supervisor"更容易上线。这条路上 Claude Code 的 sub-agent / 我们 Goalfy 的 TPE 也是相似取向。
#九、附录：组件地图、关键概念、源码索引、一句话总结
#9.1 组件地图
┌──────────────────────────────┐
│ ChatGPT 平台账号 │
│ (订阅额度 / OAuth / Apps) │
└──────────────┬───────────────┘
│
┌───────────────────┬─────────┴─────────┬───────────────────┐
▼ ▼ ▼ ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ codex CLI │ │ Codex IDE │ │ Codex App │ │ Codex Cloud │
│ (Rust TUI) │ │ Extension │ │ (Desktop) │ │ (chatgpt.com)│
└──────┬───────┘ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘
│ │ │ │
└────────────┬──────┴────────────────────┘ │
▼ ▼
┌──────────────────────────────┐ ┌──────────────────────────┐
│ codex-rs/core (agent loop) │ │ OpenAI 云 sandbox 容器 │
│ + tui/exec/cli/login/... │ │ (跑同一份 codex-rs) │
└──────────────┬───────────────┘ └─────────────┬────────────┘
│ │
├───────────── Responses API ───────────┤
│ (gpt-5.x-codex) │
▼ ▼
┌──────────────────────────┐ ┌──────────────────────────┐
│ Local sandbox │ │ Cloud sandbox │
│ bwrap/seatbelt/landlock │ │ OpenAI 自有容器 │
└──────────────────────────┘ └──────────────────────────┘
│
▼
┌──────────────────────────────────────────────┐
│ 工具层 │
│ apply_patch · shell · web_search · MCP · ... │
└──────────────────────────────────────────────┘
#9.2 关键概念词典
| 概念 | 一句话定义 |
|---|---|
| AGENTS.md | 工程记忆 markdown，多层级合并、人工维护、走 git |
| Profile | ~/.codex/config.toml 里一组运行预设（model + sandbox + approval + ...） |
| Subagent | .codex/agents/*.toml 定义的任务级 agent，显式 spawn，继承父沙箱 |
| Approval policy | 何时停下来问人：untrusted / on-request / never / auto_review |
| Sandbox mode | 物理能做什么：read-only / workspace-write / danger-full-access |
--full-auto |
等价 workspace-write + on-request，本地默认推荐 |
--yolo |
--dangerously-bypass-approvals-and-sandbox 别名，撤销所有保护 |
| apply_patch | Codex 私有结构化 diff 语法，client 严格解析后写盘 |
| MCP server | 通过 Model Context Protocol 接入的外部工具，stdio / HTTP 两种 |
codex exec |
头模式 CLI，CI/脚本用 |
codex resume / fork |
session 状态在本地 SQLite，可继续/分叉 |
codex app-server |
后台进程，CLI/IDE 通过它共享一个 session |
| Codex Cloud | chatgpt.com/codex 上的云端 task，跑在 OpenAI 容器里，可开 PR |
| Responses API | Codex 的对话 API，原生支持 tools/streaming/compaction，不是 Chat Completions |
| compaction | 把历史对话压缩成 server-side encrypted_content item，省 token |
/init /compact /review /model /agent /mcp |
高频 slash 命令 |
| ChatGPT 登录 vs API key | 个人用前者（订阅扣额度），CI 用后者（按 token 计费） |
#9.3 源码索引（截止 2026-04 主分支）
不写具体行号 / 函数名，因为仓库迭代极快，链接定位到目录足够。
| 关心什么 | 去哪个目录看 |
|---|---|
| agent loop 核心 | codex-rs/core/ |
| TUI 界面 | codex-rs/tui/（基于 ratatui） |
头模式 / codex exec |
codex-rs/exec/ |
| 命令分发主入口 | codex-rs/cli/ |
| apply_patch 解析器 + 模型指令 | codex-rs/apply-patch/（含 apply_patch_tool_instructions.md） |
| Linux 沙箱实现 | codex-rs/linux-sandbox/（README 详述 bwrap flags） |
| 登录 / OAuth | codex-rs/login/ |
| MCP client / server | codex-rs/mcp-client/ / codex-rs/mcp-server/ |
| 文件搜索 | codex-rs/file-search/ |
| 全工程文档 | docs/（顶层）+ developers.openai.com/codex/ |
| 配置 schema | docs/config.md（指向 dev portal） |
| GitHub Action | 独立仓库 openai/codex-action |
#9.4 信心标注 / 官方未披露事项
下面几点本文给的描述置信度较低，写完 10 家横评前建议二次校对：
- subagent 的 max_depth = 1 是文档里"默认值"，但近期 changelog 暗示可调到更高；具体上限未在公开文档锁定。
- 云沙箱的具体实现（容器镜像、网络 egress 限制方式、CPU/内存配额）OpenAI 没有公开技术细节，本文只描述了行为而非实现。
/yolo在早期博客出现过，2026-04 官方 slash-commands 列表已不见，相关能力被合并到/permissions+ 启动 flag--dangerously-bypass-approvals-and-sandbox；/side与/theme实际仍在最新列表里（与早期博客一致）。/hooks的具体 schema：2026-04 官方 slash-commands 列出了/hooks命令，但 hook 的事件点、字段名、与 approval policy 的交互细节未在公开文档锁定（与 Claude Code 的 27 事件 OTel hook 体系比文档化程度低很多）。gpt-5.5/gpt-5.4/gpt-5.3-codex-spark是 2026-04 docs 现状；OpenAI 命名节奏快，半年后名字可能变。- codex-rs 工作区的 70+ crate 清单：仓库 README 只列了主要几个（core/tui/exec/cli + 实验 MCP），完整列表得真去翻
Cargo.toml，本文没枚举。
#9.5 一句话总结
OpenAI Codex 是一个"内核统一、壳层多样、记忆走 git、安全双轴解耦、用 ChatGPT 账号当钱包"的编程 agent 生态：codex-rs 提供 agent loop + sandbox 内核，CLI/IDE/App/Cloud/GitHub Action 五种壳共享 ~/.codex/config.toml 与 AGENTS.md，工具层以 apply_patch + shell + MCP 三件套为主，思考靠 gpt-5-codex 家族跑在 Responses API 上，安全靠 sandbox（read-only/workspace-write/danger-full-access）× approval（untrusted/on-request/never）双轴正交策略；subagent 显式 spawn、浅层并发；云端长任务以 PR 形式回流。
#文末说明（≤200 字）
消歧结论：本文锁定的"Codex"= openai/codex 仓库（Apache-2.0，Rust 主体）+ Codex CLI（@openai/codex）+ Codex IDE 插件 + Codex App + Codex Cloud（chatgpt.com/codex）+ GitHub Action，统称 OpenAI 2025-2026 推出的编程 agent 生态。不包含 2021 年退役的 GPT-3 衍生 code-davinci-002 模型。
文件路径：agents/docs/codex-agent-architecture.md。
最不确定的两点：
- 云沙箱（OpenAI 自家容器）的具体隔离实现 —— 本文只复述了行为，OpenAI 没公开内部技术栈。
- subagent 的并发与嵌套硬上限随版本变化，2026-04 默认值（max_threads=6 / max_depth=1）可能很快被放宽。
2026-06-08 复核补充：已确认 @openai/codex@0.137.0 / rust-v0.137.0，并刷新
Codex manual。本篇未逐条重写旧的模型名与命令清单，读者应优先看官方 manual 与
official-update-check-2026-06-08.md。