CUA：让大模型操控电脑的开放框架——从原理到 Python 实战

不是只有 Claude Code 和 Hermes 才能操控桌面。CUA 提供了一套独立的开放基础设施，pip install 就能让你的 Python 程序拥有"看屏幕、点鼠标、敲键盘"的能力。

前言

2024 年 10 月 Anthropic 发布 Computer Use 的时候，"AI 操控电脑"还是 Claude 的专属能力。一年后，开源社区已经有了完整的替代方案：CUA（Computer-Use Agents），一个让任何大模型都能操控电脑的开放框架。

CUA 不绑定任何 Agent 框架——你可以在 Hermes 里用，也可以脱离 Hermes 直接用 Python 调用；你可以控制真机桌面，也可以在云端沙箱里隔离运行。这篇文章把 CUA 的架构、原理和独立使用方法梳理清楚，给出可以直接跑的 Python 代码。

一、CUA 是什么

CUA 是 trycua/cua 开源项目（18k+ Stars）提供的 Computer-Use 基础设施，核心解决一个问题：给 AI 装上一双能操作电脑的"手"。

它包含两个独立产品：

表格

两者共享同一个设计原则：模型无关——它们只负责接收操作指令、返回屏幕观察结果（截图/AX树），不做任何推理或决策。你带自己的模型，CUA 提供电脑操控接口。

二、三层操控面：不只是"看截图点鼠标"

CUA 背后的 Computer-Use 2.0 理念，把 AI 操控电脑分成三个"操控面"（Action Surface）来源：

┌─────────────────────────────────────────────────┐ │ Computer-Use 2.0 │ │ │ │ ┌──────────┐ ┌──────────┐ ┌───────────────┐ │ │ │ 编码面 │ │ 工具面 │ │ UI 自动化面 │ │ │ │ Code │ │ Tool-Use │ │ UI Automation │ │ │ │ │ │ │ │ │ │ │ │ 写代码执行 │ │ 调API/MCP│ │ 看屏幕点鼠标 │ │ │ └──────────┘ └──────────┘ └───────────────┘ │ └─────────────────────────────────────────────────┘

• 编码面：Agent 直接写代码执行任务，适合文本操作、批量文件处理
• 工具面：通过结构化 API 调用（MCP、REST），适合系统已暴露接口的场景
• UI 自动化面：看截图→理解界面→点击/输入，适合没有 API 的原生应用和遗留系统

一个成熟的 Agent 会在同一任务中切换操控面：先用 API 查数据，再打开桌面应用改设置，最后写个脚本处理文件。CUA 提供的是 UI 自动化面这条腿，补上 Agent 操控电脑的最后一块拼图。

三、架构：两条路，同一个目标

3.1 Cua Driver：操控真机

你的 Python 程序 │ ▼ MCP over stdio / CLI ─────► Cua Driver（Rust 二进制） │ ┌─────────────┼─────────────┐ ▼ ▼ ▼ macOS AX Windows UIA Linux AT-SPI + CoreGraphics + 输入注入 + 输入注入 │ │ │ ▼ ▼ ▼ 真机桌面操作（后台运行，不抢焦点）

Cua Driver 是一个 Rust 编写的单二进制文件，通过操作系统原生 API 实现操控：

• macOS：Accessibility（AX）树 + CoreGraphics，利用SLEventPostToPid等私有 SPI 实现后台输入注入，不抢焦点
• Windows：UI Automation + Windows 输入 API
• Linux：AT-SPI + X11/Wayland 输入

关键特性：后台运行（No-Foreground-Contract）——Agent 在后台操控窗口时，你可以继续用前台窗口工作，鼠标和焦点不会被抢走。来源

3.2 Cua Sandbox：一次性虚拟电脑

你的 Python 程序 │ ▼ Sandbox SDK（Python/TypeScript） │ HTTP/WebSocket ▼ computer-server（沙箱内部） │ ▼ 虚拟电脑（Docker/QEMU/Lume/云端）

Sandbox 在隔离的 VM 或容器里启动一台完整电脑，内部跑一个computer-server接收操作指令。任务完成后直接销毁，不污染真机。

支持的运行环境：

表格

3.3 模型边界

⚠️Cua Driver 和 Cua Sandbox 都不包含任何模型逻辑。它们只做两件事：接收操作指令 → 返回观察结果。决定"下一步做什么"完全由你带来的模型负责。这个边界确保了：

1. 你可以自由选择任何 VLM（Claude、GPT-4o、Gemini、开源模型……）
2. CUA 的代码不耦合任何特定推理服务
3. 你可以在同一个操控接口上切换模型，对比效果

四、Python 实战：5 分钟跑起来

4.1 安装

# 需要 Python 3.12 或 3.13（3.14 暂不支持）

pip install cua

cua是统一的元包，自动安装cua-sandbox、cua-agent等子包。

4.2 场景一：操控真机桌面（Local Computer Server）

最实用的场景——让 Agent 直接操控你的电脑。我们先写一个能看到结果的示例：打开 TextEdit 输入文字，截图保存到桌面，同时在桌面创建一个文本文件。

第一步：启动本地 Computer Server

pip install cua-computer-server

python -m computer_server

这会在localhost:8000启动一个 HTTP 服务，暴露截图、鼠标、键盘等接口。

⚠️安全警告：这个服务能完全控制你的桌面，不要暴露到公网，不用时关掉。

第二步：Python 代码——打开 TextEdit、输入文字、截图保存到桌面

python

""" CUA 实战示例：操控真机桌面 运行后你会在桌面上看到： 📄 hello_from_ai.txt — AI 写入的文本文件 📸 cua_screenshot_xxx.png — 操作截图 """ import asyncio import os import subprocess from datetime import datetime from computer import Computer async def main(): desktop = os.path.expanduser("~/Desktop") timestamp = datetime.now().strftime("%Y%m%d_%H%M%S") # ① 连接本地 computer-server computer = Computer(use_host_computer_server=True) await computer.run() try: # ② 打开 TextEdit（用 subprocess 比 CUA 模拟键盘更可靠） subprocess.Popen(["open", "-a", "TextEdit"]) await asyncio.sleep(2) # 等 TextEdit 启动 # ③ 用 CUA 在 TextEdit 中输入文字 await computer.interface.type_text("Hello from AI!") print("✏️ 已在 TextEdit 中输入文字") # ④ 截图保存到桌面（screenshot() 返回 PNG 字节） screenshot = await computer.interface.screenshot() screenshot_path = os.path.join(desktop, f"cua_screenshot_{timestamp}.png") with open(screenshot_path, "wb") as f: f.write(screenshot) print(f"📸 截图已保存: {screenshot_path}") # ⑤ 在桌面创建结果文件（演示 CUA + Python 配合） result_path = os.path.join(desktop, "hello_from_ai.txt") with open(result_path, "w") as f: f.write(f"Hello from AI!\n\n由 CUA Computer SDK 自动创建\n时间: {timestamp}\n") print(f"📄 文本已保存: {result_path}") print(f"\n✅ 完成！请查看桌面：") print(f" 📄 hello_from_ai.txt — 文本文件") print(f" 📸 cua_screenshot_{timestamp}.png — 操作截图") finally: await computer.disconnect() asyncio.run(main())

运行效果：桌面上会出现一个hello_from_ai.txt和一张截图 PNG，TextEdit 里显示着 "Hello from AI!"。三个东西都是"看得见"的结果。

💡 为什么用 subprocess 打开 TextEdit？CUA 的press_key不支持组合键（如 Cmd+Space 打开 Spotlight），对"打开应用"这种操作，Python 标准库更稳。CUA 负责"看屏幕、点鼠标、敲键盘"，Python 负责文件 I/O 和应用启动，两者各司其职。

同步写法（cua-auto 库）：如果你不习惯 async/await，cua-auto提供同步 API，更简洁：

bash

pip install cua-auto

python

import cua_auto import os import subprocess from datetime import datetime desktop = os.path.expanduser("~/Desktop") timestamp = datetime.now().strftime("%Y%m%d_%H%M%S") # 打开 TextEdit 并输入文字 subprocess.Popen(["open", "-a", "TextEdit"]) import time; time.sleep(2) cua_auto.keyboard.type_text("Hello from AI!") # 输入文字 screenshot = cua_auto.screen.screenshot() # 截图 screenshot.save(os.path.join(desktop, f"cua_screenshot_{timestamp}.png")) # 保存文本到桌面 with open(os.path.join(desktop, "hello_from_ai.txt"), "w") as f: f.write(f"Hello from AI!\n由 cua-auto 创建\n时间: {timestamp}\n") print("✅ 完成！请查看桌面")

第三步：接入大模型，实现完整 Agent 循环

上面是手动调用 API，真正强大的是让大模型自己决定点哪里、输什么。只需要三步：连接电脑 → 创建 Agent → 下达任务。

python

import os import asyncio from cua import Sandbox, Image, ComputerAgent # 设置你的模型 API Key（二选一） os.environ["ANTHROPIC_API_KEY"] = "sk-ant-..." # Anthropic # os.environ["OPENAI_API_KEY"] = "sk-..." # OpenAI async def main(): # 连接本地桌面 async with Sandbox.create(use_host_computer_server=True) as computer: # 创建 Agent，选择模型 agent = ComputerAgent( model="anthropic/claude-sonnet-4-5-20250929", # 或 "openai/gpt-4o" tools=[computer], max_trajectory_budget=5.0 # 最大花费 $5 ) # 给 Agent 下达任务 task = "打开浏览器，访问 github.com，搜索 cua" async for result in agent.run(task): print(result) asyncio.run(main())

这就是一个完整的"大模型操控电脑"程序——Agent 会自己看截图、理解界面、点击按钮、输入文字，你只需要说"做什么"。

4.3 场景二：沙箱隔离运行

不想让 AI 碰你的真机？用沙箱。

本地 Docker 沙箱（需安装 Docker）：

python

from computer import Computer import asyncio async def main(): # 在 Docker 里启动一台 Linux 虚拟电脑 computer = Computer( os_type="linux", provider_type="docker", image="trycua/cua-xfce:latest" ) await computer.run() try: await computer.interface.left_click(100, 100) await computer.interface.type_text("Hello Sandbox!") screenshot = await computer.interface.screenshot() finally: await computer.disconnect() asyncio.run(main())

云端沙箱（无需本地 Docker，cua.ai 托管）：

import os from cua import Sandbox, Image, ComputerAgent os.environ["CUA_API_KEY"] = "sk_cua-api01_..." async def main(): # 一行创建一次性云端沙箱 async with Sandbox.ephemeral(Image.linux()) as sb: agent = ComputerAgent( model="cua/anthropic/claude-sonnet-4.5", # Cua 路由模型 tools=[sb], max_trajectory_budget=5.0 ) messages = [{"role": "user", "content": "打开浏览器访问 wikipedia.org"}] async for result in agent.run(messages): print(result) asyncio.run(main())

云端沙箱 1 秒热启动，任务完成自动销毁。来源

4.4 场景三：MCP 集成（给 Claude Code 装上手）

如果你用的是 Claude Code，可以直接把 Cua Driver 作为 MCP 服务器接入：

bash

# 1. 安装 Cua Driver

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/cua-driver/scripts/install.sh)"

# 2. 注册为 Claude Code 的 MCP 服务器

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

# 3. 重启 Claude Code，然后说：

# "帮我打开浏览器，访问 google.com，搜索'天气'"

Claude Code 会自动调用 Cua Driver 来操控你的桌面。来源

Windows 用户用 PowerShell 安装：

powershell

irm https://raw.githubusercontent.com/trycua/cua/main/libs/cua-driver/scripts/install.ps1 | iex

五、支持的模型

CUA 通过 LiteLLM 支持上百种模型，无需改代码，换一个字符串即可 来源：

表格

组合模型（Composite Agents）是 CUA 的特色功能：用一个轻量视觉模型做"定位"（Grounding，识别屏幕上的按钮/输入框位置），再用一个强推理模型做"规划"（Planning，决定下一步做什么）。这样既准又省。

python

# 组合模型示例：UI-TARS 定位 + GPT-4o 规划

agent = ComputerAgent(

model="huggingface-local/ByteDance-Seed/UI-TARS-1.5-7B+openai/gpt-4o",

tools=[computer]

)

六、核心 API 速查

连接电脑后，所有操作通过computer.interface调用：

表格

生命周期方法：

表格

七、成本与选型建议

表格

省钱技巧：

1. max_trajectory_budget控制单任务花费上限
2. 简单任务用 Haiku，复杂任务才上 Sonnet/Opus
3. 组合模型比单模型省：视觉定位用本地 7B 模型（免费），只有推理调 API

八、踩坑记录

1. Python 版本：必须 3.12 或 3.13，3.14 因 pydantic-core/PyO3 兼容问题暂不支持 来源
2. macOS 按键方法名：MacOSComputerInterface上按键方法是press_key()不是文档里写的key()；回车键名用"return"不用"Enter"来源
3. 不支持组合键：press_key()只能按单个键，无法模拟 Cmd+S、Cmd+Space 等组合键。需要快捷键的场景，用 subprocess/AppleScript 启动应用或执行操作更可靠
4. macOS 权限：Cua Driver 需要在系统偏好设置中授予"辅助功能"和"屏幕录制"权限
5. Docker 沙箱分辨率：默认分辨率可能偏高，影响截图 Token 消耗，建议用trycua/cua-xfce:latest（轻量 XFCE 桌面）
6. 异步 API：所有操控方法都是 async，必须配合asyncio.run()使用；不习惯异步可用cua-auto同步库
7. cua-computer已弃用：新项目用cua-sandbox，旧代码需按迁移指南更新 来源
8. Local Computer Server 安全：默认监听所有接口，生产环境务必指定--host 127.0.0.1或加防火墙规则
9. QEMU 需要 KVM：本地跑 Linux/Windows 虚拟机需要/dev/kvm支持，Docker 启动时传devices: ["/dev/kvm"]

九、快速开始检查清单

bash

# 1. 安装

pip install cua

# 2. 操控真机——额外安装并启动 computer-server

pip install cua-computer-server

python -m computer_server

# 3. 操控沙箱——确保 Docker 已安装

docker pull trycua/cua-xfce:latest

# 4. 设置模型 API Key

export ANTHROPIC_API_KEY="sk-ant-..."

# 或

export OPENAI_API_KEY="sk-..."

# 5. 运行你的第一个 Agent

python my_first_agent.py

小结

CUA 把"AI 操控电脑"从特定厂商的专属能力变成了开放基础设施：

• 架构简洁：Driver 操真机，Sandbox 跑虚拟机，模型你自己选
• 上手极快：pip install cua+ 几行 Python 就能跑
• 安全可控：沙箱隔离、预算控制、权限管理三重保障
• 生态丰富：100+ 模型、5 种沙箱后端、MCP 集成

不需要等 Hermes 或 Claude Code，一行pip install cua就能让你的 Python 程序拥有操控电脑的能力。

参考链接：

• CUA 官方文档：cua.ai/docs
• GitHub 仓库：github.com/trycua/cua
• Computer-Use 2.0 概念：cua.ai/docs/explanation/what-is-computer-use
• 架构说明：cua.ai/docs/explanation/architecture
• Local Computer Server：cua.ai/docs/cua/guide/advanced/local-computer-server
• Agent SDK 使用：cua.ai/docs/cua/guide/get-started/using-agent-sdk