选择你的路径

---

Cua - 适用于任何操作系统的智能体就绪沙盒

构建能够查看屏幕、点击按钮并自主完成任务的智能体。一个 API 适用于任何虚拟机或容器镜像——无论是在云端还是本地。

pip install cua

# 需要 Python 3.11 或更高版本
from cua import Sandbox, Image

# 不论操作系统或运行时，API 均相同
async with Sandbox.ephemeral(Image.linux()) as sb:   # 或 .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))  # 多点触控手势

	Linux 容器	Linux 虚拟机	macOS	Windows	Android	自定义镜像 (.qcow2, .iso)
云（cua.ai）	✅	✅	✅	✅	✅	🔜 soon
本地（QEMU）	✅	✅	✅	✅	✅	✅

开始使用 | 示例 | API 参考

---

CuaBot - 任何智能体的协作式计算机使用环境

cuabot 为任何编码智能体提供了一个无缝的计算机使用沙盒。各个窗口以原生方式显示在您的桌面上，支持 H.265 编码、共享剪贴板和音频功能。

npx cuabot                 # 设置引导流程

# 在沙盒中运行任何智能体
cuabot claude              # Claude Code
cuabot openclaw            # OpenClaw 在沙盒中

# 在沙盒中运行任何 GUI 工作流
cuabot chromium
cuabot --screenshot
cuabot --type "hello"
cuabot --click <x> <y> [button]

内置对 agent-browser 和 agent-device（iOS、Android）的支持，开箱即用。

---

Cua-Bench - 基准测试与强化学习环境

在 OSWorld、ScreenSpot、Windows Arena 以及自定义任务上评估计算机使用智能体。可导出轨迹用于训练。

# 安装并创建基础镜像
cd cua-bench
uv tool install -e . && cb image create linux-docker

# 使用智能体运行基准测试
cb run dataset datasets/cua-bench-basic --agent cua-agent --max-parallel 4

开始使用 | 与我们合作 | 注册表 | CLI 参考

---

Lume - macOS 虚拟化

利用 Apple 的 Virtualization.Framework，在 Apple Silicon 上以接近原生的性能创建和管理 macOS/Linux 虚拟机。

# 安装 Lume
/bin/bash -c "$(curl -fsSL https6://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh)"

# 拉取并启动一个 macOS 虚拟机
lume run macos-sequoia-vanilla:latest

开始使用 | 常见问题解答 | CLI 参考

---

软件包

软件包	描述
cuabot	多智能体计算机使用沙盒 CLI
cua-agent	面向计算机任务的 AI 智能体框架
cua-sandbox	用于创建和控制沙盒的 SDK
cua-computer-server	沙盒中用于 UI 交互和代码执行的驱动程序
cua-bench	针对计算机使用的基准测试与强化学习环境
lume	在 Apple Silicon 上管理 macOS/Linux 虚拟机
lumier	Lume 虚拟机的 Docker 兼容接口

资源

• 文档 — 指南、示例和 API 参考
• 博客 — 教程、更新和研究
• Discord — 社区支持与讨论
• GitHub 问题 — 错误报告和功能请求

贡献

我们欢迎各类贡献！详情请参阅我们的贡献指南。

许可证

MIT 许可证 — 详情请见 LICENSE。

第三方组件拥有各自的许可证：

• Kasm (MIT)
• OmniParser (CC-BY-4.0)
• 可选的 cua-agent[omni] 包含 ultralytics (AGPL-3.0)

商标

Apple、macOS、Ubuntu、Canonical 和 Microsoft 均为其各自所有者的商标。本项目与这些公司无任何关联，亦未获其认可或背书。

---

Cua 快速上手指南

Cua 是一个用于构建、基准测试和部署计算机操作智能体（Computer-Use Agents）的开源框架。它提供统一的 API，让智能体能够像人类一样查看屏幕、点击按钮并自主完成任务，支持本地虚拟机、容器及云端环境。

环境准备

• 操作系统：支持 Linux、macOS (Apple Silicon/Intel) 和 Windows。
  • 若使用 Lume 组件管理 macOS 虚拟机，必须运行在 macOS (Apple Silicon) 上。
• Python 版本：需要 Python 3.11 或更高版本。
• 前置依赖：
  • 本地运行需安装 QEMU（用于虚拟化支持）。
  • 推荐使用 uv 或 pip 进行包管理。
• 网络要求：首次运行可能需要拉取基础镜像，建议确保网络连接畅通。

安装步骤

1. 安装核心 SDK (cua)

用于构建和控制沙箱环境。

pip install cua

2. 安装 CuaBot (可选)

如果你需要一个带有图形界面（H.265 视频流、共享剪贴板）的沙箱来运行现有的编码智能体（如 Claude Code），请安装 CuaBot。

npx cuabot

运行后按提示完成初始化设置。

3. 安装 Lume (仅限 macOS 用户)

如果你需要在 Apple Silicon Mac 上高性能地创建和管理 macOS/Linux 虚拟机：

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

基本使用

场景一：使用 Python SDK 控制沙箱

这是最基础的用法，创建一个临时的 Linux 沙箱，执行 shell 命令、截图、模拟鼠标点击和键盘输入。

# 需要 Python 3.11+
from cua import Sandbox, Image

async with Sandbox.ephemeral(Image.linux()) as sb:   # 也可替换为 .macos(), .windows(), .android()
    # 执行 Shell 命令
    result = await sb.shell.run("echo hello")
    
    # 获取屏幕截图
    screenshot = await sb.screenshot()
    
    # 模拟鼠标点击 (x=100, y=200)
    await sb.mouse.click(100, 200)
    
    # 模拟键盘输入
    await sb.keyboard.type("Hello from Cua!")
    
    # 模拟移动端多点触控手势
    await sb.mobile.gesture((100, 500), (100, 200))

场景二：使用 CuaBot 运行智能体

通过命令行直接在隔离的沙箱中运行现有的 AI 智能体或 GUI 工作流。

# 运行 Claude Code 智能体
cuabot claude

# 运行 OpenClaw 智能体
cuabot openclaw

# 运行浏览器自动化任务
cuabot chromium

# 直接执行 GUI 操作示例
cuabot --screenshot          # 截取当前沙箱屏幕
cuabot --type "hello"        # 在沙箱中输入文本
cuabot --click <x> <y>       # 在指定坐标点击

场景三：使用 Lume 启动 macOS 虚拟机 (macOS 专用)

拉取并启动一个原生的 macOS 虚拟机实例。

# 启动最新版的 macOS Sequoia  vanilla 镜像
lume run macos-sequoia-vanilla:latest