Codex 101｜06｜Approval Sandbox

生产级 coding agent 的风险不在“模型会不会说错话”，而在它可以操作本地环境：运行命令、读写文件、联网、应用 patch、调用外部工具。Codex 的安全设计把这些风险放进工具执行前后的 policy layer。

审批不是一个 bool，沙箱也不是一个命令行参数。Codex 需要同时考虑 approval policy、文件系统权限、网络权限、平台沙箱能力、是否可信工作区、是否允许失败后无沙箱重试。

学习目标

• 理解 ToolOrchestrator 如何串起 approval、sandbox、retry
• 理解 macOS/Linux/Windows 沙箱为什么是同一策略的不同实现
• 理解“沙箱失败后重试”为什么必须重新审批

Codex 里的机制边界

安全关键路径必须集中管理：不要让每个工具自己决定什么时候审批、什么时候绕过沙箱、什么时候升级权限。

把它放到“修复失败测试”的例子里，流程会变得很具体：用户不是在等待一次回答，而是在启动一个本地任务。Codex 要决定这一轮能看到哪些历史、模型可以使用哪些工具、哪些命令需要审批、工具输出如何写回上下文、哪些状态需要持久化，以及 UI 应该在什么时候向用户展示中间进展。

这也是 Codex 101 的核心阅读方式：不要只问“某个函数在哪里”，而要问“这个边界解决了什么工程问题”。如果一个边界能同时服务 TUI、exec、SDK、MCP 或 Cloud Tasks，它通常就是架构上的 load-bearing component。

关键源码锚点

这些文件不应该被当作文章目录逐个解释。更好的读法是把它们分成三类：第一类定义协议和数据结构，第二类推进运行时状态，第三类把运行时能力暴露给产品界面或外部调用方。

机制拆解

第一步是入口归一化。无论用户来自 TUI、exec、SDK 还是 app-server，请求最终都需要变成运行时可以理解的结构。这样 core 不需要知道当前前端是终端 UI 还是程序化客户端。

第二步是状态装配。Agent 每一轮并不是裸 prompt，而是由配置、历史、工具、权限、模型能力、当前工作区和用户输入共同构成。Codex 的代码库反复体现了这个原则：模型请求只是 runtime state 的一个投影。

第三步是事件推进。模型流、工具调用、审批请求、命令输出、patch diff、token usage 和完成状态都以事件形式流动。事件既给 UI 渲染，也给状态层记录，还给上层客户端形成稳定 API。

第四步是结果回填。工具执行完并不意味着任务结束。结果需要被包装成模型可读的 item，追加到历史中，再由模型决定下一步。这就是 coding agent 与普通聊天机器人的根本差别。

读者应该抓住的主线

同一个命令在可信目录、只读沙箱、需要网络、失败后重试等场景下风险完全不同。

这也是本篇的核心判断：审批和沙箱不是 UI 选项，而是本地 agent 的安全关键路径。 如果只看单个函数，很容易误以为 Codex 只是把用户输入转发给模型；如果从运行时边界看，就能看到它在处理一组更复杂的问题：谁拥有状态，谁负责安全，谁消费事件，谁把结果写回历史，谁对外暴露稳定协议。

用“修复失败测试”串起来

这个例子会在系列中反复出现，因为它足够小，又能覆盖 coding agent 的关键机制。一个好的 runtime 不是让模型“更聪明”这么简单，而是让模型的每一步行动都有边界、有记录、有回路。

和普通聊天机器人的差别

因此，Codex 101 的读法不是“看 OpenAI 怎么写代码助手”，而是借 Codex 这个实现，拆解一个本地 agent runtime 应该具备哪些工程边界。

可迁移伪实现：Approval Sandbox

// conceptual sketch, not Codex source code
type RuntimeInput = { threadId: string; userGoal: string };
type RuntimeEvent =
  | { type: "text_delta"; text: string }
  | { type: "tool_call"; name: string; args: unknown }
  | { type: "approval_required"; reason: string }
  | { type: "completed" };

async function runCodexMechanism(input: RuntimeInput): Promise<RuntimeEvent[]> {
  const state = await loadThreadState(input.threadId);
  const prompt = buildPromptFromState(state, input.userGoal);
  const events: RuntimeEvent[] = [];

  for await (const event of streamModelAndRuntime(prompt)) {
    events.push(normalizeRuntimeEvent(event));
    await persistEvent(input.threadId, event);
  }

  return events;
}

这个伪实现故意保留了几个抽象函数：loadThreadState、buildPromptFromState、streamModelAndRuntime、persistEvent。真正重要的不是函数名，而是边界：加载状态、构造模型视图、消费结构化事件、持久化事实。

工程取舍

小结

安全关键路径必须集中管理：不要让每个工具自己决定什么时候审批、什么时候绕过沙箱、什么时候升级权限。

如果只把 Codex 看成一个命令行工具，就会错过它真正值得学习的部分：它是一套把模型、工具、状态、安全和产品界面连接起来的本地 agent runtime。后续章节会继续沿着这条主线，把每个边界拆开来看。