假设 CI 报了一条测试失败：一个金额计算函数 round_amount(2.005) 应该返回 2.01，实际返回了 2.00，这是典型的浮点精度加银行家舍入问题。把这个任务交给 Codex 后，它并不是”一次性写出一段修复代码”就完事。它需要读相关代码和测试，判断改动范围，在受限环境里运行命令，看结果，如果没修好就再来一轮，最后把补丁和验证信息交回给人。

这篇文章不去猜 Codex 某个内部函数叫什么名字，而是沿着这条任务链路，把一个编码 Agent 的执行架构讲清楚：模型到底”怎样提出下一步”，工具怎样在沙箱里执行，什么情况需要审批，以及为什么”代码已经改完”不等于”任务已经完成”。我希望一个刚接触 Agent 的人读完，不只是记住几个名词，而是能自己装上 Codex、看懂它每一步在干什么、并把安全边界配对。

先说明本文的证据边界

Codex 的产品能力会持续迭代。本文把三类信息分开处理，避免把”我的推测”讲成”它的实现”：

这样写会少一些”内部揭秘”的味道，但更适合长期放在博客上。Codex 的界面、配置项和默认值都会变，真正值得学的是它处理”执行边界”的思路，以及这套思路落到命令行时长什么样。文中出现的 CLI 参数与配置项，均以 OpenAI 面向开发者的公开文档为准。

初学者最该先建立的一个概念：模型不会”自己动手”

这是最容易被跳过、却最关键的一点。很多人以为 Codex 是”一个会自己敲命令、自己改文件的 AI”。更准确的理解是：模型只负责’说’，运行环境负责’做’。

一次任务被拆成很多个”回合”。每一回合里：

1. 模型看到当前上下文（任务描述、读过的文件、上一步的命令输出），然后输出一个结构化的意图。这个意图不是自然语言的”我建议你去跑个测试”，而是一个机器能直接执行的动作，通常是两类之一：
   • 运行一条 shell 命令（比如 pytest tests/test_billing.py -x）；
   • 对文件打一个补丁（Codex 用一种类似 diff 的 apply_patch 格式描述”在哪个文件、把哪几行改成什么”）。
2. Codex 的运行环境（这一层社区常叫 harness 或 runtime）接住这个意图，在沙箱里真正执行它，然后把结果，命令的标准输出、标准错误、退出码，或者补丁是否应用成功，当作”观察”回传给模型。
3. 模型读到观察结果，进入下一回合，再提出下一个意图。

这样一轮轮转下去，直到任务完成或需要人介入。用金额计算 Bug 举一次真实回合的样子，会比任何抽象描述都清楚：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

── 第 1 回合 ────────────────────────────
模型的意图（运行命令）：
  cat -n src/billing.py | sed -n '40,70p'

运行环境的观察（回传）：
  42  def round_amount(x: float) -> float:
  43      return round(x, 2)   # ← 用了内置 round，遇到 2.005 会因浮点表示丢精度

── 第 2 回合 ────────────────────────────
模型的意图（运行命令，先复现失败）：
  pytest tests/test_billing.py::test_round_half_even -x

运行环境的观察（回传）：
  exit_code: 1
  FAILED tests/test_billing.py::test_round_half_even
  assert round_amount(2.005) == 2.01
  实际返回 2.0

── 第 3 回合 ────────────────────────────
模型的意图（打补丁）：
  apply_patch → src/billing.py
    - return round(x, 2)
    + from decimal import Decimal, ROUND_HALF_EVEN
    + return float(Decimal(str(x)).quantize(Decimal("0.01"), ROUND_HALF_EVEN))

运行环境的观察（回传）：
  Patch applied: src/billing.py

── 第 4 回合 ────────────────────────────
模型的意图（重新验证）：
  pytest tests/test_billing.py -q

运行环境的观察（回传）：
  exit_code: 0
  3 passed

上面的命令和补丁是为了讲清”回合制”而构造的示意，不是 Codex 真实输出的逐字记录；但”模型出意图 → 环境执行 → 结果回传”这个循环结构，是任何工具型 Agent 都成立的。

看懂这个循环，后面的所有设计就都有了落点：沙箱约束的是第 2 步里”环境到底允许执行什么”，审批决定的是第 2 步之前”哪些意图要先问过人”，上下文管理管的是第 1 步里”模型每回合能看到多少信息”，验证则是判断”最后一回合的观察结果，能不能算任务完成”。

把这条任务链路画成闭环

把上面逐回合的过程收拢一下，就是下面这张图。它比”模型一次性生成代码”更接近真实使用体验：

  flowchart TD
  A["任务：修复边界输入的测试失败"] --> B["理解任务与代码<br/>读取相关文件、测试与项目约定"]
  B --> C["规划下一步<br/>定位原因，决定要读、改或运行什么"]
  C --> D{"这个意图在已授权边界内？"}
  D -->|是| E["受限执行<br/>在工作区沙箱中读取、编辑或运行命令"]
  D -->|否| F["请求审批或提升权限"]
  F --> E
  E --> G["观察结果<br/>测试输出、命令退出码、代码 diff"]
  G --> H{"验证通过？"}
  H -->|否| B
  H -->|是| I["交付补丁与验证说明"]
  

官方将 Codex 描述为可在本地或云端工作、读取和修改代码、运行命令，并在需要时向用户请求批准的编码 Agent。(Codex 产品更新) 图里的分叉 D 就是”审批”介入的地方，H 就是”验证”介入的地方。它们不是可有可无的装饰，而是让这个循环”可治理”的两道闸。

一次修 Bug 时，各环节分别做什么

把循环里的角色拆开对照，能看清哪一层负责哪件事、以及最容易在哪一层出问题：

我认为这里最重要的一条，是把”生成”和”验证”分成两件事看。模型可以提出一个看着很合理的修复，但只有测试、构建或可重复的检查结果，才能说明这个修复在当前项目里真的成立。上面回合走查里，第 2 回合先复现失败、第 4 回合再确认通过，正是这条原则的体现：没有第 2 回合的”红”，第 4 回合的”绿”就说明不了任何问题。

沙箱到底是什么：为什么它比”嘱咐模型别乱来”可靠

对编码 Agent 来说，最大的风险通常不在于它给出了错误解释，而在于它能不能不受限制地读敏感文件、改工作区外的数据、或者往外发网络请求。一个自然的念头是”那就在提示词里写清楚别碰这些”，但提示词是”建议”，模型可能误解、可能被恶意输入绕过。真正可靠的做法是让操作系统来兜底：哪怕模型执意要删你的主目录，系统层面根本不放行。

这就是沙箱。Codex 的沙箱不是它自己发明的一套拦截逻辑，而是复用了操作系统本来就有的隔离机制：

• macOS 上用 Seatbelt（sandbox-exec 背后的机制）。它可以给一个进程定义一份”策略”，规定这个进程能读哪些路径、能写哪些路径、能不能联网。Codex 启动命令时，把命令包在这样一份策略里，于是即便命令本身是 rm -rf /，系统也只会允许它在被授权的目录里动手。
• Linux 上用 Landlock 加 seccomp。Landlock 负责限制文件系统访问（哪些目录可读、可写），seccomp 负责过滤系统调用（比如禁掉发起网络连接的那类调用）。两者叠加，效果和 macOS 上的 Seatbelt 类似。

官方对此的表述是：sandbox_mode 决定 Codex “技术上能做什么”，而这一层由操作系统强制执行，macOS 用 Apple Seatbelt，Linux 用 Landlock 加 seccomp；默认配置会限制网络访问和工作区外的写入。(Codex Sandbox 文档、GPT-5-Codex 系统卡)

把它落到金额计算 Bug 上，几层控制各解决一个问题：

要强调的是，这不是”沙箱一定比提示词安全”的口号。沙箱解决的是”进程能不能执行”，审批解决的是”谁来授权”，项目规则解决的是”应该怎么做”。它们覆盖的是不同问题，不能互相替代：沙箱拦不住一个”逻辑上错误但权限上合法”的改动，那得靠验证；提示词也永远拦不住一个越权的系统调用，那得靠沙箱。

三档审批模式：从”什么都问”到”什么都不问”

沙箱定义”技术上能做什么”，审批定义”什么时候停下来问你”。这两个旋钮组合起来，就是你日常使用 Codex 时最该搞清楚的东西。Codex CLI 把常见组合封装成了几档预设，官方文档里的描述如下：(Codex 审批与安全)

这些预设背后是两个可以单独控制的参数。如果你想更细地调，可以直接用命令行标志：

• --ask-for-approval（审批策略）：on-request（默认，模型觉得需要时才问）、never（从不问，配合只读或全放开使用）、untrusted（只自动执行已知安全的操作，其余都问）。
• --sandbox（沙箱模式）：read-only（只读）、workspace-write（默认，可写工作区）、danger-full-access（完全放开，别名 --yolo）。

所以官方说的”Auto 预设”，展开就是这一条命令：

1

codex --sandbox workspace-write --ask-for-approval on-request

而”只读、不打扰”（比如放进 CI 里让它做只读审查）就是：

1

codex --sandbox read-only --ask-for-approval never

初学者第一次用，我的建议是老老实实从默认的 Auto 开始，先观察它在什么节点会停下来问你。那些节点，往往正是它自己判断”这一步越界了”的地方，比你凭空想象安全边界更有教育意义。

两个你一上手就会碰的文件：config.toml 与 AGENTS.md

预设和命令行标志适合临时切换，但你不会想每次开会话都敲一长串参数。Codex 的持久配置放在 ~/.codex/config.toml，把你常用的那档预设固定下来：(Codex 配置参考)

1
2
3

# ~/.codex/config.toml
approval_policy = "on-request"
sandbox_mode   = "workspace-write"

这样每次启动就是你想要的姿态，不必重复敲标志。需要临时更保守或更放开时，再用命令行标志临时覆盖。

另一个文件是 AGENTS.md，它是 Codex 版的”项目说明书”，放在项目里，会在任务开始前作为项目指令被读进去。它的定位和 Claude Code 的 CLAUDE.md 类似：写团队长期约定，而不是一次性的任务细节。放金额计算这个项目里，一份克制的 AGENTS.md 可能是这样：

1
2
3
4
5
6
7
8
9
10
11
12

# 项目约定

## 技术栈
- Python 3.11，测试用 pytest

## 金额与精度
- 所有金额计算必须用 decimal.Decimal，禁止用内置 round 直接处理货币
- 舍入统一用 ROUND_HALF_EVEN（银行家舍入）

## 提交前
- 跑 `pytest -q` 全绿
- 只改与任务相关的文件，不要顺手格式化无关代码

关键在于分清”什么该进 AGENTS.md、什么不该”。长期、跨任务、每次都想让它看到的约定（技术栈、精度规则、提交前检查）放进去；某一次任务的复现步骤、某一段很长的报错日志，属于当前对话，任务结束就该随之消失，不要沉淀进 AGENTS.md 把它撑肥。这就自然引出下一个话题：上下文。

上下文管理是一笔持续的账

当任务从”改一个函数”变成”一次跨模块重构”，Agent 会撞上另一个限制：上下文不能无限增长。代码片段、终端日志、工具结果、历史对话都会占据模型每回合能看到的那份”视野”，而这份视野是有上限的。视野越杂，模型越难抓住当前目标，调用成本和返工概率也随之上升。

结合前面的回合制机制看会更具体：每一回合模型看到的不只是你最初的任务，还包括之前每一回合的命令输出。如果第 2 回合你让它跑了一整套测试、回传了三百行日志，这三百行就会一直挂在后续每一回合的视野里，哪怕后面根本用不到。所以组织给 Codex 的任务时，我会按这几条来：

1. 一开始就给复现步骤、失败测试和目标模块，而不是从”帮我看看整个项目”起步。给它第 1 回合就能精准落点的信息。
2. 把长期约定放进 AGENTS.md，把一次性日志留在当前任务里。前者每次都该看到，后者看完即弃。
3. 测试输出很长时，先让它只保留失败项、调用栈和关键环境信息，而不是把全量日志留在对话里滚动。
4. 把独立的调查工作拆成子任务，只回传结论，而不是把完整探查过程灌回主线。

这些做法不是 Codex 独有的机制，而是任何工具型 Agent 都会遇到的工程约束。理解了”每回合的观察都会累积进视野”，你就会明白为什么”让它一次读一百个文件”往往比”精确指到三个文件”效果更差：不是它不够聪明，是视野被噪声占满了。

安全配置与效率之间的取舍

受限环境有时会挡住必要操作，比如装依赖、访问内部包源、或者调用本地开发服务。碰到这种情况，正确的反应不是直接切到 Full Access 把门全拆了，而是先问清楚”到底缺哪一格权限”：

• 是只需要多一个可写目录？那就只加那个目录，沙箱模式仍保持 workspace-write。
• 是只需要放行一个域名的网络访问？那就只放这一个，而不是整个网络。
• 是只需要对某一条命令批准一次？那就在它问的时候批这一次，不改默认策略。

OpenAI 在内部部署 Codex 时也把这条讲成同一个意思：低风险的常规操作尽量保持顺畅，越过既定边界的操作则停下来接受审批，并保留可审计的记录。(Running Codex safely at OpenAI)

落到实际配置上，我的姿态是：

• 个人项目：默认就用 Auto（workspace-write + on-request），只为明确的需求逐项放开，用完收回。
• 团队项目：把可共享的限制和验证命令写进 AGENTS.md 与 config.toml，别让每个开发者靠口头习惯各自决定安全边界。安全边界一旦靠”记得”来维持，就等于没有。

一个可以自己动手验证的小实验

本文没有逐行验证 Codex 的内部实现。如果你想把这篇的理解落到自己项目上，最好的办法是找一个有稳定测试的 Bug，做两轮对照实验，亲眼看看那些参数的差别：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

准备：一个能稳定复现的失败测试，先记下它现在为什么红

第一轮：默认受限环境
  命令：codex --sandbox workspace-write --ask-for-approval on-request
  观察并记录：
    - Codex 读了哪些文件（它有没有先精准定位，还是漫无目的地翻）
    - 它在哪一步停下来请求审批（这就是它判断"越界"的地方）
    - 它跑了哪些命令来验证（有没有先复现失败、再确认修好）

第二轮：只为实际阻塞项增加最小权限
  做法：只放开第一轮里真正卡住的那一格（某个目录 / 某个域名 / 某条命令）
  记录：
    - 新增的权限是不是真的必要
    - 它有没有因此扩大到工作区或网络的其他范围
    - 测试结果和第一轮是否一致

最终检查：
    - diff 是否只包含任务相关改动，有没有顺手改了无关代码
    - 测试和构建是否有明确的通过证据（退出码 0、N passed）

这个实验证明不了 Codex 的内部实现，但能回答一个更实际的问题：你的配置，是不是既够安全、又能把活干完。它也能成为面试时更有说服力的实践材料。比起说”我了解 Agent 沙箱”，你能讲清”我在什么场景下把 read-only 换成了 workspace-write、为什么只放开了一个目录而不是全放开”，分量完全不同。

我的结论

我理解 Codex 的重点不是”它内部有几层状态机”，而是它把一次编码任务拆成了可治理的回合：模型每回合只提一个意图，运行环境在明确边界内执行并把结果回传，人则通过审批和验证这两道闸决定”要不要继续”和”能不能算完”。看懂了这个回合制循环，沙箱、审批、上下文、验证就不再是四个孤立名词，而是分别卡在循环的四个位置上。

对想做 Agent 的人，这里有四个可以直接带走的原则：

1. 任务上下文要小而具体，因为每回合的观察都会累积进模型视野。
2. 工具执行要有技术边界，用操作系统级沙箱兜底，而不是靠提示词嘱咐。
3. 权限提升要按最小范围进行，缺哪一格补哪一格，不要一步切到全放开。
4. 完成条件必须由测试、构建或可审计的结果定义，”看起来对”不是完成。

模型能力还会变，默认参数和界面也会变，但这四个工程问题不会消失。把它们逐个想清楚，一个 Agent 才会从”演示”走进”日常开发流程”。

参考资料

• OpenAI：Introducing upgrades to Codex
• OpenAI：Running Codex safely at OpenAI
• Codex 开发者文档：Sandbox
• Codex 开发者文档：Agent approvals & security
• Codex 开发者文档：Configuration Reference
• GPT-5-Codex 系统卡
• Claude Code 技术架构深度解析，用于对照阅读工具型 Agent 的通用问题