企业官网建设流程全解析

CUA Computer SDK 完全指南：几行代码给脚本一台可操控的虚拟机

【免费下载链接】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

假设你的场景是这样：写一段脚本，打开一台干净的 Linux 桌面，把浏览器指到某个网址，截一张全屏图回来留档。用传统方式，你得手动装 QEMU、配镜像、写 VNC 连接，一遍下来半天就过去了。而 CUA Computer SDK 把这些收敛成了十几行 Python：pip install之后，run()起机，interface上点鼠标、敲键盘、拿截图，stop()收工。这篇指南带你从零把这条链路完整跑通，最后你会得到一个"随叫随到、用完即走"的虚拟机操控方案。

它到底是什么

CUA Computer SDK（包名cua-computer）是 CUA 项目里负责"给程序一台电脑"的 Python 层：它把虚拟机的创建、连接、键鼠、屏幕、文件系统统一成一套异步接口，底层的虚拟机引擎可以换，你的代码不用换。

打个比方：它不是给你一把拧螺丝的螺丝刀，而是租给你一间带门禁的"云机房"——进门卡（api_key）一刷，里面桌椅（桌面系统）齐全，你想怎么摆弄都行，退房（stop()）时所有痕迹留在房间里，不带走任何主机状态。

准备工作：安装前检查

• ☑ Python 版本在 3.12 ~ 3.13 之间（见 libs/python/computer/pyproject.toml，3.11 装不上、3.14 暂未验证）
• ☑ 目标后端就绪：本地 macOS 需 Apple Silicon 并已装好 Lume CLI；本地 Linux 容器需 Docker +trycua/cua-ubuntu镜像；云端则只需一张CUA_API_KEY
• ☑ 端口空闲：默认占用 7777（provider API）与 8006（noVNC），被占用的话起机阶段会卡住
• ☑ （可选）想拉源码对照：git clone https://gitcode.com/GitHub_Trending/cua/cua

最小可跑示例

步骤 1：安装依赖

pip install "cua-computer[all]"

[all]会带上 Gradio 可视化等可选依赖，纯跑自动化不带也行。

步骤 2：初始化虚拟机对象

import asyncio from computer import Computer # Linux 容器最省心：Docker 里跑 XFCE 桌面，无需本机虚拟化 computer = Computer( os_type="linux", # 目标系统 provider_type="docker", # 本地后端；macOS 场景可换 "lume" name="demo-vm", display="1024x768", # 分辨率 memory="8GB", # 内存 cpu="4", # vCPU 数 )

想验证 macOS 路线的话，把provider_type换成"lume"、os_type换成"macos"即可，其余代码不变（源码见 libs/python/computer/computer/computer.py）。

步骤 3：运行、操控、关闭

async def main(): await computer.run() # 启动 VM 并建立连接 await computer.interface.type_text("hello cua") await computer.interface.left_click(500, 400) png = await computer.interface.screenshot() # 返回 PNG 字节流 open("out.png", "wb").write(png) await computer.stop() asyncio.run(main())

跑完手边会多一张out.png，虚拟机也干净退场了。

进阶玩法

想做"人在回路"地亲眼看着 VM 操作，就用内置 Gradio 界面。cua-computer[all]自带 UI，起一个网页窗口实时看屏幕并手动注入操作，调试坐标类问题比盲打代码快得多，入口在 libs/python/computer/computer/ui/gradio/app.py。

想把宿主机的目录塞进虚拟机，就用shared_directories参数。构造Computer(...)时传入本地路径列表，宿主机与 VM 之间即可互传文件，适合"脚本喂数据、VM 出报告"这类流水线。

想让动作留痕、给模型做训练素材，就用轨迹捕获。CUA 的 cua-bench 会把每次键鼠/截图事件导出成标准轨迹格式，直接对接 RL 训练与评测，SDK 这一层是它的动作数据源。

避坑指南：常见坑

现象：computer.run()长时间无响应或报端口冲突。原因：provider 默认监听 7777、noVNC 默认 8006，本机已有进程占用（比如上一次没退干净的 VM）。解法：起机前先确认端口空闲，或在构造时显式指定provider_port、noVNC_port换一组端口。

现象：RuntimeWarning: coroutine 'Computer.run' was never awaited。原因：run()/stop()/ 所有interface方法都是协程，直接同步调用不会执行。解法：把整个流程包进async def并用asyncio.run()驱动；同时用try/finally包住stop()，避免异常后 VM 泄漏挂在后台。

现象：macOS + Lume 后端首次起机失败或卡在 Setup Assistant。原因：Lume 预设（tahoe/sequoia）会创建lume用户并开启 SSH，但部分版本首次亮屏仍会弹出辅助功能确认页（上游已有 issue 跟踪）。解法：优先使用 E2E 验证过的tahoe预设；Sequoia 用户按 README 指引手动完成一次辅助功能授权后再复用该 VM。

资源区

一句话总结：CUA Computer SDK 把"开机器、动鼠标、拿截图"压缩成几行 async 代码，是本地、容器、云端三条路线下同一套的虚拟机自动化底座。

• 包说明与文档入口：libs/python/computer/README.md
• 键鼠/屏幕/文件完整接口定义：libs/python/computer/computer/interface/base.py
• 后端调度逻辑（Lume / Lumier / Docker / Cloud）：libs/python/computer/computer/providers/factory.py
• 顶层项目 README（Cua / Cua-Bench / Lume 全景）：README.md

【免费下载链接】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