OpenAI Agents SDK Sandbox 2026：上线前怎么验收？
Sandbox 能成功运行一次，不等于可以上线。获胜方案是按六道门逐步验收：工作区契约、确定性编排、真实环境集成、权限隔离、状态恢复、失败回滚；只有依赖 macOS 工具链、需要并行隔离测试或短期集中回归时，才额外准备云端 Mac。
这篇内容适合已经跑通 SandboxAgent 示例、但还没有建立上线门槛的开发者；也适合负责文件读写、命令执行、网络和凭据边界的平台工程师，以及需要在本地、容器和云端 Mac 之间安排测试环境的 AI 技术负责人。
⚠️ 截至 2026 年 8 月 26 日，官方文档仍将 Sandbox Agents 标记为 Beta。API、默认设置和受支持能力在正式可用前仍可能变化，因此验收记录必须包含 SDK 版本和复核日期，而不能只保存一次演示结果。参考：Sandbox Agents 官方快速开始文档。
失败案例：示例成功，交付却在第一步失控
一个典型失败流程是这样的：开发者在本机运行 SandboxAgent，Agent 能读取任务文件、执行测试命令并生成报告。演示看起来完整，但上线后出现三类问题：
- 目标环境没有本机缓存，依赖安装失败；
- Agent 继承了过宽的运行身份，能够读取工作区之外的文件；
- 任务中断后重新运行，已完成的删除或覆盖操作被重复执行。
这类问题不能靠增加提示词解决。它们分别属于环境一致性、权限隔离和状态恢复问题。官方概念文档也明确区分了 SandboxAgent、Manifest、实时 sandbox session 与保存状态：前者描述 Agent 和初始工作区，后者决定一次运行实际连接到哪个环境。参考：Sandbox Agents 概念与生命周期说明。
因此，验收记录至少要回答 4 个问题：
| 验收问题 | 合格证据 | 阻断条件 |
|---|---|---|
| Agent 从哪里读写文件？ | Manifest、目录树、挂载说明 | 出现未声明目录或主机路径 |
| 命令以谁的身份执行？ | run_as、权限模式、失败日志 |
使用超出任务需要的身份 |
| 中断后从哪里继续？ | RunState、session_state 或 snapshot |
只能从头重跑 |
| 失败后如何清理？ | 删除、重建、回滚记录 | 残留凭据或旧任务文件 |
第一阶段：先冻结工作区契约，再谈测试结果
上线前先把“允许存在什么”写成基线。不要直接拿开发者机器作为事实来源。
Manifest 应明确输入文件、代码目录、输出目录、临时目录、挂载内容和环境变量。需要写入的路径与只读路径要分开。凭据不要通过工作区文件长期保存，也不要默认把宿主机目录全部暴露给 Agent。
| 工作区对象 | 推荐验收定义 | 常见错误 |
|---|---|---|
| 输入目录 | 只读，内容可重复生成 | 直接挂载开发者项目根目录 |
| 输出目录 | 可写，交付物位置固定 | 输出散落在临时路径 |
| 临时目录 | 可清理，不承载长期状态 | 将缓存误当作任务状态 |
| 凭据 | 按任务注入，默认不可见 | 把完整环境变量传入沙箱 |
| 用户身份 | 最小权限的专用用户 | 直接使用本机高权限账户 |
SandboxAgent 的默认工作区只适用于创建全新 session 的场景。如果运行时注入已有 session、恢复 session_state，或从 snapshot 启动，最终工作区可能来自保存状态，而不是当前的默认 Manifest。这个边界必须写进验收基线。参考：SandboxRunConfig 官方参考。
同时记录以下版本化信息：
- Agent 指令和能力列表；
Manifest内容与目录权限；SandboxRunConfig的 client、session、snapshot 配置；- 运行身份、工作目录和网络策略；
- 输入样本、预期输出和清理规则。
如果这份记录无法在另一台机器上重建，验收对象就还不是可交付环境。
第二阶段：用确定性测试锁定编排边界
确定性测试的价值，是先排除模型随机性和真实沙箱供应方差异。官方测试工具支持使用固定模型脚本和脚本化 sandbox session，在不创建真实容器或远程沙箱的情况下验证 SDK 工作流。参考：Agents SDK 测试指南。
这一阶段重点测试“运行逻辑是否正确”，而不是测试真实文件系统：
- 固定模型输出一次合法工具调用；
- 检查工具参数是否完整、类型是否正确；
- 验证能力路由是否把调用送到预期的文件或 shell 工具；
- 模拟命令失败、文件不存在和权限拒绝；
- 验证重试次数、错误分支和最终输出；
- 模拟流程提前结束，确认清理逻辑仍会执行。
建议给每条路径设置明确的预期结果：
| 测试路径 | 应观察什么 | 不应得出的结论 |
|---|---|---|
| 正常读取并生成文件 | 参数、工具顺序、最终输出 | 真实目录权限一定正确 |
| 命令返回错误 | 错误是否传回、是否重试 | 目标系统命令一定存在 |
| 文件不存在 | 是否进入补救分支 | 真实挂载内容完整 |
| 工具调用被拒绝 | 是否停止或请求审批 | 外部凭据不会泄露 |
| 中途结束 | 状态和清理是否保存 | 真实供应方一定能恢复 |
官方参考实现也提醒，脚本化 session 只暴露预先配置的方法；它不能证明真实供应方能启动、真实进程能执行，或真实隔离边界有效。参考：scripted_sandbox_session API 说明。
这一步通过后，结论只能写成：“SDK 编排边界通过”。不能写成“沙箱安全”或“生产环境可用”。
第三阶段：在真实沙箱中复测环境一致性
确定性编排测试通过后，才进入真实集成测试。测试环境要尽量接近交付环境，包括依赖版本、目录结构、运行用户、工作目录、网络规则和清理方式。
至少准备 3 组任务：
- 冷启动任务：从空白或标准快照创建环境，验证依赖、目录和入口命令；
- 连续运行任务：在同一 session 中完成读取、修改、测试和产物生成；
- 并行任务：使用独立工作区同时执行，检查文件、缓存和凭据是否串线。
本地 Mac 通过但上线失败，通常是因为本地环境额外提供了系统命令、缓存、钥匙串、开发证书或隐藏的环境变量。尤其涉及 macOS 专属工具链、签名流程、系统组件或真实 GUI 辅助程序时，其他系统的容器结果不能替代真实 Mac 复测。
| 任务类型 | 本地或容器可验证 | 必须准备独立 Mac 的情况 |
|---|---|---|
| 文件读写与文本处理 | 通常可以 | 依赖 macOS 文件属性或系统目录 |
| 通用 shell 命令 | 通常可以 | 使用 macOS 专属命令或脚本 |
| 编译与测试 | 取决于工具链 | 依赖签名、系统 SDK 或设备组件 |
| 多任务并行 | 可做初步验证 | 需要真实 Mac 资源和独立用户环境 |
| 交付物验收 | 可验证文件结果 | 产物依赖 macOS 运行或签名 |
如果需要把本地验证迁移到独立环境，先查看 ProxyMac 帮助中心 了解交付和登录边界，再按同一份 Manifest 重建任务。不要为了“看起来一致”把整台开发机复制过去。
第四阶段：把权限测试从正向演示改成负向攻击
Agent 沙箱的权限验收，不能只证明“允许的操作能成功”。更重要的是证明“不允许的操作会失败，而且失败后不会留下半成品”。
run_as 决定模型面向的 shell、文件读取和补丁操作使用哪个沙箱身份；Manifest 中的 Permissions 决定文件物化后的读、写和执行权限。两者不是同一个概念。相关边界可参考官方 权限与运行身份说明。
至少加入以下拒绝测试：
- 读取未挂载的主机路径；
- 写入只读输入目录；
- 覆盖已经存在的交付文件；
- 删除工作区之外的文件；
- 读取不应暴露的环境变量；
- 访问未声明的网络或外部存储；
- 在没有审批的情况下执行高风险命令。
结果应分成 3 类：
✅ 允许：任务必需操作成功，并留下可审计记录。
⚠️ 审批：删除、覆盖、外发或高风险命令暂停，等待明确决定。
❌ 拒绝：超出工作区、身份或网络边界的调用失败，不继续隐式重试。
经验上，权限失败后的行为比权限成功更值得看。若 Agent 收到拒绝后自动换用更宽路径、读取备用凭据或继续执行破坏性步骤，应直接阻断，不要用“模型偶尔会这样”解释。
本地客户端也不能自动等同于生产级隔离环境。需要托管执行、容器边界或独立 Mac 时，应对真实执行边界单独验收，而不是只验证客户端 API 调用成功。
第五阶段：中断长任务，验证恢复与续跑
恢复测试是最容易被省略、却最容易在生产中造成重复操作的一关。
SandboxRunConfig 支持通过实时 session、序列化的 session_state 或 snapshot 获得后续运行所需的沙箱状态。官方文档区分了“恢复原来的后端 session”和“创建新 session、再用保存的工作区内容初始化”这两种路径。测试时必须先确定项目采用哪一种。参考：快照、session state 与生命周期说明。
建议在 3 个危险节点主动中断：
- 文件已修改，但最终报告尚未生成；
- 删除或覆盖操作已获准，但尚未执行；
- 外部调用返回后，Agent 尚未写入最终状态。
每次中断后检查：
- 恢复后的工作目录是否正确；
- 已完成步骤是否被重复执行；
- 旧任务文件是否混入新 session；
- snapshot 是否包含不应持久化的挂载内容；
- 清理失败时是否能终止并重新创建环境；
- 新旧运行的追踪记录是否能对应同一任务。
快照不是万能回滚。挂载目录和临时路径未必会作为持久化工作区保存，因此交付团队必须明确“哪些状态能恢复、哪些状态必须重新拉取”。如果恢复结果不一致，最安全的规则通常是终止当前环境、保留异常证据、创建干净 session，而不是继续猜测上一次执行到了哪一步。
中部 FAQ：把长尾问题转成放行依据
上线前，Sandbox 验收应该覆盖哪些环节？
重点不是再跑一次成功示例，而是按工作区、编排、真实环境、权限、恢复和回滚六个阶段逐项验证。每个阶段都要有通过证据和阻断条件。没有版本记录、没有异常日志或无法重建环境的验收结果，不应直接进入生产。
如何检查 SandboxAgent 的文件读写与命令边界？
使用 Manifest 固定目录和挂载边界，用 run_as 固定执行身份，再分别测试允许、审批和拒绝路径。文件权限只能说明物化文件的读写规则，不能替代网络、凭据和主机路径检查。验收时必须主动尝试越权，而不是只执行正常任务。
为什么开发机上的 Agent 沙箱结果不能代表交付环境？
最常见原因是本机缓存、系统命令、用户权限、环境变量和开发工具链没有被显式声明。另一个原因是把脚本化测试当成真实集成测试。上线前必须用目标交付环境重新创建工作区，并复测依赖、进程、目录和清理流程。
如何设计快照恢复和任务续跑的中断测试？
在关键副作用发生前后主动终止任务，分别测试 session_state、运行状态和 snapshot 的恢复路径。恢复后要检查幂等性、旧文件污染和清理结果。任何高风险动作重复执行、恢复后状态漂移或无法回滚，都应归入阻断项。
什么时候应安排独立的 Mac 验证环境？
涉及 macOS 专属工具链、签名、系统组件、真实 Mac 运行行为或短期多人并行回归时，需要独立 Mac。通用编排和基础权限可以先在确定性测试、容器或本地环境完成。云端 Mac 是隔离验证选项，不是所有 Sandbox 项目的默认答案。
第六阶段：用放行清单决定上线、补测还是换环境
最终验收不要写成“测试通过”。应把每一项结果归档为通过、需补测或阻断，并由负责人签字或在系统中确认。
- [ ] 已冻结
SandboxAgent、Manifest、能力列表和SandboxRunConfig版本。 - [ ] 已记录输入、输出、临时目录、挂载和运行身份。
- [ ] 已完成正常、失败、文件缺失、提前结束 4 类确定性编排测试。
- [ ] 已在真实沙箱中重建目标依赖、目录和工作目录。
- [ ] 已验证冷启动、连续运行和独立并行工作区。
- [ ] 已测试只读目录、未声明路径、环境变量和凭据边界。
- [ ] 删除、覆盖、外发和高风险命令均有拒绝或审批路径。
- [ ] 已中断长任务，并验证 session state 或 snapshot 恢复。
- [ ] 恢复后不会重复执行已完成的高风险操作。
- [ ] 旧任务文件不会进入新会话，失败后可以重建干净环境。
- [ ] 已保存追踪记录、异常日志、配置版本和测试负责人。
- [ ] 所有阻断项均已关闭，或明确决定不放行。
OpenAI Agents SDK 自带 tracing，可记录模型生成、工具调用、交接、护栏和自定义事件；测试环境还应根据数据敏感性决定是否关闭或隔离追踪。参考：Agents SDK Tracing 文档。
| 最终状态 | 处理方式 | 能否上线 |
|---|---|---|
| 通过 | 保存证据和负责人，进入交付 | 可以 |
| 需补测 | 限定范围、补齐证据后复核 | 暂缓 |
| 阻断 | 修复边界或更换执行环境 | 不可以 |
环境选择的回退条件：如果任务只涉及通用文件处理和短流程编排，本地或容器通常足够；如果任务依赖 macOS 工具链、多人并行隔离或短期集中回归，准备独立的云端 Mac 更合理。具体周期和交付方式应按实际测试窗口核算，可先参考 ProxyMac 的方案与价格信息，再用本文清单重新验收，而不是把开发者机器直接当成生产环境。
本地方案的真实缺点也要正面记录：环境容易被缓存和个人权限污染，团队并行时难以保持一致，Mac 专属工具链还可能受设备占用影响。云端 Mac 不能替代所有安全设计，但在临时验证、隔离回归和环境复现上，往往比继续堆叠本地例外更容易审计。若当前验收正被这些问题阻断，租赁 ProxyMac 的独立 Mac 环境，再按同一份 Manifest、权限表和恢复脚本复验，通常比直接迁移未验证的开发环境更稳妥。
最后更新于 2026 年 8 月 26 日，数据核实自 Sandbox Agents 官方快速开始文档、概念文档、测试指南及 Agents SDK 发布记录。Sandbox Agents 移除 Beta 标记、客户端能力变化、测试 API 调整或 OpenAI 发布新的安全与部署指南时，应触发全文复核。
