内容
# cua-driver MCP for OpenClaw
将 [cua-driver](https://github.com/trycua/cua) —— 一个开源的 macOS 桌面自动化守护进程 —— 集成到 OpenClaw（和 Hermes）中，作为 MCP 服务器。这使得 AI 代理可以完全控制桌面：截图、鼠标点击、键盘输入、应用程序启动、拖放和可访问性树导航。
> **33+ 工具** 通过 MCP 暴露。零云依赖。无许可费。Apache 2.0。
## 功能解锁
| 功能 | 之前 | 之后 |
|---|---|---|
| 桌面截图 | ❌ | ✅ 缩放工具 |
| 点击非浏览器应用 | ❌ | ✅ 点击、右键点击、双击 |
| 在 Finder 中拖动文件 | ❌ | ✅ 拖动工具 |
| 在任意应用中输入 | ❌ | ✅ 输入文本 |
| 键盘快捷键 | ❌ | ✅ 快捷键、按键 |
| 启动/终止应用 | ❌ | ✅ 启动应用、终止应用 |
| 检测 UI 元素 | ❌ | ✅ 获取窗口状态（AX 树） |
| 滚动页面 | ❌ | ✅ 滚动工具 |
| 代理光标叠加 | ❌ | ✅ 开始会话、移动光标 |
## 快速入门
### 通过 Hermes（推荐）
```bash
hermes computer-use install
openclaw mcp set cua-driver '{
"command": "'"$(which cua-driver)"'",
"args": ["mcp"]
}'
```
### 独立运行
```bash
# 1. 从 https://github.com/trycua/cua/releases 下载最新版本
# 或使用单行命令：
curl -fsSL https://github.com/trycua/cua/releases/download/cua-driver-rs-latest/cua-driver-rs-*-darwin-universal.tar.gz \
| tar xz -C /Applications
# 2. 注册为 OpenClaw MCP 服务器
openclaw mcp set cua-driver '{
"command": "'"$(which cua-driver)"'",
"args": ["mcp"]
}'
# 3. 启动守护进程
open -n -g -a CuaDriver --args serve
# 4. 授予权限（一次性）
# 系统设置 → 隐私和安全
# → 屏幕录制 → 勾选 CuaDriver
# → 无障碍 → 勾选 CuaDriver
# 5. 验证
cua-driver check_permissions --daemon
```
## For Hermes
在 `~/.hermes/config.yaml` 中添加：
```yaml
mcp_servers:
cua-driver:
command: "$HOME/.local/bin/cua-driver"
args: ["mcp"]
```
## 先决条件
- macOS 15.0+
- 已安装 OpenClaw（或任何 MCP 兼容的代理框架）
- [cua-driver (trycua/cua)](https://github.com/trycua/cua) —— Apache 2.0
- 无需 Docker、无需 API 密钥、无需云账户
## 架构
```
┌──────────────┐ MCP/stdin ┌──────────────┐
│ OpenClaw │◄─────────────────────│ cua-driver │
│ （Ibrahim） │ 55+ 代理工具 │ 守护进程 │
│ │ + 33 桌面工具 │ │
│ ┌────────┐ │ │ ┌────────┐ │
│ │ cua- │──┤ 截图、点击、 │ │ macOS │ │
│ │ driver │ │ 输入、AX 树... │ │ AX API │──┤
│ │ MCP │──┤ │ │ CGEvent│ │
│ └────────┘ │ │ └────────┘ │
└──────────────┘ └──────────────┘
```
## 权限注意事项
macOS 通过 **包标识符** （`com.trycua.driver`）分配 TCC 授权。你必须：
1. 以**独立进程** 启动 CuaDriver.app（通过 Finder 或 `open -n`）
2. 为 CuaDriver 授予屏幕录制和无障碍权限
3. 在检查权限时使用 `--daemon` 标志：
```bash
cua-driver check_permissions --daemon
```
从终端运行会检查终端的授权，而不是驱动程序的。`--daemon` 标志强制驱动程序使用其自己的 TCC 标识。
## 完整工具列表
| 工具 | 描述 |
|---|---|
| `zoom` | 截图一个窗口区域（返回 JPEG） |
| `click` / `double_click` / `right_click` | 通过元素或像素执行鼠标操作 |
| `type_text` | 在聚焦元素中输入 |
| `press_key` / `hotkey` | 键盘按键和快捷键 |
| `drag` | 从一个点拖动到另一个点 |
| `scroll` | 按行或页面滚动 |
| `get_window_state` | 窗口的 AX 树 + 截图 |
| `list_windows` / `list_apps` | 发现窗口和正在运行的应用程序 |
| `launch_app` / `kill_app` | 启动/停止应用程序 |
| `set_value` | 设置元素值（滑块、下拉菜单、文本字段） |
| `start_session` / `end_session` | 管理代理光标会话 |
| `set_agent_cursor_*` | 光标叠加可见性、样式、运动 |
| `move_cursor` | 移动代理光标叠加（用户的鼠标保持不动） |
| `check_permissions` | 检查无障碍 + 屏幕录制授权 |
| `get_screen_size` | 获取显示尺寸 |
| `start_recording` / `stop_recording` | 记录代理操作以供重放 |
## License
本设置指南采用 MIT 许可。cua-driver 采用 Apache 2.0 许可。OpenClaw 有其自己的许可。
