不是只有 Claude Code 和 Hermes 才能操控桌面。CUA 提供了一套独立的开放基础设施pip install 就能让你的 Python 程序拥有看屏幕、点鼠标、敲键盘的能力。前言2024 年 10 月 Anthropic 发布 Computer Use 的时候AI 操控电脑还是 Claude 的专属能力。一年后开源社区已经有了完整的替代方案CUAComputer-Use Agents一个让任何大模型都能操控电脑的开放框架。CUA 不绑定任何 Agent 框架——你可以在 Hermes 里用也可以脱离 Hermes 直接用 Python 调用你可以控制真机桌面也可以在云端沙箱里隔离运行。这篇文章把 CUA 的架构、原理和独立使用方法梳理清楚给出可以直接跑的 Python 代码。一、CUA 是什么CUA 是 trycua/cua 开源项目18k Stars提供的 Computer-Use 基础设施核心解决一个问题给 AI 装上一双能操作电脑的手。它包含两个独立产品表格组件用途运行环境适合场景Cua Driver操控真机桌面你的 Mac/Windows/Linux 本机操作已安装的应用、已登录的账号、本地文件Cua Sandbox提供一次性虚拟电脑云端或本地 VM/容器不可信任务隔离、批量并行、跨 OS 测试两者共享同一个设计原则模型无关——它们只负责接收操作指令、返回屏幕观察结果截图/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 DriverRust 二进制 │ ┌─────────────┼─────────────┐ ▼ ▼ ▼ macOS AX Windows UIA Linux AT-SPI CoreGraphics 输入注入 输入注入 │ │ │ ▼ ▼ ▼ 真机桌面操作后台运行不抢焦点Cua Driver 是一个 Rust 编写的单二进制文件通过操作系统原生 API 实现操控macOSAccessibilityAX树 CoreGraphics利用SLEventPostToPid等私有 SPI 实现后台输入注入不抢焦点WindowsUI Automation Windows 输入 APILinuxAT-SPI X11/Wayland 输入关键特性后台运行No-Foreground-Contract——Agent 在后台操控窗口时你可以继续用前台窗口工作鼠标和焦点不会被抢走。来源3.2 Cua Sandbox一次性虚拟电脑你的 Python 程序 │ ▼ Sandbox SDKPython/TypeScript │ HTTP/WebSocket ▼ computer-server沙箱内部 │ ▼ 虚拟电脑Docker/QEMU/Lume/云端Sandbox 在隔离的 VM 或容器里启动一台完整电脑内部跑一个computer-server接收操作指令。任务完成后直接销毁不污染真机。支持的运行环境表格后端支持的 OS说明DockerLinuxXFCE/Ubuntu最轻量Docker 即可QEMULinux/Windows/Android完整虚拟机需 KVMLumemacOSApple Silicon 原生虚拟化97% 原生 CPU 性能云端Linux/macOS/Windows/Androidcua.ai 托管1 秒热启动Windows SandboxWindowsWindows 自带沙箱3.3 模型边界⚠️Cua Driver 和 Cua Sandbox 都不包含任何模型逻辑。它们只做两件事接收操作指令 → 返回观察结果。决定下一步做什么完全由你带来的模型负责。这个边界确保了你可以自由选择任何 VLMClaude、GPT-4o、Gemini、开源模型……CUA 的代码不耦合任何特定推理服务你可以在同一个操控接口上切换模型对比效果四、Python 实战5 分钟跑起来4.1 安装# 需要 Python 3.12 或 3.133.14 暂不支持pip install cuacua是统一的元包自动安装cua-sandbox、cua-agent等子包。4.2 场景一操控真机桌面Local Computer Server最实用的场景——让 Agent 直接操控你的电脑。我们先写一个能看到结果的示例打开 TextEdit 输入文字截图保存到桌面同时在桌面创建一个文本文件。第一步启动本地 Computer Serverpip install cua-computer-serverpython -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_serverTrue) 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, fcua_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(fHello 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和一张截图 PNGTextEdit 里显示着 Hello from AI!。三个东西都是看得见的结果。 为什么用 subprocess 打开 TextEditCUA 的press_key不支持组合键如 CmdSpace 打开 Spotlight对打开应用这种操作Python 标准库更稳。CUA 负责看屏幕、点鼠标、敲键盘Python 负责文件 I/O 和应用启动两者各司其职。同步写法cua-auto 库如果你不习惯 async/awaitcua-auto提供同步 API更简洁bashpip install cua-autopythonimport 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, fcua_screenshot_{timestamp}.png)) # 保存文本到桌面 with open(os.path.join(desktop, hello_from_ai.txt), w) as f: f.write(fHello from AI!\n由 cua-auto 创建\n时间: {timestamp}\n) print(✅ 完成请查看桌面)第三步接入大模型实现完整 Agent 循环上面是手动调用 API真正强大的是让大模型自己决定点哪里、输什么。只需要三步连接电脑 → 创建 Agent → 下达任务。pythonimport 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_serverTrue) as computer: # 创建 Agent选择模型 agent ComputerAgent( modelanthropic/claude-sonnet-4-5-20250929, # 或 openai/gpt-4o tools[computer], max_trajectory_budget5.0 # 最大花费 $5 ) # 给 Agent 下达任务 task 打开浏览器访问 github.com搜索 cua async for result in agent.run(task): print(result) asyncio.run(main())这就是一个完整的大模型操控电脑程序——Agent 会自己看截图、理解界面、点击按钮、输入文字你只需要说做什么。4.3 场景二沙箱隔离运行不想让 AI 碰你的真机用沙箱。本地 Docker 沙箱需安装 Dockerpythonfrom computer import Computer import asyncio async def main(): # 在 Docker 里启动一台 Linux 虚拟电脑 computer Computer( os_typelinux, provider_typedocker, imagetrycua/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())云端沙箱无需本地 Dockercua.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( modelcua/anthropic/claude-sonnet-4.5, # Cua 路由模型 tools[sb], max_trajectory_budget5.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 安装powershellirm https://raw.githubusercontent.com/trycua/cua/main/libs/cua-driver/scripts/install.ps1 | iex五、支持的模型CUA 通过 LiteLLM 支持上百种模型无需改代码换一个字符串即可 来源表格模型标识特点Claude Sonnet 4.5anthropic/claude-sonnet-4-5-20250929推荐首选性价比最优Claude Opus 4.5anthropic/claude-opus-4-5-20250929最强推理复杂任务GPT-5openai/gpt-5OpenAI 最新旗舰GPT-4oopenai/gpt-4o速度快成本适中Gemini 3 Procua/google/gemini-3-pro-preview多模态能力强UI-TARS GPT-4ohuggingface-local/ByteDance-Seed/UI-TARS-1.5-7Bopenai/gpt-4o组合模型视觉定位精准GTA1 Claudehuggingface-local/HelloKKMe/GTA1-7Banthropic/claude-sonnet-4-5-20250929坐标定位推理组合组合模型Composite Agents是 CUA 的特色功能用一个轻量视觉模型做定位Grounding识别屏幕上的按钮/输入框位置再用一个强推理模型做规划Planning决定下一步做什么。这样既准又省。python# 组合模型示例UI-TARS 定位 GPT-4o 规划agent ComputerAgent(modelhuggingface-local/ByteDance-Seed/UI-TARS-1.5-7Bopenai/gpt-4o,tools[computer])六、核心 API 速查连接电脑后所有操作通过computer.interface调用表格操作Python说明截图await computer.interface.screenshot()返回当前屏幕图像左键点击await computer.interface.left_click(x, y)模拟鼠标左键右键点击await computer.interface.right_click(x, y)模拟鼠标右键双击await computer.interface.double_click(x, y)模拟双击输入文字await computer.interface.type_text(text)键盘输入按键await computer.interface.press_key(return)按特殊键macOS 上回车键名用return滚动await computer.interface.scroll(x, y, clicks)滚轮滚动生命周期方法表格方法说明await computer.run()连接已运行的沙箱/服务await computer.start()启动并连接如沙箱未运行await computer.disconnect()断开连接保持沙箱运行await computer.stop()完全停止沙箱并断开七、成本与选型建议表格场景推荐方案预估成本开发调试Local Computer Server Claude SonnetAPI 费用约 $0.3-1/任务生产任务云端沙箱 组合模型沙箱 $0.05/h API 费用批量并行多个 Docker 沙箱 Haiku最省模型费Claude Code 用户Cua Driver MCP$0用 Claude Code 自带额度省钱技巧max_trajectory_budget控制单任务花费上限简单任务用 Haiku复杂任务才上 Sonnet/Opus组合模型比单模型省视觉定位用本地 7B 模型免费只有推理调 API八、踩坑记录Python 版本必须 3.12 或 3.133.14 因 pydantic-core/PyO3 兼容问题暂不支持 来源macOS 按键方法名MacOSComputerInterface上按键方法是press_key()不是文档里写的key()回车键名用return不用Enter来源不支持组合键press_key()只能按单个键无法模拟 CmdS、CmdSpace 等组合键。需要快捷键的场景用 subprocess/AppleScript 启动应用或执行操作更可靠macOS 权限Cua Driver 需要在系统偏好设置中授予辅助功能和屏幕录制权限Docker 沙箱分辨率默认分辨率可能偏高影响截图 Token 消耗建议用trycua/cua-xfce:latest轻量 XFCE 桌面异步 API所有操控方法都是 async必须配合asyncio.run()使用不习惯异步可用cua-auto同步库cua-computer已弃用新项目用cua-sandbox旧代码需按迁移指南更新 来源Local Computer Server 安全默认监听所有接口生产环境务必指定--host 127.0.0.1或加防火墙规则QEMU 需要 KVM本地跑 Linux/Windows 虚拟机需要/dev/kvm支持Docker 启动时传devices: [/dev/kvm]九、快速开始检查清单bash# 1. 安装pip install cua# 2. 操控真机——额外安装并启动 computer-serverpip install cua-computer-serverpython -m computer_server# 3. 操控沙箱——确保 Docker 已安装docker pull trycua/cua-xfce:latest# 4. 设置模型 API Keyexport ANTHROPIC_API_KEYsk-ant-...# 或export OPENAI_API_KEYsk-...# 5. 运行你的第一个 Agentpython 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/docsGitHub 仓库github.com/trycua/cuaComputer-Use 2.0 概念cua.ai/docs/explanation/what-is-computer-use架构说明cua.ai/docs/explanation/architectureLocal Computer Servercua.ai/docs/cua/guide/advanced/local-computer-serverAgent SDK 使用cua.ai/docs/cua/guide/get-started/using-agent-sdk
)
