@srgay/computer-use-cli (cua)

用命令行 cua 或 MCP 控制 macOS 桌面应用——截图、读无障碍树、点击、键入、按键、滚动、拖拽、设值。 底层走 codex app-server 的 computer-use 原语,直接 mcpServer/tool/call,不经 LLM,零 ChatGPT 额度。

这同时是一个 Cursor / Claude Agent Skill(见 SKILL.md);CLI 与 MCP 两种形态共用一套脚本。

前置

• macOS(原语依赖 Accessibility / 屏幕录制)。
• codex CLI:codex app-server 可用(0.140+)。本地原语不需要 ChatGPT 登录态。
• Node.js ≥ 20(零第三方依赖)。
• 系统设置 → 隐私与安全性:给运行 cua 的终端授予 屏幕录制 + 辅助功能。 现象:能截图但点击/键入无效 → 多半是缺辅助功能权限。

安装

npm i -g @srgay/computer-use-cli
cua ping            # 起 daemon 并自检

如果之前按源码方式手工创建过 /opt/homebrew/bin/cua 或 /usr/local/bin/cua，npm i -g 可能报 EEXIST: file already exists。确认它是旧 symlink 后删掉再装：

ls -l /opt/homebrew/bin/cua   # 或 /usr/local/bin/cua
rm /opt/homebrew/bin/cua
npm i -g @srgay/computer-use-cli

快速上手

cua list-apps                      # 列出应用(名称 / 路径 / bundleID)
cua state "计算器"                  # 截图(落盘到 ~/.cua-cli/shots/) + 无障碍树 —— 每轮操作前必做
cua state Codex                    # Codex 本体只支持截图兜底,不返回无障碍树/元素编号
cua click "计算器" --index 9        # 按元素编号点击(编号来自最近一次 state)
cua click Safari --x 120 --y 80    # 或按像素坐标
cua type TextEdit "Hello 世界"      # 键入文本
cua key Safari "super+l"           # 组合键(xdotool 语法)
cua tools                          # 列出全部 10 个原语

工作流:看(state) → 定位(index) → 操作(click/type/...) → 复看(state)。 element_index 只在最近一次 state 之后有效(界面变化会重新编号),用前先 state。 完整命令与原语参数见 SKILL.md 与 references/。

MCP 形态(接入 Cursor 等)

~/.cursor/mcp.json:

{
  "mcpServers": {
    "computer-use": {
      "command": "cua",
      "args": ["mcp"],
      "env": { "CUA_CODEX_BIN": "/opt/homebrew/bin/codex", "CUA_AUTO_APPROVE": "true" }
    }
  }
}

由 Cursor 的模型直接调用 get_app_state / click / … 。 如果 Cursor 的启动环境找不到 cua，把 command 改成 which cua 输出的绝对路径。 全局安装后也可以直接用 cua-mcp-bridge 作为 command。

工作原理(为什么零额度 + 为什么有 daemon)

• app-server 对 mcpServer/tool/call 的实现是 thread.call_mcp_tool(...),绕过 agent loop / 模型推理, 决策由调用方完成,codex 只当执行器 → 不消耗对话额度。
• computer-use 的 element_index 与操作必须与 get_app_state 处于同一 session。CLI 形态用一个常驻 daemon 持有单一 thread,让连续 cua 命令共享 session;空闲 15 分钟自动退出。
• computer-use 出于安全原因禁止控制 Codex 本体。cua state Codex 遇到该限制时会退回到 macOS screencapture 只截取 Codex 窗口;不会返回无障碍树,也不能用于 click --index。

更多细节见 references/architecture.md 与 references/primitives.md。

常用环境变量

CUA_CODEX_BIN · CUA_CWD · CUA_TIMEOUT_MS · CUA_AUTO_APPROVE · CUA_IDLE_MS · CUA_SHOT_DIR · CUA_SERVERS · CUA_DEBUG(说明见 references/architecture.md)。

License

MIT