OpenSandbox 实战指南：为 AI Agent 构建安全的代码执行沙箱

从零开始部署阿里巴巴开源的 AI 沙箱平台，解决 AI Agent 代码执行的安全隐患

OpenSandbox 是阿里巴巴开源的 AI 应用通用沙箱平台，专门用于安全、隔离地运行 AI 代理生成的代码、自动化脚本以及桌面应用交互。

无论是本地开发还是生产部署，OpenSandbox 都提供了标准化的解决方案。该项目的诞生，正是为了解决 AI 代理在自主执行代码时带来的安全与运维挑战。

本指南将带你快速上手 OpenSandbox，从零开始在本地部署并运行一个沙箱实例。

🔍 什么是 OpenSandbox？

OpenSandbox 是一个专为 AI 应用设计的通用沙箱平台，它提供了一个安全、隔离的环境，用于执行 AI 生成的代码。你可以把它想象成一个 "数字隔离病房" ——AI 可以在里面写代码、跑脚本、操作文件，但所有操作都被隔离在一个安全的容器里，完全不会影响到宿主系统。

项目的核心价值在于，它提供了标准化的安全环境，让开发者无需从头构建复杂的防御体系，即可将本地原型无缝迁移至生产级的分布式部署架构中。

核心特性

• 🛡️ 安全隔离：基于 Docker 容器的完全隔离执行环境
• 🔧 标准化 API：统一的接口，支持本地开发和生产部署
• 📦 开箱即用：简单的安装和配置，快速启动
• 🌐 多场景支持：代码解释器、自动化测试、数据处理、强化学习等
• 📊 可监控：完整的日志记录和审计功能

💡 为什么要使用 OpenSandbox？

随着 AI Agent 技术的快速发展，越来越多的应用需要让 AI 自主执行代码。但这种能力也带来了严重的安全和运维挑战：

真实案例：传统 AI Agent 框架的安全隐患

在实际项目中，我们发现很多 AI Agent 框架没有内置沙箱机制，这带来了严重的安全风险：

常见问题：

• ❌ AI 生成的代码直接在宿主机上执行
• ❌ 可能意外删除重要文件（如 rm -rf 命令）
• ❌ 可以访问宿主机的敏感数据（环境变量、配置文件、SSH 密钥等）
• ❌ 可能安装恶意软件或创建后门
• ❌ 无法限制资源使用，AI 可能创建无限循环耗尽 CPU/内存
• ❌ 没有隔离机制，一个任务的错误可能影响整个系统

后果：

想象一下，你让 AI Agent 帮你处理一个数据分析任务，但它执行的代码不小心删除了你的项目文件夹，或者泄露了你的 API 密钥。这种风险在生产环境中是不可接受的。

OpenSandbox 的解决方案

OpenSandbox 正是为了解决这类问题而生的：

• ✅ 完全隔离：所有代码在 Docker 容器中执行，与宿主机完全隔离
• ✅ 文件系统保护：沙箱内的操作不会影响宿主机文件
• ✅ 网络隔离：可以限制沙箱的网络访问权限
• ✅ 资源限制：内置超时机制，自动清理空闲沙箱
• ✅ 可追溯：所有操作都有日志记录，便于审计

效果：

即使 AI 生成了恶意代码或执行了危险操作，也只会影响沙箱容器本身，不会对宿主机造成任何损害。沙箱销毁后，一切恢复原状。

对比总结

特性	传统 AI Agent（无沙箱）	OpenSandbox（有沙箱）
代码执行环境	宿主机直接执行	Docker 容器隔离执行
文件系统安全	❌ 可访问和修改宿主机文件	✅ 仅访问沙箱内文件
数据泄露风险	❌ 可读取环境变量、密钥	✅ 隔离的环境变量
资源控制	❌ 无法限制 CPU/内存	✅ 内置超时和资源限制
错误影响范围	❌ 可能影响整个系统	✅ 仅影响沙箱容器
生产环境适用性	❌ 不推荐	✅ 生产级安全标准

5 个核心使用理由

除了安全性，OpenSandbox 还提供了以下价值：

1. 安全问题：AI 生成的代码不可信

• 风险：AI 可能生成恶意代码、意外删除文件、访问敏感数据
• 传统方案：手动审查每一行代码（效率低、不可扩展）
• OpenSandbox 方案：在隔离容器中运行，即使代码有问题也不会影响宿主机

2. 环境隔离：避免依赖冲突

• 场景：不同任务需要不同的 Python 版本、系统库、依赖包
• 传统方案：使用虚拟环境（只能隔离 Python 包，无法隔离系统级依赖）
• OpenSandbox 方案：每个沙箱都是独立的容器环境，完全隔离

3. 资源控制：防止资源耗尽

• 风险：AI 可能创建无限循环、消耗大量 CPU/内存
• 传统方案：手动监控和限制（复杂且容易遗漏）
• OpenSandbox 方案：内置超时机制、资源限制、自动清理

4. 标准化：从开发到生产的一致性

• 挑战：本地测试环境和生产环境差异导致的问题
• 传统方案：分别维护多套环境配置
• OpenSandbox 方案：统一的 API，本地原型无缝迁移到生产环境

5. 典型应用场景

• AI 代码解释器：安全执行用户提交的代码（如 Jupyter Notebook）
• 自动化测试：在隔离环境中运行测试用例
• 数据处理管道：处理不可信数据源
• 强化学习训练：在沙箱中训练 AI agent
• GUI 自动化：安全地操作桌面应用

OpenSandbox 的核心理念是：让 AI 自由发挥，但限制在安全边界内。

🚀 快速上手：本地部署与使用

环境准备

开始前，请确保你的本地环境满足以下要求：

1. Docker：已安装并正在运行（版本 20.10 以上）
2. Python：3.10 或更高版本
3. uv：推荐的 Python 包管理器
4. 操作系统：Linux、macOS 或 Windows（需 WSL2）

1. 安装并配置沙箱服务器

首先，在终端中安装 opensandbox-server 包，并生成一个针对 Docker 运行时的示例配置文件。

uv pip install opensandbox-server
opensandbox-server init-config ~/.sandbox.toml --example docker

2. 启动沙箱服务器

使用以下命令启动服务器。默认情况下，服务会运行在 localhost:8080。

opensandbox-server

查看启动时终端的输出日志，确认服务已成功运行。

3. 安装 Python SDK

打开一个新的终端窗口，安装 OpenSandbox 的 Python SDK 和代码解释器扩展包：

uv pip install opensandbox-code-interpreter

重要：预拉取 Docker 镜像

在运行演示脚本之前，必须先预拉取所需的 Docker 镜像。如果直接运行 opensandbox_demo.py，可能会因为首次拉取镜像超时而失败。

# 使用国内镜像源预拉取（推荐）
docker pull sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/code-interpreter:v1.0.2

# 验证镜像是否成功拉取
docker images | grep code-interpreter

这一步非常重要，因为：

• 首次创建沙箱时，如果镜像不存在，Sandbox.create() 会自动尝试拉取镜像
• 国内网络访问 Docker Hub 较慢，容易导致超时错误（httpx.ReadTimeout）
• 提前拉取镜像可以显著加快沙箱创建速度，避免不必要的超时问题

4. 创建并运行你的第一个沙箱

现在，通过一个完整的 Python 脚本来验证所有组件是否正常工作。

import asyncio
import httpx
from datetime import timedelta

from code_interpreter import CodeInterpreter, SupportedLanguage
from opensandbox import Sandbox
from opensandbox.config import ConnectionConfig
from opensandbox.models import WriteEntry

async def main() -> None:
    # 配置连接(设置更长的超时时间)
    config = ConnectionConfig(
        domain="http://localhost:8080",  # Docker Desktop 默认地址
        use_server_proxy=False,  # 尝试禁用 server proxy 模式
        request_timeout=timedelta(seconds=120),  # 增加请求超时到 120 秒
        transport=httpx.AsyncHTTPTransport(
            limits=httpx.Limits(max_connections=20)
        ),
    )
    
    print("正在创建沙箱...")
    print(f"配置: {config}")
    
    # 1. Create a sandbox
    sandbox = await Sandbox.create(
        # 使用阿里云镜像源(国内网络更快)
        "sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/code-interpreter:v1.0.2",
        # "opensandbox/code-interpreter:v1.0.2",  # 原 Docker Hub 镜像
        entrypoint=["/opt/opensandbox/code-interpreter.sh"],
        env={"PYTHON_VERSION": "3.11"},
        timeout=timedelta(hours=2),  # 空闲超时:2小时(不使用时自动清理)
        connection_config=config,  # 添加连接配置
        ready_timeout=timedelta(seconds=120),  # 增加健康检查超时到 120 秒
        health_check_polling_interval=timedelta(seconds=5),  # 每 5 秒检查一次
    )
    
    print(f"✓ 沙箱创建成功! ID: {sandbox.id}")
    print(f"\n提示：现在容器正在运行，你可以打开 Docker Desktop 查看")
    print(f"按 Enter 键继续执行并清理沙箱...")
    input()

    async with sandbox:

        # 2. Execute a shell command
        execution = await sandbox.commands.run("echo 'Hello OpenSandbox!'")
        print(execution.logs.stdout[0].text)

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

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

        # 5. Create a code interpreter
        interpreter = await CodeInterpreter.create(sandbox)

        # 6. 执行 Python 代码（单次执行：直接传 language）
        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. Cleanup the sandbox
    await sandbox.kill()

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

将以上脚本保存为 demo.py，确保 opensandbox-server 正在运行，然后在终端执行 python demo.py。

如果一切顺利，你将看到类似下面的输出：

至此，你已经成功运行了自己的第一个 OpenSandbox 沙箱！

📜 总结
OpenSandbox 通过标准化的 API,将复杂的容器管理、安全隔离和资源调度等基础设施细节进行了封装,为解决 AI 应用的安全执行难题提供了生产级的解决方案。本文带你从零开始,在本地通过 Docker 完成了 OpenSandbox 的部署和基本使用。未来,你还可以基于此扩展到更复杂的场景,如 GUI 自动化、强化学习训练等。

⚠️ 实际使用中的常见问题与解决方案

根据实际使用经验，以下是遇到的一些常见问题及其解决方案：

问题 1：沙箱创建超时

现象：执行 Sandbox.create() 时出现 httpx.ReadTimeout 错误

原因：

1. 国内网络访问 Docker Hub 较慢，镜像拉取超时
2. 默认 HTTP 请求超时时间设置过短

解决方案：

from opensandbox.config import ConnectionConfig
from datetime import timedelta
import httpx

# 显式配置连接参数,增加超时时间
config = ConnectionConfig(
    domain="http://localhost:8080",
    use_server_proxy=False,  # 禁用server proxy模式
    request_timeout=timedelta(seconds=120),  # 设置为120秒
    transport=httpx.AsyncHTTPTransport(
        limits=httpx.Limits(max_connections=20)
    ),
)

sandbox = await Sandbox.create(
    "sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/code-interpreter:v1.0.2",  # 使用阿里云镜像
    entrypoint=["/opt/opensandbox/code-interpreter.sh"],
    env={"PYTHON_VERSION": "3.11"},
    timeout=timedelta(hours=2),
    connection_config=config,
    ready_timeout=timedelta(seconds=120),
    health_check_polling_interval=timedelta(seconds=5),
)

注意：不要尝试在 AsyncHTTPTransport 中设置 timeout 参数，该参数不被支持。

问题 2：健康检查超时

现象：Sandbox health check timed out after 120.0s，提示 server proxy mode enabled

原因：客户端配置 use_server_proxy=True 启用了服务端代理模式，但本地运行的 Server 未正确支持该模式

解决方案：确保 ConnectionConfig 中 use_server_proxy=False，使客户端直连沙箱容器

问题 3：API 路径不匹配导致 404 错误

现象：SDK 请求 /api/sandboxes 返回 404，而实际有效路径是 /v1/sandboxes

原因：SDK 默认请求路径与 Server 实际暴露路径不一致

解决方案：

1. 优先通过 OpenAPI 文档 (http://localhost:8080/docs) 确认 Server 真实路径
2. 确保 SDK 版本与 Server 版本兼容
3. ConnectionConfig 中避免冗余配置（如自定义 transport），仅设置 domain 和 use_server_proxy 即可

问题 4：首次运行必须预拉取镜像

现象：直接执行 opensandbox_demo.py 时报错 httpx.ReadTimeout

原因分析：

1. Sandbox.create() 在首次运行时需要拉取 Docker 镜像
2. 国内网络环境下，从 Docker Hub 或阿里云镜像仓库拉取镜像可能需要较长时间
3. 如果拉取时间超过 ready_timeout 设置，就会触发超时错误

解决方案：
在首次运行演示脚本之前，务必先手动拉取镜像：

# 使用国内镜像源预拉取
docker pull sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/code-interpreter:v1.0.2

# 验证镜像是否存在
docker images | grep code-interpreter

完整的运行流程：

# 1. 启动 OpenSandbox Server
opensandbox-server

# 2. 在新终端中预拉取镜像
docker pull sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/code-interpreter:v1.0.2

# 3. 等待镜像拉取完成后，运行演示脚本
python opensandbox_demo.py

注意：如果已经成功拉取过镜像，后续运行可以直接执行演示脚本，无需重复拉取。

问题 5：配置建议总结

推荐的 ConnectionConfig 配置：

from opensandbox.config import ConnectionConfig
from datetime import timedelta
import httpx

config = ConnectionConfig(
    domain="http://localhost:8080",  # 本地Server地址
    use_server_proxy=False,  # 禁用server proxy模式
    request_timeout=timedelta(seconds=120),  # 增加请求超时时间
    transport=httpx.AsyncHTTPTransport(
        limits=httpx.Limits(max_connections=20)
    ),
)

sandbox = await Sandbox.create(
    "sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/code-interpreter:v1.0.2",
    connection_config=config,
    ready_timeout=timedelta(seconds=120),
    health_check_polling_interval=timedelta(seconds=5),
    timeout=timedelta(hours=2),
)

避免的配置：

1. 不要在 AsyncHTTPTransport 中设置 timeout 参数
2. 不要启用 use_server_proxy=True（除非 Server 明确支持）
3. 不要使用过短的超时时间（默认值在国内网络环境下可能不够）