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 平台是同一个谱系——都是「规划 → 调工具 → 观察 → 再决策」的行动循环——但 Codex 把「工具」收窄到软件工程这一垂直域:读写代码库、打补丁、跑命令、跑测试、提交。它和姊妹篇 Claude Code 解决的是同一类问题,但 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 的权限模型是同一类问题的不同解法,值得对照读。

决策 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 用「默认断网 + 缓存搜索 + 自审 + 沙箱」多层叠起来兜它。详见质量属性与取舍对安全与可控的展开。

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 平台的「工具一律沙箱执行」。
💡 「默认断网」是对抗注入/外泄的强先验。 把「能联网」从默认权利降级为需显式申请的特权,并让「获取知识」与「打开外联通道」解耦(缓存式搜索)——大幅压低攻击面。
💡 同一内核长出多副执行躯壳,行为同源、隔离分治。 决策逻辑只此一份(好维护、可迁移),把「执行环境与隔离机制」按场景就近下放——这是「一套大脑、多种部署形态」的通用范式。
💡 让「持有凭据」与「运行不可信代码」的时间窗物理不重叠。 密钥两阶段(setup 可用、agent 阶段前移除)是个可迁移的安全模式:最小化敏感物的暴露窗口,胜过事后审计。

🎯 随堂检验

🤔Codex 用什么来描述「这个 agent 能动多大手脚」?

A一维档位,从建议到全自动
B沙箱模式与审批策略两根正交的轴
C只看模型本身的能力强弱

🤔把任务委派到 Codex 云端时,agent 阶段的网络与密钥状态是?

A全程有网有密钥,最方便
Bagent 阶段默认断网且密钥已被移除,联网/取密钥要在 setup 阶段预置
C只要审批通过就能联网

14. 参考原型与延伸阅读

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

🔧 开源原型(可直接读代码):

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

📖 官方文档:

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

🔗 同仓库延伸:

姊妹篇 Claude Code — 另一种编码 agent 的解法,对照看权限与执行模型的异同。
AI Agent / 工作流平台 — Codex 所属的更大谱系:行动循环、工具、记忆、可控性。
AI 对话产品 — 从「你问我答」到「自主行动」的起点对照。
十大核心架构模式、质量属性与取舍 — 沙箱、隔离、可控背后的通用模式与质量取舍。

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

OpenAI Codex 架构模板 ​

1. 一句话定位 ​

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

3. 核心需求与约束 ​

4. 架构全景图 ​

5. 组件职责 ​

6. 关键数据流 ​

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

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

9. 规模化与瓶颈 ​

10. 安全与合规要点 ​

11. 常见误区 / 反模式 ​

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

13. 可复用要点 ​

🎯 随堂检验 ​

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

💬 评论