computer-use-cli：在 macOS 终端里驱动虚拟机客户机做 UI 自动化

computer-use-cli 是一个在 macOS 上从终端驱动 macOS 客户机进行 UI 自动化的开源工具。它由 Swift 写成，能让你创建一次性的 macOS 虚拟机客户机，截屏、获取可访问性树、发送点击、输入、按键、拖拽、滚动等操作。适合需要把 macOS 应用操作隔离在客户机里、而不是直接操控主桌面的场景。

项目简介

computer-use-cli 提供了一套命令行工具，用来在 Apple Silicon Mac 上创建并控制一个预配置好的 macOS 客户机镜像。它结合了截图和 Accessibility API 返回的 UI 状态数据，让终端或上层 agent 可以精确地感知界面并执行操作。

典型用途包括：

• 在主桌面之外隔离运行 macOS 应用自动化
• 将 UI 状态作为截图 + 可访问性树数据捕获
• 从命令行或 agent 调用可重复的 UI 操作

核心特性

• 创建/启动/停止/删除 macOS 客户机：通过 machine 子命令管理虚拟机生命周期
• 截屏 + 可访问性树：state get 返回运行状态、element ID 和索引，可生成 PNG 截图
• 丰富的 UI 操作：click、type、key、drag、scroll、set-value、accessibility action
• 应用级目标：操作可以指定 --app 名称，避免误触其他窗口
• 元素级目标：通过 --element-index 直接对可访问性元素执行操作
• 无需安装额外 CLI 工具：主机端只需安装一个 .pkg
• 提供预置客户机镜像：默认使用 ghcr.io/jianliang00/computer-use:v0.1.6

技术栈

• 语言：Swift 6（占比 91.4%）
• 平台：Apple Silicon Mac + macOS 15+
• 虚拟化：Apple Virtualization Framework
• 授权：Apache 2.0

安装指南

前置要求

• Apple Silicon Mac
• macOS 15 或更新版本
• 一个已授权 Accessibility 和 Screen Recording 的 macOS 客户机镜像

下载安装包

从 GitHub Releases 下载 computer-use-<version>-macos-arm64.pkg。

图形界面安装

1. 双击 .pkg 文件
2. 按提示完成安装
3. 验证：computer-use --help

命令行安装

sudo installer -pkg computer-use-<version>-macos-arm64.pkg -target /
computer-use --help

安装后会得到 /usr/local/bin/computer-use。

快速开始

1. 创建并启动客户机

computer-use machine create --name demo --image ghcr.io/jianliang00/computer-use:v0.1.6
computer-use machine start --machine demo

2. 检查客户机状态

computer-use agent doctor --machine demo
computer-use permissions get --machine demo

3. 列出应用并获取 UI 状态

computer-use apps list --machine demo
computer-use state get --machine demo --app TextEdit
computer-use state get --machine demo --app TextEdit --screenshot-output ./textedit.png

4. 发送基础操作

computer-use action click --machine demo --app TextEdit --x 120 --y 240
computer-use action type --machine demo --app TextEdit --text "hello"
computer-use action key --machine demo --app TextEdit --key cmd+a

使用示例

通过 element index 点击元素

state get 会返回 element indexes。结合 --element-index 可以直接点击界面元素：

computer-use action click --machine demo \
  --app TextEdit \
  --element-index <element-index>

拖拽操作

computer-use action drag --machine demo --app TextEdit \
  --from-x 100 --from-y 100 \
  --to-x 400 --to-y 300

滚动

computer-use action scroll --machine demo --app TextEdit \
  --element-index <element-index> \
  --direction down --pages 0.5

设置元素值

computer-use action set-value --machine demo --app TextEdit \
  --element-index <element-index> \
  --value "new value"

执行 Accessibility Action

computer-use action action --machine demo --app TextEdit \
  --element-index <element-index> \
  --name AXPress

管理客户机生命周期

computer-use machine list
computer-use machine inspect --machine demo
computer-use machine logs --machine demo
computer-use machine stop --machine demo
computer-use machine rm --machine demo

从源码构建

swift build
swift test
swift run computer-use --help

注意：Swift 6 是构建必需条件。

相关文件说明

普通用户只需安装主机端 .pkg，并运行预置客户机镜像即可。

注意事项

• 客户机镜像必须提前启用 Accessibility 和 Screen Recording 授权，否则无法捕获 UI 状态。
• 该工具只支持 Apple Silicon，不支持 Intel Mac。
• 需要 macOS 15 或更新版本。
• 默认客户机镜像托管在 GitHub Container Registry，需要能访问 ghcr.io。
• 如果需要自定义客户机镜像，参考仓库里的 Guest Image 文档。

项目链接

• GitHub 仓库：https://github.com/jianliang00/computer-use-cli
• 预置镜像：ghcr.io/jianliang00/computer-use:v0.1.6
• 使用文档：docs/
• 架构说明：docs/Architecture.md
• 镜像构建：docs/Guest-Image.md
• 发布说明：docs/Releasing.md