跳到主要内容

计算机操控(Computer Use)

KOPI AI AGENT 可以驱动你的桌面——点击、输入、滚动、 拖拽——在 macOS、Windows 和 Linux 上以后台方式运行。你的 光标不会移动,键盘焦点不会改变,你的虚拟 桌面 / Spaces 也不会被切换。你和 agent 可以在同一台 机器上协同工作。

与大多数 computer-use 集成不同,它适用于任何具备工具调用能力的 模型——Claude、GPT、Gemini,或本地 OpenAI 兼容 endpoint 上运行的开放模型。你无需担心 Anthropic 原生 schema 带来的 问题。

工作原理​

computer_use toolset 通过 stdio 与 MCP 通信,连接到 cua-driver,这是一个开源的后台 computer-use 驱动。每个平台在底层都使用相应的辅助功能 + 输入技术栈:

平台辅助功能树输入派发
macOSAX(私有 SkyLight SPI)SLPSPostEventRecordTo —— 限定于 pid,不会移动光标
WindowsUIAutomationSendInput + PostMessage —— 不会抢占焦点
LinuxAT-SPI(X11 + Wayland)XTest(X11)/ virtual-keyboard(Wayland)

最终效果在每个平台上都一致:agent 可以读取 任意可见窗口的辅助功能树,并注入合成事件, 而无需将其置于前台、切换虚拟桌面或移动 真正的 OS 光标。

关于底层契约——为什么后台模式至关重要、 不抢占前台的不变式、点击派发的内部实现——请参阅 cua.ai/docs/explanation/the-no-foreground-contract。

启用​

选择最方便的方式——两条路径运行的是同一个上游 安装程序:

方式 1:专用 CLI 命令(最直接)。

kopi computer-use install

这会下载并运行上游 cua-driver 安装程序——在 macOS/Linux 上为 install.sh 在 Windows 上为 install.ps1。使用 kopi computer-use status 验证安装。

方式 2:交互式启用该 toolset。

  1. 运行 kopi tools,选择 🖱️ Computer Use (macOS/Windows/Linux)。
  2. 安装流程会运行上游安装程序(与方式 1 相同)。

安装完成后,无论你采用哪条路径,都需要授予 相应平台的前置权限:

平台前置条件
macOS系统设置 → 隐私与安全性 → 辅助功能 + 屏幕录制 → 允许你的终端(或 Kopi Agent 应用)。kopi computer-use doctor 会告诉你缺少哪项权限。
Windows安装时无需任何条件。如果你通过 SSH(而非 RDP / 控制台)进行驱动,则需要自启动模式——有关 Session 0 ↔ Session 1+ 代理,请参阅 cua.ai/docs/how-to-guides/driver/windows-ssh。
Linux一个可达的显示服务器:X11 下需设置 DISPLAY,或使用 XDG_SESSION_TYPE=wayland。Wayland 会话需要 XWayland 桥接才能进行画面捕获。AT-SPI 必须开启(在 GNOME/KDE/Xfce 上默认开启)。

然后启动一个启用了该 toolset 的会话:

kopi -t computer_use chat

或在 ~/.kopi/config.yaml 中将 computer_use 添加到已启用的 toolsets 中。

kopi computer-use doctor —— 你的第一个排查入口​

kopi computer-use doctor 运行 cua-driver 的结构化 health_report MCP 工具,并输出逐项检查矩阵。这是 查明某个操作为什么不起作用的最快方式。

$ kopi computer-use doctor
⚠️ cua-driver 0.5.8 on darwin — degraded
✅ binary_version: cua-driver 0.5.8
✅ platform_supported: macOS 26.4.1 (arm64)
✅ session_active: MCP session is active.
❌ bundle_identity: Process has no CFBundleIdentifier.
→ Run the binary inside CuaDriver.app so TCC grants attribute correctly.
✅ tcc_accessibility: Accessibility is granted.
✅ tcc_screen_recording: Screen Recording is granted.
✅ ax_capability: AX is trusted and reachable.
✅ screen_capture_capability: ScreenCaptureKit reachable; 1 display(s) shareable.
  • 退出码 0 表示总体结果为 ok——一切就绪。
  • 退出码 1 表示 degraded 或 failed——至少有一项检查失败;每个失败项上的提示会告诉你需要修复什么。
  • 退出码 2 表示 cua-driver 二进制文件本身不可达。

常用参数:

  • --include CHECK —— 仅运行列出的检查项(可重复指定多个)
  • --skip CHECK —— 跳过某项检查(优先级高于 --include)
  • --json —— 输出原始结构化载荷,格式与 tools/call health_report MCP 响应相同

检查矩阵会感知平台:bundle_identity / tcc_* 在 Windows + Linux 上为 skip,因为这些概念不适用。 ax_capability 在 macOS 检查 AX、Windows 检查 UIA、Linux 检查 AT-SPI—— 每项在无法访问时都会给出正确的诊断提示。

agent 光标与会话​

当 agent 执行操作时,你会看到一个带色调的覆盖层光标滑过 屏幕,到达每次点击 / 输入 / 滚动的位置。真正的 OS 光标始终不会移动——覆盖层只是一个视觉提示,表示“ agent 正在这里操作”。每次 Kopi Agent 运行都会声明自己的 cua-driver session id(形如 kopi-3a7b9c14d2e8);光标的 身份与该 session 绑定,因此并发运行 / 子 agent 会各自 拥有独立的光标,互不干扰。

你可以通过 cua-driver 的 CLI 参数或运行时的 set_agent_cursor_style MCP 工具来调整光标——完整选项请参阅 cua.ai/docs/how-to-guides/driver/personalize-cursor (内置 arrow 与 teardrop 剪影、通过 --cursor-icon 自定义 SVG / PNG / ICO、运行时渐变色、光晕 效果)。

深入了解 —— cua-driver skill pack​

Kopi Agent 有意将其 skill(skills/computer-use/SKILL.md) 聚焦于 Kopi Agent 侧的 computer_use action 词汇表 —— 也就是 agent 加载的唯一事实来源。至于更深入的内容 —— 平台特定的深入探讨、录制语义、浏览器页面交互 —— 请让你的 agent harness 指向 cua-driver 团队直接 发布并维护的 cua-driver skill pack:

cua-driver skills install

这会将该 pack 符号链接到你的 agent harness 的 skill 目录中。运行 之后,agent 将可以访问:

文件主题
SKILL.md跨平台核心(快照不变量、no-foreground 契约、点击分发、AX-tree 机制)
MACOS.mdmacOS 特定内容:no-foreground 契约、AXMenuBar 导航、SkyLight 点击分发、Apple Events JS 桥接
WINDOWS.mdWindows 特定内容:UIA 树、UWP / ApplicationFrameHost 宿主、Session 0 隔离、自启动模式
LINUX.mdLinux 特定内容:AT-SPI 树、X11 / Wayland、终端模拟器检测
RECORDING.md轨迹 + 视频录制语义
WEB_APPS.md浏览器页面交互技巧
TESTS.md按轨迹回放的工作流

这些是平台深入内容,并非 Kopi Agent skill 的重复 —— 当 agent 报告"在 Windows 上,我的点击落在了错误的 元素上"时,它会阅读 WINDOWS.md,从中获取 UIA / UWP 背景 信息,解释原因以及应采取的不同做法。

cua-driver skills status 会显示已安装的内容,以及它被链接到了哪些 agent harness。目前自动检测列表涵盖 Claude Code、Codex、OpenCode、OpenClaw 和 Antigravity;Kopi Agent 的自动检测计划在 trycua/cua 中作为后续工作完成 —— 在 此之前,请运行一次 cua-driver skills install,并将你的 harness 指向 生成的 ~/.cua-driver/skills/cua-driver 目录(或将其符号链接到 你常用的 skill 空间中)。

简单示例​

用户 prompt:"找到我最新的 Stripe 邮件,并总结他们要我做什么。"

Agent 的计划(在 macOS / Windows / Linux 上结构相同 —— 只是模型会代入该平台惯用的快捷键和应用名称):

  1. computer_use(action="capture", mode="som", app="Mail") —— 获取 邮件应用的截图,其中每个侧边栏条目、工具栏按钮和 邮件行都有编号。
  2. computer_use(action="click", element=14) —— 点击搜索框。
  3. computer_use(action="type", text="from:stripe")
  4. computer_use(action="key", keys="return", capture_after=True) —— 提交并获取新的截图。
  5. 点击第一条结果,阅读正文内容,进行总结。

在整个过程中,你的光标会一直停留在你离开时的位置,邮件 应用也始终不会被带到前台。

Provider 兼容性​

Provider支持视觉?可用?备注
Anthropic (Claude Sonnet/Opus 3+)✅✅整体表现最佳;SOM + 原始坐标。
OpenRouter(任意视觉模型)✅✅支持多部分 tool message。
OpenAI (GPT-4+, GPT-5)✅✅同上。
Google (Gemini 2+)✅✅同时支持 tool-calling 与视觉。
本地 vLLM / LM Studio / Ollama(视觉模型)✅✅前提是模型支持多部分 tool 内容。
纯文本模型❌✅(降级)使用 mode="ax" 仅基于 accessibility tree 的操作模式。

截图会以 OpenAI 风格的 image_url 部分形式随 tool 结果内联发送。 对于 Anthropic,adapter 会将它们转换为原生的 tool_result image block。图片的 MIME 类型来自 cua-driver 显式的 mimeType 字段(image/png 或 image/jpeg)—— 不做客户端的 magic-byte 嗅探。

安全性​

Kopi Agent 应用了多层防护措施:

  • 破坏性操作(click、type、drag、scroll、key、focus_app) 需要批准 —— 可以通过 CLI 对话框交互式批准,也可以通过 消息平台的批准按钮批准。
  • 在 tool 层面硬性拦截的组合键:清空废纸篓、强制删除、 锁屏、登出、强制登出。
  • 硬性拦截的输入模式:curl | bash、sudo rm -rf /、fork bomb 等。
  • Agent 的 system prompt 明确告知它:不得点击权限对话框、 不得输入密码、不得遵循嵌入在截图中的指令。

如果希望每个操作都得到确认,可搭配 ~/.kopi/config.yaml 中的 approvals.mode: manual 使用。

Token 效率​

截图的成本很高。Kopi Agent 应用了四层优化:

  • 截图驱逐(Screenshot eviction) —— Anthropic adapter 在上下文中仅保留最近 3 张 截图;更早的截图会变成 [screenshot removed to save context] 占位符。
  • 客户端压缩裁剪 —— 上下文压缩器会检测 多模态 tool 结果,并从旧结果中剥离图片部分。
  • 图片感知的 token 估算 —— 每张图片按约 1500 个 token 计算(Anthropic 的固定费率),而不是按其 base64 字符长度计算。
  • 服务端上下文编辑(仅限 Anthropic) —— 启用后, adapter 会通过 context_management 启用 clear_tool_uses_20250919,让 Anthropic 的 API 在服务端清除旧的 tool 结果。

在一个 1568×900 显示屏上进行 20 次操作的会话,其截图上下文 通常消耗约 30K token,而不是约 600K。

限制​

  • 性能。 后台模式比前台模式慢——经由辅助功能(accessibility)路由的事件在 macOS 上约需 5–20 毫秒,Windows UIA 上约 3–10 毫秒,Linux AT-SPI 上约 5–15 毫秒,而直接 HID 投递则更快。对于 agent 速度的点击来说无感知;但如果你尝试录制速通(speed-run),就会察觉到差异。
  • 不支持通过键盘输入密码。 type 对命令 shell 载荷设有硬性拦截模式;要输入密码,请使用系统的自动填充功能(macOS Keychain / Windows Credential Manager / GNOME Keyring / KWallet)。
  • 部分应用不暴露辅助功能树。 Windows 上的现代 UWP 应用、Linux 上低于 28 版本的 Electron,以及少数采用自定义绘制的 macOS 应用(Logic、Final Cut、某些游戏)的 AX 树非常稀疏或为空。如果树为空,请回退到像素坐标——或者干脆跳过该任务。
  • Windows:提权(管理员)窗口无法由普通 agent 操控。 Windows UIPI(用户界面特权隔离)会强制执行完整性级别边界:中等完整性进程(默认的 Kopi Agent)无法枚举由高完整性(Administrator)进程拥有的窗口的 UIA 树,也无法向其注入鼠标输入。症状:capture(mode='som') 返回 0 个元素,而 click(...) 报告成功但实际上什么都没做,即使截图渲染正常(GDI 捕获位于完整性检查之下)。键盘事件可以部分绕过 UIPI,因此 Tab / Enter 仍可在一个提权对话框中导航。这是操作系统层面的限制,而非 cua-driver 的 bug——它会影响所有 Windows 自动化技术栈。要操控提权窗口,请以高完整性运行 Kopi Agent 本身(从提权的终端启动);否则请以未提权窗口为目标。
  • 平台特定的部署注意事项:
    • macOS 使用私有的 SkyLight SPI。Apple 可能在任何系统更新中更改它们。当已安装的 cua-driver 版本低于其测试所针对的版本时,Kopi Agent 会发出警告。
    • Windows SSH 会话运行在 Session 0 中,该会话没有交互式桌面。请在 RDP / 控制台会话内部操控 Kopi Agent,或者配置 cua-driver 的自启动计划任务—— windows-ssh 中有具体方案。
    • Linux 需要一个可访问的显示服务器。无头服务器需要先启动 Xvfb (Xvfb :99 -screen 0 1920x1080x24), computer_use 才能捕获或注入事件。纯 Wayland 会话需要 XWayland 桥接来进行屏幕捕获(cua-driver 的 Wayland 注入路径独立处理输入)。

如果要在没有桌面开销(也无需 TCC / Session 0 / X11 配置)的情况下进行跨平台 GUI 自动化,browser 工具集使用真实的无头 Chromium,是仅面向 Web 任务的正确选择。

配置​

覆盖驱动二进制文件路径(测试 / CI / 本地构建):

KOPI_CUA_DRIVER_CMD=/path/to/your/cua-driver

完全替换后端(用于测试):

KOPI_COMPUTER_USE_BACKEND=noop   # records calls, no side effects

遥测​

cua-driver 默认带有上游启用的匿名使用遥测(PostHog)。Kopi Agent 已为你禁用它——在每次调用 cua-driver 时(MCP 后端、status、doctor 以及安装过程),Kopi Agent 都会在驱动的环境中设置 CUA_DRIVER_RS_TELEMETRY_ENABLED=0。

要重新选择加入(让 cua-driver 使用其自身默认设置并发送遥测),请在 config.yaml 中设置:

computer_use:
cua_telemetry: true # default: false (telemetry off)

启用时,kopi computer-use doctor 会报告 telemetry: enabled;禁用时(默认情况),它会报告 telemetry: disabled via CUA_DRIVER_RS_TELEMETRY_ENABLED。

使用本地 cua-driver 构建版本进行测试​

当你在开发 cua-driver 本身 —— 或想测试一个尚未发布的修复时 —— 可以让 Kopi Agent 指向你从源码构建的二进制文件,而不是官方发布版。Kopi Agent 通过 shutil.which("cua-driver") 解析 driver,且不强制要求 KOPI_CUA_DRIVER_VERSION,因此本地构建(报告为 0.0.0-local-*)会被原样接受。两种方式:

选项 A —— install-local(构建并放入 PATH)​

在你的 trycua/cua 检出目录中,运行上游的本地安装脚本。它会以 release 模式构建 Rust 后端,并将 cua-driver 放入与生产安装脚本 相同的安装布局中,同时将其 bin 目录加入你的 PATH:

# Windows (PowerShell), from the cua repo root
./libs/cua-driver/scripts/install-local.ps1 -NoAutoStart
# macOS / Linux, from the cua repo root  (defaults to a debug build without --release)
./libs/cua-driver/scripts/install-local.sh --release
  • Windows 会将构建产物暂存在 %USERPROFILE%\.cua-driver\packages\… 下, 并把 %LOCALAPPDATA%\Programs\Cua\cua-driver\bin(已加入你的用户 PATH)以 junction 方式链接到该位置。macOS/Linux 会将 cua-driver 符号链接到 ~/.local/bin (可用 --bin-dir <path> 覆盖)。
  • -NoAutoStart 会跳过注册 cua-driver-serve 登录守护进程 —— Kopi Agent 测试不需要它(参见备注)。

然后打开一个新的 shell(以便 PATH 变更生效)并确认:

cua-driver --version                 # local builds report 0.0.0-local-release
# Windows: (Get-Command cua-driver).Source
# macOS/Linux: which cua-driver

选项 B —— 让 Kopi Agent 直接指向构建出的二进制文件(迭代最快)​

完全跳过安装流程:cargo build,然后把 KOPI_CUA_DRIVER_CMD 设置为生成的二进制文件。最适合快速的 编辑/构建/测试循环。

cargo build -p cua-driver            # add --release for a release build; run from libs/cua-driver/rust
# Windows (.env)
KOPI_CUA_DRIVER_CMD=C:\path\to\cua\libs\cua-driver\rust\target\debug\cua-driver.exe
# macOS / Linux (.env)
KOPI_CUA_DRIVER_CMD=/path/to/cua/libs/cua-driver/rust/target/debug/cua-driver

确认 Kopi Agent 正在使用你的构建​

  • kopi computer-use status 会打印解析到的二进制路径和版本。
  • kopi computer-use doctor 确认二进制文件可达,并端到端验证完整的 MCP 路径。
  • 在会话中,computer_use(action="capture") 会运行所生成的 cua-driver mcp 子进程。

备注与注意事项​

  • Kopi Agent 会通过 stdio 生成自己的 cua-driver mcp 子进程 —— 它 不会附加到长时间运行的 cua-driver serve 自启动守护进程 或其命名管道。因此测试时不需要计划任务 / LaunchAgent (-NoAutoStart 即可)。自启动守护进程和 Windows UIAccess worker(cua-driver-uia.exe)仅在某些应用 (例如 WPF)需要前台安全输入时才起作用;标准工具接口通过 stdio 子进程工作。 在 Windows SSH 会话中,则需要自启动模式 —— 参见限制一节。
  • Windows 上二进制文件被锁定。 运行中的 cua-driver-serve 守护进程可能 占用 cua-driver.exe,导致重新构建时无法覆盖写入。 install-local.ps1 会自动将被锁定的二进制文件重命名移开; 如果你手动 cargo build(选项 B),请先用 cua-driver autostart disable(或 schtasks /End /TN cua-driver-serve)停止它。
  • 重新构建循环。 修改 cua-driver 源码后,对于选项 A,请重新运行 install-local(重新构建、重新暂存、翻转 current junction);对于选项 B,只需重新 cargo build —— 两种方式都不需要改动 Kopi Agent。
  • 本地构建跳过版本检查。 当已安装的 cua-driver 低于其各操作系统的已测试基线版本时, Kopi Agent 会发出警告,但会豁免 0.0.0-local-* 开发构建 —— 因此你的本地构建 永远不会触发该警告。

故障排查​

出现任何异常时的第一步:运行 kopi computer-use doctor。 这个结构化的逐项检查矩阵会告诉你(以及任何帮你调试的 agent) 到底哪里出了问题。

doctor 捕获不到的特定故障模式:

computer_use backend unavailable: cua-driver is not installed —— 运行 kopi computer-use install 来获取 cua-driver 二进制文件,或 运行 kopi tools 并启用 Computer Use 工具集。

点击似乎没有效果 —— 截图并检查。一个你没注意到的模态对话框可能 正在阻塞输入。用 escape 或关闭按钮将其关掉。

元素索引已过期 —— SOM 索引仅在下一次 capture 之前有效。 任何改变状态的操作后都需要重新截图。wrapper 中携带不透明的 element_token 用于检测过期 —— 你会看到明确的错误,而不是错误点击。

"blocked pattern in type text" —— 你尝试 type 的文本 匹配了危险 shell 模式列表。请拆分命令或重新考虑。

Linux 上截图为空 —— 未设置 DISPLAY,或者你处于没有 XWayland 桥接的纯 Wayland 环境。kopi computer-use doctor 会将其标记为 ax_capability: fail 并给出 Set DISPLAY (X11)… 提示。

Windows 上通过 SSH 时截图为空 —— 你处于 Session 0(服务会话)中。 请直接通过 RDP / 控制台操作,或设置自启动模式 —— 参见 cua.ai/docs/how-to-guides/driver/windows-ssh。

另请参阅​

  • Kopi Agent 侧 skill —— skills/computer-use/SKILL.md —— 教会 Kopi Agent computer_use 动作词汇表;这是 agent 加载的内容。
  • cua-driver skill pack —— 用于各平台的深入专题 (macOS 无前台契约、Windows UIA + Session 0、Linux AT-SPI
    • X11/Wayland、录制、浏览器页面),运行 cua-driver skills install 并阅读 MACOS.md / WINDOWS.md / LINUX.md / RECORDING.md / WEB_APPS.md。一旦 cua-driver skills install 能自动检测 Kopi Agent(后续计划),安装时就会自动完成这一步。
  • cua.ai/docs —— cua-driver 项目的文档:
  • cua-driver source (trycua/cua)
  • Browser automation 适用于无需驱动原生应用的跨平台 Web 任务。