OpenAI Agents SDK #6：把 Agent 关进「安全箱」——Sandbox 执行环境全解析

你写了一个 Agent，让它帮你改代码、操作文件、跑测试脚本。

然后它误删了宿主机上的 /etc/hosts。

这不是段子，是任何「直接跑在宿主机上的 Agent」都会碰到的问题。OpenAI 在 v0.14.0 给出了官方答案：Sandbox Agents。1

SandboxAgent：普通 Agent 多了什么？

SandboxAgent 是 Agent 的派生类，核心差异是四个额外属性：

属性	作用
`default_manifest`	定义沙箱的工作区环境（文件、目录、Git repos、环境变量）
`sandbox instructions`	沙箱专用指令，补充说明 Agent 在沙箱内的行为规范
`capabilities`	开放给 Agent 的能力集（shell、文件系统、memory、skills 等）
`run_as`	沙箱内执行身份，指定 user/group

普通 Agent 只是「配了工具的 LLM」——你告诉它能做什么，它通过函数调用去触发。SandboxAgent 则额外持有一个「执行环境的完整描述」，每次运行时 SDK 会根据这份描述初始化一个干净的工作区。2

关键区别：SandboxAgent 不仅知道「能做什么」，还规定了「在哪里做、能碰什么」。

Manifest：工作区合约

Manifest 是 Sandbox 架构的核心概念。它是一份声明式的工作区合约，告诉 SDK「为这个 Agent 准备什么样的执行环境」。

支持的字段：2

字段	含义
`files`	在沙箱内创建的合成文件（内容直接在 Manifest 中定义）
`dirs`	在沙箱内创建的合成目录
`local_files`	从宿主机挂载的本地文件（只读或读写）
`local_dirs`	从宿主机挂载的本地目录
`git_repos`	在沙箱启动时 clone 的 Git 仓库（支持 branch/commit 固定）
`environment`	注入沙箱的环境变量
`users` / `groups`	沙箱内的用户和组定义
`mounts`	远程存储挂载（S3、R2、GCS、Azure Blob 等）

这份合约有几个特性值得注意：

可覆盖性：SandboxAgent.default_manifest 是默认值，但每次 Runner.run() 时，可以通过 SandboxRunConfig.manifest 字段覆盖——同一个 Agent，用不同 Manifest 跑出完全隔离的工作区。

可快照（Snapshot）：执行完成后，沙箱工作区可以被序列化为 SandboxSessionState，下次运行时直接恢复到上次的状态，无需重新初始化。长周期任务和断点续跑靠的就是这个。1

SandboxRunConfig：单次运行的精细控制

如果说 Manifest 管的是「空间」（工作区长什么样），SandboxRunConfig 管的是「时间」（这次跑怎么配置）。

from agents.sandbox import SandboxRunConfig, DockerSandboxClient

run_config = SandboxRunConfig(
    client=DockerSandboxClient(image="python:3.11-slim"),  # 指定运行时
    session=None,                                           # 注入已有 session（可选）
    session_state=my_snapshot,                             # 恢复快照（可选）
    snapshot=True,                                         # 运行完后生成快照
    materialize_concurrency=4,                             # 并发挂载 mount 的限制
)

核心参数说明：2

client：创建沙箱的客户端。不传则使用 Agent 级默认值
session：注入一个已有的 sandbox session（适合多轮对话共享同一工作区）
session_state：从快照恢复（RunState、SandboxSessionState 或已保存快照均可）
snapshot：是否在运行结束后序列化当前工作区状态
materialize_concurrency：并发初始化 mount 的上限（避免大量 Git clone 同时触发）

支持的执行环境：从本地到云端

Sandbox 设计里有一件事挺实用：同一套 SandboxAgent 代码，换一行 client 参数就能换执行环境。1

内置支持

首发版本

v0.14.0

GitHub Stars

25.3k

正在加载统计卡片...

本地开发用：

客户端	特点	适用场景
`UnixLocalSandboxClient`	直接用本机文件系统，无额外依赖	本地快速验证、调试
`DockerSandboxClient`	启动 Docker 容器，完整隔离	本地生产级测试

托管云端用（7 家供应商）：

供应商	特点
E2B	轻量沙箱，冷启动快
Modal	弹性计算，支持 GPU
Cloudflare	Workers 边缘执行
Vercel	前端友好，适合 Web 场景
Daytona	开发工作区管理
Blaxel	Agent 专用执行层
Runloop	高并发 Agent 任务

v0.14.5 还新增了 Modal 的 idle timeout 配置选项，让云端 session 不再无限等待。3

如何选择？ 简单原则：开发阶段 UnixLocalSandboxClient，测试阶段 DockerSandboxClient，生产阶段根据延迟、成本、语言运行时需求选托管方案。Modal 适合 GPU 任务，E2B 适合快速冷启动，Cloudflare/Vercel 适合 Web 场景。

完整代码示例解读

下面是官方文档提供的基础示例，展示如何从本地 repo 加载 skills 并创建 Unix-local sandbox session：2

from agents.sandbox import (
    SandboxAgent,
    Manifest,
    LocalDir,
    SandboxRunConfig,
    UnixLocalSandboxClient,
)
from agents import Runner

# 1. 定义 SandboxAgent
agent = SandboxAgent(
    name="code-assistant",
    instructions="你是一个代码助手，可以读写文件并运行 shell 命令。",

# 工作区合约：从宿主机挂载当前项目目录
    default_manifest=Manifest(
        local_dirs=[
            LocalDir(
                host_path="./my-project",   # 宿主机路径
                sandbox_path="/workspace",  # 沙箱内路径
                read_only=False,            # 允许写入
            )
        ],
        environment={"PYTHONPATH": "/workspace"},
    ),

# 能力声明：允许 shell 执行和文件系统操作
    capabilities=["shell", "filesystem"],
)

# 2. 配置本次运行：使用本地 Unix 沙箱，运行后生成快照
run_config = SandboxRunConfig(
    client=UnixLocalSandboxClient(),
    snapshot=True,   # 运行结束后序列化 session 状态
)

# 3. 执行
result = await Runner.run(
    agent,
    "帮我检查 /workspace 下的所有 Python 文件并运行测试",
    run_config=run_config,
)

# 4. 保存快照，供下次运行恢复
session_state = result.session_state

几个关键点：

LocalDir(read_only=False) 表示 Agent 可以向宿主机写回文件。生产环境建议先用 read_only=True 验证逻辑，再开放写权限
capabilities=["shell", "filesystem"] 是白名单机制——没有列出的能力默认不开放。内置 capabilities 还包括 skills、memory、compaction2
snapshot=True 后，result.session_state 可以序列化存储，下次通过 SandboxRunConfig(session_state=...) 恢复，这是长周期任务断点续跑的核心机制

Capabilities 内置能力清单

capabilities 字段控制 SandboxAgent 在沙箱内能做什么。目前支持：2

Capability	含义
`shell`	执行 shell 命令（`bash`、`python` 等）
`filesystem`	文件读写、目录操作、图片检查
`skills`	加载 `.agents/skills/` 中预定义的技能集
`memory`	从历史运行中学习（支持 read-only 和 generate-only 模式）
`compaction`	上下文压缩，管理长对话的 token 消耗

memory capability 尤其值得单独说一下：它不是「对话历史」，而是「跨 run 的工作区记忆」。Agent 可以从先前运行中积累的状态里学习——支持 conversation_id、Session、group_id 多种颗粒度的记忆分组，甚至可以绑定 S3 做持久化存储。1

为什么需要 Sandbox？三个真实场景

场景一：代码生成与执行

Agent 帮用户写 Python 脚本，然后在沙箱内跑，把结果返回。代码跑在哪里完全隔离，哪怕写出 import shutil; shutil.rmtree('/') 也只是在容器里自毁，宿主机毫发无损。

场景二：合规敏感任务

税务处理、医疗数据分析这类任务，数据不能离开受控环境。凭证留在 Harness（控制层），模型看不到；文件操作发生在隔离 Sandbox，不会外泄。官方 examples 套件里有完整的 tax-prep 和 healthcare workflow 示例。1

场景三：长周期工程任务

网站 clone、代码 review、数据房间 QA——这些任务可能跑几分钟到几小时。Snapshot 机制让任务可以在任何一个检查点暂停、序列化，再从断点恢复，不需要从头重跑。

国内有开发者写道：「过去一年开发者把 Agent 上半场——模型调用工具、拆任务、接 MCP、流程串联——做得差不多了，真正卡住的是下半场：读写真实文件、安装依赖、运行测试、生成产物时的隔离与可靠性。」4 这个判断大致准确。

关于 Sandbox 供应商生态

v0.14 发布后，国内也出现了跟进。腾讯云在 2026 年 4 月开源了 Cube Sandbox，定位为面向 AI Agent 的开源沙箱底座，原生兼容 E2B 接口标准，可与 OpenAI Agents SDK 无缝集成。官方声称冷启动时间低于 100ms，支持 Python/Node.js/Go/Java 多语言运行时。5 对需要自主可控部署的国内开发者来说，多了一个选项。

实践建议

① 按「最小权限」配置 capabilities

capabilities 是白名单，默认什么都不开。不需要 shell 就不要加 shell，不需要跨 run 记忆就不要加 memory。开放越少，爆炸半径越小。

② 用 Manifest 的 read_only=True 做第一道防线

开发期间挂载本地目录时，先用只读模式验证 Agent 的读取逻辑是否正确，确认无误后再开放写权限。这能避免一大批「Agent 把源代码弄乱了」的事故。

③ 善用 Snapshot 拆解长任务

长周期任务不要一次跑完。在每个关键检查点调用 snapshot=True，把 session_state 存到数据库。任务失败时从最近快照恢复，而不是从头开始。这也是生产级 Agent 和 Demo Agent 的核心区别之一。

④ 本地先跑 UnixLocalSandboxClient

不要上来就对接云端供应商。UnixLocalSandboxClient 零依赖、秒启动，能快速验证 Manifest 结构、capabilities 配置和 Agent 逻辑。逻辑通了再换 DockerSandboxClient 做隔离测试，最后上云。

小结

说白了，Sandbox 解决的是「Agent 真的能干活吗」这个问题——不只是调 API 返回文本，而是能在受控环境里读写文件、跑代码、生成产物、被审计。

Harness 管推理，Sandbox 管执行，Manifest 定边界，Snapshot 管恢复。四件事分开做，才能在生产环境里放心跑。

下一篇 #7：Tracing——可观测性追踪

Agent 跑起来了，出了问题怎么排查？v0.14 内置了 Tracing 系统，不只是打日志，而是完整记录 Agent Loop 的每一个决策节点——工具调用、Handoff 发生、LLM 输入输出全链路可视化。下篇拆解 Tracing 的架构与实际调试技巧。

封面图：AI 生成，主题为 Agent 安全沙箱执行环境可视化。