CUA (Computer-Use Agents) 深度实战：当 AI 真正学会"使用电脑"——从沙箱基础设施到多模型接入、评测闭环与生产级部署的完全指南（2026）

2024 年 Anthropic 发布 Computer Use 功能，让"AI 操控桌面"从实验室概念变成了开发者能摸到的东西。但真正要把这个能力落地，你需要一整套基础设施：安全的隔离沙箱、统一的跨平台 API、后台无感驱动、评测基准、训练数据 pipeline……这些脏活累活，CUA 全部打包解决了。本文深度拆解 CUA 五大模块，带你从零搭建生产级 Computer-Use Agent。

目录

1. 引言：AI Agent 的"最后一公里"
2. Computer-Use Agents 是什么？
3. CUA 架构全景：五大模块逐一拆解
   • 3.1 Cua Sandbox：一个 API 跑遍所有 OS
   • 3.2 Cua Driver：不抢光标的后台操控
   • 3.3 cua-agent：主流模型全支持
   • 3.4 Cua-Bench：真实桌面任务评测
   • 3.5 Lume：Apple Silicon 上的 macOS 虚拟化
4. 实战：从零搭建 Computer-Use Agent
   • 4.1 环境准备与安装
   • 4.2 第一个 Agent 任务
   • 4.3 多 OS 沙箱实战
   • 4.4 接入本地模型（Ollama + OmniParser）
5. 深度：架构设计与技术决策分析
   • 5.1 为什么需要统一的 Sandbox API
   • 5.2 后台驱动的底层实现原理
   • 5.3 OmniParser 的 UI 元素识别原理
   • 5.4 沙箱快照与 Fork 机制
6. 性能优化与生产实践
   • 6.1 热启动优化
   • 6.2 并行 Agent 任务
   • 6.3 轨迹录制与训练数据 Pipeline
7. 评测：Cua-Bench 完全指南
8. 安全考量：沙箱隔离与权限控制
9. 未来展望：Computer-Use Agent 的下一步
10. 总结

1. 引言：AI Agent 的"最后一公里"

你有没有想过，让 AI 帮你在电脑上干活——不是生成文本，而是真的打开浏览器、点击按钮、填写表单、提交代码？

这件事听起来像科幻，但现在已经有人把基础设施搭好了。

过去两年，"Computer Use"（计算机使用）已成为 AI 领域最热的方向之一。Anthropic 的 Claude 3.5+、OpenAI 的 Operator、Google 的 Gemini，各家大模型纷纷宣布具备"操控桌面"的能力。但当开发者真正想把这个能力落地时，却撞上了一堵墙：

一句话总结：缺一套专门为 AI Agent 设计的、安全隔离的"电脑基础设施"。

CUA（Computer-Use Agents）就是这个基础设施。它不是一个模型，不是一个算法，而是一整套开源的 Computer-Use Agent 基础设施平台，覆盖从"搭环境"到"评测训练"的整条链路。

核心数据：

• GitHub Stars：17,300+（2025 年 1 月上线，约一年半时间）
• Forks：1,083
• 贡献者：70 人
• 发布版本：500+
• 许可证：MIT（无商用限制）
• 社区规模：50,000+ 工程师使用
• 知名用户：Hugging Face、Meta、Apple、NVIDIA、Duolingo 等公司工程师

2. Computer-Use Agents 是什么？

在深入 CUA 之前，我们需要先理解 Computer-Use Agent 这个概念本身。

2.1 从 Chatbot 到 Agent 到 Computer-Use Agent

AI 的能力演进可以分为三个阶段：

阶段 1：对话模型（Chatbot）
  输入：文本
  输出：文本
  能力：问答、写作、翻译、代码生成
  限制：无法感知环境，无法执行操作

阶段 2：工具调用 Agent（Tool-Using Agent）
  输入：文本 + 工具定义
  输出：文本 + 工具调用
  能力：搜索、查数据库、调用 API、执行代码
  限制：操作范围受工具定义限制，无法操作任意应用

阶段 3：Computer-Use Agent（桌面操控 Agent）
  输入：屏幕截图 + 任务描述
  输出：鼠标/键盘操作序列
  能力：操作任意应用，包括没有 API 的闭源软件
  突破：真正通用的计算机操作能力

2.2 Computer-Use Agent 的核心挑战

让 AI 操控桌面，远比让 AI 调用 API 难。核心挑战有三个：

挑战一：感知（Perception）

AI 需要"看懂"屏幕。这不仅仅是 OCR，而是理解 UI 元素的语义：

• 哪个是按钮？哪个是输入框？哪个是下拉菜单？
• 按钮当前是可用状态还是禁用状态？
• 页面加载完成了吗？有没有弹出对话框？

挑战二：决策（Decision）

AI 需要根据当前屏幕状态决定下一步操作：

• 要点击哪个元素？
• 要输入什么内容？
• 如果操作失败，如何恢复？

挑战三：执行（Execution）

AI 的操作需要精确转换为鼠标坐标和键盘事件，同时保证：

• 操作的可复现性（用于训练数据收集）
• 执行的安全性（不能操作宿主机器）
• 并发的可行性（多个 Agent 同时运行）

2.3 为什么是现在？

Computer-Use Agent 为什么在 2024-2026 年突然热起来？三个技术拐点：

1. 多模态大模型的成熟：GPT-4V、Claude 3.5+、Gemini 1.5+ 等模型具备了强大的视觉理解能力，能"看懂"屏幕截图。

2. 上下文长度的突破：Claude 3.5 支持 200K tokens，Gemini 1.5 支持 1M tokens，足够容纳多张截图和完整的操作历史。

3. 开源生态的完善：OmniParser、Set-of-Marks 等 UI 元素识别工具开源，使得基于开源模型的 Computer-Use Agent 成为可能。

3. CUA 架构全景：五大模块逐一拆解

CUA 的核心架构可以概括为"三层体系"：

┌─────────────────────────────────────────────────────┐
│          你的 AI Agent（逻辑层）                      │
│    Claude / GPT / Gemini / Ollama / 自定义模型       │
└────────────────────┬────────────────────────────────┘
                     │ 统一 API
┌────────────────────▼────────────────────────────────┐
│        Computer SDK（接口层）                        │
│   截图 · 点击 · 键盘 · Shell · 文件 I/O · 触控       │
└────────────────────┬────────────────────────────────┘
                     │ 隔离执行
┌────────────────────▼────────────────────────────────┐
│          Sandbox（隔离层）                           │
│  macOS VM · Linux Docker · Windows · Android         │
└─────────────────────────────────────────────────────┘

在这个三层体系之上，CUA 提供了五大核心模块：

下面逐一深度拆解。

3.1 Cua Sandbox：一个 API 跑遍所有 OS

Cua Sandbox 的设计思路很干净——同一套 Python API，不管是 Linux 容器、macOS VM 还是 Windows 沙箱，调用方式完全一样。

3.1.1 核心 API 设计

from cua import Sandbox, Image

# Linux 沙箱
async with Sandbox.ephemeral(Image.linux()) as sb:
    result = await sb.shell.run("echo hello")
    screenshot = await sb.screenshot()
    await sb.mouse.click(100, 200)
    await sb.keyboard.type("Hello from Cua!")

# macOS 沙箱（只需改一行）
async with Sandbox.ephemeral(Image.macos()) as sb:
    ...

# Windows 沙箱
async with Sandbox.ephemeral(Image.windows()) as sb:
    ...

# Android 沙箱
async with Sandbox.ephemeral(Image.android()) as sb:
    await sb.mobile.gesture((100, 500), (100, 200))  # 多点触控

这种抽象做得很彻底。本地用 QEMU 或 Lume 跑 VM，云端走 cua.ai，切换时代码完全不用动。

3.1.2 沙箱类型对比

3.1.3 云端沙箱的高级特性

CUA 的云端沙箱（cua.ai）提供了几个非常实用的高级特性：

热启动（Warm Start）

传统 VM 启动需要 30-60 秒，CUA 云端沙箱通过预启动池 + 快照恢复，将热启动时间压缩到不到 1 秒。

实现原理：

1. 预启动池维护一组已经启动到登录界面的 VM 快照
2. 收到请求时，从池中取出一个快照，恢复网络配置
3. 通过 Copy-on-Write 技术，支持从一个" golden image "瞬间 fork 出 N 个并行实例

环境快照与 Fork

# 创建一个配置好开发环境的沙箱
async with Sandbox.ephemeral(Image.macos("sequoia")) as sb:
    # 安装开发工具
    await sb.shell.run("brew install git node python3")
    await sb.shell.run("npm install -g typescript")
    
    # 创建快照
    snapshot_id = await sb.snapshot()
    
    # 从快照 fork 出 10 个并行沙箱
    sandboxes = await Sandbox.fork(snapshot_id, count=10)
    
    # 并行执行 10 个 Agent 任务
    # ...

这个特性对于需要大规模并行评测的场景非常关键。

3.1.4 统一 API 的底层实现

Cua Sandbox 的统一 API 并不是简单的封装，而是有一套完整的设备抽象层（Device Abstraction Layer）：

┌─────────────────────────────────────┐
│         Python SDK (用户接口)         │
├─────────────────────────────────────┤
│        Device Abstraction Layer      │
│  (Screen / Mouse / Keyboard / Shell)│
├────────────────┬───────────┬────────┤
│  macOS Driver  │ Linux SHIM │  ...  │
│  (Cua Driver) │ (Docker API│       │
└────────────────┴───────────┴────────┘

每种设备能力（屏幕、鼠标、键盘、Shell）都有统一的接口定义，不同平台的实现负责将统一接口转换为平台特定的调用。

3.2 Cua Driver：不抢光标的后台操控

这是 CUA 中最实用的一个模块，也是区别于其他 Computer-Use 方案的核心竞争力。

3.2.1 传统桌面自动化的痛点

普通的桌面自动化工具（如 PyAutoGUI、Selenium）有个老毛病：

• 抢光标：Agent 在操作时，你的鼠标光标会被抢走，什么都干不了
• 焦点劫持：Agent 打开应用时，会劫持窗口焦点，打断你当前的工作
• 无障碍接口限制：传统工具主要依赖系统无障碍接口（Accessibility API / AX），对 Chromium 内容和 Canvas 类应用（Blender、Figma、DAW、游戏引擎等）支持不好

3.2.2 Cua Driver 的解决方案

Cua Driver 通过苹果私有的屏幕合成器接口，实现了真正的后台无感操控：

传统方案：
  Agent → 模拟输入事件 → 系统事件队列 → 前台应用接收

Cua Driver 方案：
  Agent → Cua Driver → 直接向目标应用发送事件 → 后台执行
                      ↑
              不经过系统事件队列，不抢焦点

核心优势：

1. 不抢光标：Agent 在后台静默运行，不抢光标、不切换焦点、不打断你当前的工作
2. 支持 Chromium/Canvas 应用：通过屏幕合成器接口，可以操作依赖 GPU 渲染的应用
3. 内置 MCP Server：可以直接接入 Claude Code 和 Cursor，让这些编程 Agent 多一双"眼睛和手"

3.2.3 安装与使用

安装只需要一行：

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

安装后，Cua Driver 会自动注册为 macOS 的辅助功能（需要授权）。

MCP Server 模式下，Cua Driver 会启动一个本地 HTTP 服务器，提供以下端点：

# 截图
curl http://localhost:8765/screenshot

# 点击
curl -X POST http://localhost:8765/mouse/click \
  -H "Content-Type: application/json" \
  -d '{"x": 100, "y": 200}'

# 输入文本
curl -X POST http://localhost:8765/keyboard/type \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello from Cua!"}'

3.2.4 轨迹录制与回放

Cua Driver 每次会话自动录制成可回放的轨迹：

from cua.driver import Driver, Recording

# 启动录制
driver = Driver()
recording = driver.start_recording()

# 执行 Agent 任务
await agent.run("在 GitHub 上搜索 trycua/cua")

# 停止录制
recording.stop()

# 保存轨迹
recording.save("github_search.json")

# 回放轨迹（用于调试和训练数据收集）
recording.replay()

轨迹文件的格式：

{
  "metadata": {
    "task": "在 GitHub 上搜索 trycua/cua",
    "model": "claude-4.7-sonnet",
    "timestamp": "2026-06-18T00:00:00Z"
  },
  "steps": [
    {
      "step": 1,
      "screenshot": "base64...",
      "action": {"type": "click", "x": 100, "y": 200},
      "reasoning": "我看到浏览器图标，点击打开浏览器"
    },
    {
      "step": 2,
      "screenshot": "base64...",
      "action": {"type": "type", "text": "github.com"},
      "reasoning": "在地址栏输入 GitHub 网址"
    }
  ]
}

3.3 cua-agent：主流模型全支持

CUA 的 Agent 框架（cua-agent）支持三种 Agent Loop 模式，分别针对不同的模型生态：

3.3.1 Agent Loop 模式对比

3.3.2 Anthropic Loop 实战

from cua import Sandbox, Image
from cua.agent import ComputerAgent, AgentLoop, LLM, LLMProvider

async with Sandbox.ephemeral(Image.macos()) as sb:
    agent = ComputerAgent(
        computer=sb,
        loop=AgentLoop.ANTHROPIC,
        model=LLM(
            provider=LLMProvider.ANTHROPIC,
            model="claude-4.7-sonnet",
            api_key="sk-ant-...",
            max_tokens=4096,
            temperature=0.0,
        )
    )
    
    # 执行任务
    result = await agent.run(
        "在 GitHub 上搜索 trycua/cua，打开最新的 Issue 并读取内容"
    )
    
    print(result.summary)
    print(f"总步骤数：{result.total_steps}")
    print(f"总 Token 消耗：{result.total_tokens}")

Anthropic Computer Use 协议的核心流程：

1. 截取屏幕截图 → 发送给 Claude
2. Claude 分析截图，返回下一步操作（JSON 格式）
   {
     "type": "computer_20241022",
     "action": "click",
     "coordinate": [100, 200]
   }
3. 执行操作
4. 返回步骤 1，循环直到任务完成

3.3.3 OMNI Loop：让任意 VLM 驱动桌面

OMNI 模式是 CUA 中最有技术创新的部分。它用 OmniParser 做 UI 元素识别和 Set-of-Marks 像素级标注，把视觉定位和推理拆开。

OmniParser 工作原理：

1. UI 元素检测：使用微调的 YOLOv8 模型，检测截图中的可交互元素（按钮、输入框、链接等）
2. Set-of-Marks 标注：在每个检测到的元素上叠加一个唯一的编号标记
3. VLM 推理：将标注后的图片发送给 VLM，VLM 只需要输出元素编号，不需要输出坐标
4. 坐标映射：根据元素编号，从检测结果中获取精确的坐标

原始截图：
  ┌─────────────────────┐
  │  [按钮1]  [按钮2]    │
  │  ┌───────────────┐  │
  │  │  文本框        │  │
  │  └───────────────┘  │
  └─────────────────────┘

OmniParser 标注后：
  ┌─────────────────────┐
  │  [1]  [2]           │
  │  ┌───────────────┐  │
  │  │  3             │  │
  │  └───────────────┘  │
  └─────────────────────┘

VLM 输出：
  {"action": "click", "element_id": 1}

这种设计的优势：

• 降低 VLM 的负担：VLM 只需要做"选择"，不需要做"定位"
• 提高精度：坐标来自计算机视觉检测，不依赖 VLM 的视觉定位能力
• 支持本地模型：理论上用 Ollama 跑本地模型也能驱动桌面操作

OMNI 模式实战：

# 安装 OMNI 模式（包含 Ollama 本地模型支持）
pip install "cua-agent[omni]"

from cua import Sandbox, Image
from cua.agent import ComputerAgent, AgentLoop, LLM, LLMProvider

async with Sandbox.ephemeral(Image.linux()) as sb:
    agent = ComputerAgent(
        computer=sb,
        loop=AgentLoop.OMNI,
        model=LLM(
            provider=LLMProvider.OLLAMA,
            model="llava:13b",  # 本地多模态模型
            base_url="http://localhost:11434",
        )
    )
    
    await agent.run("打开浏览器，访问 https://github.com")

3.4 Cua-Bench：真实桌面任务评测

光搭环境不够，还得知道 Agent 到底表现如何。Cua-Bench 是 CUA 配套的评测框架。

3.4.1 支持的评测数据集

3.4.2 运行评测

# 安装 Cua-Bench
pip install cua-bench

# 在 OSWorld 数据集上评测 cua-agent
cb run dataset osworld \
  --agent cua-agent \
  --model anthropic/claude-4.7-sonnet \
  --max-parallel 4 \
  --output results/osworld.json

# 查看评测结果
cb report results/osworld.json

评测报告示例：

OSWorld 评测报告
==================
数据集：OSWorld (369 任务)
Agent：cua-agent (Anthropic Loop)
模型：claude-4.7-sonnet
并行数：4

整体指标：
  任务完成率：68.3%
  平均步骤数：12.4
  平均耗时：45.2 秒/任务
  Token 消耗：2,340 / 任务

按难度分解：
  简单（120 任务）：完成率 89.2%
  中等（160 任务）：完成率 71.3%
  困难（89 任务）：完成率 38.2%

常见失败原因：
  1. 元素定位失败（23.4%）：OmniParser 漏检或误检
  2. 页面加载超时（18.7%）：等待时间不够或无限加载
  3. 推理错误（15.3%）：模型理解了任务但选择了错误的操作
  4. 环境错误（8.2%）：沙箱崩溃或网络问题

3.4.3 自定义任务集

Cua-Bench 支持定义自定义任务集：

# my_tasks.yaml
dataset: my-company-tasks
description: 公司内部系统的自动化任务评测
tasks:
  - id: task-001
    instruction: 登录公司 OA 系统，提交本周工作计划
    setup:
      - type: open_url
        url: https://oa.example.com
    evaluation:
      - type: screenshot_contains
        text: "工作计划提交成功"
      - type: url_equals
        url: "https://oa.example.com/dashboard"
    
  - id: task-002
    instruction: 打开 Jira，创建一个优先级为 High 的 Bug 工单
    setup:
      - type: open_url
        url: https://jira.example.com
    evaluation:
      - type: element_exists
        selector: "[data-testid='issue-created-message']"

cb run dataset my_tasks.yaml --agent cua-agent --max-parallel 2

3.4.4 评测注册表

CUA 官方在搭建评测注册表（cuabench.ai/registry），不同模型在相同任务集上的成绩可以横向对比。

截至 2026 年 6 月的排行榜：

3.5 Lume：Apple Silicon 上的 macOS 虚拟化

Lume 是 CUA 的第五个核心模块，也是 macOS 生态的独家优势。

3.5.1 为什么需要 Lume？

在 Apple Silicon（M1/M2/M3/M4）上运行 macOS 虚拟机，传统方案有几个问题：

• UTM：基于 QEMU，性能损失较大（约 30-40%）
• Parallels：商业软件，价格贵，且没有 API 供程序化调用
• Docker Desktop：只支持 Linux 容器，不支持 macOS VM

Lume 的优势：

• 基于苹果官方的 Virtualization.Framework，性能接近原生（性能损失 < 5%）
• 开源、免费、有完整的 CLI 和 API
• 和 Cua Sandbox 深度集成

3.5.2 安装与使用

# Homebrew 安装（推荐）
brew tap trycua/lume
brew install lume

# 或者一键安装脚本
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh)"

基本使用：

# 拉取并启动 macOS Sequoia
lume run macos-sequoia-vanilla:latest

# 创建自定义 VM
lume create my-vm \
  --os macos \
  --cpu 4 \
  --memory 8192 \
  --disk 60

# 启动 VM（无界面模式，适合 Agent 使用）
lume run my-vm --no-display

# 列出所有 VM
lume ls

# 停止 VM
lume stop my-vm

# 删除 VM
lume delete my-vm --force

3.5.3 Lume 的架构

┌─────────────────────────────────────┐
│           Lume CLI / API            │
├─────────────────────────────────────┤
│    Virtualization.Framework 封装     │
│  (苹果官方，性能接近原生)             │
├─────────────────────────────────────┤
│     VM 生命周期管理                   │
│  (创建/启动/暂停/快照/恢复)           │
├─────────────────────────────────────┤
│    镜像管理                          │
│  (下载/缓存/版本管理)                 │
└─────────────────────────────────────┘

Lume 通过 Virtualization.Framework 的 VZVirtualMachine 类创建和管理 VM，通过 VZGraphicsDisplay 实现无界面模式下的屏幕截图。

3.5.4 与 Cua Sandbox 的集成

Lume 和 Cua Sandbox 是完全集成的：

from cua import Sandbox, Image

# 使用本地 Lume VM
async with Sandbox.ephemeral(
    Image.macos("sequoia", source="lume")  # 指定使用 Lume
) as sb:
    await sb.shell.run("sw_vers")  # 确认是 macOS
    screenshot = await sb.screenshot()

Cua Sandbox 会自动检测本地是否安装了 Lume，如果安装了就优先使用 Lume，否则回退到 QEMU。

4. 实战：从零搭建 Computer-Use Agent

理论讲完了，现在动手实战。

4.1 环境准备与安装

4.1.1 系统要求

4.1.2 完整安装步骤

# 步骤 1：安装 Lume（macOS 虚拟化基础）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh)"

# 步骤 2：安装 Cua Driver（后台驱动）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/cua-driver/scripts/install.sh)"

# 步骤 3：安装 Python SDK
pip install cua-computer cua-agent cua-bench

# 步骤 4：验证安装
python3 -c "from cua import Sandbox, Image; print('CUA 安装成功')"

# 步骤 5：拉取 macOS 镜像（首次需要下载，约 3-5GB）
lume create base-vm --os macos --cpu 4 --memory 8192 --disk 60

4.1.3 配置 API Key

# 创建配置文件
mkdir -p ~/.config/cua
cat > ~/.config/cua/config.yaml << EOF
anthropic:
  api_key: "sk-ant-..."
  
openai:
  api_key: "sk-..."
  
omni:
  omniparser_server: "http://localhost:8000"
EOF

4.2 第一个 Agent 任务

让我们从最简单的任务开始：让 AI 打开浏览器，访问 GitHub。

import asyncio
from cua import Sandbox, Image
from cua.agent import ComputerAgent, AgentLoop, LLM, LLMProvider

async def main():
    # 创建沙箱
    async with Sandbox.ephemeral(Image.macos()) as sb:
        print("沙箱已启动")
        
        # 创建 Agent
        agent = ComputerAgent(
            computer=sb,
            loop=AgentLoop.ANTHROPIC,
            model=LLM(
                provider=LLMProvider.ANTHROPIC,
                model="claude-4.7-sonnet",
            )
        )
        
        print("Agent 已创建，开始执行任务...")
        
        # 执行任务
        result = await agent.run("打开 Safari 浏览器，访问 https://github.com/trycua/cua")
        
        print(f"\n任务完成！")
        print(f"总结：{result.summary}")
        print(f"总步骤数：{result.total_steps}")
        print(f"总 Token 消耗：{result.total_tokens}")

if __name__ == "__main__":
    asyncio.run(main())

运行结果示例：

沙箱已启动
Agent 已创建，开始执行任务...

[步骤 1] 截图 → Claude 分析：我需要打开 Safari 浏览器。
      操作：click(x=1200, y=50)  # 点击 Dock 上的 Safari 图标

[步骤 2] 截图 → Claude 分析：Safari 已打开，我需要在地址栏输入网址。
      操作：click(x=600, y=50)  # 点击地址栏
      → type(text="https://github.com/trycua/cua")
      → key(key="Return")

[步骤 3] 截图 → Claude 分析：页面正在加载...
      操作：wait(ms=2000)  # 等待页面加载

[步骤 4] 截图 → Claude 分析：GitHub 页面已加载完成，任务完成。
      操作：done(summary="成功访问 https://github.com/trycua/cua")

任务完成！
总结：成功打开 Safari 浏览器并访问了 https://github.com/trycua/cua
总步骤数：4
总 Token 消耗：3,842

4.3 多 OS 沙箱实战

CUA 的强大之处在于同一套代码可以无缝切换 OS。下面演示一个跨平台任务。

任务：在 Linux 和 macOS 上分别安装 Python 依赖并运行脚本。

import asyncio
from cua import Sandbox, Image

async def setup_python_env(sb, os_name):
    """在沙箱中配置 Python 环境"""
    print(f"\n=== 在 {os_name} 上配置 Python 环境 ===")
    
    # 安装依赖
    if os_name == "Linux":
        await sb.shell.run("apt-get update && apt-get install -y python3 python3-pip")
    else:  # macOS
        await sb.shell.run("brew install python3")
    
    # 安装 Python 包
    await sb.shell.run("pip3 install requests flask")
    
    # 运行测试脚本
    script = '''
import requests
import flask

print("Python 环境配置成功！")
print(f"Requests version: {requests.__version__}")
print(f"Flask version: {flask.__version__}")
'''
    
    with open("test.py", "w") as f:
        f.write(script)
    
    result = await sb.shell.run("python3 test.py")
    print(result.stdout)

async def main():
    # 在 Linux 上运行
    async with Sandbox.ephemeral(Image.linux()) as sb:
        await setup_python_env(sb, "Linux")
    
    # 在 macOS 上运行（只需改一行）
    async with Sandbox.ephemeral(Image.macos()) as sb:
        await setup_python_env(sb, "macOS")

if __name__ == "__main__":
    asyncio.run(main())

4.4 接入本地模型（Ollama + OmniParser）

如果你不想把截图数据发到云端，可以使用本地模型。CUA 的 OMNI 模式支持通过 Ollama 运行本地多模态模型。

4.4.1 安装 Ollama 和 OmniParser

# 安装 Ollama
curl -fsSL https://ollama.com/install.sh | sh

# 拉取多模态模型（如 LLaVA）
ollama pull llava:13b

# 启动 OmniParser 服务器
git clone https://github.com/microsoft/OmniParser.git
cd OmniParser
pip install -r requirements.txt
python server.py  # 启动在 http://localhost:8000

4.4.2 使用本地模型驱动 Agent

from cua import Sandbox, Image
from cua.agent import ComputerAgent, AgentLoop, LLM, LLMProvider

async def main():
    async with Sandbox.ephemeral(Image.linux()) as sb:
        agent = ComputerAgent(
            computer=sb,
            loop=AgentLoop.OMNI,  # 使用 OMNI 模式
            model=LLM(
                provider=LLMProvider.OLLAMA,
                model="llava:13b",
                base_url="http://localhost:11434",
            ),
            omniparser_server="http://localhost:8000"  # OmniParser 服务器
        )
        
        await agent.run("打开终端，运行 echo Hello from Local Model")

if __name__ == "__main__":
    asyncio.run(main())

性能对比（本地模型 vs 云端模型）：

5. 深度：架构设计与技术决策分析

5.1 为什么需要统一的 Sandbox API

你可能会问：为什么需要 CUA 的 Sandbox API？我直接用 Docker API 或者 macOS 的 Virtualization.Framework 不行吗？

核心原因是抽象层次不同：

低层 API（Docker API / Virtualization.Framework）
  - 只管"创建和启动 VM/容器"
  - 不管"如何在 VM 里执行操作"
  - 不同平台的 API 完全不一样

CUA Sandbox API（高层抽象）
  - 管"创建、启动、操作、销毁"全生命周期
  - 提供统一的"截图/点击/键盘/Shell"接口
  - 同一套代码跨平台运行

具体来说，CUA Sandbox API 解决了以下几个实际问题：

问题 1：跨平台截图

在 Linux 上截图用 scrot 或 import，在 macOS 上用 screencapture，在 Windows 上用 pyautogui.screenshot()。CUA 统一为 sb.screenshot()。

问题 2：跨平台输入事件

在 Linux 上模拟鼠标点击用 xdotool，在 macOS 上用 cliclick 或通过 Accessibility API。CUA 统一为 sb.mouse.click(x, y)。

问题 3：环境一致性

不同开发者的本地环境不一样，导致 Agent 脚本在一个机器上能跑，在另一个机器上失败。CUA 通过沙箱快照解决这个问题——一次配置，到处运行。

5.2 后台驱动的底层实现原理

Cua Driver 的"后台无感操控"是怎么实现的？这需要深入 macOS 的窗口系统和事件处理机制。

5.2.1 macOS 的事件处理架构

macOS 的事件处理分为几个层次：

┌─────────────────────────────────────┐
│          应用层（Cocoa/AppKit）       │
├─────────────────────────────────────┤
│        Accessibility API (AX)        │  ← 传统自动化工具用这个
├─────────────────────────────────────┤
│        HID Event System              │  ← Cua Driver 用这个
├─────────────────────────────────────┤
│        Window Server                 │
├─────────────────────────────────────┤
│        硬件事件（鼠标/键盘）           │
└─────────────────────────────────────┘

传统的自动化工具（如 PyAutoGUI）通过 Accessibility API 发送事件，这会导致：

• 事件被标记为"辅助功能事件"，某些应用会拒绝响应
• 事件会触发系统的辅助功能警告
• 事件处理会抢焦点

Cua Driver 通过更底层的 HID Event System 直接注入事件，绕过了这些限制。

5.2.2 具体实现

Cua Driver 的核心是一个 macOS 系统扩展（System Extension），它：

1. 注册为一个 HID Event Driver
2. 接收来自 Agent 的操作指令
3. 将操作指令转换为 HID Event
4. 将 HID Event 直接注入到目标应用的事件队列

// 伪代码：Cua Driver 内核扩展的核心逻辑
kern_return_t CuaDriver::send_mouse_event(int x, int y, int button, bool click) {
    // 创建 HID Mouse Event
    IOHIDEventRef event = IOHIDEventCreateMouseEvent(
        kCFAllocatorDefault,
        kIOHIDEventTypeMouseButtonDown,  // 或 MouseButtonUp / MouseMove
        x, y,
        button,
        0,  // 时间戳
        true  // isAbsolute（绝对坐标）
    );
    
    // 获取目标应用的 IOService
    IOService* target_app = find_target_application();
    
    // 注入事件
    IOHIDEventAppendEvent(target_app->event_queue, event);
    
    return KERN_SUCCESS;
}

5.3 OmniParser 的 UI 元素识别原理

OmniParser 是 CUA OMNI 模式的核心依赖，负责"看懂"屏幕上的 UI 元素。

5.3.1 技术栈

5.3.2 检测流程

输入：屏幕截图 (1920x1080 RGB)

  ↓

[步骤 1] 缩放截图到 640x360（YOLO 输入尺寸）
  
  ↓

[步骤 2] YOLOv8 推理
  输出：
    - bbox: [120, 50, 200, 80]  (x1, y1, x2, y2)
    - class: "button"
    - confidence: 0.92
    - ... (多个检测结果)

  ↓

[步骤 3] 将 bbox 映射回原始分辨率
  bbox_original = bbox * (1920/640, 1080/360)

  ↓

[步骤 4] 对每个检测到的元素，用 PaddleOCR 识别文字
  如：button_1_text = "登录"

  ↓

[步骤 5] 用 OpenCV 在原始截图上叠加标注
  如：在 button_1 的位置画一个红色的 "①"

  ↓

输出：标注后的截图 + 元素列表 JSON

5.3.3 为什么不用 VLM 直接定位？

你可能会问：为什么需要 OmniParser？直接用 GPT-4V 分析截图并输出坐标不行吗？

有两个核心原因：

原因一：VLM 的视觉定位精度不够

VLM 的视觉定位误差通常在 20-50 像素，对于小按钮（如关闭按钮，只有 12x12 像素）来说，这个误差是不可接受的。

OmniParser 的检测精度：

• mAP@0.5（UI 元素检测）：92.3%
• 平均定位误差：3.2 像素

原因二：VLM 的推理成本高

每次截图都发给 VLM，成本高昂。OmniParser 在本地运行，单次检测成本接近 0。

成本对比（处理 1000 张截图）：
  GPT-4V：$15/百万 tokens × 约 1000 tokens/截图 × 1000 = $15
  OmniParser：本地运行，电费约 $0.5

5.4 沙箱快照与 Fork 机制

CUA 的沙箱快照与 Fork 机制是实现大规模并行 Agent 任务的关键。

5.4.1 快照的实现原理

CUA 的快照功能基于 Copy-on-Write (COW) 技术：

传统快照（如 VMware 快照）：
  1. 暂停 VM
  2. 复制整个磁盘文件（40GB）
  3. 恢复 VM
  耗时：10-30 分钟

CUA 快照（COW）：
  1. 暂停 VM
  2. 创建一个"快照指针"，指向当前磁盘状态
  3. 后续写入时，只复制被修改的块（通常 < 100MB）
  4. 恢复 VM
  耗时：< 1 秒

具体实现（以 Lume 为例）：

Lume 使用 macOS Virtualization.Framework 的 VZDiskImageStorageDevice 类，它原生支持 APFS 的 COW 快照。

// 伪代码：Lume 创建快照
func createSnapshot(name: String) throws -> VZDiskImageStorageDevice {
    let disk = try VZDiskImageStorageDevice(
        url: URL(fileURLWithPath: "/path/to/disk.img"),
        storageDevice: .init(type: .diskImage, deviceProtocol: .nvme)
    )
    
    // 创建 APFS 快照
    let snapshot = try disk.createSnapshot(name: name)
    
    return snapshot
}

// Fork：从快照创建新 VM
func forkFromSnapshot(snapshot: VZDiskImageStorageDevice) throws -> VZVirtualMachine {
    // COW：新 VM 共享快照的数据块，只复制写入的块
    let newDisk = try snapshot.cloneCOW()
    
    let vm = VZVirtualMachine(
        configuration: VZVirtualMachineConfiguration(
            disk: newDisk,
            cpuCount: 4,
            memorySize: 8 * 1024 * 1024 * 1024
        )
    )
    
    return vm
}

5.4.2 Fork 的实战场景

场景一：并行评测

# 创建一个配置好浏览器和基础软件的快照
async with Sandbox.ephemeral(Image.macos()) as sb:
    await sb.shell.run("brew install google-chrome firefox")
    snapshot_id = await sb.snapshot()

# 从快照 fork 出 20 个并行沙箱，分别评测 20 个不同的任务
tasks = [...]  # 20 个评测任务
sandboxes = await Sandbox.fork(snapshot_id, count=20)

results = await asyncio.gather(*[
    run_task(sb, task) 
    for sb, task in zip(sandboxes, tasks)
])

场景二：多用户服务

如果你在做 Computer-Use Agent 的 SaaS 服务，每个用户需要一个独立的沙箱。通过 Fork，你可以在毫秒级为每个用户创建一个独立的沙箱实例。

6. 性能优化与生产实践

6.1 热启动优化

在生产环境中，Agent 的启动速度直接影响用户体验。CUA 通过多层优化实现热启动（< 1 秒）。

6.1.1 优化策略

6.1.2 实战：配置热启动池

from cua import Sandbox, Image, WarmPool

# 创建热启动池（预启动 10 个沙箱）
pool = WarmPool(
    image=Image.macos("sequoia"),
    min_size=10,
    max_size=20,
    idle_timeout=300  # 空闲 5 分钟后回收
)

# 从池中获取沙箱（< 1 秒）
async with pool.acquire() as sb:
    await agent.run("...")
    
# 沙箱使用完毕后自动归还到池中

6.2 并行 Agent 任务

在生产环境中，你可能需要同时运行数百个 Agent 任务（如大规模评测、多用户服务）。

6.2.1 并行策略

import asyncio
from cua import Sandbox, Image

async def run_agent_task(task_id, instruction):
    """运行单个 Agent 任务"""
    async with Sandbox.ephemeral(Image.linux()) as sb:
        agent = ComputerAgent(computer=sb, ...)
        result = await agent.run(instruction)
        return {"task_id": task_id, "result": result}

async def main():
    # 定义 100 个任务
    tasks = [
        (i, f"任务 {i}：在 GitHub 上搜索关键词 'agent'")
        for i in range(100)
    ]
    
    # 并行执行（限制并发数为 20，避免资源耗尽）
    semaphore = asyncio.Semaphore(20)
    
    async def bounded_task(task_id, instruction):
        async with semaphore:
            return await run_agent_task(task_id, instruction)
    
    results = await asyncio.gather(*[
        bounded_task(task_id, instruction)
        for task_id, instruction in tasks
    ])
    
    print(f"完成 {len(results)} 个任务")

if __name__ == "__main__":
    asyncio.run(main())

6.2.2 资源限制与隔离

并行运行多个沙箱时，需要注意资源限制：

# 为每个沙箱限制资源
sandbox_config = {
    "cpu_limit": 2,      # 最多使用 2 个 CPU 核心
    "memory_limit": 4096, # 最多使用 4GB 内存
    "disk_limit": 20480,  # 最多使用 20GB 磁盘
}

async with Sandbox.ephemeral(Image.linux(), **sandbox_config) as sb:
    ...

6.3 轨迹录制与训练数据 Pipeline

Computer-Use Agent 的训练需要大量的**"任务-操作序列"数据**。CUA 的轨迹录制功能可以帮助你构建这样的数据集。

6.3.1 自动录制

from cua.driver import Driver, Recording

# 启动录制
driver = Driver()
recording = driver.start_recording(
    capture_screenshots=True,  # 录制截图
    capture_network=False,     # 不录制网络请求（节省空间）
    capture_logs=True          # 录制系统日志
)

# 执行任务
await agent.run("...")

# 停止录制
recording.stop()

# 保存为训练数据格式
recording.save_as_training_data(
    output_path="training_data/task_001.jsonl",
    format="openai_messages"  # 兼容 OpenAI Fine-tuning 格式
)

6.3.2 训练数据格式

// training_data/task_001.jsonl
{
  "messages": [
    {"role": "system", "content": "你是一个 Computer-Use Agent，可以操控桌面。"},
    {"role": "user", "content": [
      {"type": "text", "text": "打开浏览器，访问 GitHub"},
      {"type": "image_url", "image_url": {"url": "data:image/png;base64,..."}}
    ]},
    {"role": "assistant", "content": "{\"action\": \"click\", \"coordinate\": [1200, 50]}"},
    {"role": "user", "content": [
      {"type": "text", "text": "截图显示浏览器已打开，接下来应该..."},
      {"type": "image_url", "image_url": {"url": "data:image/png;base64,..."}}
    ]},
    {"role": "assistant", "content": "{\"action\": \"type\", \"text\": \"https://github.com\"}"},
    ...
  ]
}

6.3.3 用录制的数据微调模型

import openai

# 上传训练数据
file = openai.File.create(
    file=open("training_data.jsonl", "rb"),
    purpose="fine-tune"
)

# 启动微调任务
job = openai.FineTuningJob.create(
    model="gpt-4o-2024-08-06",
    training_file=file.id,
    hyperparameters={
        "n_epochs": 3,
        "learning_rate_multiplier": 0.1
    }
)

print(f"微调任务已启动：{job.id}")

7. 评测：Cua-Bench 完全指南

Cua-Bench 是 Computer-Use Agent 领域的 ImageNet——它定义了"什么是好的 Computer-Use Agent"。

7.1 评测指标

Cua-Bench 使用以下指标评测 Agent 的性能：

7.2 运行完整评测

# 在 OSWorld 数据集上运行完整评测
cb run dataset osworld \
  --agent cua-agent \
  --model anthropic/claude-4.7-sonnet \
  --max-parallel 8 \
  --runs-per-task 3 \  # 每个任务运行 3 次，计算鲁棒性
  --output results/osworld_full.json \
  --verbose

# 生成评测报告
cb report results/osworld_full.json \
  --format markdown \
  --output report.md

7.3 评测结果分析

评测完成后，你需要分析结果，找出 Agent 的弱点：

import json
from cua.bench import BenchmarkResult

# 加载评测结果
with open("results/osworld_full.json") as f:
    data = json.load(f)

result = BenchmarkResult.from_dict(data)

# 分析失败案例
failed_tasks = result.get_failed_tasks()
print(f"失败任务数：{len(failed_tasks)}")

# 按失败原因分类
failure_reasons = result.categorize_failures()
for reason, count in failure_reasons.items():
    print(f"{reason}: {count} ({count/len(failed_tasks)*100:.1f}%)")

# 找出"高价值"失败案例（任务难度高但模型接近成功）
hard_but_close = result.get_hard_but_close_tasks(threshold=0.8)
print(f"\n高价值失败案例（用于重点优化）：{len(hard_but_close)}")

8. 安全考量：沙箱隔离与权限控制

Computer-Use Agent 的安全风险是真实存在的。CUA 通过多层隔离和权限控制来降低风险。

8.1 沙箱隔离层次

┌─────────────────────────────────────┐
│          Host OS (你的 Mac)          │
├─────────────────────────────────────┤
│        macOS Sandbox (沙盒)          │  ← 第 1 层：系统沙盒
│  (限制文件系统访问、网络访问等)        │
├─────────────────────────────────────┤
│        Virtualization (虚拟化)       │  ← 第 2 层：虚拟机隔离
│  (VM 崩溃不影响 Host)                │
├─────────────────────────────────────┤
│        Network Isolation (网络隔离)  │  ← 第 3 层：网络隔离
│  (VM 可以访问网络，但 Host 不可见)   │
└─────────────────────────────────────┘

8.2 权限控制最佳实践

# 创建一个受限制的沙箱
sandbox_config = {
    # 文件系统限制：只允许访问特定目录
    "allowed_paths": ["/tmp", "/home/agent"],
    
    # 网络限制：只允许访问特定域名
    "allowed_domains": ["github.com", "stackoverflow.com"],
    
    # 禁止危险操作
    "forbidden_actions": [
        "rm -rf /",           # 禁止递归删除根目录
        "dd if=/dev/zero",    # 禁止写零到磁盘
        "chmod 777",          # 禁止修改权限
    ],
    
    # 操作审计：记录所有操作
    "audit_log": "/var/log/cua_audit.log",
}

async with Sandbox.ephemeral(Image.linux(), **sandbox_config) as sb:
    # 即使 Agent 尝试危险操作，也会被沙箱拦截
    result = await sb.shell.run("rm -rf /")
    # 返回：{"error": "Operation forbidden by sandbox policy"}

8.3 敏感数据保护

如果 Agent 需要访问敏感数据（如密码、API Key），应该使用秘密管理：

from cua import Sandbox, SecretManager

# 创建秘密管理器
secrets = SecretManager()
secrets.set("github_token", "ghp_...")

async with Sandbox.ephemeral(Image.linux()) as sb:
    # 将秘密注入到沙箱的环境变量中
    await sb.env.set("GITHUB_TOKEN", secrets.get("github_token"))
    
    # 在沙箱中，Agent 可以通过环境变量访问秘密
    # 但秘密不会出现在截图或日志中

9. 未来展望：Computer-Use Agent 的下一步

9.1 技术趋势

根据 CUA 的 Roadmap 和社区讨论，Computer-Use Agent 的未来有以下几个方向：

方向一：多 Agent 协作

目前的 Computer-Use Agent 都是单 Agent。未来会出现多 Agent 协作操控同一个桌面的场景：

任务：开发一个 Web 应用

Agent A（前端专家）：负责编写 HTML/CSS/JS
Agent B（后端专家）：负责编写 API 代码
Agent C（测试专家）：负责运行测试并报告 Bug
Agent D（协调者）：分配任务、检查进度

所有 Agent 共享同一个沙箱，通过"屏幕"和"文件"协作

方向二：长期记忆

目前的 Agent 每次任务都是"从头开始"，没有记忆。未来会引入持久化记忆：

# 未来的 API（概念验证）
agent = ComputerAgent(
    computer=sb,
    memory=LongTermMemory(path="~/.cua/memory.db")
)

# Agent 会记住：
# - 用户的偏好（如"我喜欢用 Vim 而不是 Nano"）
# - 常用的操作流程（如"每次打开终端都要先激活 conda 环境"）
# - 过去的错误（如"上次删错了文件，这次要小心"）

方向三：主动感知

目前的 Agent 是"被动响应"——用户给任务，Agent 执行。未来会出现主动感知的 Agent：

Agent 在后台运行，持续监控屏幕：
  - 发现用户打开了 10 个标签页 → 主动建议："要不要我帮你整理标签页？"
  - 发现用户在同一个错误上卡了 10 分钟 → 主动建议："要不要我帮你搜索解决方案？"
  - 发现用户复制了一段代码 → 主动建议："这段代码有一个潜在的 Bug，要不要我帮你修复？"

9.2 CUA 的 Roadmap

根据 CUA 的 GitHub Project 和社区讨论，以下是即将推出的功能：

10. 总结

CUA（Computer-Use Agents）是目前最完整的开源 Computer-Use Agent 基础设施。它解决了 AI Agent 操控桌面的核心问题：

1. 沙箱隔离：通过 Cua Sandbox，提供安全的、跨平台的隔离环境
2. 后台驱动：通过 Cua Driver，实现不抢光标的无感操控
3. 多模型支持：通过 cua-agent，支持 OpenAI、Anthropic、Omni 三种 Loop
4. 评测闭环：通过 Cua-Bench，提供标准的评测数据集和指标
5. macOS 虚拟化：通过 Lume，在 Apple Silicon 上实现接近原生的 VM 性能

CUA 适合谁用？

• 在 Mac 上做 Agent 开发，想要一个标准化的沙箱环境
• 做 Computer-Use 相关研究，需要评测基准和轨迹数据
• 想把 Claude / GPT 接入桌面操控，但不想自己搭底层
• 需要做大规模 Agent 评测或提供多用户 Agent 服务

CUA 的局限性

• Windows 本地端支持还在完善中
• 本地模型的性能（如 LLaVA）和云端模型（如 Claude）仍有较大差距
• 需要一定的系统管理经验来维护和优化沙箱环境

最终建议

如果你在做 Computer-Use Agent 相关的项目，CUA 是目前最值得深入研究的开源框架。它的模块化设计使得你可以只使用其中的一部分（如只用 Lume 做 macOS 虚拟化，或只用 Cua-Bench 做评测）。

开源地址：https://github.com/trycua/cua
官方文档：https://cua.ai/docs
评测注册表：https://cuabench.ai/registry

本文撰写于 2026 年 6 月，基于 CUA 最新版本（v0.1.5）和社区讨论。如有技术问题，欢迎在评论区交流。

参考文献与延伸阅读

1. Anthropic Computer Use 官方文档：https://docs.anthropic.com/claude/docs/computer-use
2. OmniParser 论文与代码：https://github.com/microsoft/OmniParser
3. OSWorld 数据集：https://os-world.github.io/
4. Apple Virtualization.Framework 文档：https://developer.apple.com/documentation/virtualization
5. YC W25: CUA (Computer-Use Agents) 赛道分析
6. Set-of-Marks 提示工程：Wang et al., "Visual Programming: Compositional visual reasoning without training", CVPR 2023