前言

随着 AI Agent 从"对话生成"演进到"自主执行"，一个核心工程问题浮出水面：如何为 LLM 驱动的代码执行提供安全、标准化、可扩展的运行环境。

OpenSandbox 是阿里巴巴开源的通用沙箱平台，已进入 CNCF Landscape。它提供多语言 SDK、统一的沙箱协议、可插拔的运行时后端（Docker/Kubernetes），覆盖 Coding Agent、GUI Agent、代码解释器、RL 训练等场景。

本文将从功能架构、使用方式、网络管控三个维度对 OpenSandbox 进行系统性介绍，并分析其对于 AI Agent 系统的工程必要性。

---

一、AI Agent 为什么需要沙箱

1.1 问题本质

当 AI Agent 具备代码执行能力时，其输出本质上是不可信的用户输入。LLM 生成的代码可能：

• 执行破坏性操作（rm -rf /、DROP TABLE）
• 读取敏感信息（环境变量、密钥文件、云 metadata 接口）
• 发起恶意网络请求（数据外泄、内网扫描）
• 消耗系统资源（死循环、fork bomb、内存泄漏）

1.2 判断标准

一个简明的判断标准：AI 的输出是否会被当作代码或命令执行？

• 纯文本生成（RAG、聊天、摘要）→ 不需要沙箱
• 代码执行（Code Interpreter、Coding Agent、自动化测试）→ 需要沙箱

1.3 为什么不直接用 Docker

直接使用 Docker 容器执行代码在技术上可行，但存在以下工程缺口：

缺口	说明
生命周期管理	需要自行实现创建、超时回收、暂停恢复
执行 API	需要自行实现容器内命令执行和结果回传
文件操作	需要自行实现文件上传/下载协议
网络管控	需要自行配置 iptables/网络策略
多语言接入	需要为每种语言编写客户端
可观测性	需要自行实现日志、指标采集

OpenSandbox 的定位正是填补这些缺口：在容器运行时之上提供标准化的沙箱编排层。

---

二、OpenSandbox 架构概览

2.1 系统组件

┌─────────────────────────────────────────────────────────┐
│                    客户端层                               │
│  Python SDK │ Java SDK │ JS SDK │ C# SDK │ Go SDK │ CLI │
└──────────────────────────┬──────────────────────────────┘
                           │ REST API
                           ▼
┌─────────────────────────────────────────────────────────┐
│              OpenSandbox Server (FastAPI)                │
│  生命周期管理 │ 认证 │ 资源配额 │ 状态追踪 │ 定时清理    │
└──────────────────────────┬──────────────────────────────┘
                           │
              ┌────────────┼────────────┐
              ▼                         ▼
┌──────────────────────┐   ┌──────────────────────────┐
│   Docker Runtime     │   │   Kubernetes Runtime     │
│   (本地开发)          │   │   (生产/分布式)           │
└──────────┬───────────┘   └──────────┬───────────────┘
           │                          │
           ▼                          ▼
┌──────────────────────────────────────────────────────┐
│                   沙箱容器                             │
│  ┌─────────┐  ┌──────────────┐  ┌────────────────┐  │
│  │  execd  │  │ Egress Sidecar│  │ 用户工作负载    │  │
│  │(执行守护)│  │ (网络管控)    │  │ (Python/Node等)│  │
│  └─────────┘  └──────────────┘  └────────────────┘  │
└──────────────────────────────────────────────────────┘

2.2 核心组件职责

组件	职责
Server	沙箱生命周期管理（创建、暂停、恢复、销毁）、API 认证、资源配额
execd	沙箱内执行守护进程，提供命令执行和文件操作的 HTTP API
Egress	网络出站控制 Sidecar，基于域名/IP 的流量过滤
Ingress	流量入站代理，支持 Header/URI 路由模式
SDKs	多语言客户端库，封装 REST API 调用
CLI	命令行工具 osb，用于交互式沙箱管理

---

三、功能详解

3.1 沙箱生命周期管理

OpenSandbox 定义了完整的沙箱状态机：

Pending → Running → Paused → Resuming → Running → Stopping → Terminated
                                                            → Failed

关键能力：

• TTL 管理：创建时指定超时时间，到期自动销毁
• 续期机制：活跃沙箱可通过 API 延长生命周期
• 暂停/恢复：保存沙箱状态，释放计算资源，需要时恢复
• 异步创建：后台预创建，减少用户感知延迟

3.2 命令执行与文件操作

通过 execd 守护进程，SDK 可以在沙箱内执行任意操作：

import asyncio
from datetime import timedelta
from opensandbox import Sandbox
from opensandbox.models import WriteEntry

async def main():
    sandbox = await Sandbox.create(
        "python:3.11-slim",
        entrypoint=["sleep", "infinity"],
        timeout=timedelta(minutes=10),
    )

    async with sandbox:
        # 执行命令
        result = await sandbox.commands.run("pip install pandas && python -c 'import pandas; print(pandas.__version__)'")
        print(result.logs.stdout[0].text)

        # 写入文件
        await sandbox.files.write_files([
            WriteEntry(path="/workspace/analysis.py", data="import pandas as pd\nprint('ready')", mode=644)
        ])

        # 读取文件
        content = await sandbox.files.read_file("/workspace/analysis.py")
        print(content)

        # 执行脚本
        result = await sandbox.commands.run("python /workspace/analysis.py")
        print(result.logs.stdout[0].text)

    await sandbox.kill()

asyncio.run(main())

3.3 网络出站控制（Egress）

Egress 组件是 OpenSandbox 的安全核心之一，通过 Sidecar 模式实现域名级别的出站流量管控。

工作原理：

沙箱应用发起 DNS 查询
    │
    ▼ (iptables 重定向)
Egress DNS 代理 (127.0.0.1:15353)
    │
    ├── 域名在白名单中 → 正常解析，返回 IP
    │                      └── (dns+nft 模式) 将 IP 加入 nftables 放行集合
    │
    └── 域名不在白名单中 → 返回 NXDOMAIN（解析失败）

两种执行模式：

模式	机制	安全级别
dns	仅 DNS 过滤	中等（可通过直接 IP 绕过）
dns+nft	DNS + nftables IP 过滤	高（默认拒绝所有出站，仅放行已解析的白名单 IP）

配置示例：

sandbox = await Sandbox.create(
    "python:3.11-slim",
    entrypoint=["sleep", "infinity"],
    network_policy={
        "defaultAction": "deny",
        "egress": [
            {"action": "allow", "target": "*.pypi.org"},
            {"action": "allow", "target": "files.pythonhosted.org"},
            {"action": "allow", "target": "api.openai.com"},
        ]
    },
)

运行时动态调整：

curl -XPOST http://127.0.0.1:18080/policy \
  -d '{"defaultAction":"deny","egress":[{"action":"allow","target":"*.github.com"}]}'

3.4 多语言 SDK

OpenSandbox 提供五种语言的客户端 SDK：

语言	安装方式
Python	pip install opensandbox
Java/Kotlin	com.alibaba.opensandbox:sandbox
JavaScript/TypeScript	npm install @alibaba-group/opensandbox
C#/.NET	dotnet add package Alibaba.OpenSandbox
Go	go get github.com/alibaba/OpenSandbox/sdks/sandbox/go

这使得不同技术栈的 Agent 系统都可以统一接入沙箱能力。

3.5 Code Interpreter

OpenSandbox 提供专门的 Code Interpreter SDK，支持多语言代码执行：

from code_interpreter import CodeInterpreter, SupportedLanguage

interpreter = await CodeInterpreter.create(sandbox)

result = await interpreter.codes.run(
    """
    import numpy as np
    data = np.random.randn(1000)
    print(f"mean: {data.mean():.4f}, std: {data.std():.4f}")
    """,
    language=SupportedLanguage.PYTHON,
)
print(result.logs.stdout[0].text)

3.6 MCP 集成

OpenSandbox 提供 MCP（Model Context Protocol）Server，可直接被 Claude Code、Cursor 等 AI 工具调用：

{
  "mcpServers": {
    "opensandbox": {
      "command": "opensandbox-mcp",
      "args": ["--domain", "localhost:8080", "--protocol", "http"]
    }
  }
}

3.7 可插拔隔离后端

OpenSandbox 的运行时层支持多种容器运行时：

运行时	隔离级别	适用场景
Docker (runc)	命名空间隔离	开发/测试
gVisor (runsc)	用户态内核	生产（中等安全需求）
Kata Containers	轻量 VM	生产（高安全需求）
Firecracker	MicroVM	生产（极高安全需求）

切换运行时只需修改 Docker daemon 配置，上层 SDK 和 API 无需变更。

---

四、部署与使用

4.1 本地快速启动

# 安装并初始化配置
uvx opensandbox-server init-config ~/.sandbox.toml --example docker

# 启动服务
uvx opensandbox-server

4.2 Docker Compose 部署

services:
  opensandbox-server:
    image: opensandbox/server:latest
    ports:
      - "8090:8090"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - SANDBOX_CONFIG_PATH=/etc/opensandbox/config.toml

4.3 Kubernetes 部署

OpenSandbox 提供完整的 Kubernetes 部署方案，包括 CRD（BatchSandbox）、Operator、Ingress Controller 等组件，支持大规模分布式调度。

4.4 CLI 使用

# 安装
pip install opensandbox-cli

# 配置
osb config init
osb config set connection.domain localhost:8080
osb config set connection.protocol http

# 创建沙箱
osb sandbox create --image python:3.12 --timeout 30m -o json

# 执行命令
osb command run <sandbox-id> -o raw -- python -c "print(1 + 1)"

# 销毁沙箱
osb sandbox delete <sandbox-id>

---

五、集成到现有 Agent 系统

5.1 典型集成架构

┌─────────────────────────────────────────────────┐
│  Agent 应用（LangChain / LangGraph / 自研）      │
│                                                 │
│  def execute_code(code: str):                   │
│      sandbox = await Sandbox.create(...)        │
│      result = await sandbox.commands.run(code)  │
│      return result                              │
└────────────────────┬────────────────────────────┘
                     │ HTTP (SDK 封装)
                     ▼
┌─────────────────────────────────────────────────┐
│  OpenSandbox Server                             │
│  (可与 Agent 同在一个 docker-compose 中)         │
└────────────────────┬────────────────────────────┘
                     │ docker.sock
                     ▼
┌─────────────────────────────────────────────────┐
│  沙箱容器（按需创建，用完销毁）                    │
└─────────────────────────────────────────────────┘

5.2 集成步骤

1. docker-compose 中添加 OpenSandbox Server 服务
2. Agent 代码中安装对应语言的 SDK
3. 将原有的"直接执行"逻辑替换为"通过 SDK 在沙箱中执行"
4. 配置网络策略（可选）

5.3 会话级沙箱复用

对于多轮对话场景，建议在会话开始时创建沙箱，整个对话期间复用同一个沙箱实例：

class AgentSession:
    async def start(self):
        self.sandbox = await Sandbox.create(
            "python:3.11-slim",
            entrypoint=["sleep", "infinity"],
            timeout=timedelta(minutes=30),
        )

    async def run_code(self, code: str) -> str:
        result = await self.sandbox.commands.run(f"python -c '{code}'")
        return "\n".join([log.text for log in result.logs.stdout])

    async def end(self):
        await self.sandbox.kill()

这样用户在对话中安装的依赖、创建的文件在后续轮次中仍然可用。

---

六、适用场景分析

6.1 适合使用 OpenSandbox 的场景

场景	说明
Coding Agent	AI 写代码、跑测试、修 bug，需要完整开发环境
Code Interpreter	数据分析、可视化、科学计算
浏览器自动化	Chromium + Playwright，GUI Agent
RL 训练/评测	大量并行环境，SWE-Bench 等 benchmark
多租户 SaaS	不同用户的代码需要互相隔离
Agent 框架集成	LangGraph、Google ADK 等框架的工具节点

6.2 不需要沙箱的场景

场景	原因
纯 RAG 系统	AI 只输出文本，不执行代码
聊天机器人	纯对话，无副作用操作
文档摘要/翻译	纯文本处理
结构化数据提取	输出 JSON，不执行

6.3 OpenSandbox vs 自建方案的选择

条件	建议
单一 Agent 产品，团队有容器管理经验	可自建（参考 DeerFlow 的实现）
多产品/多团队共享沙箱基础设施	使用 OpenSandbox
需要多语言 SDK 接入	使用 OpenSandbox
需要网络出站控制	使用 OpenSandbox（Egress 组件）
需要快速验证原型	使用 OpenSandbox（开箱即用）
已有深度定制的沙箱逻辑	保持自建，按需引入 OpenSandbox 组件

---

七、与同类方案的对比

维度	OpenSandbox	E2B	CubeSandbox
开源协议	Apache 2.0	部分开源	Apache 2.0
部署方式	自托管	SaaS	自托管
隔离后端	Docker/gVisor/Kata/Firecracker	Firecracker	KVM MicroVM
SDK 语言	5 种	Python/JS	Python (E2B 兼容)
网络管控	Egress Sidecar（域名级）	有限	eBPF（IP/CIDR 级）
启动速度	取决于运行时	~150ms	<60ms
适用规模	中小到大规模	中小规模	大规模

---

八、总结

OpenSandbox 的核心价值在于：

1. 标准化：定义了沙箱生命周期协议和执行 API，避免各 Agent 系统重复造轮子
2. 多语言生态：五种语言 SDK + CLI + MCP Server，降低集成门槛
3. 安全纵深：Egress 网络管控 + 可插拔隔离后端，满足不同安全等级需求
4. 部署灵活：从本地 Docker 到 Kubernetes 集群，覆盖开发到生产全链路
5. 生态开放：CNCF Landscape 项目，社区活跃，与主流 Agent 框架深度集成

对于正在构建 AI Agent 系统的团队，OpenSandbox 提供了一条从"直接执行代码"到"安全隔离执行"的标准化升级路径。其价值不在于替代 Docker 的隔离能力，而在于将沙箱管理从一个需要反复解决的工程问题，转化为一个开箱即用的基础设施服务。

---

参考资料：

• OpenSandbox GitHub 仓库：https://github.com/alibaba/OpenSandbox
• 官方文档：https://open-sandbox.ai/
• Egress 组件：components/egress/README.md
• Server 配置：server/configuration.md
• OpenAPI 规范：specs/README.md
• CNCF Landscape：https://landscape.cncf.io/?item=orchestration-management–scheduling-orchestration–opensandbox