Vercel 开源 agent-desktop 上手教程：让 AI 智能体通过无障碍树操作桌面应用（macOS/Windows/Linux）

agent-desktop 是什么，为什么最近这么火

过去一年，「Computer Use」（让大模型像人一样操作电脑）一直是 AI 智能体最热的方向之一。但主流做法大多是截图 + 视觉模型猜坐标：慢、贵，而且界面稍一变化就点错位置。

Vercel Labs 开源的 agent-desktop（Apache-2.0 协议）换了一条路：它不看像素，而是读取操作系统本身的无障碍树（Accessibility Tree）——也就是读屏软件使用的那套界面结构数据。每个按钮、输入框、菜单项都会被分配一个引用（ref），智能体对 ref 下指令，再重新读取界面确认结果。这几天它冲上了 GitHub Trending 日榜前列，是近期最受关注的智能体基础设施项目之一。

它的几个关键特点：

跨平台：macOS、Windows、Linux 都支持，x64 和 ARM64 均有原生二进制。
一切输出皆 JSON：每条命令只打印一个 JSON 信封（ok + data 或 error），天生适合被智能体解析。
默认无头（headless）：基于 ref 的操作走无障碍 API，不移动鼠标、不抢焦点，你可以边让 AI 干活边用电脑。
它是工具，不是智能体：agent-desktop 本身不调用任何模型，「观察—行动—验证」的循环由你接入的智能体（Claude Code、Codex 等）来跑。
可嵌入：除 CLI 外还提供 C ABI 动态库，Python、Go、Swift 等可以进程内直接调用。

准备工作

项目	要求
Node.js	18 及以上（通过 npm 安装时）
macOS	需授予终端「辅助功能」权限；截图另需「屏幕录制」权限
Windows	操作与终端同权限级别的应用无需额外授权
Linux	官方主要目标为 Ubuntu 24.04+ / GNOME 46，需安装 `at-spi2-core`，并且必须在图形会话内运行

注意：Linux 下如果你是从纯 TTY 或 SSH 登录，拿不到图形会话的无障碍总线，是看不到任何应用的。

第一步：安装

官方推荐用 npm 全局安装（pnpm、Yarn、Bun 同样可用）：

npm install -g agent-desktop
agent-desktop version

如果不想依赖 Node，也可以到 GitHub Releases 下载对应系统的原生压缩包，把可执行文件和同包的平台 helper 放在同一目录并加入 PATH。

一个容易忽略的性能细节：npm 包的 postinstall 脚本会把 Node 启动器替换为原生二进制的链接。如果你的包管理器默认拦截安装脚本，就会退回到 Node 启动器，每次调用明显变慢。官方文档给出的处理方式是：

npm install-scripts approve agent-desktop
# 或安装时显式允许脚本
npm install -g agent-desktop --allow-scripts

另外，不加 -g 的本地安装命令不会进 PATH，需要用 npx agent-desktop 运行。

第二步：检查状态与权限

agent-desktop status          # 平台、权限、支持的界面类型
agent-desktop permissions     # 只报告权限状态，不弹窗

macOS 用户如果看到权限被拒绝，运行：

agent-desktop permissions --guide

它会直接打开「系统设置」中缺失的权限页面，并提示你把哪个应用（通常是你的终端，如 Terminal、iTerm2）拖进列表。授权后建议重启终端再检查一次。

第三步：核心循环——快照、ref、操作、验证

agent-desktop 的全部用法都围绕一个循环：观察 → 对 ref 操作 → 再观察确认。先列出可操作的应用：

agent-desktop list-apps

以 macOS 的「访达」为例，获取它的可交互元素：

agent-desktop snapshot --app Finder -i

返回的 JSON 大致结构如下（已精简）：

{
  "ok": true,
  "command": "snapshot",
  "data": {
    "app": "Finder",
    "snapshot_id": "s8f3k2p9",
    "tree": {
      "role": "window",
      "name": "Downloads",
      "children": [
        { "role": "treeitem", "name": "Documents", "ref_id": "@s8f3k2p9:e8", "available_actions": ["Click"] }
      ]
    }
  }
}

拿到 ref 后执行点击，然后再拍一次快照确认界面确实变了：

agent-desktop click @s8f3k2p9:e8
agent-desktop snapshot --app Finder -i

理解 ref 的规则非常关键：

ref 属于某一次快照。格式是 @<快照ID>:e<序号>，只写 @e8 会被拒绝并返回 INVALID_ARGS。
界面变化后旧 ref 会失效，操作会返回 STALE_REF，此时重新快照、使用新 ref 即可。
多窗口时会返回 AMBIGUOUS_TARGET，错误详情里会列出候选窗口 ID，用 --window-id 指定即可。
只有可交互元素才有 ref，纯文本、无意义的容器没有。

第四步：复杂应用用「骨架 + 下钻」

Slack、VS Code 这类 Electron 应用元素成百上千，一次全量快照又长又费 token。官方建议先拿浅层骨架，再只展开要操作的区域：

# 1. 浅层地图，被截断的分支会显示 children_count
agent-desktop snapshot --skeleton --app "Slack" -i --compact
# 2. 只下钻某个区域
agent-desktop snapshot --root @s8f3k2p9:e2 -i --compact
# 3. 操作并重新读取同一区域验证
agent-desktop click @s8f3k2p9:e18
agent-desktop snapshot --root @s8f3k2p9:e2 -i --compact

如果你已经知道按钮的角色和名称，可以跳过地图直接查找：

agent-desktop find --app "App" --role button --name "OK" --exact

第五步：常用操作速查

填写表单：优先用 set-value，需要真实按键事件时再用 clear + type。

agent-desktop set-value @s8f3k2p9:e3 "My MacBook Pro"
agent-desktop type @s8f3k2p9:e2 "hello@example.com"

等待异步界面：不要用固定 sleep，用 wait 等具体信号：

agent-desktop wait --text "Download complete" --app "App" --timeout 30000
agent-desktop wait --window "Save As" --app "TextEdit"

复选框：check / uncheck 是幂等的，比 toggle 安全；操作前可用 is 读取状态。

agent-desktop is @s8f3k2p9:e6 --property checked
agent-desktop check @s8f3k2p9:e6

读取文本：

agent-desktop get @s8f3k2p9:e5 --property value

启动与关闭应用（macOS 用显示名称；Windows 需绝对路径或 System32 下的程序名如 calc.exe）：

agent-desktop launch "Calculator"
agent-desktop snapshot --app "Calculator" -i
agent-desktop close-app "Calculator"

第六步：接入你的 AI 智能体

agent-desktop 的二进制自带与版本匹配的使用说明，智能体可以自己读：

agent-desktop skills get desktop    # 核心循环、ref、验证与重试规则
agent-desktop skills get platform   # 当前操作系统的差异说明

最省事的接入方式有两种：

方式一：通过 skills.sh 安装技能（适用于支持 Skills 的智能体框架，如 Claude Code）：

npx skills add https://github.com/vercel-labs/agent-desktop --skill agent-desktop

方式二：在项目的 AGENTS.md 中加一段说明（Codex 等读取 AGENTS.md 的工具均适用）：

Use `agent-desktop` to see and operate desktop apps. Before the first use, run
`agent-desktop skills get desktop` and `agent-desktop skills get platform`, and follow them.

之后你就可以直接对智能体说：「打开计算器，算一下 128 乘以 37，把结果告诉我」，它会自己完成快照、找按钮、点击、读结果的整个循环。

自己写脚本调用

如果想用 Python 写自己的小工具，基于 README 中的 JSON 结构，可以这样递归列出所有可操作元素：

import json, subprocess

def ad(*args):
    out = subprocess.run(["agent-desktop", *args], capture_output=True, text=True).stdout
    return json.loads(out)

def walk(node, depth=0):
    if node.get("ref_id"):
        print("  " * depth, node.get("role"), node.get("name"), node["ref_id"])
    for child in node.get("children", []):
        walk(child, depth + 1)

res = ad("snapshot", "--app", "Finder", "-i")
if res["ok"]:
    walk(res["data"]["tree"])
else:
    print(res["error"])

常见坑与安全建议

不要盲目重试。动作结果里带有 disposition，只有 retry 为 safe（即 not_delivered，确定没送达）时才能重试；否则动作可能已经生效，重复执行会导致重复提交，toggle 甚至会把自己撤销。应先用 get、is 或新快照读取真实状态再决定。
不要用 --headed 去「补救」无头失败。全局 --headed 会使用真实鼠标键盘输入，只应在你明确允许物理输入（如拖拽、悬停）时使用。
PowerShell 用户必须给 ref 加引号，例如 '@s8f3k2p9:e8'，因为裸的 @token 在 PowerShell 里是 splatting 运算符。
弹窗要对「表面」快照。打开菜单、sheet、alert 后，用 --surface sheet 等参数快照，并且不要对 surface 使用 --skeleton。
Linux 环境差异大：Wayland 下指针输入和原生窗口控制受限，剪贴板需要 wl-clipboard；Ubuntu 22.04 存在已知兼容问题，建议用 24.04 及以上。
注意隐私：快照、截图、剪贴板内容和调试产物都可能包含你桌面上的私密信息，不要上传到公开日志或 issue 里。CLI 本身不依赖远程模型服务，但你接入的智能体会把这些内容发给模型服务商，请确认可以接受。

总结

agent-desktop 把「让 AI 操作电脑」从「看图猜坐标」变成了「读结构、按引用操作」，带来了更低的 token 消耗、更稳定的定位和可预期的错误处理。上手只需三步：npm install -g agent-desktop 安装、agent-desktop status 检查权限、按「snapshot → 操作 ref → 再 snapshot 验证」的循环使用；再通过 skills 或 AGENTS.md 接入你常用的智能体，就能把重复的桌面操作交给 AI。建议先在计算器、备忘录这类简单应用上练手，熟悉 ref 与错误码后再用于真实工作流。

agent-desktop 是什么，为什么最近这么火#

准备工作#

第一步：安装#

第二步：检查状态与权限#

第三步：核心循环——快照、ref、操作、验证#

第四步：复杂应用用「骨架 + 下钻」#

第五步：常用操作速查#

第六步：接入你的 AI 智能体#

自己写脚本调用#

常见坑与安全建议#

总结#

参考来源#