Vercel agent-desktop 怎么用？让 Claude Code、Codex、Cursor 操作桌面应用（安装、接入、实测与报错）

先说结论：agent-desktop 是 Vercel Labs 开源的命令行工具（Apache-2.0），让编程 Agent 能「看见」并操作电脑上的原生桌面应用。它读的是操作系统的无障碍树（accessibility tree），给每个按钮、输入框一个 ref，Agent 点 ref、再读一遍界面确认结果，而不是看截图猜像素坐标。

• 它不是 Agent，里面没有模型。 每条命令输出一段 JSON 就退出，「观察→操作→验证」的循环由你的 Claude Code、Codex 或 Cursor 来跑，所以三家都能用。
• 装法一行：npm install -g agent-desktop，再用 npx skills add 把官方 skill 装进项目，Claude Code、Codex、Cursor 会各自读到。
• 我们实测跑通了：用本站 Key，Claude Code 约 28.6 秒、Codex 约 35 秒，各自在桌面计算器上点按钮算出结果并读回，答案都对。
• 两个坑要先知道：有的应用（比如我们测的 GTK4 版 GNOME 计算器）不提供控件位置，ref 点击会报 bounds unavailable；Codex 默认沙箱下在 Linux 上连不上桌面的 D-Bus，会报 Operation not permitted。解法见文末报错一节。

创建 API Key，在 Claude Code、Codex、Cursor 里接入 agent-desktop →

agent-desktop 是什么，为什么这两天这么火

10 月 31 日早上（北京时间），Vercel 的 Chris Tate 在 X 上发布 agent-desktop，一句话介绍是「agent-browser, for your whole computer」：任何编程 Agent 都能用的 Computer Use，支持 macOS、Windows、Linux，在后台运行不抢你的鼠标，多个 Agent 还能同时操作。截至 11 月 1 日下午，这条帖子约 64 万次浏览、7700 多个赞、8700 多次收藏。作者 Lahfir 的发布帖列了几个卖点：用 Agent 给桌面应用做端到端测试、读无障碍树、只钻进窗口的一部分来省 token、多个 Agent 同时操作一个应用。

GitHub 仓库目前约 5000 star，10 月 30 日发了 v1.0.2，同时上线了官方文档。几个关键事实：

社区反馈里，据 @decildmc，他把 Mac 上的 Computer Use 方案从 cua-driver 换成了 agent-desktop，原因是后者只把能点的元素发给模型，点击直接触发按钮，鼠标不动。据 @o_kwasniewski，他周末用 agent-desktop 做了原生桌面应用的 e2e 测试 demo。据 X 话题汇总，有人演示 52 步操作时，用骨架加局部展开的方式把 token 从约 198k 降到约 31k。

和截图类 Computer Use 比，它的优点是 ref 稳定、动作可以安全重试（报错里会写明输入有没有送达），缺点是只对暴露了无障碍信息的应用有效。

第 1 步：安装 agent-desktop 并检查权限

npm install -g agent-desktop
agent-desktop version
agent-desktop status

status 返回的 supported_surfaces 不为空、accessibility 是 granted，就说明能用了。我们在 Linux 上看到的正常输出：

{"ok":true,"command":"status","data":{"permissions":{"accessibility":{"state":"granted"}},
 "platform":"linux","supported_surfaces":["window","sheet","alert","menu"],"version":"1.0.2"}}

各系统的权限：

• macOS：给启动 agent-desktop 的应用（终端、iTerm2、VS Code 或 Agent 的宿主应用）开「辅助功能」权限，运行 agent-desktop permissions --guide 会直接打开系统设置的对应页面。截图另需「屏幕录制」权限。详见 macOS 文档。
• Windows：不用授权，但以管理员身份运行的应用只能读不能操作，要从同样提权的终端运行。二进制没有签名，SmartScreen 或杀毒软件可能拦截。详见 Windows 文档。
• Linux：要在用户的图形会话里运行，并装好 at-spi2-core。详见 Linux 文档。

第 2 步：把 agent-desktop 接入 Claude Code、Codex、Cursor

agent-desktop 自带与版本匹配的说明书（agent-desktop skills get desktop 和 skills get platform），接入的意思就是让 Agent 在第一次用之前先读这两份。有两种办法，任选一种。

办法 A：用 skills 安装官方 skill（推荐）

# in your project root
npx skills add https://github.com/vercel-labs/agent-desktop --skill agent-desktop

# non-interactive, pick the clients explicitly
npx skills add https://github.com/vercel-labs/agent-desktop --skill agent-desktop \
  -a claude-code -a codex -a cursor -y

我们在项目里执行后，安装器的输出是：

✓ ./.agents/skills/agent-desktop
  universal: Codex, Cursor
  symlinked: Claude Code

也就是说，skill 文件放在项目的 .agents/skills/agent-desktop，Codex 和 Cursor 直接读这个目录，Claude Code 通过 .claude/skills/agent-desktop 的软链接读同一份。想对所有项目生效，加 -g 装到用户级目录。skills 的基本用法见《AI Agent 里怎么用 Skills》。

安装器同时会显示几家安全扫描的结果（我们这次看到 Gen 判 Safe、Socket 0 alerts、Snyk 判 Med Risk），并提醒 skill 以 Agent 的完整权限运行，装之前最好自己看一遍 SKILL.md。

办法 B：在 AGENTS.md / CLAUDE.md 里加两行

不想装 skill，就把官方给的这段话放进项目的 AGENTS.md（Codex、Cursor 读这个），Claude Code 放进 CLAUDE.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.

想让 Claude Code 和 Codex 共用一份说明，可以参考《Claude Code 和 Codex 共用一份 AGENTS.md》。

第 3 步：配置客户端用本站 Key

1. 在 aicodewith.ai 注册并登录，进入「密钥管理」创建一个 Key，复制完整字符串。
2. 按你用的客户端配置。

Claude Code：

export ANTHROPIC_BASE_URL="https://api.aicodewith.ai"
export ANTHROPIC_AUTH_TOKEN="你的 API Key"

想长期保存或在 Windows 上配置，看《Claude Code 如何接入第三方 API》，Cursor 里选用模型的方式也在这篇。

Codex：写在全局 ~/.codex/config.toml 里：

# ~/.codex/config.toml
model_provider = "aicodewith"
model = "gpt-6.1-sol"

[model_providers.aicodewith]
name = "aicodewith"
base_url = "https://api.aicodewith.ai/chatgpt/v1"
wire_api = "responses"
experimental_bearer_token = "你的 API Key"

更多字段见《Codex config.toml 配置详解》。

Cursor：按上面那篇配置好模型后，Cursor 的 Agent 会读项目里的 .agents/skills 和 AGENTS.md，用法和 Codex 一样。

第 4 步：让 Agent 跑「观察→操作→验证」

agent-desktop 的基本循环只有三步：snapshot 拿到带 ref 的控件树，对 ref 执行 click、type 等操作，再 snapshot 或 get 读一遍确认。ref 带着产生它的 snapshot id（如 @s2jrj9msmdpdlw:e46），界面变了要重新 snapshot 拿新 ref。

agent-desktop list-apps                                # app names agent-desktop can see
agent-desktop snapshot --app galculator -i --compact   # interactive elements, each with a ref
agent-desktop click @s2jrj9msmdpdlw:e46                # act on a ref from that snapshot
agent-desktop snapshot --app galculator -i --compact   # observe again to verify

# dense apps (Electron, IDEs): map a skeleton first, then drill into one region
agent-desktop snapshot --app "Visual Studio Code" --skeleton -i --compact
agent-desktop snapshot --root @sXXXX:e1 -i --compact

元素很多的应用（Electron 客户端、IDE），官方建议先用 --skeleton 拿一个浅层骨架，再用 --root 只展开要操作的那一块，这样 token 只跟你操作的区域有关，见骨架与局部展开文档。

平时你不用自己敲这些命令，直接对 Agent 说「用 agent-desktop 打开 XX 应用，做 YY，做完确认结果」即可。

实测：用本站 Key 让 Claude Code 和 Codex 操作计算器

测试日是 2026 年 11 月 1 日，环境是 Linux（Debian 13，X11 + xfwm4 窗口管理器），agent-desktop 1.0.2，目标应用是 GTK3 的 galculator 计算器。任务是：只能点按钮，不能输入算式，算完把结果从应用里读回来。两个客户端都只装了上面办法 B 的 CLAUDE.md / AGENTS.md。

Claude Code 2.1.316

claude -p "Use agent-desktop to operate the galculator app that is already open: calculate 12 × 34 by clicking its buttons, then read the result back (Edit > Copy Display Value, then agent-desktop clipboard-get). Reply with RESULT=<number>." \
  --model claude-sonnet-4-6 \
  --allowedTools "Bash(agent-desktop:*)"

Claude Code 实际执行的命令（节选）：

agent-desktop skills get desktop
agent-desktop skills get platform
agent-desktop snapshot --app "galculator" -i --compact
agent-desktop click @s2jrj9msmdpdlw:e40        # AC
agent-desktop click @s2jrj9msmdpdlw:e46        # 1  (then 2, *, 3, 4, =)
agent-desktop click @s2jrj9msmdpdlw:e6         # "Copy Display Value" -> ACTION_FAILED, menu not open
agent-desktop click @s2jrj9msmdpdlw:e4         # open the Edit menu
agent-desktop snapshot --surface menu --app "galculator" -i --compact
agent-desktop click @s1muxufwf6hxgz:e3         # Copy Display Value
agent-desktop clipboard-get                    # -> 408

可以看到它先按 CLAUDE.md 读了两份 skill，然后 snapshot、按 ref 依次点按钮。第一次直接点「Copy Display Value」失败了，因为菜单还没打开，报错如下；它随后打开 Edit 菜单、用 --surface menu 重新 snapshot，再点就成功了，最后用 clipboard-get 读到 408：

{"ok":false,"command":"click","error":{"code":"ACTION_FAILED",
 "message":"Target is not actionable: visible (live offscreen state is true)"}}

单次 click 在这台机器上约 0.07 秒，大部分时间花在模型思考上。

Codex 0.164.0

codex exec "Use agent-desktop to operate the galculator app that is already open: calculate 56 × 78 by clicking its buttons, then read the result back from the app. Reply with RESULT=<number>."

两条失败都是开头的 agent-desktop: command not found：我们为了测试把 agent-desktop 装在项目目录里而不是全局，Codex 用登录 shell 执行命令时 PATH 里没有它。Codex 自己找到了可执行文件的路径继续完成了任务。正式使用请用 npm install -g 全局安装。

一个没跑通的对照：GTK4 的 GNOME 计算器

我们最开始用的是 GNOME 计算器（GTK4）。agent-desktop 能列出全部按钮，但每次点击都报 bounds unavailable：这个应用在我们的 X11 环境里不提供控件的位置信息，agent-desktop 的可见性预检过不去，就拒绝点击（delivery: not_delivered，没有误点）。Claude Code 在这种情况下改去猜屏幕坐标、用 mouse-click --headed 一个个试，10 分钟还没完成，我们手动停掉了。键盘输入 agent-desktop press 在这个应用上是能用的。

经验：Agent 连续报 bounds unavailable 时，不要让它去猜坐标，换成键盘操作或换应用。 可以在提示词里直接写明「点击失败就用 press 发键盘」。

创建 API Key，在自己的电脑上试一遍 →

常见报错和处理

agent-desktop 的报错都是 JSON，按 error.code 和 disposition.retry 判断即可：retry 是 safe 说明输入没送达，可以重试；是 unsafe 或 unknown 时先观察再决定，避免重复提交。完整列表见官方报错文档。下面是我们实际遇到的。

status 显示 accessibility denied、supported_surfaces 为空（Linux）

{"ok":true,"command":"status","data":{"permissions":{"accessibility":{"state":"denied",
 "suggestion":"AT-SPI is not installed or not visible to this process. Install the at-spi2-core package, then retry."}},
 "supported_surfaces":[]}}

没装 AT-SPI 或当前进程看不到无障碍总线。装 at-spi2-core，并确认在图形会话里运行（SSH 进去、没有会话变量的 shell 看不到任何应用）。Flatpak、snap 里的应用另需开放对应接口。

list-apps 报 native window type could not be proven

{"ok":false,"command":"list-apps","error":{"code":"ACTION_NOT_SUPPORTED",
 "message":"The native window type of accessibility frame owned by pid 3857714 could not be proven"}}

我们在没有窗口管理器的虚拟显示上遇到这个错，启动一个窗口管理器（我们用的是 xfwm4）后 list-apps 立刻正常。普通桌面系统一般不会遇到。

click 报 TIMEOUT，原因是 bounds unavailable

{"ok":false,"command":"click","error":{"code":"TIMEOUT",
 "message":"Target did not become actionable within the wait budget",
 "details":{"kind":"actionability_timeout","last_report":{"report":{"checks":[
   {"check":"visible","reason":"bounds unavailable","status":"unknown"}]}}},
 "disposition":{"delivery":"not_delivered","retry":"safe"}}}

应用没提供控件位置。加 --headed 也没用。改用 press 发键盘，或者换一个无障碍支持更完整的应用。见上面的 GTK4 对照。

click 报 ACTION_FAILED：visible (live offscreen state is true)

目标在当前界面不可见，比如菜单项所在的菜单没展开。先点开菜单，再用 snapshot --surface menu 拿新 ref。

Codex 里报 INTERNAL：Operation not permitted

{"ok":false,"command":"list-apps","error":{"code":"INTERNAL",
 "message":"The accessibility bus returned an unexpected error",
 "platform_detail":"Failed to connect to address `unix:path=/tmp/dbus-...`: Operation not permitted (os error 1)"}}

我们在 Linux 上用 codex exec -s workspace-write 跑时遇到：Codex 的沙箱挡住了到桌面 D-Bus 的连接，agent-desktop 读不到无障碍总线。处理办法是让 agent-desktop 命令在沙箱外执行：交互模式下在 Codex 请求时批准这条命令，或者只在专门的测试机、虚拟机里用 --dangerously-bypass-approvals-and-sandbox。我们的实测是在一台单独的测试桌面上用后者跑的。

command not found

/bin/bash: line 1: agent-desktop: command not found

agent-desktop 不在 Agent 执行命令时的 PATH 里，用 npm install -g agent-desktop 全局安装，或在 AGENTS.md 里写明完整路径。

Windows PowerShell 里 ref 不生效

PowerShell 会把裸的 @xxx 当成 splatting 运算符，ref 要加单引号：

agent-desktop click '@s8f3k2p9:e8'

安全提醒

• snapshot 里有你屏幕上的内容。 据 @mikawuf，snapshot 会包含屏幕上显示的信息，别把它放进公开日志。打开了密码管理器、聊天软件时，最好先关掉再让 Agent 操作。
• 给 Agent 的权限按需开。 Claude Code 可以用 --allowedTools "Bash(agent-desktop:*)" 只放行 agent-desktop；Codex 关掉沙箱只在隔离环境里做。
• skill 和 AGENTS.md 都是 Agent 会执行的指令，来源要可信，参见《AGENTS.md 被劫持风险》。
• 想在云端跑，据作者 Lahfir，agent-desktop 也能在 Vercel Sandbox 里起一个 Linux 桌面运行。

常见问题

agent-desktop 和 agent-browser 有什么区别

agent-browser 操作网页，agent-desktop 操作原生桌面应用。Chromium、Electron 应用里的网页内容，agent-desktop 可以用 launch "App" --cdp 打开 DevTools 端口交给 agent-browser 处理。

需要用支持 Computer Use 的特定模型吗

不需要。agent-desktop 只输出文字（JSON），任何能执行 shell 命令的编程 Agent 都能用，我们实测用的是 Claude Sonnet 4.6 和 GPT-6.1 Sol。

能用来给自己的桌面应用写 e2e 测试吗

可以，这是官方列出的主要用途之一。验证代码改动在真实应用里是否生效，也可以参考《用 verification skill 驱动真应用验收代码》。

相关阅读

• Claude Code 如何接入第三方 API
• Codex config.toml 配置详解
• AI Agent 里怎么用 Skills
• Claude Code 和 Codex 共用一份 AGENTS.md
• 用 verification skill 驱动真应用验收代码

创建 API Key，开始用 Claude Code、Codex、Cursor →