Open Computer Use (E2B) — 架构与原理

30 秒导读： 这是一个让开源大模型自己操作一台电脑的 agent。它在 E2B 云沙箱里开一台 Ubuntu 桌面，反复「截图 → 让模型看图想下一步 → 把动作落到真实鼠标键盘」，直到把你交代的任务干完。最巧的一点：它不用一个大模型硬扛全部，而是把活拆给三个各有所长的模型——一个描述屏幕、一个决定动作、一个把「点那个按钮」翻译成精确的像素坐标。

---

1. 这是什么（零基础也能懂）

一句话定义： 一个命令行 agent，给它一句自然语言指令（"用浏览器查一下旧金山的天气"），它就自己在一台云端 Linux 桌面上动鼠标、打字、跑 shell 命令，一步步把任务做完。

解决什么问题 / 给谁用：

• 你想让 AI 帮你操作图形界面——不是调 API，而是真的去点按钮、填表单、开应用。
• 你不想（或不能）用闭源的 computer-use 产品，想换任意开源模型试试，还想让它跑在一个摔不坏的隔离沙箱里（模型乱点也只是弄坏一台一次性云电脑，不碰你的真机）。

它能做什么（功能）：

• 通过鼠标、键盘、shell 命令操作整台电脑（os_computer_use/sandbox_agent.py）。
• 支持 10+ 家 LLM 提供商，随便换（os_computer_use/providers.py）。
• 把沙箱桌面的画面实时串流到你本地窗口看（main.py:38-43）。
• 你随时可以按 Ctrl-C 打断、重新下指令（main.py:45-61）。

用起来什么样： 一条命令启动，然后像聊天一样下指令。

poetry run start --prompt "use the web browser to get the current weather in sf"

启动后终端里会出现一个交互循环，你打字它就干活：

USER: open firefox and search for e2b
THOUGHT: The objective is: open firefox ...
ACTION: click {'query': 'Firefox icon in the taskbar'}
OBSERVATION: The mouse has clicked.
...

一句话直觉/类比： 把它想成一个蒙着眼、只能靠拍照片看世界的实习生——每做一步之前它先拍张屏幕照（screenshot），描述看到了啥，想好下一步，然后伸手去点。它自己看不准坐标，所以雇了个专门「指哪打哪」的助手（grounding 模型）帮它把「点登录按钮」换算成屏幕上的第几个像素。

---

2. 顶层全景（它大概怎么转）

部件一句话职责

部件	干什么	在哪个文件
入口 / 交互循环	起沙箱、开桌面串流、读用户输入、跑 agent	main.py
SandboxAgent	核心：看→想→做→观察的主循环 + 所有工具	os_computer_use/sandbox_agent.py
三个模型（config）	指定用哪个模型做 vision / action / grounding	os_computer_use/config.py
LLMProvider 家族	把各家 LLM 的 API 差异抹平成统一接口	os_computer_use/llm_provider.py、providers.py
grounding 模型	把文字描述变成屏幕像素坐标	os_computer_use/osatlas_provider.py、grounding.py
Sandbox	E2B 云 Linux 桌面：真正执行鼠标/键盘/命令的地方	os_computer_use/streaming.py
Browser / Logger	本地看画面的窗口；彩色终端 + HTML 日志	os_computer_use/browser.py、logging.py

顶层图

怎么读这张图：中间的 SandboxAgent 主循环是心脏。每一圈它都向左问三个模型「现在该干嘛」，向右把动作打到 E2B 沙箱里，再截个图带回来问下一圈。

              ┌───────────────────────────────────────────────┐
              │                你（终端下指令）                  │
              └───────────────────────┬───────────────────────┘
                                       │ "打开浏览器查天气"
                                       ▼
   ┌──────────────┐         ┌────────────────────────┐        ┌──────────────────┐
   │  三个模型     │◀────────│      SandboxAgent        │───────▶│   E2B 云沙箱      │
   │              │  问：    │      （主循环）           │  动作： │  Ubuntu 桌面      │
   │ ① vision 看图 │ 看/想/  │  看→想→做→观察 反复转    │ 点/打字/│                  │
   │ ② action 定动作│ 定位    │                          │ 跑命令  │  真的鼠标/键盘    │
   │ ③ grounding  │────────▶│                          │◀───────│  截图带回          │
   │   给坐标      │  答：    └────────────┬─────────────┘  截图    └────────┬─────────┘
   └──────────────┘                       │                              │ 画面串流
                                          │ 日志                          ▼
                                          ▼                       ┌──────────────┐
                                    终端 + log.html                │ 本地 Browser  │
                                                                  │ 窗口(看画面)  │
                                                                  └──────────────┘

主线走一遍（高层，不进代码）

1. 起环境。 main.py 创建一个 E2B Sandbox（云端 Ubuntu 桌面），启动 VNC 串流，本地弹一个 Browser 窗口让你实时看画面。
2. 收指令。 终端 input() 拿到你的一句话，交给 agent.run(...)。
3. 进主循环。 agent 反复做四件事：截图 → 让 vision 模型描述屏幕并判断任务是否完成 → 让 action 模型决定调哪个工具（点击/打字/跑命令/停止）→ 执行并把结果作为观察写回记忆。
4. 动作落地。 如果是「点击」，先让 grounding 模型把「点登录按钮」换算成 (x, y)，再让沙箱把鼠标移过去点下。
5. 收尾。 模型调 stop 工具就结束这一轮，回到终端等你下一句；你按 Ctrl-C 可随时打断。

目标：看懂「大盘」——一个截图驱动的循环，三个模型分工，一个隔离沙箱执行。逐层深入见下面各章。

---

3. 阅读地图（各章讲什么，建议顺序）

按下面顺序读，由浅入深：

1. 01-agent-loop.md — 主循环。 一条指令如何变成一串鼠标键盘动作：看→想→做→观察的四拍节奏，记忆怎么攒，工具怎么注册和调用，循环怎么停。先读这章建立主干。
2. 02-three-models.md — 三模型分工。 为什么不用一个模型硬扛，而是拆成 vision / action / grounding 三个角色；每个角色输入输出是什么、config 里怎么配、各自能力边界。
3. 03-grounding.md — 视觉定位。 整个项目工程含量最高的一环：把「点那个蓝色按钮」这种人话，落成屏幕上精确的像素坐标。OS-Atlas 的 bbox 解析、取中点、画红点校验。
4. 04-providers.md — Provider 抽象。 一套 call() 接口如何接住 OpenAI 系、Anthropic、Gradio 三种截然不同的 API；工具 schema 转换、图片编码差异、以及「模型不肯好好返回 JSON 时手动抠出来」的容错。

---

4. 代码地图（导航索引）

主题	文件	关键符号
程序入口 / 交互循环	main.py	start、main
Agent 主循环	os_computer_use/sandbox_agent.py	SandboxAgent.run、SandboxAgent.append_screenshot
工具注册装饰器	os_computer_use/sandbox_agent.py	SandboxAgent.tool、tools（模块级 dict）
工具实现	os_computer_use/sandbox_agent.py	run_command、type_text、send_key、click、click_element
三模型配置	os_computer_use/config.py	vision_model、action_model、grounding_model
Provider 基类	os_computer_use/llm_provider.py	LLMProvider、OpenAIBaseProvider、AnthropicBaseProvider、MistralBaseProvider
具体 provider 列表	os_computer_use/providers.py	GroqProvider、OpenRouterProvider、AnthropicProvider …
视觉定位	os_computer_use/grounding.py	extract_bbox_midpoint、draw_big_dot
grounding 模型客户端	os_computer_use/osatlas_provider.py、showui_provider.py	OSAtlasProvider.call、ShowUIProvider.call
沙箱 / 串流	os_computer_use/streaming.py	Sandbox.start_stream、Sandbox.kill、DisplayClient
本地看画面窗口	os_computer_use/browser.py	Browser.open、Browser._create_window
彩色 / HTML 日志	os_computer_use/logging.py	Logger.log、Logger.write_log_file

---

5. 横向对比（computer-use area）

本项目在 computer-use 这一 area 里的取舍很有代表性：

• 不依赖模型自带的 computer-use 能力。 官方 computer-use 产品（如 Anthropic 的 computer use）通常靠一个多模态大模型端到端输出坐标。本项目反其道而行：假设底层模型不会精确定位，专门外挂一个 grounding 模型补这一课——于是几乎任何能看图 + 能调工具的开源模型都能拼进来。
• 隔离靠 E2B 沙箱，而非本机权限沙箱。 执行面是一台一次性云 Ubuntu，模型再乱来也只是毁掉一台可丢弃的机器。

更细的对比、以及「三模型分工 vs 单模型端到端」的权衡，见 02-three-models.md 与 03-grounding.md。