如果你是一名AI Agent开发者，大概率经历过这样的窘境：为了让Agent同时完成“浏览网页下载论文”“用Python分析数据”“用VSCode编写脚本”这一系列操作，你得手动配置浏览器自动化环境、搭建Python运行环境、部署VSCode远程服务，还得费劲心思让这些工具之间能共享文件——往往光是环境配置就要花上大半天，最后却发现浏览器下载的文件终端读不到，VSCode编辑的代码Jupyter调用不了。
但现在，有一个开源项目彻底解决了这个问题——它就是agent-infra团队开发的AIO Sandbox。这个被称为“全功能AI Agent沙箱环境”的工具，把浏览器、终端、文件系统、VSCode Server、Jupyter Notebook甚至AI专用的MCP服务器，全都打包进了一个Docker容器里。不管是开发者手动调试，还是AI Agent自动执行任务，都能在这个统一的环境里完成，工具间无缝协作，文件实时共享，真正实现了“一键启动，开箱即用”。
一、什么是AIO Sandbox？解决了AI开发的哪些痛点？
在了解AIO Sandbox的具体用法前，我们得先搞清楚：它到底是什么，又能帮我们避开哪些“坑”？
简单来说，AIO Sandbox是一个云原生轻量级沙箱环境，核心目标是为AI Agent和开发者提供“一站式工作空间”。它不是单一工具，而是把AI开发中常用的6大类工具整合到了一起：
- 浏览器：支持可视化操作（VNC）和程序化控制（CDP协议），能自动浏览网页、下载文件；
- 终端：WebSocket-based的网页终端，可执行Linux命令，预配置了Python、Node.js、Git等工具；
- 文件系统：所有工具共享的存储空间，浏览器下载的文件、终端生成的结果、VSCode编辑的代码都在这里；
- VSCode Server：在浏览器里就能用的VSCode，支持代码高亮、插件扩展，和本地IDE体验一致；
- Jupyter Notebook：交互式Python环境，适合数据处理、模型调试，能直接调用沙箱里的文件和工具；
- MCP服务器：预配置的“模型上下文协议”服务，AI Agent能直接调用浏览器、文件、Shell等能力，不用写复杂接口。
而它要解决的，正是传统AI开发中的3大核心痛点：
痛点1：工具碎片化，协同效率低
传统开发中，浏览器、终端、代码编辑器都是独立的工具。比如你用Selenium控制浏览器下载了一篇PDF论文，想在Python里提取内容，得先把文件从浏览器的下载目录复制到Python的工作目录；如果要在VSCode里编辑提取脚本，又得确保VSCode能访问到这个目录——光是文件传递就要反复操作，更别说跨工具调试了。
AIO Sandbox的解决办法是统一文件系统：不管是浏览器下载的PDF、终端生成的日志，还是VSCode编辑的代码，都存放在同一个容器的文件系统里。比如你在VNC浏览器里下载了一篇Arxiv论文，不用任何额外操作，马上就能在终端里用pdf2txt命令提取文字，也能在VSCode里直接打开编辑，工具间的协同像“在同一个电脑上操作”一样自然。
痛点2：环境配置复杂，新手望而却步
AI Agent开发涉及的工具链非常长：浏览器自动化需要安装Chrome和ChromeDriver，Python环境需要配置依赖包，VSCode远程开发需要设置SSH或隧道，MCP服务需要部署服务器……哪怕是有经验的开发者，把这些环境搭好也得1-2小时，新手更是容易在“版本不兼容”“端口冲突”这些问题上卡壳。
AIO Sandbox用Docker容器化解决了这个问题：所有工具、依赖、配置都已经打包进Docker镜像，你只需要执行一条docker run命令，30秒内就能启动完整的开发环境，不用手动安装任何依赖。哪怕是刚入门的开发者，也能立刻开始调试AI Agent，不用再跟环境配置“死磕”。
痛点3：AI Agent集成难，需要重复造轮子
要让AI Agent调用浏览器、执行Shell命令，你得自己写API接口、处理权限控制、做错误捕获——比如为了让Agent能下载论文，你要写一个基于Playwright的浏览器控制接口，再写一个文件存储接口，还要考虑并发安全问题。这些工作重复且繁琐，却又是每个AI Agent项目都要做的。
AIO Sandbox预配置了MCP兼容API，把浏览器导航、文件读写、Shell执行这些常用能力都封装成了标准化接口。AI Agent不用关心底层实现，直接调用browser.navigate“命令”就能打开网页，调用file.write就能保存文件，甚至能通过Arxiv服务器直接搜索、下载论文。相当于给AI Agent提供了一套“现成的工具包”，开发者不用再重复造轮子。
二、30秒上手：AIO Sandbox启动与访问指南
AIO Sandbox的最大优势就是“简单”——哪怕你对Docker了解不多，只要会复制粘贴命令，就能快速启动环境。下面我们分步骤讲解如何上手，包括普通用户、中国大陆用户的不同启动方式，以及启动后如何访问各个工具。
1. 前提条件：安装Docker
首先你需要在电脑上安装Docker（Windows、macOS、Linux都支持）。安装方法很简单：
- Windows/macOS：下载Docker Desktop，双击安装后启动；
- Linux：执行
sudo apt-get install docker-ce docker-ce-cli containerd.io（Ubuntu为例）。
安装完成后，打开终端输入docker --version，能看到版本号就说明安装成功了。
2. 启动AIO Sandbox：一条命令搞定
AIO Sandbox提供了不同地区的镜像，你可以根据自己的位置选择对应的命令：
（1）普通用户（非中国大陆）
执行以下命令启动最新版本的AIO Sandbox：
docker run --rm -it -p 8080:8080 ghcr.io/agent-infra/sandbox:latest（2）中国大陆用户
由于网络原因，中国大陆用户可以使用火山引擎的镜像，速度更快：
docker run --rm -it -p 8080:8080 enterprise-public-cn-beijing.cr.volces.com/vefaas-public/all-in-one-sandbox:latest（3）指定版本启动
如果需要稳定版本（避免最新版可能的bug），可以指定版本号，格式为agent-infra/sandbox:${version}。比如启动1.0.0.125版本：
# 普通用户
docker run --rm -it -p 8080:8080 ghcr.io/agent-infra/sandbox:1.0.0.125
# 中国大陆用户
docker run --rm -it -p 8080:8080 enterprise-public-cn-beijing.cr.volces.com/vefaas-public/all-in-one-sandbox:1.0.0.125命令中的参数含义：
--rm：容器停止后自动删除，避免占用磁盘空间；-it：交互式运行，能看到容器的日志输出；-p 8080:8080：把容器的8080端口映射到本地的8080端口，通过本地8080端口访问环境。
执行命令后，等待镜像下载完成（第一次启动可能需要几分钟，取决于网络速度），当终端出现“Sandbox started successfully”的提示时，就说明环境启动成功了。
3. 访问各个工具：5个核心入口
启动后，你可以通过浏览器访问以下地址，使用AIO Sandbox的各种功能：
| 工具/服务 | 访问地址 | 用途 |
|---|---|---|
| 官方文档 | http://localhost:8080/v1/docs | 查看所有API的详细说明，包括参数、返回值 |
| VNC浏览器 | http://localhost:8080/vnc/index.html?autoconnect=true | 可视化操作浏览器，支持鼠标、键盘控制 |
| VSCode Server | http://localhost:8080/code-server/ | 浏览器中的VSCode，可编辑代码、安装插件 |
| MCP服务 | http://localhost:8080/mcp | 查看MCP服务器的工具列表，测试AI Agent调用 |
| Jupyter Notebook | 需通过VSCode或终端启动 | 交互式Python环境，执行代码片段 |
举个例子：打开http://localhost:8080/code-server/，你会看到一个完整的VSCode界面，左侧有文件浏览器，中间是编辑区，下方是终端——和本地安装的VSCode几乎没有区别。你可以在里面创建Python文件、安装依赖包，甚至连接Git仓库，所有操作都会保存在容器的文件系统里。
三、核心功能深度解析：从工具协同到AI集成
AIO Sandbox的强大之处，不仅在于“整合了多个工具”，更在于这些工具之间的“协同能力”和对AI Agent的“友好支持”。下面我们深入讲解几个核心功能，看看它是如何提升AI开发效率的。
1. 统一文件系统：工具间的“数据桥梁”
统一文件系统是AIO Sandbox的“灵魂”，也是它和传统工具最大的区别。在容器内部，所有工具都共享同一个文件空间，默认的用户目录是/home/gem（相当于Linux的~/）。
我们举一个实际场景来理解它的作用：假设你需要让AI Agent完成“下载Arxiv论文→提取文字→生成PPT”的任务，步骤如下：
- 浏览器下载论文：通过VNC浏览器打开Arxiv，下载一篇名为
1234.5678.pdf的论文，文件会自动保存到/home/gem/Downloads； - 终端提取文字：打开VSCode下方的终端，执行
pdf2txt.py /home/gem/Downloads/1234.5678.pdf > /home/gem/paper.txt，把PDF内容提取成文本文件； - VSCode编辑脚本：在VSCode里创建
generate_ppt.py，编写代码读取paper.txt的内容，用python-pptx生成PPT； - Jupyter运行代码：在Jupyter里运行
generate_ppt.py，生成的PPT文件paper.pptx会保存在/home/gem目录下； - 浏览器预览PPT：通过VNC浏览器打开
/home/gem/paper.pptx，直接预览生成的PPT。
在这个过程中，你不需要手动复制任何文件——浏览器下载的文件终端能直接访问，VSCode编辑的脚本Jupyter能直接运行，所有工具都围绕同一个文件系统工作，效率提升非常明显。
2. 浏览器自动化：3种控制方式，满足不同需求
AIO Sandbox的浏览器功能不仅支持可视化操作（VNC），还支持程序化控制，非常适合AI Agent自动完成网页相关任务。它提供了3种控制方式，覆盖不同场景：
（1）VNC：可视化操作，适合调试
通过http://localhost:8080/vnc/index.html访问的VNC浏览器，本质是一个“远程桌面”，你可以用鼠标点击、键盘输入，和本地浏览器完全一样。这种方式适合调试AI Agent的浏览器操作——比如你想确认Agent是否能正确打开某个网页，就可以通过VNC实时查看。
（2）CDP协议：代码控制，适合自动化
CDP（Chrome DevTools Protocol）是Chrome浏览器的调试协议，支持用代码控制浏览器的所有操作，比如打开网页、点击按钮、获取页面内容、截图等。AIO Sandbox的浏览器默认开启CDP服务，地址是ws://localhost:8080/browser/cdp。
下面是一个Python示例，用Playwright通过CDP控制浏览器截图：
from playwright.async_api import async_playwright
from agent_sandbox import Sandbox
async def browser_screenshot():
# 初始化沙箱客户端
client = Sandbox(base_url="http://localhost:8080")
# 获取浏览器CDP地址
browser_info = client.browser.get_browser_info().data
cdp_url = browser_info.cdp_url
# 连接CDP，控制浏览器
async with async_playwright() as p:
browser = await p.chromium.connect_over_cdp(cdp_url)
page = await browser.new_page()
await page.goto("https://example.com") # 打开网页
await page.screenshot(path="/home/gem/example.png") # 截图保存
await browser.close()
asyncio.run(browser_screenshot())这种方式不需要在本地安装Chrome，所有操作都在容器内完成，避免了“本地浏览器版本与代码不兼容”的问题。
（3）MCP工具：AI Agent“即插即用”
对于AI Agent来说，直接调用CDP协议还是有点复杂——AIO Sandbox的MCP服务器把浏览器操作封装成了更简单的“工具”，AI Agent只需要发送一个JSON请求，就能完成对应的操作。
比如要让AI Agent打开https://example.com并截图，只需要调用MCP的browser.navigate和browser.screenshot工具，不需要写复杂的CDP连接代码。这种“封装好的工具”让AI Agent能快速用上浏览器功能，不用关心底层实现。
3. MCP集成：为AI Agent打造的“工具超市”
MCP（Model Context Protocol）是AIO Sandbox为AI Agent设计的核心功能，它相当于一个“工具超市”，把浏览器、文件、Shell等常用能力封装成标准化的工具，AI Agent可以通过API直接调用。
目前AIO Sandbox预配置了5个MCP服务器，每个服务器提供不同的工具：
| MCP服务器 | 提供的工具 | 用途示例 |
|---|---|---|
| browser | navigate（导航）、screenshot（截图）、click（点击）、type（输入）、scroll（滚动） | 自动打开网页、填写表单、截图保存 |
| file | read（读取）、write（写入）、list（列表）、search（搜索）、replace（替换） | 读取文件内容、保存数据、查找指定文件 |
| shell | exec（执行命令）、create_session（创建会话）、kill（终止会话） | 执行Linux命令、运行脚本、查看命令输出 |
| markitdown | convert（转换）、extract_text（提取文字）、extract_images（提取图片） | HTML转Markdown、提取Markdown中的图片 |
| arxiv | search（搜索）、get_paper（获取论文信息）、download_pdf（下载PDF） | 搜索AI领域论文、下载论文PDF、获取论文摘要 |
你可以通过http://localhost:8080/mcp访问MCP Inspector，可视化测试这些工具。比如测试arxiv.search工具，输入关键词“GPT-4”，就能返回相关的论文列表，还能直接下载PDF到沙箱的文件系统里。
对于AI Agent开发者来说，MCP的价值在于“标准化”——不管你用LangChain、LLaMA Index还是自定义框架，都能通过统一的API调用这些工具，不用为每个工具单独写集成代码。
4. 开发工具集：一站式编码体验
AIO Sandbox整合了VSCode Server、Jupyter Notebook、终端等开发工具，并且做了优化，让编码体验更流畅：
（1）VSCode Server：浏览器里的“全能IDE”
通过http://localhost:8080/code-server/访问的VSCode Server，和本地VSCode几乎没有区别：
- 支持安装插件：比如Python、TypeScript、Docker等插件，直接在浏览器里安装；
- 集成终端：下方的终端可以执行Shell命令，支持多标签页；
- 代码补全：支持Python、JavaScript等语言的代码补全，依赖容器内的开发环境；
- 文件同步：所有代码都保存在容器的文件系统里，重启容器后不会丢失（如果挂载了卷）。
如果你习惯用VSCode，几乎不需要适应就能上手，而且不用在本地安装庞大的IDE，尤其适合在轻量设备（比如平板）上开发。
（2）Jupyter Notebook：交互式代码调试
AIO Sandbox预安装了Jupyter Notebook，你可以通过两种方式启动：
- 在VSCode里打开
.ipynb文件，直接在编辑区运行代码块； - 在终端执行
jupyter notebook --ip=0.0.0.0 --allow-root，通过http://localhost:8080/tree访问。
Jupyter的优势在于“交互式”——比如你需要调试一段Python代码，每写几行就能运行一次，查看结果，不用等整个脚本跑完。而且它能直接访问沙箱里的文件，比如读取/home/gem/paper.txt的内容，非常方便。
（3）端口转发：Web应用“一键预览”
如果你在沙箱里开发Web应用（比如用React、Vue写一个AI Agent的前端界面），启动服务后，AIO Sandbox会自动进行端口转发，让你在本地就能预览。
比如你用npm run dev启动一个React应用，默认端口是3000，AIO Sandbox会自动把容器的3000端口映射到本地，你只需要在浏览器里打开http://localhost:8080/forward/3000/，就能看到Web应用的界面，不用手动配置端口转发规则。
四、SDK使用教程：3种语言，轻松集成到项目中
AIO Sandbox提供了Python、TypeScript/JavaScript、Golang三种语言的SDK，开发者可以轻松把沙箱的功能集成到自己的AI Agent项目中。下面我们分别讲解这三种语言的基础用法，包括初始化客户端、执行Shell命令、文件操作、浏览器自动化等。
1. Python SDK：最常用的AI开发语言
Python是AI开发的主流语言，AIO Sandbox的Python SDK功能也最完善。
（1）安装SDK
首先通过pip安装SDK：
pip install agent-sandbox（2）基础用法示例
下面的代码演示了如何初始化客户端、执行Shell命令、读取文件、浏览器截图：
from agent_sandbox import Sandbox
# 1. 初始化沙箱客户端（base_url是沙箱的访问地址）
client = Sandbox(base_url="http://localhost:8080")
# 2. 获取沙箱上下文信息（比如用户目录）
sandbox_context = client.sandbox.get_sandbox_context()
home_dir = sandbox_context.data.home_dir # 获取用户目录，比如"/home/gem"
print(f"沙箱用户目录：{
浙公网安备 33010602011771号