小白一键部署｜agent-desktop：给 AI Agent 装上桌面眼睛和手（Debian 亲测）

正宗咸豆花

141人浏览 · 2026-11-03 11:37:15

正宗咸豆花 · 2026-11-03 11:37:15 发布

实机环境：Debian 13（glibc 2.41）x86_64 · 验证时间：2026-11-03（Asia/Shanghai）
实机版本：agent-desktop 1.0.2（npm 全局包）· 命令路径：~/.local/bin/agent-desktop
说明：本文命令与报错来自本机真实安装；已用 Thunar 完成「启动 → snapshot → click → 再观察」。Chrome 在本机即使加了无障碍参数也上不了 AT-SPI 总线，文中如实标明。
中文现状：网上已有接入 Claude Code / Codex / Cursor 的长文（例如 AI Code With），以及评测向介绍；系统化的「Debian/小白装机 + 真实报错对照」仍少，本文补这一块。

1. 这是啥 / 适合谁

agent-desktop 是 Vercel Labs 开源的 Computer Use CLI（GitHub 星标已破万）。它不靠截图+像素瞎点，而是通过操作系统的**无障碍树（Accessibility Tree）**读取桌面控件，并返回带 ref 的 JSON；Agent 对某个 ref 执行 click / type 等操作，再 snapshot 验证。

一句话：让 AI Agent 像人一样看见、点到桌面 App 里的按钮和输入框。

适合谁：

想给 Claude Code、Codex、Cursor 等 Agent 接上「操作本机桌面」能力的人
需要可脚本化、可机器读的桌面自动化（输出是统一 JSON 信封）
不想搞一套重型 RPA / 图像匹配方案的开发者、折腾党

不适合谁：

完全没有图形桌面会话的纯 SSH/TTY（装得上命令，但看不见任何 App）
期望「装完就有一个带聊天窗的 GUI 产品」的人——这是 CLI 工具，不是聊天客户端
只想点网页：那更适合浏览器自动化；本工具主战场是桌面原生应用

官网 / 文档入口：https://agent-browser.dev/desktop
GitHub：https://github.com/vercel-labs/agent-desktop
安装说明：docs/install.md

2. 你将得到什么

按本文做完，你将得到：

项目	结果
命令行工具	`agent-desktop`（本机验证：`1.0.2`）
默认安装位置	npm 全局：`~/.local/bin/agent-desktop` → 原生 ELF（约 7MB 的 linux-x64 二进制）
状态目录	`~/.agent-desktop`（权限需私有，见踩坑）
观察能力	`snapshot` 返回带 `@snapshot_id:eN` 的控件树
操作能力	`click` / `type` / `clipboard-*` / `launch` / `close-app` 等 50+ 命令

本机已验证：

✅ npm install -g agent-desktop --allow-scripts 成功
✅ agent-desktop version → 1.0.2 / linux x86_64
⚠️ 未装 at-spi2-core 时：status 里 accessibility=denied，list-apps 报 PLATFORM_NOT_SUPPORTED
✅ 装好 AT-SPI 后：accessibility=granted，supported_surfaces 有 window/sheet/alert/menu
✅ launch Thunar → snapshot -i --compact（81 个 ref）→ click Home → 窗口标题从工作区变到家目录
✅ clipboard-set / clipboard-get 读写文本成功
⚠️ google-chrome 进程能启动，但本机始终不上无障碍总线（见踩坑）

3. 环境要求

系统

平台	要求（官方 + 本机对照）
Linux	官方主测 Ubuntu 24.04+ / GNOME；glibc ≥ 2.35。本机 Debian 13、glibc 2.41，满足。需用户的图形会话 + `at-spi2-core`
macOS	需辅助功能（Accessibility）；截图另需屏幕录制
Windows	同完整性级别一般无需额外授权；浏览器下载的未签名包可能被 SmartScreen 拦（npm 安装路径通常不会）

Linux 额外说明（官方）：

必须在「目标桌面」同一用户的图形会话里跑（带上 DISPLAY / WAYLAND_DISPLAY、DBUS_SESSION_BUS_ADDRESS、XDG_RUNTIME_DIR）
X11 / Wayland 都能观察与语义操作；物理鼠标类命令多半要 X11 + --headed
Wayland 剪贴板需要 wl-clipboard
Ubuntu 22.04 的 ATK 桥在 Action.GetActions 上会 abort，不推荐

软件依赖（Linux）

Node.js + npm（用来装官方 npm 包；本机 Node v22.21.0 / npm 10.9.4）
at-spi2-core（无障碍总线；本机缺它时几乎什么都干不了）
可选：有一个「能暴露无障碍树」的 GUI App（Thunar、部分 GTK 应用较友好；Chrome/Chromium 要额外参数）

4. 一键安装

4.1 Linux（主路径，本机实装）

步骤 A：先装无障碍总线（很多人漏这一步）

Debian / Ubuntu：

sudo apt-get update
sudo apt-get install -y at-spi2-core

本机坑：默认 deb.debian.org 一度 500，apt 装不上。改用镜像直接下 .deb 也能装（并补依赖 gsettings-desktop-schemas）：

# 示例：中科大镜像（版本号按你的发行版改）
curl -fsSL -o at-spi2-core.deb \
  https://mirrors.ustc.edu.cn/debian/pool/main/a/at-spi2-core/at-spi2-core_2.56.2-1%2Bdeb13u2_amd64.deb
curl -fsSL -o gsettings-desktop-schemas.deb \
  https://mirrors.ustc.edu.cn/debian/pool/main/g/gsettings-desktop-schemas/gsettings-desktop-schemas_48.0-1_all.deb
sudo dpkg -i gsettings-desktop-schemas.deb at-spi2-core.deb
# 若还有依赖问题：sudo apt-get -f install

步骤 B：npm 全局安装（官方推荐）

npm install -g agent-desktop --allow-scripts
agent-desktop version

本机输出（JSON 信封）：

{"version":"2.5","ok":true,"command":"version","data":{"os":"linux","target":"x86_64","version":"1.0.2"}}

说明：

--allow-scripts：让 postinstall 把 Node 启动器换成原生二进制（官方说每次调用大约从 ~146ms 降到 ~21ms）。npm 12 默认会拦 install scripts，更要加。
若提示找不到命令，把 npm 全局 bin 加进 PATH（本机是 ~/.local/bin）：

export PATH="$HOME/.local/bin:$PATH"
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
hash -r
command -v agent-desktop

步骤 C：健康检查（必做）

agent-desktop status
agent-desktop permissions

健康时大致长这样（本机装好 AT-SPI 之后）：

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

记住官方第一句忠告：supported_surfaces 为空，通常不是「桌面没有窗口」，而是无障碍总线没应答。

可选：不解压 JS，直接下 Release 原生包

到 GitHub Releases 下载对应 OS/架构的归档，把可执行文件和平台 helper（Linux 还要 agent-desktop-linux-clipboard-owner）放在同一目录并加入 PATH。

Homebrew / Scoop 官方包「正在提交」，默认源里暂时还没有。

4.2 macOS（顺带）

npm install -g agent-desktop --allow-scripts
agent-desktop permissions --guide
agent-desktop version

按引导给「终端 / iTerm / VS Code / Agent 宿主」开辅助功能；截图再开屏幕录制。

4.3 Windows（顺带）

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

同完整性级别一般不用额外授权。管理员进程只能被同级提权的 Agent 操作。

5. 实机踩坑与解决

以下均为本机真实遇到，或对照官方文档复现的坑。

坑 1：装完命令能跑，但看不见任何 App（必踩）

现象（本机原文，未装 at-spi2-core 时）：

agent-desktop status：

"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": []

agent-desktop list-apps：

{
  "ok": false,
  "error": {
    "code": "PLATFORM_NOT_SUPPORTED",
    "message": "The AT-SPI accessibility bus is not available in this session",
    "platform_detail": "org.freedesktop.DBus.Error.ServiceUnknown: The name org.a11y.Bus was not provided by any .service files"
  }
}

解决： 安装 at-spi2-core（见第 4 节），然后在同一图形会话里再跑 agent-desktop status。
本机装好后立刻变成 accessibility=granted，list-apps 恢复正常（当时桌面没有带 a11y 的 App 时会返回空数组，这是正常的）。

坑 2：`apt install at-spi2-core` 失败（源 500 / 无候选）

本机：

E: Failed to fetch http://deb.debian.org/debian/dists/trixie/InRelease  500  Internal Server Error
E: Package 'at-spi2-core' has no installation candidate

只装了 at-spi2-common / libatspi 还不够——缺的是提供 org.a11y.Bus 服务的 core 包。

解决： 换镜像 apt update，或直接下载匹配版本的 .deb + 依赖 gsettings-desktop-schemas 后 dpkg -i（本机已验证此路径）。

坑 3：只在项目里 `npm install`（没加 `-g`），终端找不到命令

npm install agent-desktop   # 没有 -g
agent-desktop version       # 可能 command not found

包会在 ./node_modules/.bin/agent-desktop。解决任选：

npx agent-desktop version
# 或
./node_modules/.bin/agent-desktop version
# 或改回全局
npm install -g agent-desktop --allow-scripts

坑 4：Chrome / Chromium 启动了，但 `list-apps` 里没有

本机两次启动：

agent-desktop launch google-chrome --activate \
  --arg=--no-sandbox \
  --arg=--user-data-dir=/tmp/ad-chrome-test

返回类似：

"suggestion": "The process started but is not on the accessibility bus yet. ... Run 'list-apps' to see whether it appears."

随后 list-apps 仍是空的，snapshot --app google-chrome → APP_NOT_FOUND。

即便加上官方常提的：

--arg=--force-renderer-accessibility

本机 Chrome 依然未出现在 AT-SPI 上（可能与本环境的 Chrome 打包/沙箱/会话有关）。

小白建议：

先用 Thunar / 计算器 / 文本编辑器 等 GTK 应用验证整条链路
再专啃 Chromium：官方 Linux skill 写明 Chromium/Qt 常需额外启动参数；Electron 一般不需，但缺 setuid sandbox 时可能要 --no-sandbox
以 list-apps 里出现的名字为准做 --app，不要猜

坑 5：ref 写成裸的 `@e8` —— 直接 `INVALID_ARGS`

agent-desktop click '@e8'

本机报错：

{
  "ok": false,
  "error": {
    "code": "INVALID_ARGS",
    "message": "Invalid ref_id '@e8': expected @<snapshot_id>:e<N>",
    "suggestion": "Use the snapshot-qualified ref that snapshot prints, for example @s8f3k2p9:e1. A bare @eN ref is not accepted."
  }
}

规则： ref 绑定某次 snapshot，必须带 snapshot id，例如 @s1xdaeklcao8xz:e5。界面一变就要重新 snapshot，旧 ref 可能 STALE_REF。

坑 6：SSH / 另一用户会话里跑 —— 永远空桌面

官方明确：TTY、没带会话环境变量的 SSH、容器里没总线、别人的桌面会话，都看不见 App。
请在本机图形会话的终端里跑，或把那套 DISPLAY / DBUS_SESSION_BUS_ADDRESS / XDG_RUNTIME_DIR 正确传过去（进阶玩法，小白先本机终端）。

坑 7：`~/.agent-desktop` 权限太开

官方：目录若 group/world 可写，snapshot 可能直接 INTERNAL。本机自动创建的是 700。若你改过：

chmod 700 ~/.agent-desktop

6. 装完怎么用（最小闭环）

核心循环只有三步：观察 → 操作 → 再观察。

6.1 启动一个好抓的 App（本机用 Thunar）

agent-desktop launch Thunar --activate
agent-desktop list-apps
agent-desktop list-windows --app Thunar

本机 list-apps：

{"apps":[{"name":"thunar","pid":526990,"presentation":"foreground"}]}

6.2 拍一棵控件树

agent-desktop snapshot --app Thunar -i --compact

本机：ref_count: 81，例如工具栏 Home 按钮：

name: "Home"
ref_id: "@s1xdaeklcao8xz:e5"
role: "button"

密集界面（IDE、Slack 等）可先骨架再下钻：

agent-desktop snapshot --app "Visual Studio Code" --skeleton -i --compact
agent-desktop snapshot --root @sXXXX:e3 -i --compact

6.3 点一下，再确认

agent-desktop click '@s1xdaeklcao8xz:e5'   # 换成你 snapshot 里的完整 ref
agent-desktop list-windows --app Thunar

本机点击 Home 后，窗口标题从 xiaobai-agent-desktop - Thunar 变成 box - Thunar（进了家目录）——闭环成立。

6.4 剪贴板（顺手）

agent-desktop clipboard-set "hello-agent-desktop"
agent-desktop clipboard-get
# 本机返回："text":"hello-agent-desktop"

6.5 给 AI Agent 挂说明书（强烈建议）

二进制自带与版本匹配的 skill：

agent-desktop skills get desktop
agent-desktop skills get platform

装进常见 Agent 宿主：

npx skills add https://github.com/vercel-labs/agent-desktop --skill agent-desktop
# 或非交互指定客户端：
# npx skills add https://github.com/vercel-labs/agent-desktop --skill agent-desktop \
#   -a claude-code -a codex -a cursor -y

或在项目 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.

6.6 关掉 App

agent-desktop close-app Thunar

本机返回 delivered_verified / process_instance_exited。

7. 卸载

npm 全局安装的卸载：

npm uninstall -g agent-desktop

可选清理状态目录（会丢掉本地 snapshot 缓存等）：

rm -rf ~/.agent-desktop

若你是用 Release 归档解压的，删掉那两个可执行文件（CLI + clipboard helper）即可。

8. 原文与延伸阅读

仓库 README：https://github.com/vercel-labs/agent-desktop/blob/main/README.md
安装与权限：https://github.com/vercel-labs/agent-desktop/blob/main/docs/install.md
JSON 信封 / 错误码：https://github.com/vercel-labs/agent-desktop/blob/main/docs/json-output.md
FAQ（含隐私：snapshot/剪贴板/截图可能含私人桌面内容，别往公网日志丢）：https://github.com/vercel-labs/agent-desktop/blob/main/docs/faq.md
已有中文接入向教程（偏 Agent 宿主，不是本稿这种装机踩坑实录）：agent-desktop 教程：Claude Code、Codex、Cursor 接入桌面 Computer Use

9. 一句话总结

npm i -g agent-desktop 只是开始；Linux 上先让 at-spi2-core 活着，再用 Thunar 之类跑通「snapshot → click → snapshot」，你才算真正装上了。 Chrome 不上总线、裸 @e8、SSH 空桌面——这三坑小白几乎都会撞，对照本文就能过。

北京朝阳AI社区

更多推荐

Spring AI Alibaba 集成 MCP：工具异常场景抑制大模型幻觉落地实践

随着 AI Agent 开发热度上升，MCP（Model Context Protocol）正在成为 Agent 对接外部能力的标准方案。MCP Host（宿主）：AI 应用本体，本文为 SpringBoot + Spring AI Alibaba 应用，是整个交互流程的控制方，掌握 MCP 连接真实状态；MCP Client：内嵌在 Host 内部，基于 JSON-RPC 协议和远端 MCP S