10 分钟搞懂 cua：开源 AI 操作电脑基础设施，附 Python 沙箱与 Agent 上手代码

[10 分钟搞懂 cua：开源 AI 操作电脑基础设施，附 Python 沙箱与 Agent 上手代码](#10 分钟搞懂 cua：开源 AI 操作电脑基础设施，附 Python 沙箱与 Agent 上手代码)
- [一、项目概览：把"AI 操作电脑"做成开源基础设施](#一、项目概览：把"AI 操作电脑"做成开源基础设施)
- [二、四大组件总览：一张表看懂 cua 的能力地图](#二、四大组件总览：一张表看懂 cua 的能力地图)
- [三、核心上手：Sandbox + ComputerAgent，10 行代码跑通第一个 Agent](#三、核心上手：Sandbox + ComputerAgent，10 行代码跑通第一个 Agent)
- - [3.1 安装与 Python 版本](#3.1 安装与 Python 版本)
  - [3.2 Sandbox 上手：一套 API 通吃四大平台](#3.2 Sandbox 上手：一套 API 通吃四大平台)
  - [3.3 ComputerAgent 上手：让 LLM 接管沙箱](#3.3 ComputerAgent 上手：让 LLM 接管沙箱)
  - [3.4 沙箱生命周期与本地模式](#3.4 沙箱生命周期与本地模式)
- [四、Cua Drivers：让 Claude Code/Cursor 后台操控你的桌面](#四、Cua Drivers：让 Claude Code/Cursor 后台操控你的桌面)
- [五、Cua-Bench 与 Lume：评测环境与 macOS 虚拟化](#五、Cua-Bench 与 Lume：评测环境与 macOS 虚拟化)
- - [5.1 Cua-Bench：基准测试与 RL 环境](#5.1 Cua-Bench：基准测试与 RL 环境)
  - [5.2 Lume：Apple Silicon 上的 macOS 虚拟化](#5.2 Lume：Apple Silicon 上的 macOS 虚拟化)
- [六、CLI 与 MCP 集成：命令行管理沙箱与权限粒度](#六、CLI 与 MCP 集成：命令行管理沙箱与权限粒度)
- 七、注意事项与适用场景：客观说清边界
- [八、总结：开源基础设施让 AI 操作电脑从演示走向可复现工程](#八、总结：开源基础设施让 AI 操作电脑从演示走向可复现工程)

10 分钟搞懂 cua：开源 AI 操作电脑基础设施，附 Python 沙箱与 Agent 上手代码

让 AI 真正"操作"电脑--点按钮、填表单、跨应用跑流程--一直是 AI 落地难啃的骨头：闭源 SaaS 不开放，自研又得从零搭沙箱、接模型、写驱动。cua把这件事做成了开源基础设施，一套 API 覆盖 macOS、Linux、Windows、Android 四大平台。本文从四大组件切入，给出可直接复制的 Python 上手代码，10 分钟跑通你的第一个 Computer-Use Agent。

一、项目概览：把"AI 操作电脑"做成开源基础设施

cua 是一套 MIT 开源的 Computer-Use Agent（CUA）基础设施，目标是让 AI 像人一样操作完整的桌面环境。它和闭源 SaaS 的根本区别在于：沙箱、SDK、驱动、基准测试全部开源可自托管，你可以看清每一步、改每一处。

官方在 GitHub 页面用一句话这样描述它（逐字引用）：

Open-source infrastructure for Computer-Use Agents. Sandboxes, SDKs, and benchmarks to train and evaluate AI agents that can control full desktops (macOS, Linux, Windows).

基本信息一览：

项目	内容
仓库	trycua/cua
git地址	https://github.com/trycua/cua
官网地址	https://cua.ai
Stars	约 22k stars

技术栈上 cua 是典型的多语言 monorepo：Python 用 uv workspace 管理 agent/core/computer/computer-server/som/mcp-server/bench-ui 等核心子包，cua-sandbox、cua-cli、cua 元包为独立发布包；TypeScript 用 pnpm workspace 管理 agent/computer/fleet/playground；Rust 用 Cargo workspace 实现 cua-driver 的跨平台后台驱动。这种结构意味着不同能力用合适的语言写--驱动求性能用 Rust，Agent 框架求生态用 Python，前端求迭代用 TypeScript。

二、四大组件总览：一张表看懂 cua 的能力地图

cua 的能力分布在四个相对独立的组件里，你可以按需取用，不必一次全装。下表并置它们的定位、实现语言与上手方式（来源：README.md:23-158）。

组件	定位	实现语言	上手方式
Cua Drivers	在 macOS/Windows/Linux 后台驱动原生桌面应用，代理可点击/输入/校验，不抢占光标与焦点	Rust（Cargo workspace）	`install.sh` / `install.ps1`，或作为 MCP server 接入 Claude Code 等
Cua（Sandbox + Agent）	任意 OS 的 VM/容器沙箱 + LLM 驱动的 computer-use agent，一套 API 云或本地	Python	`pip install cua`
Cua-Bench	在 OSWorld、ScreenSpot、Windows Arena 及自定义任务上评测 agent，可导出轨迹训练	Python（uv）	`cb run dataset ...` 命令
Lume	在 Apple Silicon 上用 Apple Virtualization.Framework 创建管理 macOS/Linux VM，近原生性能	Swift / 脚本	`lume create` / `lume run`

一句话区分：Drivers 解决"驱动真实桌面"，Sandbox+Agent 解决"在隔离环境里跑 AI 操作"，Cua-Bench 解决"怎么客观评测"，Lume 解决"在 Mac 上批量起 VM"。下文逐一展开，最重的第三节给到可直接复制的 Python 代码。

三、核心上手：Sandbox + ComputerAgent，10 行代码跑通第一个 Agent

这一节兑现标题里的"Python 沙箱与 Agent 上手代码"。你只需要一条 pip install 加十几行异步 Python，就能让一个 LLM 驱动的 agent 在沙箱里打开浏览器。

3.1 安装与 Python 版本

bash 复制代码

pip install cua

Python 版本务必精确（来源：libs/python/cua/pyproject.toml:27-28、libs/python/cua/README.md:46）：

cua 元包要求 Python 3.12 或 3.13 （requires-python = ">=3.12,<3.14"），因为 cua-cli 要求 3.12+（元包取子包约束的交集）。
Python 3.11 可直接安装 cua-sandbox （cua-agent 本身也支持 3.11，可单独安装），但 cua 元包与 cua-cli 要求 3.12+，所以 3.11 下装不了 cua 元包。

可选 extras（来源：libs/python/cua/README.md:37-42）：cua[omni]（SOM 视觉定位）、cua[uitars-mlx]（Apple Silicon 上 UiTars）、cua[uitars-hf]（HuggingFace UiTars）、cua[all]（全部）。

3.2 Sandbox 上手：一套 API 通吃四大平台

Sandbox 是 cua 的核心抽象。下面这段代码逐字引用自根 README.md:96-107，展示了沙箱能做的所有基础操作：

python 复制代码

# Requires Python 3.11 or later
from cua import Sandbox, Image

# Same API regardless of OS or runtime
async with Sandbox.ephemeral(Image.linux()) as sb:   # or .macos() .windows() .android()
    result = await sb.shell.run("echo hello")
    screenshot = await sb.screenshot()
    await sb.mouse.click(100, 200)
    await sb.keyboard.type("Hello from Cua!")
    await sb.mobile.gesture((100, 500), (100, 200))  # multi-touch gestures

⚠️ 版本提示：源码注释里的 "Requires Python 3.11 or later" 指的是 cua-sandbox 的最低门槛；若你通过 pip install cua 安装元包，实际要求 Python 3.12/3.13。两者并不矛盾，但容易混淆--以 3.1 节为准。

注意 Image.linux() 可以换成 .macos() / .windows() / .android()，API 形态完全一致。这是 cua 的核心卖点："Same API regardless of OS or runtime"--同一套 shell.run / screenshot / mouse.click / keyboard.type / mobile.gesture，在 Linux 容器、Linux VM、macOS、Windows、Android 上都能跑。

平台支持矩阵（来源：README.md:109-112）：

运行方式	Linux 容器	Linux VM	macOS	Windows	Android	BYOI(.qcow2/.iso)
云（cua.ai）	支持	支持	支持	支持	支持	即将支持
本地（QEMU）	支持	支持	支持	支持	支持	支持

3.3 ComputerAgent 上手：让 LLM 接管沙箱

有了沙箱，下一步是把 LLM 接上去。下面这段代码逐字引用自 libs/python/cua/README.md:13-23，是官方推荐的 Agent 最小可运行示例：

python 复制代码

from cua import Sandbox, Image, ComputerAgent

# Ephemeral local sandbox with an agent
async with Sandbox.ephemeral(Image.linux(), local=True) as sb:
    await sb.shell.run("uname -a")

    agent = ComputerAgent(model="anthropic/claude-sonnet-4-5", tools=[sb])
    async for response in agent.run("Open the browser and go to example.com"):
        print(response)

关键在 ComputerAgent(model=..., tools=[sb])：把沙箱作为工具交给 agent，agent 就能看屏幕、点鼠标、敲键盘去完成任务。agent.run(...) 返回一个异步迭代器，逐条吐出 agent 的中间动作与响应。

模型后端由 cua-agent 通过 litellm 集成，支持面较广（来源：libs/python/agent/pyproject.toml:29-101）：

API 类：openai、anthropic、gemini、qwen、uitars（API 模式）
本地/HF 类：uitars-mlx（Apple Silicon）、uitars-hf、glm45v-hf、opencua-hf、internvl-hf、moondream3
视觉定位：omni（基于微软 OmniParser 的 SOM）

cua-agent[cloud] 默认随 cua 元包安装，只含 API 类后端（不含 torch/transformers），适合容器/云部署；要本地模型就装对应 extras 或 cua[all]。

3.4 沙箱生命周期与本地模式

Sandbox 有四种生命周期形态（来源：libs/python/cua-sandbox/README.md）：

ephemeral ：进入 async with 即建、退出即毁，适合一次性任务。
persistent ：用 Sandbox.create 创建，脚本退出后仍存活；保存 sb.name 后可用 Sandbox.connect(name) 重连。
销毁：sb.destroy() 显式回收。
本地 VM ：Sandbox.ephemeral(Image.linux(), local=True, runtime=QEMURuntime())，用本地 QEMU 或 Lume 跑，不走云。

⚠️ Localhost.connect() 是直接控制宿主机，不是沙箱。它能驱动你当前这台机器，没有隔离，谨慎使用，仅在你明确需要"驱动本机"时再用。

四、Cua Drivers：让 Claude Code/Cursor 后台操控你的桌面

Cua Drivers 解决的是另一类问题：不进沙箱，直接驱动你真实桌面上的原生应用，而且在后台执行--不抢占你的光标和焦点（来源：README.md:62-64）。它用 Rust 写成，macOS/Windows/Linux 三端共用一套 CLI 和 MCP server，可接入 Claude Code、Cursor、Codex、OpenClaw 及自定义客户端。

Linux 端有显式边界：支持 X11 与特定 Wayland 合成器路由，raw background input（原始后台输入）存在限制，Wayland 体验取决于合成器，建议参考官方文档确认你的桌面环境。

安装（逐字引用，来源：README.md:66-76）：

macOS / Linux：

bash 复制代码

/bin/bash -c "$(curl -fsSL https://cua.ai/driver/install.sh)"

Windows（PowerShell）：

powershell 复制代码

irm https://cua.ai/driver/install.ps1 | iex

接入 Claude Code （逐字引用，来源：README.md:80-82、libs/cua-driver/README.md:33-41）：

标准 MCP 接入：

bash 复制代码

claude mcp add --transport stdio cua-driver -- cua-driver mcp

兼容模式让 Claude Code 的视觉/computer-use 流程基于 CuaDriver 的窗口截图来定位：

bash 复制代码

claude mcp add --transport stdio cua-computer-use -- cua-driver mcp --claude-code-computer-use-compat

macOS 权限模型值得单独说明（来源：libs/cua-driver/README.md:47-54）：Accessibility 与 Screen Recording 权限要授予给 responsible app identity，而不是裸的可执行路径；启动分 Standalone（CuaDriver.app）与 Embedded（设 CUA_DRIVER_EMBEDDED=1）两种模式。

易混淆点 ：cua-driver 面向本地后台驱动 （驱动你本机真实桌面），cua-cli 面向 cua.ai 云服务管理 （管云上的沙箱和镜像，需 API Key 认证）。两者名字相近、定位完全不同，下文第六节讲 cua-cli 时再展开。

五、Cua-Bench 与 Lume：评测环境与 macOS 虚拟化

这两个组件各走"定位 + 上手命令"的小循环，按需选用。

5.1 Cua-Bench：基准测试与 RL 环境

定位：在 OSWorld、ScreenSpot、Windows Arena 及自定义任务上评测 computer-use agent，并可导出轨迹用于训练（来源：README.md:118-120）。Registry 与合作入口在 cuabench.ai。

上手（逐字引用，来源：README.md:122-129）：

bash 复制代码

# Clone, install, and create base image
git clone https://github.com/trycua/cua && cd cua/cua-bench
uv tool install -e . && cb image create linux-docker

# Run benchmark with agent
cb run dataset datasets/cua-bench-basic --agent cua-agent --max-parallel 4

--max-parallel 4 控制并发，--agent cua-agent 指定用前文的 ComputerAgent 作为被测对象。跑完可以导出轨迹用于训练（RL 等场景）。

5.2 Lume：Apple Silicon 上的 macOS 虚拟化

定位：在 Apple Silicon 上用 Apple Virtualization.Framework 创建管理 macOS/Linux VM，近原生性能（来源：README.md:135-137）。它是 cua 本地沙箱在 Mac 上的底层运行时之一。

上手（逐字引用，来源：README.md:139-147）：

bash 复制代码

# Install Lume
/bin/bash -c "$(curl -fsSL https://cua.ai/lume/install.sh)"

# Create and start a vanilla macOS VM from an Apple restore image
curl -L "$(lume ipsw | tail -n 1)" -o ~/Downloads/macos-tahoe.ipsw
lume create macos-tahoe --ipsw ~/Downloads/macos-tahoe.ipsw --unattended tahoe
lume run macos-tahoe

--unattended 会离线准备已安装的 guest；内置 sequoia / tahoe 预设会创建 lume 用户、启用 SSH、配置自动登录、禁用睡眠与锁屏；默认凭据是 lume / lume（来源：README.md:149-152）。

⚠️ 已知限制：Tahoe 流程已 E2E 验证；Sequoia 首次显示启动时可能仍会打开 Setup Assistant 的 Accessibility 步骤，详见 issue #2155（来源：README.md:154-155）。用 Sequoia 预设时做好手动兜底的准备。

六、CLI 与 MCP 集成：命令行管理沙箱与权限粒度

cua-cli（命令名就是 cua）是 cua.ai 云服务的管理入口，MCP 则是把沙箱能力接入 AI 客户端的桥梁。安装（来源：libs/python/cua-cli/README.md:7-9,59-73）：

bash 复制代码

pip install cua-cli            # 基础安装
pip install cua-cli[mcp]       # 带 MCP server
pip install cua-cli[skills]    # 带技能录制（VLM captioning）
pip install cua-cli[all]       # 全部

主要命令组（来源：libs/python/cua-cli/README.md:13-57）：

命令组	作用	代表子命令
`cua auth`	认证	`login` / `login --api-key` / `status` / `logout` / `env`
`cua ws`	工作区	`set <slug>`
`cua sb`	沙箱管理	`list` / `create` / `start` / `stop` / `restart` / `suspend` / `delete` / `vnc`
`cua image`	镜像管理	`list [--local]` / `push` / `pull` / `delete`
`cua skills`	技能管理	`list` / `read` / `record` / `replay` / `delete` / `clean`
`cua serve-mcp`	启动 MCP server	`--permissions ...`

创建一个云沙箱的示例：

bash 复制代码

cua sb create --os linux --size medium --region north-america

MCP 接入 Claude Code （逐字引用，来源：libs/python/cua-cli/README.md:79-88）：

bash 复制代码

# 把 CUA 作为 MCP server 加进 Claude Code
claude mcp add cua -- cua serve-mcp

# 指定权限范围
claude mcp add cua -- cua serve-mcp --permissions sandbox:all,computer:readonly

# 绑定默认沙箱
claude mcp add cua -- cua serve-mcp --sandbox my-sandbox

常用环境变量（来源：libs/python/cua-cli/README.md:102-109、libs/python/cua/README.md:48-63）：

CUA_API_KEY：认证 API key
CUA_API_BASE：API 地址，默认 https://api.cua.ai
CUA_TELEMETRY_ENABLED=false：关闭匿名遥测（也可在实例级传 telemetry_enabled=False）

七、注意事项与适用场景：客观说清边界

已知限制：

Python 版本 ：cua 元包仅支持 3.12/3.13；Python 3.11 可装 cua-sandbox 和 cua-agent，但装不了 cua 元包与 cua-cli（要求 3.12+）。
Linux 桌面：cua-driver 的 raw background input 有显式限制，Wayland 仅特定合成器支持，X11 体验较佳。
Lume Sequoia：Sequoia 预设首次启动可能残留 Setup Assistant 的 Accessibility 步骤（issue #2155），Tahoe 已 E2E 验证。
Localhost 非沙箱 ：Localhost.connect() 直接控制宿主机，无隔离，谨慎使用。
文档域名 ：https://cua.ai/docs（官网主域）与 https://docs.trycua.com（部分子包 pyproject 仍在用）并存，以 cua.ai/docs 为准。
云服务定价：cua.ai 云服务的具体定价与额度未核实，建议参考官方文档。

适用场景：

需要在隔离沙箱里跑 AI Agent 做自动化测试、评测、训练数据生成。
想在 Claude Code / Cursor 里后台操控真实桌面应用，不抢占当前焦点。
在 Apple Silicon 上批量起 macOS VM 跑自动化。
做 computer-use 研究，需要 OSWorld/ScreenSpot 等公开基准的可复现评测环境。

不适用场景：

只想用纯 API 调 LLM--直接用 litellm 即可，不必上 cua。
生产环境高并发、对云成本敏感--云服务定价未核实，建议先查 cua.ai 官网评估。
Wayland 桌面且有强后台输入需求--当前限制较多，建议先在 X11 验证。

八、总结：开源基础设施让 AI 操作电脑从演示走向可复现工程

cua 把"AI 操作电脑"从闭源演示变成了可复现的开源工程：四大组件覆盖了驱动真实桌面（Cua Drivers）、隔离沙箱与 Agent（Cua）、基准评测（Cua-Bench）、macOS 虚拟化（Lume）的全链路，且沙箱 API 在四大平台上一致，云与本地双轨。它适合做 computer-use 研究与自动化的工程师、想在 AI 编程客户端里后台操控桌面的开发者、以及在 Apple Silicon 上批量跑 macOS VM 的团队。

如果你属于上述任何一类，现在就动手：

bash 复制代码

pip install cua

然后回到本文第三节，复制那十几行代码，10 分钟内你就能看到第一个 Computer-Use Agent 在沙箱里替你打开浏览器。从能跑的代码开始，是理解一个基础设施项目更高效的方式。

🎬 博客主页：https://xiaoy.blog.csdn.net

🎥 本文由 呆呆敲代码的小Y 原创 🙉

🎄 学习专栏推荐：Unity系统学习专栏

🌲 游戏制作专栏推荐：游戏制作

🌲Unity实战100例专栏推荐：Unity 实战100例教程

🏅 欢迎点赞 👍 收藏 ⭐留言 📝 如有错误敬请指正！

📆 未来很长，值得我们全力奔赴更美好的生活✨

------------------❤️分割线❤️-------------------------

资料白嫖，技术互助

学习路线指引（点击解锁）	知识定位	人群定位
🧡 Unity系统学习专栏	入门级	本专栏从Unity入门开始学习，快速达到Unity的入门水平
💛 Unity实战类项目	进阶级	计划制作Unity的 100个实战案例！助你进入Unity世界，争取做最全的Unity原创博客大全。
❤️ 游戏制作专栏	难度偏高	分享学习一些Unity成品的游戏Demo和其他语言的小游戏！
💚 游戏爱好者万人社区	互助/吹水	数万人游戏爱好者社区，聊天互助，白嫖奖品
💙 Unity100个实用技能	Unity查漏补缺	针对一些Unity中经常用到的一些小知识和技能进行学习介绍，核心目的就是让我们能够快速学习Unity的知识以达到查漏补缺