Roky Wang 的技术知识库

Cua Driver：面向 Agent 的后台桌面操作驱动

17分钟阅读

Cua Driver：面向 Agent 的后台桌面操作驱动

概述

Cua Driver（命令名通常为 cua-driver）是 Cua 项目中的 Computer Use 执行驱动。它不负责理解自然语言任务或选择模型，而是把上层 Agent 的“观察、点击、输入、滚动、拖拽”等请求落到操作系统桌面上，并可经 CLI 或 MCP 被 Agent harness 调用。Cua 官方将其描述为可在后台驱动原生 macOS 应用、记录可回放操作轨迹的 driver；Cua 项目本身还包含沙箱、Agent 框架和基准等不同组件，不能把它们混为同一个产品。^[来源：Cua 官方仓库]

在这层意义上，它最接近 open-computer-use 和 macOS-use：三者都可作为上层 Agent 的桌面执行底座。它不同于 UI-TARS Desktop，后者还包含视觉模型驱动的独立 GUI Agent 体验；也不同于 Computer Use OOTB，后者主要是比较模型与后端的实验操作台。

本文重点说明 macOS 的后台控制语义，并以 2026-07-27 查阅的 Cua 官方仓库和 Hermes 对 Cua Driver 的集成文档为依据。Cua Driver 的跨平台实现与发行节奏变化较快；部署前应以当前上游 README、Release 和运行时 doctor 输出为准。

核心区别：后台投递，不是移动真实鼠标

常见 GUI 自动化通过 HID 级鼠标键盘事件驱动前台窗口，结果是光标移动、输入焦点切换，用户无法同时正常工作。Cua Driver 的 macOS 路线则将合成事件按目标进程投递，并保持“不切到前台”的约束：官方项目说明其可在不抢占 cursor、focus 或 Space 的情况下驱动原生 App。^[来源：Cua 官方仓库]

Hermes 的 Cua Driver 集成文档进一步解释了该语义：macOS 侧通过 SkyLight 私有 SPI（包括 SLPSPostEventRecordTo）向指定 PID 分发输入，而非用 HID event tap 改变全局光标位置；它还通过私有 Accessibility 接口读取界面状态。因此，真实 macOS 光标不应移动，当前键盘焦点也不应被改走。这一机制依赖私有系统接口，不应把它理解为 Apple 承诺长期兼容的公开 API。^[来源：Hermes Computer Use 集成文档]

上层 Agent / MCP 客户端
          │  observe、click、type、scroll
          ▼
      cua-driver
          │  目标 PID 的合成事件 + Accessibility 观察
          ▼
后台目标 App ───────→ 自身界面状态改变
 
用户的真实光标、焦点、Space：保持不变（预期行为）

“不抢鼠标”不等于“毫无可见副作用”。目标应用可能自行打开窗口、弹出模态框、播放动画或改变文档；一些客户端还会显示独立的 Agent 覆盖光标，用来提示动作落点。该覆盖层不是 macOS 的真实光标，不能据此判断后台模式失效。^[来源：Hermes Computer Use 集成文档]

观察与执行闭环

Cua Driver 所处的闭环可以概括为：

capture / Accessibility tree / screenshot
                │
                ▼
       上层模型规划下一步
                │
                ▼
  cua-driver 向目标 App 投递动作
                │
                ▼
          再次 capture 并验证

上层模型可以根据屏幕截图、Set-of-Mark（SOM）标注或 Accessibility tree 选择元素；Cua Driver 负责将动作送到应用。可靠性关键不在“点击调用返回成功”，而在操作后重新捕获并确认状态真的变化。界面刷新、模态框、窗口关闭或页面跳转后，旧元素索引可能失效，必须重新观察，不能把上一帧的元素坐标或序号直接复用。^[来源：Hermes Computer Use 集成文档]

相较纯坐标脚本，这一设计可让 Agent 同时利用截图和可访问性语义；相较仅靠 Accessibility 的方案，它又能在树不完整时退到视觉或坐标操作。代价是背景模式的事件链路通常会比前台 HID 注入更慢，且不同 App 对可访问性树和后台事件的响应不完全一致。^[来源：Hermes Computer Use 集成文档]

在 macOS 上部署

1. 确认前提

当前官方安装文档要求 macOS 14（Sonoma）或更高版本，支持 Apple Silicon 与 Intel Mac。Cua Driver 运行在当前登录用户的图形会话中：远程 SSH、无 GUI 的后台进程或另一个 macOS 用户的会话，不能天然代替本机桌面会话。开始前应关闭未保存的敏感文档，并准备一个低风险应用用于验证。^[来源：Cua Driver 安装文档]

2. 安装官方发布包

官方提供无需管理员权限的一行安装器：

/bin/bash -c "$(curl -fsSL https://cua.ai/driver/install.sh)"

安装器会把 CuaDriver.app 放在 /Applications，并创建 ~/.local/bin/cua-driver 链接；如果该目录不在 zsh、bash 或 fish 的 PATH 中，安装器会尝试写入对应的 shell 配置。执行完后打开新终端，或按当前 shell 的配置重新加载环境，再确认二进制可见。^[来源：Cua Driver 安装文档]

cua-driver --version
cua-driver doctor

上述安装脚本来自网络，会下载并执行发布脚本。对需要严格供应链审查的设备，应先在受控环境中查看脚本内容、核对上游 Release 与签名/哈希策略，再执行；不要从第三方教程复制来源不明的安装器。

3. 以 App 身份启动并授予 TCC 权限

macOS 的 Accessibility 和 Screen Recording 授权按进程/App 身份归属。官方要求先通过 LaunchServices 启动 CuaDriver.app 的 daemon，再触发授权，以确保授权绑定到 CuaDriver.app 而不是正在运行命令的终端：^[来源：Cua Driver 安装文档、Cua Driver 进程模型]

open -n -g -a CuaDriver --args serve
cua-driver permissions grant

在系统弹窗或「系统设置 → 隐私与安全性」中允许 Accessibility 与 Screen Recording。随后检查驱动自身看到的授权状态：

cua-driver permissions status
cua-driver doctor

若 permissions status 显示 unknown，常见原因是 daemon 没有运行；不要仅给 Terminal 授权后就假定 CuaDriver.app 已获得权限。官方进程模型明确不支持将一个裸 cua-driver serve 进程当作稳定的 TCC 身份；生产环境应保持 App 身份启动，或采用宿主 App 的 embedded 模式。^[来源：Cua Driver 安装文档、Cua Driver 进程模型]

4. 先验证本机桌面，再连接 Agent

授权完成后，先让 driver 列出其能看见的应用，而不是立刻交给模型做长链路任务：

cua-driver call list_apps

看到预期的图形应用后，说明安装、daemon、TCC 和当前桌面会话基本连通。之后再让上层 Agent 以 MCP 方式连接。cua-driver mcp 是 stdio MCP proxy；最稳妥的配置方式是让 driver 为指定客户端生成当前版本所需的命令或配置，而不是手写可能过期的配置格式：^[来源：连接 Agent 文档、Cua Driver CLI Reference]

cua-driver mcp-config --client codex

按该命令输出注册到 Codex 后，重启或重新打开对应的 Agent 会话。MCP 连接意味着该 Agent 可以接触当前用户会话中的已登录应用、浏览器和本地 App；只应注册受信任的 Agent 配置，并先用“列出应用”“读取非敏感测试窗口”一类操作验证。

5. 首次运行、更新和隐私设置

可将首次验证控制在小范围内：在测试 App 中执行一次只读 capture，再做一个可撤销的动作，并重新 capture 确认结果。对发送、付款、删除、授权或生产发布，始终保留人工确认。

上游文档说明 Cua Driver 默认启用不含内容的产品遥测；如不希望发送这类事件，可主动关闭：^[来源：Cua Driver 安装文档]

cua-driver telemetry disable

升级时先检查版本和 Release Notes，再决定是否应用更新；由于 macOS 路线依赖私有 SPI，升级 macOS 或 driver 后都应重新执行 doctor 与小型回归任务。更新后，停止旧 daemon，并再次通过 App 身份启动：^[来源：Cua Driver 更新文档、Cua Driver 进程模型]

cua-driver check-update
cua-driver update --apply
cua-driver stop
open -n -g -a CuaDriver --args serve
cua-driver doctor

常见部署故障

现象先检查什么不应采用的做法
cua-driver: command not found重新打开终端；检查 ~/.local/bin 是否在 PATH直接猜测或修改全局系统目录
doctor 显示 Accessibility / Screen Recording 未授权确认 CuaDriver.app daemon 已通过 LaunchServices 运行，再执行 permissions grant仅授权 Terminal 后假定 driver 自动继承
permissions status 显示 unknown用 cua-driver status 确认 daemon，必要时再次 open -n -g -a CuaDriver --args serve将 status 的 unknown 当作已经授权
能启动 MCP 但看不到预期桌面应用确认当前用户的图形登录会话、Screen Recording 和 list_apps 结果以 SSH/无 GUI 后台会话替代交互桌面
macOS 更新后动作异常运行 doctor、阅读 driver Release Notes、在测试 App 回归在真实生产任务中直接盲目重试

接入方式与 macOS 前提

上游将 Cua Driver 提供为 CLI 与 MCP Server，可由支持 MCP 的 Agent harness 通过标准输入输出启动并调用。具体客户端的安装器与配置位置并不相同，应以其官方集成文档为准；不要把某一宿主（例如 Hermes）的命令机械套用到 Codex 或其他客户端。^[来源：Cua 官方仓库]

在 macOS 上，读取屏幕和控制辅助功能一般需要在「系统设置 → 隐私与安全性」中授予对应的 Screen Recording 与 Accessibility 权限。运行前应用先执行其健康检查（如 doctor 或等价报告）确认二进制身份、TCC 授权、Accessibility 可用性和屏幕捕获能力；只有这些基础条件成立，才应排查模型或任务规划问题。具体部署顺序见上节。^[来源：Cua Driver 安装文档]

适用范围与限制

情况是否适合 Cua Driver原因
希望 Agent 操作另一个 App，同时不打断当前键鼠工作适合后台、目标 PID 投递是其核心设计
将 GUI 控制接到既有 MCP/CLI Agent适合driver 作为工具执行层，而非固定模型产品
Web-only 自动化通常不优先浏览器协议/DOM 自动化通常更快、更可验证，桌面操作留给无 API 的步骤
无人值守执行付款、发送、删除、授权不适合后台模式降低干扰，不降低业务与权限风险
依赖公开、长期稳定 macOS 自动化 API谨慎macOS 路线涉及私有 SkyLight SPI，系统更新可能改变行为
自绘 UI、游戏或可访问性树缺失的应用谨慎可尝试视觉/坐标回退，但元素语义和验证能力会降低

后台模式还会暴露一种容易忽略的风险：用户可能看不到焦点切换，误以为 Agent 没有做事；而 Agent 的确可能已经在另一个 App 中修改数据。因此应保留清晰的操作记录、可回放轨迹和关键节点确认。Cua 官方说明每个会话可记录为可回放轨迹；能否满足审计要求仍取决于宿主 Agent 是否保存、保护和关联这些记录。^[来源：Cua 官方仓库]

安全边界

Screen Recording 与 Accessibility 的组合意味着进程既能看到敏感窗口内容，也能代表用户修改应用状态。Cua Driver 的“后台”特性不能被误当成权限隔离或沙箱：它操作的仍是用户真实桌面和真实账号。建议：

  1. 首次只在测试账号、测试文件和独立浏览器 profile 中运行；先验证只读动作，再验证可逆的单步操作。
  2. 对发送、购买、删除、权限授权、生产发布等动作保留显式人工批准；不让 Agent 输入密码或处理验证码。
  3. 每个状态改变后重新 capture 或用 API/文件内容做独立校验，避免仅依据工具返回值判定成功。
  4. 更新 macOS 或 Cua Driver 后先运行健康检查和小型回归任务；私有 SPI 的兼容性应作为真实运维风险管理。
  5. 结束试验后撤销不再需要的 Accessibility 与 Screen Recording 权限，并审查 Agent、MCP 配置和轨迹保存位置。

这些原则同样适用于 macOS 开源 Computer Use 方案对比中的其他方案；Cua Driver 的独特优势是降低对用户当前交互的干扰，而不是绕开系统权限或业务控制。

与前述方案如何选

  • 已有 Codex、Claude Code 或其他 MCP 宿主，并且后台不打扰用户是首要条件：优先评估 Cua Driver。
  • 需要一个独立、视觉优先的桌面 Agent：选择 UI-TARS Desktop。
  • 需要 Python 中可组合、可写断言的 macOS 辅助功能工作流：选择 macOS-use。
  • 需要实验比较本地模型与 API 模型：选择 Computer Use OOTB。

结论是：Cua Driver 不是“又一个看图点按钮的 Agent”，而是为上层 Agent 提供后台桌面观察与动作投递能力的执行层。它适合处理确实无法通过 API、CLI 或浏览器协议完成的 GUI 环节；其高权限、私有 API 依赖与可见性较低的副作用，要求更严格地设置确认和验证机制。

关系图谱

反向链接