> 本指南中的命令在本地项目根目录运行。网站只展示调研与操作说明，不会直接连接或操作你的电脑。CLI 实验封装与配置可下载：[CLI Lab 源码包](/cli-lab-source.zip)。下载包不包含驱动二进制；解压后运行 install_local.py 获取校验过的固定版本。

# Terminal Computer Use Lab

可以从 Terminal 使用 Computer Use，无需打开 Codex Desktop。链路是 **Codex CLI / Claude Code → MCP → Cua Driver → macOS 应用**。这里复用开源 Cua Driver 的原生驱动，提供自己的薄 CLI 封装；它不是 OpenAI 私有 `@oai/cua` 的移植，也不是完整的新模型代理。

Terminal 是控制入口，仍需一台有登录图形会话的 Mac 和必要的 macOS 权限。CuaDriver.app 在这里充当具有稳定签名身份的后台 helper，不是需要日常打开的聊天界面。纯 SSH / 没有图形登录的机器不等于能直接操作桌面。

## 已在这台 Mac 验证

- macOS 26.2，Apple Silicon arm64。
- 官方 Cua Driver **0.28.2** 独立二进制已下载至 `vendor/cua-driver`，并核对 GitHub release asset 的 SHA-256。
- `--version`、`manifest`、`list-tools`、三个工具的 `describe` 均成功，exit code 为 0。
- CLI 封装的配置输出、JSON 参数序列化、拒绝非显式执行的行为已验证。
- **没有启动 daemon、安装 App、改变系统权限、枚举应用、截图或模拟输入。** 因此已验证的是终端接口和封装，不是 GUI 控制成功率。

版本固定信息见 固定版本清单（随本地项目保存）。GitHub 将此版本标记为 `prerelease: true`；这里按确切已发布版本固定，没有把它称为稳定 GA。源码审读还使用了较新的主线提交，差异见研究附录。

## 现在即可运行

在项目根目录执行，仅需 Python 3.9+ 标准库：

```bash
python3 cli-lab/cu.py inspect
python3 cli-lab/cu.py list-tools
python3 cli-lab/cu.py describe launch_app
python3 cli-lab/cu.py describe get_window_state
python3 cli-lab/cu.py plan launch_app '{"bundle_id":"com.apple.calculator"}'
python3 cli-lab/cu.py config codex
python3 cli-lab/cu.py config claude
```

`inspect/list-tools/describe` 是静态元数据检查，不查看正在运行的应用。`plan` 只打印将要执行的 argv。`config` 只输出配置，不修改 Codex、Claude 或系统设置。封装通过 argv 数组调用进程，不使用 shell 拼接。

如果重新获取该二进制：

```bash
python3 cli-lab/install_local.py
```

下载脚本只向当前 Lab 写文件，只从 tar 中提取一个普通可执行文件，校验固定 SHA-256；不执行官方安装脚本，不写 `/Applications`、shell rc 或 TCC。这个独立文件用于接口研究，封装不会用它直接启动 macOS GUI/MCP 服务。

## 开始实际控制前的一次性设置

以下是官方 macOS 安装流程，**本次没有执行**。它会安装 `/Applications/CuaDriver.app`、建立 `~/.local/bin/cua-driver`，必要时修改 shell PATH；要求 macOS 14+。这是从 Terminal 驱动原生 App 的正常依赖，不依赖 Codex Desktop。

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

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

在 macOS 设置中为 **CuaDriver** 开启辅助功能与屏幕录制权限，并按系统要求退出重启 helper。不要把权限归属混淆成 Codex Desktop、当前 Terminal 或随机裸二进制。Cua 默认有内容不包含在内的产品遥测；如需关闭可执行 `cua-driver telemetry disable`。Lab 自己运行的子进程已经通过环境变量关闭遥测。

`permissions grant` 会主动走系统许可界面并可能做捕获探测，所以本次没有运行。较新主线文档规定 `permissions status` 是无提示查询且不做直接截图探测；对不同旧版本，应按该版本文档确认行为。

## 接到 Codex CLI

安装并完成权限设置后：

```bash
codex mcp add cua --env CUA_DRIVER_RS_TELEMETRY_ENABLED=0 -- cua-driver mcp
codex
```

上述 `codex mcp add` 语法已用本机 `--help` 核实，但没有执行注册。若新 Terminal 无法找到 `cua-driver`，将 MCP command 改成 `~/.local/bin/cua-driver` 展开后的绝对路径。

也可把 `python3 cli-lab/cu.py config codex` 输出的 TOML 合并进 Codex 配置。Claude Code 可使用 `config claude` 输出的标准 stdio MCP JSON。两种方式都将自然语言规划交给既有 CLI agent，Cua 只负责观察/操作工具。

第一次任务建议明确指定 Calculator：读取当前状态，计算 `6 × 7` 并核对 `42`。这是建议的后续验证任务，本次未执行。

## 直接调用工具 / 做自己的 agent loop

正式安装之后，`cu.py` 优先使用 PATH 中的官方 `cua-driver`。也可通过全局参数 `--driver /absolute/path/to/cua-driver` 指定。

```bash
# 真正打开 Calculator；这一条是 GUI 操作
python3 cli-lab/cu.py run launch_app '{"bundle_id":"com.apple.calculator"}' --execute
```

从返回结果拿实际 `pid` 与 `window_id`，再查询该窗口。下面用占位 ID 展示结构，必须换成刚读到的值：

```bash
python3 cli-lab/cu.py plan get_window_state '{"pid":12345,"window_id":67890,"include_screenshot":false}'
```

`get_window_state` **默认包含截图和 AX 树**；`include_screenshot:false` 可只取树。树本身也可能包含应用内容，所以不要把它当作纯环境检查。点击优先使用新快照返回的 `element_token`；需要元素索引时同时带最新 `snapshot_id`。不要硬编码示例里的控件索引或拿旧窗口 ID 重试。

最小闭环：

```text
任务 → 读取工具 schema → 观察指定窗口 → 模型选择动作
     → 执行动作 → 再观察并核对结果 → 完成/停止
```

本次封装到“执行器”这一层。你可以把 `plan` / `run` 的工具参数接自己的模型调用与状态机；`config` / `mcp` 则让现成 Codex CLI 承担 agent loop。Windows/Linux 也有 Cua Driver，但本 Lab 固定下载的是 macOS 二进制。

## 文件

| 文件 | 用途 |
|---|---|
| `cu.py` | 原始 Python CLI 封装，无第三方 Python 依赖 |
| `install_local.py` | 项目局部下载、校验、只提取二进制 |
| `driver-release.json` | 固定 tag、发布时间、下载 URL、SHA-256 |
| `vendor/cua-driver` | 已验证的离线检查用二进制，不提交到 Git |
| `../research/cli/` | 官方源码快照、schema、smoke 结果与来源 |

## 官方来源

- [安装文档](https://cua.ai/docs/how-to-guides/driver/install)
- [macOS 权限与身份](https://cua.ai/docs/reference/cua-driver/macos-permissions)
- [平台支持范围](https://cua.ai/docs/reference/cua-driver/platform-support)
- [固定 0.28.2 release](https://github.com/trycua/cua/releases/tag/cua-driver-rs-v0.28.2)
- [0.28.2 的 CLI 启动分发源码](https://github.com/trycua/cua/blob/fc188250b4ca8549b8e61f937fdb1fb560770e86/libs/cua-driver/rust/crates/cua-driver/src/main.rs#L502)
- [当前文档固定源码快照](https://github.com/trycua/cua/blob/d1a01f8580d5963702427b9e110fbcd98c39fac3/docs/content/docs/how-to-guides/driver/install.mdx)