20.02拆解更新于 2026年9月17日

Codex

沙箱、工作区、云端长任务与验证闭环。

20.02 · 课时讲解

产品拆解：Codex

把“沙箱加审批策略”做成 Agent 的第一原则，最后交付一个可审阅的 diff 或 PR。

1 / 13

一句话理解：Codex 把“沙箱 + 审批策略”做成了 Agent 的第一原则——本地在工作区边界内自由行动、越界才请求批准；云端在隔离容器里跑长任务，默认断网、密钥不进入 Agent 阶段，最后交付一个可审阅的 diff 或 PR。

Codex 是 OpenAI 的 Coding Agent。和上一课的 Claude Code 相比，它们要完成的 Job 几乎相同，但在 执行环境、安全边界与交付方式 上做出了不少不同的选择。把两者放在一起对比，是理解“同一类 Agent 有多种合理设计”的最好方式。

先说明产品现状（截至 2026 年 9 月，以 OpenAI 官方文档与更新日志为准）：

  • Codex 仍是独立的产品线，有开源的 CLI（仓库 openai/codex，Apache-2.0 许可）、IDE 插件、云端任务（chatgpt.com/codex）以及 GitHub、Slack 等集成。
  • 2026 年 7 月 9 日的更新日志显示，Codex 桌面应用并入了新的 ChatGPT 桌面应用，在同一个应用里与 Chat、Work 并列使用。
  • 原 developers.openai.com/codex 文档地址现在重定向到 learn.chatgpt.com/docs，Codex 与 ChatGPT Work 共用一套文档。

把 Codex 的入口、本地与云端两种执行形态和交付方式放进一张图：

Codex 架构图：多个入口，本地的沙箱与审批策略，云端的隔离容器流程，以及以 diff 为中心的交付与审查 入口 CLI 开源 · Apache-2.0 IDE 插件 ChatGPT 桌面应用 与 Chat、Work 并列 网页云端任务 chatgpt.com/codex GitHub · Linear Slack 等集成 GitLab 集成 Beta 本地：CLI · IDE · 桌面应用 AGENTS.md 分层上下文 全局 → Git 根目录 → 当前目录，默认最多 32 KiB 沙箱模式 × 审批策略（两个独立控制） 沙箱模式 read-only workspace-write danger-full-access 审批策略 on-request never 默认组合：workspace-write + on-request Rules：Starlark 编写的 .rules prefix_rule()：allow / prompt / forbidden，取最严格 越界审阅者：user 或 auto_review 连续 3 次或累计 10 次拒绝即中断回合 云端：隔离容器中的长任务 创建容器并检出仓库 默认 universal 镜像 运行 setup 脚本 可联网 · Secrets 可用 应用网络策略 默认断网 · 移除 Secrets Agent 循环 编辑、检查、验证 展示结果与 diff 审阅、追问或创建 PR 容器状态最多缓存 12 小时 交付与审查 diff 优先 diff 呈现 本地或云端产出 人审阅后创建 PR Git 负责回滚 独立审查 /review · @codex review 降噪输出 GitHub 默认只标 P0 / P1
图 1 · Codex 架构：本地用“沙箱 + 审批策略”划边界，云端把联网与密钥留在准备阶段

用八个问题拆解

1. 它完成什么 Job？

在代码仓库中完成开发任务：写功能、修 Bug、回答代码库问题、审查代码。与 Claude Code 相比，Codex 的产品叙事更强调两种形态：

  • 本地协作：在 CLI、IDE 或桌面应用里与开发者同步工作。
  • 云端委派：把任务交给云端环境并行运行，完成后审阅 diff、追问或直接开 PR。

另一个被做成独立 Job 的是 代码审查：在 CLI 里用 /review 选择审查范围（对比基础分支、未提交变更、特定提交或自定义标准），或在 GitHub PR 里评论 @codex review，也可以开启对每个新 PR 自动审查。

2. 它能调用哪些工具？

  • 本地：读写文件、在沙箱中执行命令、使用 Git；可以通过 MCP 接入外部工具，通过 Skills 复用工作方法，也支持配置自定义 Subagent。
  • 云端：在容器中检出仓库、运行安装脚本、编辑代码和执行验证命令，完成后产出 diff，可以直接创建 PR。
  • 入口集成：云端任务可以从网页、GitHub（PR 与 Issue）、Linear、Slack 发起，GitLab 集成处于 Beta。

3. 它拿得到什么上下文？

核心上下文载体是 AGENTS.md，官方文档描述的发现规则非常清晰：

AGENTS.md 的发现与合并规则：全局一份，项目从 Git 根目录到当前目录逐层查找，从根向下拼接，默认最多 32 KiB 全局 ~/.codex/AGENTS.override.md 或 ~/.codex/AGENTS.md 取先存在的一个 项目 · Git 根目录 依次查找 override → AGENTS.md → 备用文件名 项目 · 中间各层目录 每一层按同样顺序查找 项目 · 当前目录 最靠后拼接，优先级最高 从根向下拼接 越靠近当前目录， 越靠后、优先级越高 每一层的查找顺序 AGENTS.override.md → AGENTS.md → 备用文件名 合并后默认最多 32 KiB（project_doc_max_bytes）
图 2 · AGENTS.md 分层：根目录写全局规范，子目录写本服务的命令与注意事项

这个设计让大型仓库可以“分层写规则”：根目录写全局规范，子服务目录写本服务的测试命令与注意事项。在云端任务中，Agent 会参考 AGENTS.md 找到项目的 Lint 与测试命令；在 GitHub 审查中，AGENTS.md 里的 ## Code Review Rules 小节会被用作审查规则。

4. 它在哪里执行？

本地执行 由两个独立的控制共同决定：

控制 选项 含义
沙箱模式 read-only 可以查看文件，未经批准不能编辑或运行命令
workspace-write 可以读文件、在工作区内编辑、运行常规本地命令
danger-full-access 移除文件系统与网络边界
审批策略 on-request 默认在沙箱内工作，需要越界时请求批准
never 不停下来请求批准

官方文档说明，本地默认组合是 workspace-write + on-request。沙箱由操作系统机制实现：macOS 使用 Seatbelt，Linux 与 WSL2 使用 bubblewrap，Windows 有原生沙箱实现。

云端执行 的流程是：

Codex 云端任务流程：准备阶段可联网并使用 Secrets，自主阶段默认断网且拿不到 Secrets 创建容器并检出仓库 默认 universal 镜像 运行 setup 脚本 此阶段可联网，用于安装依赖 Secrets 只在此阶段可用 应用网络策略 Agent 阶段默认关闭互联网 Secrets 被移除，环境变量全程可用 Agent 循环 编辑代码、运行检查、验证 展示结果与 diff 用户审阅、追问或创建 PR 准备阶段 可联网 有 Secrets 自主阶段 默认断网 无 Secrets 容器状态最多缓存 12 小时；恢复缓存时可运行可选的 maintenance 脚本
图 3 · 云端流程：把“需要网络和密钥的准备”与“模型自主行动”分成两个阶段

容器状态最多缓存 12 小时，恢复缓存容器时可以运行可选的 maintenance 脚本更新依赖。

这个流程里有一个非常值得学习的安全设计：把“需要网络和密钥的准备阶段”与“模型自主行动的阶段”分开。模型在行动时既拿不到密钥，也默认无法联网，从根本上降低了被注入后外泄数据的可能。

5. 它如何决定下一步？

由模型在 Agent Loop 中动态决定读哪些文件、改哪里、跑什么命令。与之配合的是 规则（Rules）：用 Starlark 编写 .rules 文件，通过 prefix_rule() 按命令前缀匹配，决定沙箱外的命令是 allow（直接运行）、prompt（每次询问）还是 forbidden（直接拒绝）。多条规则同时匹配时，取最严格的结果：forbidden 高于 prompt 高于 allow。

规则支持写 match 与 not_match 测试样例，用来验证规则本身是否写对——这是“把策略当代码管理”的好例子。

6. 它如何验证结果？

  • 运行项目检查：云端任务参考 AGENTS.md 中的 Lint 与测试命令验证修改。
  • 可审阅的交付物：结果以 diff 形式展示，由人决定是否创建 PR，而不是直接合入主分支。
  • 独立审查环节：/review 在不改动工作区的前提下给出按优先级排列的问题；GitHub 审查默认只标记 P0 与 P1 级别的问题，避免噪音淹没重要风险。

把“写代码的 Agent”和“审代码的 Agent”分成两个环节，相当于在流程里加入了一次外部验证（参见「自我检查与外部验证」）。

7. 什么时候需要人确认？

默认在沙箱边界内自主行动，越界才需要确认。越界请求可以交给两种审阅者，由 approvals_reviewer 配置：

  • user：由用户直接批准。
  • auto_review：交给自动审阅。官方文档说明，审阅者本身是一个 Codex Agent，职责比主 Agent 更窄——只判断某个越界动作是否应该执行。它审查的范围包括请求提升沙箱权限的命令、被策略拦截的网络请求、允许目录以外的文件编辑、需要批准的 MCP 或应用工具调用等；沙箱内的常规动作不会进入自动审阅。

自动审阅有两个值得注意的保护：被拒绝后，主 Agent 不应通过变通方式达成同样的目的；连续 3 次或在滚动窗口内累计 10 次被拒绝时，会中断当前回合。官方文档也坦承，自动审阅“不是确定性的安全保证”。

8. 失败如何恢复？

  • 隔离即恢复：云端任务在独立容器中运行，失败不会影响本地或主分支；不满意可以追问修改或直接丢弃。
  • diff 优先：所有变更先以 diff 呈现，人审阅后才进入 PR 与合并流程，Git 负责回滚。
  • 熔断：自动审阅多次拒绝后中断回合，把控制权交还给人，而不是无限尝试。

与 Claude Code 的对比

维度 Claude Code Codex
持久指令 CLAUDE.md + 自动记忆 AGENTS.md 分层合并（含 override 文件）
本地安全模型 多种权限模式 + allow/ask/deny 规则 + Bash 沙箱 + Hooks 沙箱模式 × 审批策略 + Starlark 规则
自动放行的判断者 auto 模式下的后台分类器 auto_review：一个职责更窄的审阅 Agent
云端执行 Anthropic 托管虚拟机或自托管环境 容器 + setup 脚本；Agent 阶段默认断网、无 Secrets
审查 可通过 GitHub Actions 等集成审查 PR /review 与 @codex review，GitHub 中默认只标 P0/P1

两者没有绝对优劣。更有价值的问题是：它们都在用“边界 + 越界审批”替代“每一步都问人”，只是边界的划法和审批者的实现不同。

可借鉴的设计决策

设计决策 Codex 的做法 迁移到业务 Agent
行动边界与审批策略分离 沙箱模式定义“能碰什么”，审批策略定义“越界时怎么办” 数据范围与动作审批分两层配置，分别调整
准备阶段与自主阶段分离 联网与密钥只在 setup 阶段可用 凭据由确定性层使用，模型推理阶段拿不到凭据
策略可测试 规则文件自带 match/not_match 样例 审批规则、风险分级规则也要有测试用例
审阅者职责单一 自动审阅 Agent 只判断越界动作是否应执行 用专门的校验器审查高风险动作，而不是让执行 Agent 自评
降噪的审查输出 GitHub 审查只标 P0/P1 给人看的风险提示要分级，只把真正需要判断的推给人
交付可审阅产物 diff → 人审阅 → PR 业务写入先生成“变更预览”，确认后执行

常见误区

  • “云端 Agent 更危险，因为不在我眼前。” 设计得当的云端环境往往比本地更安全：隔离容器、默认断网、密钥不进入 Agent 阶段。风险取决于边界设计，而不是位置。
  • “自动审阅等于安全。” 官方文档明确它不是确定性保证。高风险动作仍需要程序规则与人工兜底。
  • “Codex 已经并入 ChatGPT，所以不再是独立产品。” 并入的是桌面应用形态；CLI、云端任务、IDE 插件与各类集成仍然存在，官方文档也仍以 Codex 为名组织这些能力。

设计要点

  • 先定义行动边界，再定义越界时由谁、如何批准。
  • 让模型自主行动的阶段拿不到长期凭据。
  • 把审批与安全策略写成可测试、可版本化的配置。
  • 执行与审查分成两个角色或两个环节。
  • 交付物默认是“待审阅的变更”，而不是“已生效的变更”。

练习

用 45 分钟完成一次对比实验（可以只阅读文档，也可以实际使用）：

  1. 为同一个小仓库分别写一份 CLAUDE.md 和一份分层 AGENTS.md（根目录一份，子目录一份），比较两者的组织方式。
  2. 为“禁止强制推送、允许运行测试、其余 Git 写操作需询问”分别写出 Claude Code 的权限规则思路和 Codex 的 .rules 思路。
  3. 为「订单售后处理 Agent」借鉴 Codex 云端流程，设计“准备阶段”和“自主阶段”分别能拿到哪些凭据与网络权限。

延伸阅读

下一步

Coding Agent 有天然的反馈闭环。下一课「通用工作 Agent」会看离开代码仓库之后，ChatGPT Work、Manus 这类产品如何在搜索、浏览器与文件的世界里建立控制与验证。

试试：上下文、MCP、沙箱、Prompt 注入、外链