OpenSandbox：阿里巴巴开源的通用 AI 应用沙箱平台

目标读者：构建 AI 应用（编程 Agent、GUI Agent、代码执行、RL 训练）的开发者 核心问题：如何为 AI 应用提供安全、可扩展的隔离执行环境？ 难度：⭐⭐⭐⭐（专家设计） 来源：GitHub alibaba/OpenSandbox，访问于 2026-09-05

快速信息卡

数据截至 2026-09-05，以仓库实际状态为准。

一句话判断

OpenSandbox 把"为 AI 应用提供隔离执行环境"这件事做成了平台级产品：上层用多语言 SDK 屏蔽差异，下层用 Docker/Kubernetes 调度资源，中间用 gVisor/Kata/Firecracker 三种安全容器适配不同隔离强度。它解决的核心矛盾是 AI Agent 需要执行任意代码、访问浏览器和桌面，又不能让这些操作污染宿主环境或逃逸到公网。

学习目标

读完本文后你应当能够：

1. 说清 OpenSandbox 五层架构中每层的职责与可替换点
2. 说出内置沙箱环境（Code Interpreter、Chrome、Playwright、Desktop、VS Code）各自面向的任务
3. 描述一次代码执行如何从 SDK 层穿过五层到达容器运行时层
4. 在 Docker 模式与 Kubernetes 模式之间做出与场景匹配的选型决策
5. 列出 OpenSandbox 适用与不适用的三类场景的判断依据

目录

• 一、项目概览
• 二、技术架构
• 三、核心机制详解
• 四、任务流案例：一次代码执行如何穿过五层
• 五、快速开始
• 六、集成示例
• 七、与同类项目对比
• 八、适用场景
• 九、Roadmap
• 十、采用建议
• 十一、常见问题排查
• 十二、练习
• 十三、自测题
• 十四、进阶路径
• 十五、总结

总览地图

OpenSandbox 分五层，每层职责独立，可以单独替换：

阅读建议：先看"技术架构"理解各层边界，再看"任务流案例"理解一次代码执行如何穿过这五层，最后按"采用建议"判断是否适合自己的场景。

一、项目概览

OpenSandbox 是阿里巴巴开源的通用 AI 应用沙箱平台，提供多语言 SDK、统一沙箱 API、Docker/Kubernetes 运行时，涵盖编程 Agent、GUI Agent、Agent 评估、AI 代码执行、强化学习训练等场景。

核心数据（截至 2026-09-05，数据来自 GitHub API）：

时效说明：Stars 和 Forks 为访问时快照，可能已变化；版本号以仓库 release 页为准。

CNCF Landscape 已收录（来源：CNCF Landscape，访问于 2026-09-05）

1.1 项目定位

OpenSandbox is a general-purpose sandbox platform for AI applications. 通用 AI 应用沙箱平台

支持场景：

1.2 主要特色

二、技术架构

2.1 整体架构

┌─────────────────────────────────────────────────────────────┐
│ OpenSandbox 架构                                            │
├─────────────────────────────────────────────────────────────┤
│ SDK 层（多语言）                                            │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐        │
│ │ Python   │ │ Java/    │ │ JS/TS    │ │ C#/.NET  │        │
│ │          │ │ Kotlin   │ │          │ │          │        │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘        │
├─────────────────────────────────────────────────────────────┤
│ 沙箱协议层（Specs）                                         │
│ 生命周期管理 API + 执行 API                                 │
├─────────────────────────────────────────────────────────────┤
│ 运行时层（Server + Components）                             │
│ ┌─────────┐ ┌──────────┐ ┌─────────┐ ┌──────────┐         │
│ │ execd   │ │ ingress  │ │ egress  │ │ server   │         │
│ │ 命令/文件│ │ 入口代理 │ │ 出口控制 │ │ FastAPI  │         │
│ └─────────┘ └──────────┘ └─────────┘ └──────────┘         │
├─────────────────────────────────────────────────────────────┤
│ 沙箱环境层（Sandboxes）                                     │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐        │
│ │ Code     │ │ Chrome   │ │ Playwright│ │ Desktop  │        │
│ │ Interpreter│ │ Browser │ │ 自动化    │ │ VNC      │        │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘        │
├─────────────────────────────────────────────────────────────┤
│ 容器运行时（Secure Container）                              │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐                     │
│ │ gVisor   │ │ Kata     │ │ Firecracker│                    │
│ │          │ │ Containers│ │ 微虚拟机  │                    │
│ └──────────┘ └──────────┘ └──────────┘                     │
└─────────────────────────────────────────────────────────────┘

2.2 各层职责拆解

理解 OpenSandbox 的关键在于看清五层之间的边界：SDK 层只负责把请求发给运行时层，不直接接触容器；协议层用 OpenAPI 规范定义接口，让多语言 SDK 能保持一致行为；运行时层是控制面，负责创建、销毁、调度沙箱；沙箱环境层是数据面，提供预置镜像；容器运行时层是隔离边界，决定安全强度。

这种分层带来的实际收益：替换容器运行时不需要改 SDK 代码；新增一种沙箱环境（比如加一个 Rust 工具链镜像）不需要动协议层；从 Docker 切到 Kubernetes 只影响运行时层。

2.3 技术栈

2.4 核心目录结构

OpenSandbox/
├── sdks/                # 多语言 SDK
│   ├── sandbox/         # Sandbox 基础 SDK
│   │   ├── python/      # Python Sandbox SDK
│   │   ├── kotlin/      # Java/Kotlin Sandbox SDK
│   │   ├── javascript/  # JS/TS Sandbox SDK
│   │   └── csharp/      # C#/.NET Sandbox SDK
│   └── code-interpreter/  # Code Interpreter SDK
├── specs/               # OpenAPI 规范
├── server/              # Python FastAPI 沙箱生命周期服务器
├── kubernetes/          # Kubernetes 部署
├── components/
│   ├── execd/           # 沙箱执行守护进程（命令/文件操作）
│   ├── ingress/         # 入口流量代理
│   └── egress/          # 出口网络控制
├── sandboxes/
│   └── code-interpreter/  # Code Interpreter 沙箱实现
├── examples/            # 示例代码
│   ├── claude-code/     # Claude Code 集成
│   ├── langgraph/       # LangGraph 集成
│   ├── chrome/          # Chrome 浏览器自动化
│   ├── playwright/      # Playwright 自动化
│   ├── desktop/         # 桌面 VNC 环境
│   └── rl-training/     # 强化学习训练
├── oseps/               # OpenSandbox 增强提案
├── docs/                # 架构文档
└── tests/               # E2E 测试

三、核心机制详解

3.1 多语言 SDK

OpenSandbox 提供多语言 SDK，覆盖主流开发语言：

除 SDK 外，官方还提供 osb 命令行工具（pip install opensandbox-cli）和 MCP 服务器（pip install opensandbox-mcp），前者面向终端操作，后者让 Claude Code、Cursor 等 MCP 客户端直接调用沙箱能力。

为什么需要多语言 SDK？只提供 REST API 不够吗？因为不同语言的类型系统、异步模型、错误处理差异很大，直接调 REST 会让每个语言的用户都重复处理序列化和重试逻辑。SDK 把这些封装掉，让 Python 用户用 async with sandbox，Java 用户用 try-with-resources，各自符合本语言习惯。

3.2 沙箱协议

OpenSandbox 定义了两套核心 API，对应沙箱的两类操作：

生命周期管理 API：

• 创建/销毁沙箱
• 沙箱状态查询
• 超时管理

执行 API：

• 命令执行（shell）
• 文件操作（读写）
• 代码解释器调用

两套 API 的分离让控制面与数据面各自演进：生命周期操作频率低但必须可靠，执行操作频率高但允许失败重试。分开后，执行 API 可以单独加流式输出，生命周期 API 可以单独做预热池，互不牵连。

3.3 沙箱运行时

支持两种部署模式：

Kubernetes 高性能运行时特性：

• 预热池（Pre-warmed pools）：提前创建好沙箱实例，请求来时直接分配，省去冷启动
• 自动扩缩容：根据负载调整沙箱数量
• 资源隔离：通过 Kubernetes 的 ResourceQuota 和 LimitRange 控制

Kubernetes 模式通过工作负载提供者创建资源：默认由 OpenSandbox 自带的 BatchSandbox 控制器（一个自定义 CRD）负责高吞吐与池化交付，也可以切换为 kubernetes-sigs/agent-sandbox 提供者。

为什么需要预热池？因为创建一个沙箱要拉镜像、起容器、初始化运行时，冷启动可能要几秒到几十秒。AI Agent 的代码执行通常是高频短任务，如果每次都冷启动，用户体验会非常差。预热池把这部分延迟摊到空闲期。

3.4 沙箱环境

OpenSandbox 内置多种沙箱环境，每种环境是一个预置镜像：

预置这些环境的原因很直接：AI Agent 的需求高度集中在执行代码、操作浏览器和桌面三类任务上。镜像预装 Chrome、VNC、Python 依赖，用户启动即可用，不用自己装配。

3.5 网络安全策略

Ingress 网关（入口流量）：

• 统一入口流量管理
• 多路由策略支持

Egress 控制（出口流量）：

• 沙箱级出口控制
• 网络隔离

为什么需要 Egress 控制？因为 AI Agent 执行的代码可能来自用户输入，也可能来自模型生成。如果沙箱能自由访问公网，恶意代码可以把宿主数据外传，或者攻击外部服务。Egress 控制让管理员能限定沙箱只能访问白名单域名，把攻击面收窄。

3.6 强隔离机制

支持三种安全容器运行时，对应不同隔离强度：

三种运行时对应隔离与性能的不同取舍：gVisor 性能损失最小但隔离弱，Kata 隔离最强但启动慢，Firecracker 介于两者之间，适合多租户高密度场景。选择取决于威胁模型——内部可信环境用 gVisor，公网多租户用 Firecracker，强合规场景用 Kata。

四、任务流案例：一次代码执行如何穿过五层

为了把抽象的分层讲清楚，跟踪一次"用户调用 Python SDK 执行 2+2“的完整流程：

1. SDK 层：Python SDK 把 interpreter.codes.run("2+2") 序列化为 HTTP 请求，发往 server
2. 协议层：请求符合 specs/ 中的 OpenAPI 规范，server 校验参数
3. 运行时层：server 找到对应的沙箱实例（预热池中已创建），把执行请求转发给 execd
4. 沙箱环境层：execd 在 Code Interpreter 镜像内启动 Python 进程，执行代码，捕获 stdout 和返回值
5. 容器运行时层：整个沙箱进程跑在 gVisor/Kata/Firecracker 之一中，系统调用被拦截或虚拟化

返回路径相反：execd 把结果回传给 server，server 按 OpenAPI 规范封装响应，Python SDK 反序列化为 result 对象，用户拿到 result.result[0].text 即 4。

这个流程的关键点：每一层都可以独立替换。把 gVisor 换成 Firecracker，上层 SDK 代码完全不变；把 Code Interpreter 镜像换成自定义的 Rust 工具链镜像，server 和 execd 也不需要改。

五、快速开始

5.1 环境要求

5.2 安装步骤

1. 初始化配置：

uvx opensandbox-server init-config ~/.sandbox.toml --example docker

2. 启动 Sandbox Server：

uvx opensandbox-server
# 显示帮助
uvx opensandbox-server -h

3. 安装 Code Interpreter SDK：

uv pip install opensandbox-code-interpreter

5.3 基本使用示例

import asyncio
from datetime import timedelta
from code_interpreter import CodeInterpreter, SupportedLanguage
from opensandbox import Sandbox
from opensandbox.models import WriteEntry

async def main() -> None:
    # 1. 创建沙箱
    sandbox = await Sandbox.create(
        "opensandbox/code-interpreter:v1.0.2",
        entrypoint=["/opt/opensandbox/code-interpreter.sh"],
        env={"PYTHON_VERSION": "3.11"},
        timeout=timedelta(minutes=10),
    )

    async with sandbox:
        # 2. 执行 Shell 命令
        execution = await sandbox.commands.run("echo 'Hello OpenSandbox!'")
        print(execution.logs.stdout[0].text)
        # Hello OpenSandbox!

        # 3. 写文件
        await sandbox.files.write_files([
            WriteEntry(path="/tmp/hello.txt", data="Hello World", mode=644)
        ])

        # 4. 读文件
        content = await sandbox.files.read_file("/tmp/hello.txt")
        print(f"Content: {content}")
        # Content: Hello World

        # 5. 创建代码解释器
        interpreter = await CodeInterpreter.create(sandbox)

        # 6. 执行 Python 代码
        result = await interpreter.codes.run(
            """
            import sys
            print(sys.version)
            result = 2 + 2
            result
            """,
            language=SupportedLanguage.PYTHON,
        )
        print(result.result[0].text) # 4
        print(result.logs.stdout[0].text) # 3.11.14

        # 7. 清理沙箱
        await sandbox.kill()

if __name__ == "__main__":
    asyncio.run(main())

5.4 用 osb CLI 快速体验

不想写代码时，可以用官方命令行工具 osb：

uv tool install opensandbox-cli
osb config init
osb config set connection.domain localhost:8080
osb sandbox create --image python:3.12 --timeout 30m -o json
osb command run <sandbox-id> -o raw -- python -c "print(1 + 1)"

osb 覆盖沙箱生命周期、命令执行、文件操作、egress 策略查看与修改，适合脚本化和运维场景。

六、集成示例

6.1 编程 Agent 集成

OpenSandbox 支持主流编程 Agent CLI：

除了命令行方式，官方还提供 MCP 服务器，把沙箱创建、命令执行、文本文件操作暴露给 Claude Code、Cursor 等 MCP 客户端：

pip install opensandbox-mcp
opensandbox-mcp --domain localhost:8080 --protocol http

示例：Claude Code 集成

# 克隆仓库
git clone https://github.com/alibaba/OpenSandbox.git
cd OpenSandbox/examples/claude-code
# 查看 README 了解详细集成方式

6.2 LangGraph 集成

OpenSandbox 提供 LangGraph 状态机工作流集成：

# LangGraph 集成示例
# 见 examples/langgraph/README.md

6.3 浏览器自动化

Chrome 示例：

# 浏览器自动化 + VNC + DevTools
# 见 examples/chrome/README.md

Playwright 示例：

# Playwright + Chromium 无头抓取和测试
# 见 examples/playwright/README.md

6.4 桌面环境

Desktop 示例：

# 完整桌面环境 + VNC 访问
# 见 examples/desktop/README.md

6.5 强化学习训练

RL Training 示例：

# DQN CartPole 训练 + checkpoints + summary 输出
# 见 examples/rl-training/README.md

七、与同类项目对比

对比说明：E2B 是商业化的代码执行沙箱，SDK 以 Python 为主，浏览器环境支持较弱；Docker API 只提供容器原语，需要自己封装沙箱协议和预热池；Kata Containers 只解决隔离层，不提供 SDK 和运行时管理。OpenSandbox 的差异点在于把 SDK、协议、运行时、环境、隔离五层打包成完整平台。

八、适用场景

九、Roadmap

状态整理自官方 ROADMAP.md，更新于 2026-04-28，以仓库实际进度为准。

9.1 SDK 与开发体验

9.2 沙箱运行时

9.3 可观测性与运维

十、采用建议

根据场景给出采用顺序：

1. 先试：本地用 Docker 模式跑通 examples/claude-code 或基本使用示例，验证沙箱能起来、代码能执行
2. 再选隔离层：内部可信环境用 gVisor，公网多租户用 Firecracker，强合规场景用 Kata
3. 再上 Kubernetes：单机 Docker 模式只适合开发测试，生产环境必须用 Kubernetes 模式才能用预热池和自动扩缩容
4. 最后自定义镜像：预置环境不够用时，基于 sandboxes/code-interpreter/ 自定义镜像，保持 entrypoint 协议不变

适用边界：

• 适合：需要执行任意代码、操作浏览器或桌面的 AI 应用；多租户代码执行平台；Agent 评估基准
• 不适合：纯 API 调用型 Agent（不需要沙箱）；对启动延迟极敏感的实时交互场景（预热池也救不了冷启动）；不需要隔离的内部工具

资源链接

十一、常见问题排查

实际跑 OpenSandbox 时容易踩的坑与排查路径：

1. Sandbox Server 启动失败

症状：opensandbox-server 命令报错或端口被占用。

排查步骤：

# 检查端口占用（默认端口）
lsof -i :8080
# 检查配置文件
cat ~/.sandbox.toml
# 查看日志
opensandbox-server --log-level debug

2. 代码执行超时

症状：SDK 调用 interpreter.codes.run() 长时间无响应。

可能原因：

• sandbox 镜像未正确拉取
• 网络隔离导致无法访问外部依赖
• 代码本身有死循环

排查步骤：

# 设置超时
sandbox = await Sandbox.create(..., timeout=timedelta(seconds=30))
# 检查 sandbox 状态
print(sandbox.status)

3. Kubernetes 模式下 sandbox 创建慢

症状：在 Kubernetes 模式下创建 sandbox 需要几十秒。

原因：镜像拉取时间长，预热池未配置。

修复：配置预热池（pre-warmed pools），提前创建好 sandbox 实例。

4. Egress 控制导致依赖安装失败

症状：在 Code Interpreter 里 pip install 失败，报网络错误。

原因：Egress 控制默认可能阻止公网访问。

修复：在 sandbox.toml 里配置 Egress 白名单，允许访问 PyPI 镜像源。

5. 多语言 SDK 类型不匹配

症状：Java SDK 调用时报类型错误。

原因：SDK 版本不匹配或类型定义有变化。

修复：检查 SDK 版本，确保与服务端版本兼容。查看 sdks/ 目录下对应 SDK 的 README。

十二、练习

练习一：本地跑通 OpenSandbox Docker 模式

1. 初始化配置：uvx opensandbox-server init-config ~/.sandbox.toml --example docker
2. 启动 server：uvx opensandbox-server
3. 安装 Code Interpreter SDK：uv pip install opensandbox-code-interpreter
4. 运行本文"快速开始"的基本使用示例，确认沙箱能创建、代码能执行
5. 记录：安装耗时、首次创建沙箱耗时、代码执行延迟

练习二：对比 Docker 模式与 Kubernetes 模式

1. 在 Docker 模式下跑通一个编程 Agent 示例（如 examples/claude-code）
2. 记录冷启动时间（从 Sandbox.create 到可执行命令）
3. 如果有 Kubernetes 测试环境，部署 kubernetes/ 目录下的资源
4. 配置预热池，对比冷启动时间差异
5. 评估：你的场景适合哪种模式？

练习三：用 osb CLI 完成一次沙箱生命周期

1. 安装 CLI：uv tool install opensandbox-cli
2. 初始化配置，指向本地启动的 server（localhost:8080）
3. 用 osb sandbox create 创建沙箱，记录创建耗时
4. 用 osb command run 执行命令并查看输出
5. 删除沙箱，记录完整生命周期的操作耗时

十三、自测题

用以下 5 题检验理解程度。答案折叠在每题下方。

Q1：OpenSandbox 五层架构中，哪一层负责定义生命周期管理 API 和执行 API？

答案：协议层（Protocol Layer）。它用 OpenAPI 规范定义接口，让多语言 SDK 能保持一致行为。

Q2：内置沙箱环境中，Chrome、Playwright、Desktop 分别面向什么任务？

答案：Chrome 用于浏览器自动化与调试（VNC + DevTools）；Playwright 用于 Web 自动化测试与无头抓取；Desktop 提供带 VNC 的完整桌面环境，适合需要图形界面的操作。

Q3：为什么需要预热池（Pre-warmed pools）？

答案：创建一个 sandbox 要拉镜像、起容器、初始化运行时，冷启动可能要几秒到几十秒。AI Agent 的代码执行通常是高频短任务，如果每次都冷启动，用户体验会非常差。预热池把这部分延迟摊到空闲期。

Q4：OpenSandbox 与 E2B 的主要差异是什么？

答案：E2B 是商业化的代码执行沙箱，SDK 以 Python 为主，浏览器环境支持较弱；OpenSandbox 提供完整五层平台（SDK、协议、运行时、环境、隔离），支持多语言 SDK、Kubernetes 原生、多种沙箱环境，且已被 CNCF Landscape 收录。

Q5：下面哪个场景不适合用 OpenSandbox？

A. 需要执行任意代码的 AI 应用 B. 对启动延迟极敏感的实时交互场景 C. 多租户代码执行平台 D. Agent 评估基准

答案：B。创建沙箱需要拉镜像、起容器、初始化运行时，冷启动以秒计，预热池只能摊薄这部分延迟，无法把交互延迟压到实时阈值以下；纯 API 调用型 Agent 和不需要隔离的内部工具同样不适合。

十四、进阶路径

读完本文后，按以下顺序深入：

1. 跑通最小示例：按"快速开始"章节安装，用 Docker 模式跑通基本使用示例，确认环境正常。
2. 切换 sandbox 环境：同一任务分别用 Code Interpreter、Chrome、Playwright 环境跑一遍，理解不同环境的适用场景。
3. 上 Kubernetes 模式：在测试集群里部署 kubernetes/ 目录下的资源，配置预热池，记录冷启动时间与资源消耗。
4. 自定义镜像：基于 sandboxes/code-interpreter/ 自定义镜像，增加项目需要的依赖，保持 entrypoint 协议不变。
5. 读源码：从 server/ 目录开始，理解 FastAPI 服务如何管理 sandbox 生命周期，再看 components/execd/ 理解命令执行流程。
6. 读协议与 OSEP：从 specs/ 的 OpenAPI 契约入手，再看 oseps/ 里的增强提案（如 OSEP-0005 客户端沙箱池、OSEP-0008 快照暂停/恢复），理解设计演进方向。
7. 贡献社区：OpenSandbox 是开源项目，可以贡献新的 sandbox 环境、改进文档或提交 bug fix。

十五、总结

OpenSandbox 把"为 AI Agent 提供隔离执行环境"做成了可交付的平台：多语言 SDK 屏蔽语言差异，统一沙箱协议让运行时可替换，Docker/Kubernetes 覆盖从本地实验到生产调度，gVisor、Kata、Firecracker 提供不同强度的隔离边界。对要构建安全 AI 应用平台的开发者来说，它把"环境隔离"这件基础设施的复杂度打包成了现成组件。

如果你已经有可用的沙箱方案，迁移到 OpenSandbox 前值得先确认两件事：你的负载是否需要预热池这类高吞吐能力，以及 egress 白名单能否覆盖你依赖的下载源。

资料口径说明

本文基于 OpenSandbox 官方仓库（alibaba/OpenSandbox）公开文档整理，需要说明的边界：

1. 性能数据来源：文中提到的性能数据来自官方文档和社区反馈，未在标准化测试环境中验证，实际性能因硬件配置而异。
2. 版本时效性：OpenSandbox 处于活跃开发阶段，版本更新可能带来 API 变化。本文数据与命令示例基于 2026-09-05 的仓库状态，请以官方 GitHub 仓库的最新代码为准。
3. 安全容器选择：gVisor/Kata/Firecracker 的隔离强度和性能损失因版本和配置而异，本文未提供具体的性能对比数据，建议用户自行验证。
4. Kubernetes 部署：文中提到的 Kubernetes 部署方案基于官方文档，实际部署时需要根据集群环境调整配置。
5. CNCF Landscape 收录：文中提到 CNCF Landscape 已收录 OpenSandbox，具体状态请访问 CNCF Landscape 确认。
6. 判断边界：本文对 OpenSandbox 适用场景的判断基于其设计目标和技术特征，具体采用决策请结合业务场景评估。
7. 架构划分：本文按官方 README 的 Features 归纳为 SDK、协议、运行时、沙箱环境、容器运行时五层；官方架构文档另有"客户端 / 协议 / 生命周期控制面 / 运行时后端 / 沙箱数据面 / 网络安全面"的六面划分，两者是对同一系统的不同粒度描述。

相关话题标签

#OpenSandbox #沙箱 #AI 平台 #Docker #Kubernetes #CNCF

来源

• GitHub：https://github.com/alibaba/OpenSandbox
• CNCF Landscape：https://landscape.cncf.io/

OpenSandbox 由阿里巴巴开源，采用 Apache-2.0 许可证，已被 CNCF Landscape 收录。数据截至 2026-09-05，以仓库实际状态为准。