Cua 计算机使用代理指南：把 AI 关进沙箱桌面里快速上手

Cua 计算机使用代理指南：把 AI 关进沙箱桌面里快速上手

【免费下载链接】cuaScale computer-use 2.0 with open-source drivers, cross-OS fleets, and benchmarks for training, evaluation, and data generation.项目地址: https://gitcode.com/GitHub_Trending/cua/cua

让 AI 替你点鼠标，最容易被低估的坑不是点不准，而是点完你的机器就乱了。Cua 把代理的桌面操作放进一次性沙箱（用完即弃的隔离虚拟机），也支持后台驱动你真机，一套接口打通截图、点击、输入和 Shell，覆盖 Linux、Windows、macOS 和 Android。

它到底在解决什么问题

先想三个"没有它，会怎样"的场景。

没有视觉理解：大量老应用、设计软件、签了名的业务系统根本不给 API，GUI 就是唯一入口。你只能写死坐标或控件选择器，界面一改版脚本全崩，维护成本远超人工。

没有安全隔离：代理一定会犯错。它没有沙箱的话，一次误点"删除"或误输命令就落进你的真机；CI 里更糟——每个测试都依赖同一台机器的状态，跑一遍结果就漂一次，没法复现。

没有跨平台一致性：同样的"截图→点击"，在 Docker 容器、QEMU 虚拟机、macOS 虚拟机里各有各的底层。没有统一接口，你每换一个操作系统就得重写一遍输入注入和画面采集。

说白了，Cua 干的事就是：给代理一个看得见、点得动、删得掉的计算机，并且这个计算机在 Linux、Windows、macOS、Android 上长得一样。

一条工作流跑通：从截图到验证

我们挑一个典型任务走一遍时间线：让代理在 Linux 桌面里打开应用、填一个表单、点提交，然后确认结果。

整个过程是一圈循环，每一圈大约耗时从百毫秒到几秒不等，取决于 VLM（会看图的 AI 模型）的推理速度：

1. 截图：screenshot()从沙箱桌面抓当前画面，容器环境里走远程显示栈，虚拟机里走虚拟显卡。
2. 理解：截图连同任务描述交给 VLM。模型看到的不是 DOM，而是"屏幕上有什么、按钮在哪"。
3. 决策：代理循环（OpenAI / Anthropic / Omni 等 100+ 模型可插）输出下一步动作——点 (100, 200)、输入文本，或干脆跑一段 Shell 绕过 GUI。
4. 执行：mouse.click()、keyboard.type()把动作注入沙箱。这里有个设计细节：代码半区和 GUI 半区是同一台机器——代理可以先shell.run造一个文件，再用鼠标去应用里打开它，两者共享同一份文件系统。
5. 验证：再截一张图，让模型确认状态变了；没变就重试或换路径。

每圈的截图、动作、结果都会被录成轨迹（操作回放录像），方便事后回放和做训练数据。

from cua import Sandbox, Image async with Sandbox.ephemeral(Image.linux()) as sb: # 换 .macos()/.windows() 即换系统 result = await sb.shell.run("echo hello") shot = await sb.screenshot() await sb.mouse.click(100, 200) await sb.keyboard.type("Hello from Cua!")

环境选型藏在这一行里：Linux 容器启动最快（共享宿主内核），全虚拟机（QEMU、Hyper-V、Apple Virtualization）启动慢一点但操作系统保真度高。macOS 虚拟机由 libs/lume/ 下的 Lume（macOS 虚拟化器）负责，在 Apple Silicon 上接近原生性能。

5 分钟上手：怎么跑起来

先装 SDK，再开一个临时沙箱，全程不超过三条命令。

pip install cua

Python 3.11+，装完直接开沙箱试手：

python -c "import cua; print(cua.__version__)"

import asyncio from cua import Sandbox, Image async def main(): async with Sandbox.ephemeral(Image.linux()) as sb: print(await sb.shell.run("uname -a")) print(await sb.screenshot()) asyncio.run(main())

先做pip install，再做Sandbox.ephemeral——用完async with自动销毁，不留任何状态。想跑基准测试的话，另装cua-benchCLI，用cb task create搭一个模拟桌面任务，无需 Docker 和 API key 就能验证全流程，步骤见 docs/content/docs/tutorials/your-first-cua-bench-task.mdx。

和 Selenium、Playwright、传统 RPA 差在哪

维度	Cua	Selenium / Playwright	传统 RPA
界面理解	VLM 读截图 + 无障碍树	解析 DOM	固定选择器/坐标
覆盖范围	桌面 GUI、浏览器、移动端	基本只有 Web 页面	单一桌面环境
运行隔离	一次性沙箱整机	浏览器进程	宿主进程
界面变化后	自适应重新决策	选择器失效即崩	脚本需人工修

主要跑 Web 页面的话，Playwright 更轻更成熟；要碰原生桌面应用、老系统或者"没有 API 的 UI"，Cua 这类计算机使用代理才真正派上用场。两者也不互斥——代理循环里完全可以让它浏览器部分走 DOM、桌面部分走截图。

目前的边界与下一步

坦白讲，现在确实还有几处不太行：

• Linux Wayland 原生应用收不到合成的键盘输入，原始按键注入受限，得走 XWayland 或前台兜底。
• 全虚拟机启动明显慢于容器，macOS 沙箱还绑死在 Apple Silicon 硬件上。
• 复杂 UI 的语义理解精度很大程度取决于底层 VLM 本身，框架不兜底。
• 后台驱动是尽力而为：少数应用只认真正的前台输入，得逐动作升级回前台。

接下来值得盯的：本地模型接入的持续打磨（上下文预算和推理吞吐对轨迹长度影响很大）、多代理并行跑一个桌面任务、以及 BYOI 自定义镜像上云的路径。

拆一个最有辨识度的点：不打扰你的后台驱动

有意思的是，Cua Driver 驱动你真机时默认不抢你的鼠标。它在屏幕上层画一个"假光标"展示代理动作，你的真光标和当前窗口原封不动。底层路径按平台挑最后台的方案：macOS 走无障碍 API + 窗口级画面采集，Windows 走 UI Automation 按窗口句柄操作控件，Linux 走 AT-SPI 语义动作。协议层用 MCP（模型上下文协议）over stdio，所以 Claude Code、Cursor 这类编码代理可以当工具直接挂载。

# 驱动本地应用的调用形态（示意） tool("screenshot", {"window": "notepad"}) # 只采目标窗口 tool("click", {"element": "保存按钮"}) # 经无障碍树直达控件 # 需要前台的动作会显式上报，由调用方决定是否升级

沙箱与真机驱动共用同一套动作语义，这是它把"可复现的评估环境"和"日常可用的自动化"缝在一起的关键，更多细节在 docs/content/docs/concepts/how-sandboxes-work.mdx。

---

回到开头那个坑：AI 点鼠标怕的不是点错，是点错没地方兜底。如果你的任务要碰桌面 GUI——测试、数据搬运、老系统自动化——Cua 是目前少数能把"隔离"和"跨平台"同时交给你的选择。

【免费下载链接】cuaScale computer-use 2.0 with open-source drivers, cross-OS fleets, and benchmarks for training, evaluation, and data generation.项目地址: https://gitcode.com/GitHub_Trending/cua/cua