AIO Sandbox：把浏览器、Shell、MCP和VSCode装进同一个Agent沙箱

做 Agent 项目的朋友应该都经历过这种循环：先配好 Playwright 环境，跑通一个浏览器自动化脚本；接着要执行清理命令，又得切到另一套容器；数据落到文件里，还得把卷挂出来让另一个服务读到。我自己之前维护的工具链就是这么碎，改一次镜像就牵一发动全身——直到我实际用了一遍 AIO Sandbox，这个开源项目做的事情用一句话就能讲完：把浏览器、Shell、文件、MCP、VSCode 全部集成进同一个容器，做成一个专门面向 Agent 的沙箱环境。这篇文章会从设计动机、组件分工、容器架构讲到实操部署，再把我测试时踩过的坑摊开来讲，希望能帮正在做 Agent 开发、AI 应用集成、工具调用的朋友少走点弯路。

1. 为什么 Agent 项目需要一个把什么都能塞进去的沙箱

1.1 "工具链是碎的"到底有多疼

大多数 Agent 项目不是一开始就想到要用沙箱的，是工具链碎到实在忍不了才去求一个容器。

我举一个很常见的场景：你要做一个"网页数据采集 + 本地脚本清洗 + 落盘输出"的 Agent。浏览器自动化你得准备一个环境，至少要有 Chromium、Playwright、截图依赖；shell 清洗脚本又得有 Python、ffmpeg、各种系统库；输出文件还要和宿主机的某个目录打通。很多人第一反应是开两个容器，一个跑浏览器，一个跑脚本，中间用 volume 或 API 传数据。听起来挺干净，可实际维护起来完全是另一个故事：两个容器的基础镜像要分别更新，环境变量各有一套，Python 版本还经常对不上。你在浏览器容器里装好的依赖，shell 容器里根本没有；shell 容器里生成的报表，浏览器容器又读不到。这种割裂带来的配置漂移，会在 Agent 跑批量任务时集中爆发。

更难受的是排障。Agent 一次任务在浏览器容器里执行到第 7 步，突然挂在文件读取上，你第一反应是进容器去看日志，结果发现路径不存在——为什么？因为上一个容器里挂载的路径和这个容器不一样。为了一个路径映射问题，我也见过有人硬编码了十几个环境变量，最后还是每次都要手动对齐。工具链分散带来的不只是环境维护成本，它会让 Agent 每一步的执行状态都变得不可预测。

1.2 Agent 在执行时到底需要哪些能力

大模型驱动的 Agent，工作循环本质上就是：规划、调用工具、观察结果、再规划。工具就是它和外界交互的手和脚，一个务实的 Agent 至少需要三种能力：能看懂网页的感知能力，能执行命令的操作能力，能读写文件的记忆与输出能力。

这三种能力如果分别部署，Agent 调用工具时就要跨进程、跨网络传递上下文。浏览器截完图，文件在容器 A 里；Shell 要去处理，得先传过去。单步调用看着没问题，一个长任务动辄几十步，每多一次跨容器传递，失败概率就翻一番。反过来，如果这些能力全在一个容器里，Agent 的每一步操作都落在同一个文件系统、同一组环境变量、同一个网络命名空间下。浏览器下载的附件就在 workspace 里，shell 命令能直接处理它，file 工具能读取结果，人还能通过 VSCode 随时看到全过程。状态的一致性，才是"塞进同一个容器"最大的价值。

1.3 All-in-One 不等于盲目堆料

有一点得说清楚：All-in-One 不是把能装的软件全部装一遍，那只会得到一个又大又脆的镜像。AIO Sandbox 这类项目的思路，是把 Agent 运行必需的能力层收拢成一个可复现的单元，而不是堆一个全功能桌面环境。每个组件有明确的职责边界，之间通过统一的协议和服务接口协作。

打个比方，这就像厨房里把所有厨具放在同一个操作台上，而不是把厨房改造成一间百货超市。操作台解决的是"动线"问题：洗菜、切菜、炒菜不用来回跑。对于 Agent 来说，这个"动线"就是工具调用的上下文与状态传递。所以你看这类沙箱项目，重点通常不是装了多少个软件，而是组件之间的目录怎么共享、服务怎么拉起、协议怎么统一。抓住了这个视角，后面看它的架构和配置就不会懵。

2. 拆开这个箱子：浏览器、Shell、文件、MCP、VSCode 各自扮演什么角色

2.1 浏览器组件：给 Agent 一双"眼睛"

浏览器组件是 Agent 感知能力最直接的表现。容器里通常会带一个 Chromium 内核，配合无头模式或者虚拟帧缓冲，让页面在没有任何显示器的环境里也能渲染出来。

MCP 工具一般会暴露 navigate、snapshot、screenshot、click 这些操作。navigate 让 Agent 打开指定地址；snapshot 提取页面可访问性树或简化文本；screenshot 直接出图。这里有个很关键的细节：纯文本模型依赖 snapshot 的内容，多模态模型可以直接看截图。两个模式接口不同，但解决的都是同一个问题——让 LLM 知道网页里到底有什么。

在实际跑数据采集任务时，浏览器组件的价值会被放大。网站如果是纯静态 HTML，snapshot 就够了；但遇到 React、Vue 这类前端渲染的页面，除了等网络请求结束，通常还得配合截图来确认界面渲染结果。这也是为什么很多 Agent 沙箱里不仅要有 headless Chromium，还要预留出截图落盘的目录。否则 Agent 看到的是空 DOM，推理再多也白搭。

2.2 Shell 组件：给 Agent 一双"手"

Shell 工具解决的是"怎么把计划变成现实"。装依赖、跑脚本、清理临时文件、批量重命名，都是通过执行命令完成的。你在沙箱里看到的是一个完整的 Linux 用户环境，PATH 里已经预置了常用的运行和管理工具。

面对 shell 能力要有个底线意识：Agent 一旦有了通用命令执行权，等于容器内有了一个低配管理员。所以合理的沙箱不会让 Agent 默认以 root 跑命令，而是专门开一个低权限用户，甚至把工作目录限定在具名空间，再配合审计日志记录每一步执行。给 Agent"手"可以，但得知道这双手能摸到哪。

另外还要考虑命令的交互性。很多模型喜欢直接执行 python -c 或者 node -e，而不是写脚本文件。这种写法适合短任务，但长任务最好落到文件再运行，既方便审计，也能避免一行命令太复杂导致转义错误。我会在工具说明里明确引导 Agent：复杂逻辑写进 /workspace/scripts 下的 .py/.sh 文件，再执行，输出结果写进文件而不是塞回工具返回值。

2.3 文件组件：一个所有组件共享的"工作台"

如果只让我保留一个理由往 All-in-One 这个方向倾斜，那就是共享文件系统。

沙箱里通常会有一个 workspace 目录，浏览器下载的文件落在里面，shell 命令的输出也写到这里，file 工具可以任意读写这里，VSCode 打开的工作区也是这里。这种设计的真正价值在于：你不需要知道某个文件在"哪个容器的哪个路径"，你只需要知道它在 workspace 里，任何组件都能访问它。对这种统一文件视图，我的使用体会是管道效率提升非常明显——数据源和目标地之间的搬运几乎被消灭了。

文件组件的工具形态一般是 file_read、file_write、file_list、file_search 这几类。对于 Agent 来说，file_search 甚至比 shell 里的 grep 更好用，因为返回的是结构化结果，模型直接消费，不需要自己解析文本流。如果你正在设计自己的沙箱工具集，我建议把文件工具和 shell 工具分开，让模型优先选文件工具，只有真正需要系统级操作时才动 shell。

2.4 MCP：把能力变成"标准插座"

MCP 是 Model Context Protocol 的缩写，可以理解为一个把外部能力变成标准工具插座的协议。AIO Sandbox 里浏览器、Shell、文件这些能力，最后都是通过 MCP server 暴露出来的。

客户端只需要知道 server 地址和工具名，就能像调用函数一样操作这些能力。调用协议本身基于 JSON-RPC，消息里包含 tools/list、tools/call 这类方法，模型通过 server 返回的结果继续往下规划。比如拉取工具列表，实际就是这样一个请求：

{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}

server 返回的每个 tool 里会有 name、description、inputSchema。模型看到 description 就知道什么场景该用哪个工具、参数怎么填。AIO Sandbox 的价值在于：它不只搭好了浏览器和 Shell，还用 MCP 把这层能力做成了一套可被任意 MCP 客户端直接消费的标准接口。这层细节非常关键——因为 Agent 客户端只要支持 MCP，就能无缝接入，不需要为每个组件单独写适配。

2.5 VSCode 组件：人的"观察窗"和"急救包"

Agent 是自动跑的，但工程上你不能对它完全撒手。VSCode 组件通常是 code-server 的实现——一个跑在浏览器里的 VSCode，直接打开容器内的工作区。

它的两个价值最明显：一是观察，你能实时看到 Agent 在 workspace 里生成了哪些文件、日志里打印了什么；二是急救，任务失败时，你不需要重新配置环境，直接在 VSCode 里改文件、补代码、执行命令，然后让 Agent 继续跑。这也是我把 VSCode 看作沙箱完整度重要指标的原因——没有这层人的接口，沙箱只是一个黑盒。

3. 一个容器装下所有东西，靠的不只是"堆进程"

3.1 启动编排：谁先起来，谁后起来

容器一启动，里面同时装了很多服务，排列组合很讲究。如果只是把所有进程一股脑丢进 Dockerfile 的 CMD，你会发现服务之间互相抢端口、互相等不到依赖。

常规做法是一个入口脚本或 supervisor 负责编排：先确保 workspace 目录可写，再拉起 code-server；code-server 起来后，再启动各个 MCP server 进程，最后才启动浏览器进程，因为浏览器主要依赖前几个服务的端口和资源。docker compose 里的 healthcheck 再来一道把关，避免容器显示 running 但服务其实还在爬坡。我自己在排查"连上了但服务没就绪"的问题时，最常用的命令就是反复看 health 状态和日志。

healthcheck 的写法也很直白，比如给 MCP server 加一个：

services: mcp: healthcheck: test: ["CMD", "curl", "-f", "http://localhost:3001/mcp"] interval: 15s timeout: 5s retries: 5

有了这层，compose 才能在依赖服务就绪后再启动浏览器这类重量级进程，而不是一拥而上。

3.2 MCP 传输方式如何影响部署

MCP server 有两种传输方式，直接影响你怎么部署。stdio 模式下，MCP server 是客户端拉起的子进程，适合本地原生客户端；HTTP/SSE 模式下，MCP server 是一个网络服务，外部 Agent 通过 URL 连接，适合容器化部署。

AIO Sandbox 里一般会默认把 HTTP 模式打开，因为 Agent 客户端很可能跑在宿主机或远端。配置上要注意 server 绑定地址，默认绑 127.0.0.1 的话外部容器访问不到，要改成 0.0.0.0。如果开启了 Bearer Token 认证，客户端那里要配好 headers，否则会出现"工具列表拉得到、一调用就 401"的诡异现象。

3.3 共享文件系统：串起所有组件的隐形关键

前面讲过的 workspace，到这里要从实现层面理解：它通常是一个 Docker named volume 或 bind mount，挂进容器后，所有相关进程的工作目录都指向它。

这种设计的价值在于，文件不是"传"过去的，而是"生来就在同一个地方"。浏览器把页面截图保存到 /workspace/downloads，Agent 下一步立刻可以读取；Shell 命令把中间结果写进 /workspace/artifacts，file 工具马上就能引用；code-server 打开 /workspace，你看到的就是 Agent 的完整现场。没有共享文件系统的话，组件间每一次数据交换都要显式传输，那 All-in-One 就名存实亡了。

权限这里也要提一句：挂载卷的所有者如果和容器内用户不一致，很容易出现"Agent 读不了自己刚写的文件"这种低级但见效的翻车事故。我建议第一次启动前就把 uid 映射好，别等数据跑了半天再回头改。

3.4 安全边界：沙箱容纳的是聪明调用，不是无限制管理员

Agent 里跑的是大模型，它什么时候会被 prompt 引导去做危险操作，谁都不敢打包票。所以沙箱的安全边界不能只靠自觉。

我实际会做的四件事：第一，不用 root 跑 Agent 相关进程；第二，把关键目录设置只读，比如系统目录、配置目录；第三，对出网做限制，默认允许访问业务需要的端口，其余流量一律丢弃；第四，Shell 调用全部打日志，会话粒度可审计。另外 Docker 自身还能加 --memory、--cpu 配额，防止某个失控的工具调用把整个宿主机拖垮。要明白，沙箱不是把命令执行权限给模型就完事了，而是精心划定了一个"它可以自由发挥但不能越界"的区域。

4. 从零把这套沙箱跑起来：我的实操流程

4.1 前置检查：内存和 Docker 别省

动手之前先看三样东西：Docker 是否就绪、docker compose 是否有、内存够不够。

浏览器是最吃资源的，Chromium 多进程模式轻松占到 1.5～2GB；code-server 是 Node 进程，保守算 500MB～800MB；几个 MCP server 加起来还要 300MB 上下。所以我建议主机至少留 4GB 内存给这个沙箱，只有 2GB 的话纯测试能跑，但浏览器一开就容易 OOM。

docker --version docker compose version free -h

这三个命令确认完，再往下走。

4.2 clone 启动：靠 compose 而不是手搓启动命令

把项目 clone 到本地（一般从项目 Releases 或源码仓库拿），进入目录后先看有没有 .env.example。很多这种 All-in-One 项目都会用环境变量控制端口、密码和挂载路径，复制一份 .env 改成自己的值：

git clone <aio-sandbox 仓库地址> aio-sandbox cd aio-sandbox cp .env.example .env docker compose up -d

项目的目录结构通常长得像这样，细节不同，但骨架类似：

aio-sandbox/ ├── docker-compose.yml # 服务编排、端口、volume ├── .env.example # 端口/密码/workspace 路径模板 ├── config/ # MCP server 与 code-server 配置 ├── tools/ # 浏览器、shell、file 的 MCP 实现 └── workspace/ # 默认挂载为容器内 /workspace

这里强烈建议别绕过 compose 手敲 docker run。compose 文件里通常已经编排好了端口映射、volume 挂载、健康检查和服务依赖，手敲一个 docker run -d 只能启动单个容器，根本表达不了"AIO"里的多层依赖关系。

启动后看状态：

docker compose ps docker compose logs -f

docker compose ps如果显示 healthy，说明关键组件都起来了；日志里会有 MCP server 监听端口、code-server 初始化 workspace 的信息，可以从中确认各组件实际监听的端口。

4.3 检查 VSCode 和浏览器：容器内部能力肉眼确认

先打开浏览器访问 VSCode 界面，默认端口我见过不少是 8080。页面会要求输入密码或 token，这个值一般就在 .env 里，直接填进去。进去之后打开文件夹 /workspace，这时候你应该能看到一个待命的工作区。

浏览器组件不一定有独立的可视化页面，更多时候是通过 MCP 工具验证。你可以在 Agent 客户端里调一次 browser_navigate 访问一个本地服务的地址，如果返回了页面快照，说明浏览器组件正常。如果没反应，最常见的病因是系统库缺失，这个我放到第 5 节展开。

4.4 在外面接一个 Agent 客户端：MCP 地址和工具验证

沙箱起来之后，真正的重头戏是让 Agent 客户端连上它。现在主流客户端基本都支持 MCP，添加一个 MCP server 地址即可：

http://localhost:3001/mcp

如果客户端跑在另一台机器，就把 localhost 换成沙箱所在主机的 IP。加上之后，客户端会拉一次工具列表。正常情况下你应该能看到类似下面这些工具：

• browser_navigate
• browser_snapshot
• shell_execute
• file_read / file_write / file_list

看到这些工具，说明"浏览器、Shell、文件"三大能力已经通过 MCP 打通了。如果工具列表拉到空，先查 server 是否监听正确端口，再查认证 token。

4.5 最小闭环：让 Agent 自己跑一个三件套任务

全部就绪后，我建议先跑一个很小但完整的任务，验证整条链路是不是真的通。

任务设计很简单：让 Agent 读取 workspace 里的 README.md，用 shell 统计一下项目文件数量，再打开浏览器访问本地 VSCode 页面确认服务在线，最后把所有结果写进一个 result.log。

对应的工具调用大致像这样：

file_read(path="/workspace/README.md") shell_execute(command="find /workspace -type f | wc -l") browser_navigate(url="http://localhost:8080") browser_snapshot() file_write(path="/workspace/result.log", content="...")

跑完之后，切到 VSCode 刷新 workspace，会看到 result.log 出现。这个闭环里每一步之间都没有跨容器传输，所有结果都落在同一份 workspace 里——这就是前面聊的 All-in-One 真正舒服的地方。

5. 实际用下来最容易踩的坑，以及我最后的优化方案

5.1 浏览器进程被 OOM 干掉，容器直接退出

我第一轮测试时，容器在任务跑到第三个页面时退出，日志里出现 killed process，docker inspect 看退出码是 137。根本原因是 Chromium 的多进程模型内存峰值太高，加上 MCP server、code-server 叠在一起，把容器的内存配额吃满了。

解决思路分两层。一是给容器设置合理的 --memory 上限，并给浏览器进程加 --max-old-space-size 之类的限制；二是关掉不需要的特性，无头模式比带 Xvfb 的完整渲染省不少内存。这里要提醒一句：有些教程为了省事会让你加 --no-sandbox，这个参数在容器里确实常用，但它关闭了 Chromium 的沙箱机制，非必要不要在生产环境沿用。

5.2 MCP 长任务超时：输出太大、会话太久都是坑

Agent 调 shell_execute 执行一个几分钟的任务，客户端大概率在几十秒就会报 timeout，因为多数 MCP client 有个默认的超时设置。这不算 bug，是长任务和同步调用之间的天然矛盾。

我现在的做法是给 Agent 一套"异步模式"的提示词：启动长命令时用 nohup 写到日志文件，然后周期性 sleep + tail 检查进度。另一件事是输出截断。一个 find 命令能把几十万字符灌回上下文，模型直接变傻。所以我在工具说明里特意引导 Agent 用| tail、| head、只输出摘要。这些细节看着琐碎，实际能避免大量无意义的上下文爆炸。

5.3 挂载卷写出来的文件全是 root，宿主机改不动

容器内默认以 root 运行，挂载卷里的文件自然都是 uid 0。宿主机普通用户删除或修改这些文件时会发现权限不够，很膈应。

解决办法是让容器内用户和宿主机用户 uid 对齐。在 compose 里给服务指定 user: "1000:1000"，或者在启动脚本里把工作用户固定成 uid 1000。这个事最好在第一次启动前就设置好，不然后面要大批量 chown，浪费几分钟。顺带一提，如果 workspace 目录要在宿主机上直接编辑，bind mount 比 named volume 更方便管理。

5.4 浏览器启动报缺库：无头也不是"零依赖"

第一次调 browser_navigate 时，工具返回错误，里面写着缺 libnss3、libatk-bridge 这类系统库。我当时的反应是：无头浏览器难道不是没有界面就没依赖？实际不是，Chromium 内核依然需要大量图形和媒体相关的系统库。

如果你的 base 镜像比较精简，建议直接装齐浏览器运行依赖，常见的有 libnss3、libatk-1.0、libatk-bridge-2.0、libcups2、libxkbcommon、libgbm 这些。嫌麻烦的话，直接基于官方带 Chromium 依赖的镜像改造会更省事。这点放在很靠前的位置，能省下一小时。

5.5 容器重启之后 Agent 状态全没了

有朋友跑了一晚上 Agent 任务，第二天起来发现容器所在机器重启过，docker compose 拉起来之后 workspace 是空的。原因很常见：docker run 时没有配置持久化，数据放在容器可写层，容器一删，数据全没了。

AIO 这类项目默认都会在 compose 里声明 named volume，挂到 /workspace。但如果你自己手改过 compose，或者用了 bind mount 但宿主机路径写错，就很容易踩。建议启动前先确认 volume 真实存在，再跑一个文件写入测试，重启容器验证一次。别等到跑了半天任务才想起来。

5.6 token 和绑定地址引发的"连不上"错觉

MCP server 绑定 127.0.0.1 时，外部 Agent 客户端能 ping 通宿主机，但连不上 3001 端口；或者开了 token 校验但客户端 headers 没配置，工具列表都能拉，一调用就报 401。这类问题最迷惑人。

排查顺序：先确认容器端口映射，docker compose ps 看 3001 是否映射到宿主机；再进容器 curl 一下 127.0.0.1:3001，确认进程正常；最后检查 MCP server 是否绑定了 0.0.0.0，以及客户端是否带了认证头。三个点过一遍，基本能定位。

5.7 我目前的稳定配置思路

跑了一段时间后，我在 AIO Sandbox 上的稳定用法大概是这样的。

首先，内存配额设成 4GB，运行期监控，不够时优先关掉多模态截图这类重操作。其次，workspace 持久化用 named volume，Agent 的状态、中间产物、日志都留在那里，任何时刻都能恢复到前一天现场。再次，Shell 工具不做完全白名单，但坚持用低权限用户，并且把重要系统目录设为只读，命令全部审计。最后，每个 Agent 项目分配独立的 workspace 子目录，让多个 Agent 任务互不干扰。

这套配置不复杂，但能挡掉 90% 我在实际测试中遇到过的问题，剩下的就只能靠对具体任务的日志观察来逐步优化了。如果你也刚好在折腾 AIO Sandbox，或者正被散落的 Agent 工具链折磨，欢迎把你这边的踩坑经验也整理出来，这类项目最有意思的地方就在于每个真实场景都会逼出新的解决方案。