# OpenAI Codex 架构模板

> **代表产品 / 原型**:OpenAI Codex(Codex CLI + Codex Cloud) —— 旁参 Claude Code、Cursor Agent、Devin
> **一句话定位**:OpenAI 的 agentic 软件工程 agent——同一内核两种形态:本地终端实时结对,或把任务丢进云端独立沙箱里异步跑完并回交 PR;整套架构都在「自治执行」与「沙箱+审批的可控」之间做权衡。

---

## 1. 一句话定位

Codex = **一个 agentic 编码 agent 的内核,长出两副执行躯壳**:在你机器上跟你实时结对(CLI / IDE,同步、逐步审批),或把整个任务委派到云端一个隔离容器里异步跑完、回交一个 PR。

它和 [AI Agent 平台](../ai-agent-platform/README.md) 是同一个谱系——都是「规划 → 调工具 → 观察 → 再决策」的行动循环——但 Codex 把「工具」收窄到**软件工程**这一垂直域:读写代码库、打补丁、跑命令、跑测试、提交。它和姊妹篇 [Claude Code](../claude-code/README.md) 解决的是同一类问题,但 Codex 的灵魂在于**两种执行形态共享一个内核**,以及**用「沙箱 × 审批」两根正交的轴**而不是一维档位来描述「这个 agent 能动多大手脚」。

## 2. 业务本质:它在解决什么问题

传统的「写代码」是一个**人盯着改一行、跑一次、看结果、再改**的紧耦合循环——人是循环里每一步的瓶颈。Codex 要做的事,是把这件事从「实时手动循环」升级为**可委派、可并行、可异步的工程任务执行**:

- **可委派**:你说「把这个鉴权 bug 修了 / 给这个模块补测试 / 把这个依赖升级了」,agent 自己去读代码、改、跑、验,你不必盯着每一步。
- **可并行**:把五个互不相干的任务同时丢进五个云端沙箱,各跑各的,而不是排队等你一个个手动来。
- **可异步**:任务在云端独立环境里跑到完成(可能十几分钟),期间你去干别的;它跑完开一个 PR 等你 review。

换句话说,它把工程师从「循环里的每一步」中解放出来,只保留在**关键决策点(审批、review PR)**上。卖的不是「自动补全」,而是「**把一个有明确目标的工程任务整段交付出去**」。这也决定了它的全部架构张力:任务交付得越「整段、自治」,**失控的副作用**(改错文件、跑危险命令、泄露密钥)就越需要被结构性地约束——于是有了沙箱与审批。

## 3. 核心需求与约束

**功能性需求(系统要能做什么):**
- [ ] 行动循环:读代码库 → 规划 → 打补丁 / 跑命令 → 观察结果 → 再决策,直到任务完成
- [ ] 两种执行形态:本地实时结对(CLI / IDE)+ 云端异步委派(独立容器,跑完开 PR)
- [ ] headless 执行(`codex exec` 之类):能嵌进 CI / 脚本,无人值守地跑
- [ ] 沙箱执行:agent 要跑的命令必须落在受控的隔离环境里
- [ ] 分级审批:危险/越界操作可暂停等人确认,自治程度可调
- [ ] MCP 双向:既能作为客户端接外部工具,又能把自己暴露成 MCP server 供别的 agent 调
- [ ] 就近生效的项目指令(AGENTS.md):让 agent 懂这个仓库的约定
- [ ] 本地 ↔ 云端可迁移:本地起的任务可委派上云,云端结果可拉回本地

**非功能性需求 / 质量属性(系统要做得多好):**

| 质量属性 | 目标 | 为什么对这类系统重要 |
|---|---|---|
| **任务成功率** | 越高越好 | agent 的根本价值;改错/跑偏直接等于负产出 |
| **安全 / 可控** | 必须,且可调 | agent 能改代码、跑命令、联网——副作用真实且可能不可逆 |
| **长程连贯性** | 长任务不迷失 | 工程任务跨度大,上下文一长就容易重复、偏题、忘了目标 |
| **隔离强度** | 内核级,不可被绕过 | 应用层「自律」挡不住失控或恶意;隔离必须比应用更底层 |
| **长程稳定性** | 长会话不崩、不卡顿 | 一个任务跑几十分钟,运行时抖动/内存增长/GC 停顿都会毁掉它 |
| **并行吞吐** | 多任务同时跑 | 云端委派的核心卖点就是并行 |

**关键约束(不可逾越的边界):**
- 🔴 **沙箱是内核强制的,不是君子协定**:agent 跑的命令(及其派生的子进程)被操作系统级机制关进笼子,不靠模型「自觉」。
- 🔴 **云端 agent 阶段默认断网、且密钥已被移除**:容器在真正让 agent 干活前会切断网络、抹掉 setup 阶段用过的凭据——把提示注入能造成的外泄面压到最小。
- 🔴 **`workspace-write` 下 `.git/`、`.agents/`、`.codex/` 递归只读**:不让 agent 篡改版本历史、自身配置与 agent 元数据(防它「改掉给自己上的锁」)。
- 🔴 **模型会出错、会跑偏**:循环可能不收敛、可能自信地改错;所以要有审批与自审兜底。
- 🔴 **Windows 无原生完整沙箱**:完整隔离走 WSL2(Linux 子系统),原生 Windows 路径上沙箱能力受限。

## 4. 架构全景图

```
                         一个共享内核 (core)
        行动循环 · 模型交互 · 工具/补丁/命令调度 · 配置 · 会话/历史
        ┌──────────────────────────────────────────────────────────┐
        │   config.toml(策略 + MCP)   ·   AGENTS.md(就近项目指令)    │
        └───────────────┬───────────────────────────┬──────────────┘
                        │                           │
       ┌────────── 审批 / 执行策略层(双轴正交)──────────┐
       │  sandbox_mode  ×  approval_policy             │  ← 决定「能动多大手脚」
       │  read-only /     untrusted /                  │
       │  workspace-write/ on-request /                │
       │  danger-full     never                        │
       └───────────────┬───────────────────────────┬──┘
                        │                           │
        ┌───────────────▼───────────┐   ┌───────────▼───────────────────┐
        │     本地形态(同步结对)      │   │      云端形态(异步委派)         │
        │  CLI(tui 全屏) / IDE 插件   │   │  chatgpt.com/codex 绑 GitHub   │
        │  · Auto Context 跟踪在看文件 │   │  · 任务进托管的独立隔离容器       │
        │  · 逐步可审批               │   │  · 异步 / 并行,多任务同时跑      │
        │                            │   │                                │
        │     ┌──────────────────┐   │   │   建容器 → checkout 代码         │
        │     │  OS 内核级沙箱     │   │   │   → setup 阶段【有网·有密钥】    │
        │     │  macOS: Seatbelt  │   │   │   → agent 阶段【断网·无密钥】    │
        │     │  Linux: bwrap+    │   │   │      (沙箱内自治打补丁/跑测试)    │
        │     │  seccomp+nnp      │   │   │   → 产出 diff → 开 PR            │
        │     │ (约束派生子进程)   │   │   │   态 ≤12h 缓存,加速下次冷启动    │
        │     └──────────────────┘   │   └────────────────────────────────┘
        │   headless: codex exec(CI)│
        └────────────────────────────┘
                        ▲                           ▲
                        │   MCP 双向(client ⇄ server) │
                ┌───────┴──────────┐        ┌─────────┴──────────┐
                │ 外部 MCP 工具/服务 │        │ 别的 agent 把 Codex │
                │ (作为 client 调)   │        │ 当 MCP server 调用  │
                └──────────────────┘        └────────────────────┘

        本地 ◀───────────  任务可迁移  ───────────▶ 云端
        最终产物(两路殊途同归):Git 提交 / Pull Request
```

> 灵魂有两点。其一,**一个 `core` 内核,两副躯壳**:本地形态把隔离责任交给「你机器上的 OS 内核沙箱」,云端形态交给「OpenAI 托管的独立容器」——agent 的*行为*同源,只是*执行环境与隔离机制*不同。其二,**「能动多大手脚」不是一个旋钮,而是两根正交的轴**(沙箱模式 × 审批策略);看懂这张图,就看懂了 Codex 区别于其它编码 agent 的地方。

## 5. 组件职责

逐个说明上图里每个关键部件**做什么 + 为什么需要它**。

- **共享内核(core)**:agent 的大脑与中枢——驱动行动循环、与模型交互、调度「打补丁 / 跑命令 / 调工具」、管理配置与会话历史。*为什么需要*:这是「本地与云端行为同源」的物理基础;两副躯壳只是给它换了执行环境与 UI,决策逻辑只此一份,避免两套实现各自漂移。
- **本地交互层(CLI 的全屏终端 UI / IDE 插件)**:把 agent 的思考、补丁、命令实时呈现给你,接收你的逐步审批;IDE 形态额外有 **Auto Context**(自动跟踪你正在看的文件,把注意力喂给 agent),并能与云端任务同项目同步。*为什么需要*:本地场景的价值在于**实时结对**——人就在循环里,能边看边拦。
- **headless 执行(`codex exec`)**:无 UI、无人值守地跑同一个内核,供 CI / 脚本调用。*为什么需要*:把 agent 嵌进自动化流水线,典型搭配是 `read-only + never`(只读、不打断),让它在 CI 里安全地跑分析/校验。
- **云端容器编排**:经 `chatgpt.com/codex` 绑定 GitHub,为每个委派任务拉起一个托管的独立隔离容器,跑完整生命周期(建容器 → checkout → setup → agent → diff → 开 PR),并维护 ≤12h 的环境缓存。*为什么需要*:**异步 + 并行**的物理载体;把任务从「你机器的资源与你的盯守」中彻底解耦出去。
- **OS 内核级沙箱执行器**:agent 要跑的命令的牢笼。macOS 用 Apple **Seatbelt**(`sandbox-exec`);Linux 用独立 helper 二进制——**bubblewrap** 搭只读根 + 选择性可写目录 + `unshare` 断网,进程内再上 `PR_SET_NO_NEW_PRIVS` + **seccomp** 网络过滤(Landlock 作为旧内核的 fallback)。*为什么需要*:把隔离做在**比应用更底层**的层,才能约束 agent 派生出的子进程——否则一条 `make` 拉起的脚本就能绕过应用自律。
- **MCP 客户端 / 自身可作 MCP server**:对外作为 client 接入外部工具与数据源;对内可把自己暴露成 MCP server,供别的 agent 编排调用。*为什么需要*:让 Codex 既能「用别人的能力」,又能「被别人当能力用」,在 agent 生态里双向可组合。
- **审批 / 执行策略层**:把「能动多大手脚」拆成两根正交的轴——`sandbox_mode`(隔离强度)× `approval_policy`(何时停下问人),并提供 `auto_review`(agent 执行前自审,给数据外泄/凭据探测/破坏性操作分级)。*为什么需要*:这是整个系统的**安全总阀**,也是第 8 节最值钱的那个决策的落点。

## 6. 关键数据流

**场景一:本地 agent 循环(同步结对,人在环里)**
```
你:「修掉登录接口的空指针,并补一个回归测试」
  ① 内核读代码库 + 就近的 AGENTS.md → 规划:先定位、再打补丁、再跑测试
  ② propose:agent 给出补丁 / 要跑的命令
  ③ approve? ── 看 approval_policy:
        untrusted  → 改状态前都问你
        on-request → 沙箱内自治,只在「越界」(出工作区/要联网)时才问
        never      → 沙箱约束内全自治,不打断
  ④ 在 OS 内核沙箱里执行(写文件限工作区内、命令受 seccomp/Seatbelt 约束)
  ⑤ 反馈:把 stdout / 测试结果 / 报错喂回内核 → 回到 ①,直到任务完成
  ⟲ 沙箱兜底:就算第 ③ 步放行,沙箱仍兜住「能改哪、能否联网」的物理边界
```

**场景二:委派任务到云端(异步,跑完开 PR)**
```
你在 CLI / IDE / chatgpt.com 上委派:「把这个仓库的 axios 升到 v1 并跑通测试」
  ① 编排器建一个托管的独立隔离容器(若有缓存,冷启动更快)
  ② checkout:拉取目标分支代码到容器工作区
  ③ setup 阶段【有网 · 有密钥】:装依赖、跑构建准备、需要的私网/凭据在此用掉
  ④ ——切断网络,移除 setup 用过的密钥——        ← 关键的「态」切换
  ⑤ agent 阶段【断网 · 无密钥】:在沙箱内自治改代码、跑测试、迭代
        (要联网的事必须在 ③ 预置好,否则 ⑤ 拿不到)
  ⑥ 产出 diff → 在绑定的 GitHub 仓库开一个 Pull Request
  ⑦ 你异步回来 review 这个 PR(此时人才重新进入循环)
  ※ 容器态 ≤12h 缓存,供同环境的下个任务复用,摊薄冷启动 setup 的重依赖成本
```

> 两场景的产物**殊途同归——都是 Git 提交 / PR**;差别只在「人何时在循环里」(本地全程 vs 云端只在收尾 review)与「隔离交给谁」(本地 OS 内核 vs 云端托管容器)。第 ④ 步那个**断网+抹密钥的「态」切换**,是云端形态对抗提示注入的结构性护栏,值得记牢。

## 7. 数据模型与存储选择

核心实体:`配置 / 策略`;`项目指令`;`工作区`;`会话 / 历史`;`容器环境态`;`密钥`;`最终产物(提交 / PR)`。

| 数据 | 存储 / 形态 | 为什么 |
|---|---|---|
| 全局配置 / 策略 / MCP 接入 | `config.toml`(共享,本地与云端同源) | 沙箱模式、审批策略、MCP 服务都是「跨形态一致」的设定,集中一处避免漂移 |
| 项目级指令 | `AGENTS.md`(就近生效,可逐目录覆盖) | 让 agent 懂这个仓库/这个子目录的约定;**就近**意味着越靠近改动点的指令越优先 |
| 代码工作区 | 容器内文件系统 / 本地仓库 | agent 真正读写的对象;`workspace-write` 下可改,但 `.git/.agents/.codex` 递归只读 |
| 会话 / 行动历史 | 内核会话状态 | 行动循环的连贯性靠它;长任务需 compaction 压缩续命 |
| 云端环境态 | 容器快照,**≤12h 缓存** | 摊薄「装依赖 / 构建准备」的冷启动成本,加速同环境下个任务 |
| 密钥 / 凭据 | **两阶段**:额外加密,仅 setup 阶段可用 | agent 阶段开始前移除——让「能拿到密钥的窗口」与「跑不可信生成代码的窗口」物理不重叠 |
| 最终产物 | **Git 提交 / Pull Request** | 工程任务的天然交付物;落到版本控制里天然可审计、可回滚、可 review |

> 注意一个设计取向:Codex 几乎不自建「业务数据库」,它的「存储」就是**代码库本身 + 一份共享配置 + 就近的项目指令**。这让它**无状态地依附于任何仓库**,产物又回流到 Git——版本控制顺便成了它的审计与回滚层。

## 8. 关键架构决策与权衡 ⭐

**(本模板最值钱的一节。)**

**决策 1:沙箱与审批「双轴解耦」——用正交两轴取代一维档位 ⭐(Codex 的灵魂)**
- 旧世界:用一维预设档位描述自治度(类似 `suggest / auto-edit / full-auto`)。直觉,但把两件本质不同的事**搅在了一起**——「agent 物理上能动多大范围」和「什么时候该停下来问人」。
- 新世界:拆成两根**正交**的轴。
  - `sandbox_mode`(隔离强度,物理边界):`read-only`(只读) / `workspace-write`(默认:可读、可在工作区内改与跑命令,但 `.git/.agents/.codex` 只读、默认断网) / `danger-full-access`(去掉边界,高风险)。
  - `approval_policy`(何时停下问人,流程边界):`untrusted`(改状态都问) / `on-request`(沙箱内自治、越界才问) / `never`(沙箱约束内全自治)。
- 正交组合即取代旧档位:`Auto = workspace-write + on-request`;`CI = read-only + never`;真·全自治 = `danger-full-access + never`。
- **取向**:**用两根正交轴。** 它让「物理能动范围」与「流程打扰程度」可以**独立**调——例如「物理上只读、但每一步都向我汇报」或「物理上能改工作区、但绝不打断我」都成了清晰的一格,而非含混的「中间档」。**代价**:心智负担更高(要同时理解两个概念),也更容易被新手混淆(见第 11 节)。这与姊妹篇 [Claude Code](../claude-code/README.md) 的权限模型是同一类问题的不同解法,值得对照读。

**决策 2:本地交互 vs 云端异步——共享一内核,隔离责任分别下放 ⭐**
- 选项 A:本地与云端各做一套 agent 逻辑。代价:两套实现行为漂移、双倍维护、bug 不一致。
- 选项 B:**一个 `core` 内核,两副执行躯壳**;隔离责任按形态就近下放——本地交给**你机器上的 OS 内核沙箱**,云端交给**OpenAI 托管的独立容器**。
- **取向**:**B。** agent 的*决策行为*只此一份(同源、好维护、可迁移),变的只是*执行环境与隔离机制*。本地换来「实时结对、人能逐步拦」,云端换来「异步、并行、跑完开 PR」。代价:两种形态对用户的「能力心智」并不完全等价(本地 CLI ≠ 云端,见第 11 节反模式),迁移任务时要理解环境差异。

**决策 3:OS 内核级沙箱,而非应用层自律 ⭐**
- 选项 A:应用自己「克制」,约定不碰危险操作。代价:**挡不住派生子进程**——agent 跑的一条命令再拉起脚本/子进程,应用层的自律对它们无效;遇到失控或恶意更是形同虚设。
- 选项 B:把隔离压到 **OS 内核层**——macOS Seatbelt、Linux bubblewrap + seccomp + `no_new_privs`(Landlock 作旧内核 fallback)。
- **取向**:**B。** 内核级机制天然覆盖「这个进程及其所有后代」,且 `no_new_privs` 杜绝提权逃逸。代价:平台相关(各 OS 机制不同、要分别适配),且 **Windows 无原生完整沙箱,需走 WSL2**。这正是质量属性表里「隔离必须比应用更底层」的落地。

**决策 4:Rust 重写,换长程稳定性 ⭐**
- 历史:早期是 Node/TS 实验版;后**全面 Rust 重写**为共享 `core`。
- 它在架构上换取了什么:**单二进制**(分发简单、`linux-sandbox` 这类 helper 可作独立二进制精确控权限)、**无 GC 停顿**(长会话不被周期性停顿打断)、**可预测的资源占用**(几十分钟的长任务不被运行时抖动/内存增长拖垮)。一句话——**用语言层的确定性换 agent 的长程稳定与连贯**。
- **取向**:**重写值得。** 代价是一次性的重写成本与生态迁移,但对「一个任务要稳跑很久」的 agent 是结构性收益。(正文不钉死具体模型号,默认用 OpenAI 当代旗舰编码模型。)

**决策 5:默认断网 + 缓存式 Web 搜索,对抗提示注入 ⭐**
- 风险:agent 会读到大量**外部内容**(网页、依赖、issue 文本),其中可能藏「去把密钥发出去 / 删库」的注入指令;一旦 agent 又有联网与工具权限,后果严重。
- 选项 A:放开实时联网。最灵活,但把外泄面和注入面同时拉满。
- 选项 B:**默认禁网**;要联网走**域名 allowlist 代理**(deny 优先、私网默认禁、带 DNS rebinding 防护、Unix socket allowlist);**Web 搜索默认走 OpenAI 维护的缓存索引而非实时抓取**;再加 `auto_review` 让 agent 执行前自审。
- **取向**:**B。** 「默认断网」是一条强先验——**把『能联网』从默认权利降级为需显式申请的特权**;缓存式搜索则让「获取知识」与「打开实时外联通道」解耦,大幅压注入面。代价:固有摩擦(agent 阶段要联网的事必须在 setup 预置,见第 9 节)。

## 9. 规模化与瓶颈

- **第一个瓶颈:长程任务的上下文与连贯性。** 工程任务跨度大,会话一长,模型就开始重复、偏题、忘了最初目标——这才是长程任务真正的天花板。→ 破解:**compaction**(把历史压缩成摘要续命);但 compaction 不是银弹,压缩仍可能丢关键细节,本质是在「记多久」与「记多清」之间取舍。
- **第二个瓶颈:云端并行受容器供给与冷启动制约。** 并行度上限取决于能拉起多少托管容器;每个容器的 setup(装重依赖、构建准备)是冷启动大头。→ 破解:**≤12h 环境缓存**复用容器态,摊薄重依赖成本;但缓存有寿命,且首次/缓存失效时仍要吃完整冷启动。
- **第三个瓶颈:断网的固有摩擦。** agent 阶段默认离线,任何「跑时才发现要联网」的需求都会卡住。→ 破解:把网络需求**前移到 setup 阶段**预置(在有网窗口装好/抓好),或对特定域名显式放行——安全与便利在此对冲。
- **第四个瓶颈:同步流里,审批人是天花板。** `untrusted` / `on-request` 下,人审批的速度决定 agent 的吞吐;人一离开,循环就停。→ 破解:把可信、可逆的任务调到更高自治(`on-request → never`)或丢上云端异步跑;但**调高自治 = 抬高风险**,这是绕不开的对冲。

## 10. 安全与合规要点

这是 Codex 架构里被着墨最重的一块——因为它的 agent 真的能改代码、跑命令、碰网络。

- 🔴 **沙箱是内核强制的物理边界**:macOS **Seatbelt** / Linux **bubblewrap + seccomp + `no_new_privs`**(Landlock 作旧内核 fallback)。关键在于它**约束 agent 派生的所有子进程**,且 `no_new_privs` 封死提权逃逸——隔离不靠模型自觉。
- 🔴 **网络默认禁**:要开走**域名 allowlist 代理**——deny 优先、私网默认禁、带 **DNS rebinding 防护**、Unix socket 也走 allowlist。**Web 搜索默认用缓存索引而非实时抓取**,从源头压低注入与外泄。
- 🔴 **审批三级 + 自审**:`approval_policy` 三档(`untrusted / on-request / never`)给人留刹车;`auto_review` 让 agent 在执行前自审,对**数据外泄 / 凭据探测 / 破坏性操作**分级预警。
- 🔴 **密钥云端两阶段**:secrets 额外加密,**仅 setup 阶段可用**;**agent 阶段开始前移除**,该阶段默认离线。等于让「持有密钥」与「运行不可信生成代码」两个窗口物理不重叠——把外泄面压到最小。
- 🔴 **`workspace-write` 下 `.git/`、`.agents/`、`.codex/` 递归只读**:防 agent 篡改版本历史、改掉自身配置、动 agent 元数据(尤其防它「解开给自己上的锁」)。
- 把一切**外部内容(网页、依赖、issue/PR 文本、工具返回)当不可信输入**——这是所有有工具权限的 agent 的通则,Codex 用「默认断网 + 缓存搜索 + 自审 + 沙箱」多层叠起来兜它。详见 [质量属性与取舍](../../tutorial/06-质量属性与取舍.md) 对安全与可控的展开。

## 11. 常见误区 / 反模式

- ❌ **以为非 `danger-full-access` 就「不好用」** → ✅ 默认的 `workspace-write` 足以覆盖绝大多数编码任务(读、在工作区内改与跑命令);`danger-full-access` 是去掉物理边界的高风险档,只在极少数确需突破工作区/联网且你完全清楚后果时才用。
- ❌ **混淆沙箱模式与审批策略**(把它们当成一回事或一个旋钮的两端)→ ✅ 它们**正交**:`sandbox_mode` 管「物理上能动多大范围」,`approval_policy` 管「什么时候停下问人」。可以「物理只读但每步都问」,也可以「能改工作区但绝不打断」。
- ❌ **以为云端 agent 阶段能联网、能用密钥** → ✅ agent 阶段**默认断网且密钥已被移除**;一切联网/取密钥的事必须在 **setup 阶段**(有网有密钥的窗口)预置好。
- ❌ **把 AGENTS.md 当普通 README,随手放在仓库根就完事** → ✅ 它是**就近生效**的 agent 指令——越靠近改动点(子目录)的 AGENTS.md 越优先;它直接塑造 agent 行为,不是给人看的说明。
- ❌ **指望在原生 Windows 上拿到完整沙箱** → ✅ 完整隔离走 **WSL2**;原生 Windows 路径上沙箱能力受限,别把它当等价物。
- ❌ **把本地 CLI 当云端的等价物**(以为两者能力完全一样)→ ✅ 内核同源,但**执行环境与隔离机制不同**:本地是同步结对 + OS 内核沙箱,云端是异步并行 + 托管容器、且有断网/抹密钥的「态」切换。理解差异再迁移任务。

## 12. 演进路线:MVP → 成长期 → 成熟期

架构是会长大的;agent 的「自治度」也该随信任与流程成熟度逐步放开。

| 阶段 | 规模 / 信任度 | 怎么设置(具体) | 此时该操心什么 |
|---|---|---|---|
| **MVP** | 个人 / 试探 | 本地 CL/ IDE,`read-only`(纯看)或 `workspace-write + on-request`(默认 Auto,逐步审批);先在小任务上建立信任 | 先验证「这个 agent 改得对不对」,人全程在环里盯 |
| **成长期** | 团队 / 半信任 | 把可信可逆的任务调到 `workspace-write` 自治、减少打断;`auto_review` 常开;CI 里用 `codex exec` + `read-only + never` 做无人值守校验;规整 AGENTS.md 让行为可预测 | 任务成功率、可控性、审批人不再是瓶颈 |
| **成熟期** | 组织 / 高吞吐 | 云端**并行委派**(多容器、缓存复用),跑完开 PR 异步 review;为安全任务保留高自治、危险任务收紧审批;CI 全自治流水线 | 并行吞吐、安全边界、容器供给与缓存成本、组织级审计 |

## 13. 可复用要点

- 💡 **安全边界用「正交两轴」比「一维档位」更清晰。** 把「物理能动范围」与「流程打扰程度」拆成独立两轴(沙箱 × 审批),任何需要描述「自治度/权限」的系统都可借鉴——一维档位看似简单,实则把不同维度搅在一起,边界反而模糊。
- 💡 **隔离要交给「比应用更底层」的层。** 应用自律挡不住派生子进程与恶意;把隔离压到 OS 内核(或托管容器)层,才能覆盖「这个进程及其所有后代」。这是任何「执行不可信代码」的系统的通则,呼应 [AI Agent 平台](../ai-agent-platform/README.md) 的「工具一律沙箱执行」。
- 💡 **「默认断网」是对抗注入/外泄的强先验。** 把「能联网」从默认权利降级为需显式申请的特权,并让「获取知识」与「打开外联通道」解耦(缓存式搜索)——大幅压低攻击面。
- 💡 **同一内核长出多副执行躯壳,行为同源、隔离分治。** 决策逻辑只此一份(好维护、可迁移),把「执行环境与隔离机制」按场景就近下放——这是「一套大脑、多种部署形态」的通用范式。
- 💡 **让「持有凭据」与「运行不可信代码」的时间窗物理不重叠。** 密钥两阶段(setup 可用、agent 阶段前移除)是个可迁移的安全模式:最小化敏感物的暴露窗口,胜过事后审计。

## 🎯 随堂检验

<Quiz
  question="Codex 用什么来描述「这个 agent 能动多大手脚」?"
  :options="['一维档位,从建议到全自动', '沙箱模式与审批策略两根正交的轴', '只看模型本身的能力强弱']"
  :answer="1"
  explanation="Codex 把它拆成正交两轴:sandbox_mode 管物理能动范围,approval_policy 管何时停下问人。正交组合取代了旧的一维预设档位——更清晰,但心智负担更高。"
/>

<Quiz
  question="把任务委派到 Codex 云端时,agent 阶段的网络与密钥状态是?"
  :options="['全程有网有密钥,最方便', 'agent 阶段默认断网且密钥已被移除,联网/取密钥要在 setup 阶段预置', '只要审批通过就能联网']"
  :answer="1"
  explanation="云端是两阶段:setup 阶段有网有密钥用来装依赖;切换到 agent 阶段时断网、抹掉密钥,让跑不可信生成代码的窗口与持有凭据的窗口物理不重叠,压低提示注入的外泄面。"
/>

---

## 14. 参考原型与延伸阅读

> 本模板基于 OpenAI Codex 的**官方开源仓库**与**官方文档**整理。想深入,直接读 `codex-rs` 源码,或对照官方文档逐项核对沙箱与云端机制。

**🔧 开源原型(可直接读代码):**
- [openai/codex](https://github.com/openai/codex) — Codex 的官方仓库(`codex-rs`,Rust 重写):`core` 内核、`tui` 全屏终端、`exec` headless、`cli` 聚合入口、`linux-sandbox` 独立 helper 二进制都在此,是本模板「共享内核 + 双形态 + 内核级沙箱」最直接的代码印证。

**📖 官方文档:**
- [Codex CLI 文档](https://developers.openai.com/codex/cli) — 本地形态:终端结对、配置、`codex exec` headless 用法。
- [Codex Cloud](https://developers.openai.com/codex/cloud) — 云端形态:异步任务、独立容器、绑 GitHub 开 PR。
- [云端环境生命周期](https://developers.openai.com/codex/cloud/environments) — 容器 / checkout / setup & maintenance / ≤12h 缓存 / 两阶段网络与密钥的权威说明。
- [审批与安全](https://developers.openai.com/codex/agent-approvals-security) — 审批三级、`auto_review` 自审、密钥两阶段。
- [沙箱概念](https://developers.openai.com/codex/concepts/sandboxing) — Seatbelt / bubblewrap / WSL2、三种沙箱模式、以及「沙箱与审批解耦」的双轴模型。
- [AGENTS.md 开放标准](https://agents.md/) — 就近生效的项目级 agent 指令规范。

**🔗 同仓库延伸:**
- 姊妹篇 [Claude Code](../claude-code/README.md) — 另一种编码 agent 的解法,对照看权限与执行模型的异同。
- [AI Agent / 工作流平台](../ai-agent-platform/README.md) — Codex 所属的更大谱系:行动循环、工具、记忆、可控性。
- [AI 对话产品](../ai-chat-product/README.md) — 从「你问我答」到「自主行动」的起点对照。
- [十大核心架构模式](../../tutorial/04-十大核心架构模式.md)、[质量属性与取舍](../../tutorial/06-质量属性与取舍.md) — 沙箱、隔离、可控背后的通用模式与质量取舍。

---

> 📌 一句话记住 Codex:**同一内核两副躯壳——本地实时结对、云端异步开 PR;它用「沙箱 × 审批」两根正交的轴,而非一维档位,在『自治执行』与『可控』之间精确落子,并把隔离交给比应用更底层的 OS 内核与托管容器。**