作者注：本文讲解 agent-desktop 的安装、授权、snapshot/click 闭环和 MCP 接入，并说明怎样给“循环里的大脑”配置模型与 Base URL。
让编程 Agent 或自制 Agent 去点 Finder、填系统设置、操作一个原生客户端，过去基本只能靠截图、视觉模型和像素坐标，链路长，也容易点错。Vercel Labs 开源的 agent-desktop 换了一条路：它读取操作系统的无障碍树（Accessibility Tree），把桌面界面变成带 ref 的 JSON，Agent 按 ref 执行点击和输入。这就是它说的“无截图 computer use”。
这不是又一个自带 AI 的桌面机器人。 开始之前先说清三件事：
- agent-desktop 不含模型：二进制里没有嵌入 LLM，没有 GUI，也没有交互提示。每条命令打印一个 JSON envelope 后就退出。
- 循环在调用方：观察、行动、校验（observe-act-verify）的循环由调用它的 Agent 负责，比如 Claude Code、OpenCode 或你自己写的脚本。
- 不做网页：网页自动化交给同门项目 agent-browser，agent-desktop 只管原生桌面应用。
既然工具本身不带模型，“大脑”就得由调用方 Agent 提供，这一步需要 API Key 和 Token。你可以把调用方 Agent 的 Base URL 指向 API易 apiyi.com，用一个 Key 调用 claude-opus-5-5、claude-sonnet-5-5 等模型。
核心价值：读完本文，你能把 agent-desktop 装好、授权、跑通 snapshot → click → 再 snapshot 的最小闭环，再通过 MCP 接进自己的 Agent，并配好模型侧的 Base URL 和型号。
agent-desktop 核心要点
先用一张表看清 agent-desktop 的定位。下表信息来自官方 README、FAQ 和文档站，观察日期为 2026-11-13。
| 要点 | 说明 | 对开发者的价值 |
|---|---|---|
| 数据来源 | 读取 OS 无障碍树：macOS 用 AX API，Windows 用 UI Automation，Linux 用 AT-SPI | 不依赖截图和像素匹配，结构化程度高 |
| 输出格式 | 每条命令输出一个 JSON envelope 后退出，元素带 ref | 方便 LLM 解析，也方便脚本做断言 |
| 默认模式 | headless，走无障碍 API，不移动指针、不抢焦点 | 可以在后台操作，不打断用户 |
| 是否含模型 | 不含，循环由调用方负责 | 模型自选，成本和效果由调用方控制 |
| 接入方式 | CLI、MCP（stdio）、skills、C 库 FFI | 能接进 Claude Code、OpenCode、自制 Agent |
截至 2026-11-13，GitHub 仓库 vercel-labs/agent-desktop 约 22,900 star，采用 Apache-2.0 协议，npm 包名就是 agent-desktop，当天仍有新提交。命令总数约 61 个名字、57 个可运行，分为 Observe、Act on ref、Keyboard mouse、Apps windows、Notifications、Clipboard、Wait、Sessions、Sandboxes、System 等组。
agent-desktop 如何工作：无障碍树与 ref
agent-desktop 的核心概念是 snapshot 和 ref。执行 snapshot 时，它会遍历目标应用的无障碍树，把按钮、文本框、菜单项等元素输出为 JSON，每个元素分配一个 ref。完整 ref 的形式类似 @s8f3k2p9:e8：前半段是这次 snapshot 的标识，后半段是元素编号。
ref 只属于产生它的那一次 snapshot。如果只传裸的 @e8，会得到 INVALID_ARGS。界面变化后，旧 ref 可能失效，返回 STALE_REF 或 AMBIGUOUS_TARGET，这时需要重新 snapshot。这个设计逼着调用方每次行动后都重新观察，也就是 observe-act-verify 中“校验”这一步。
上图中的“Agent 选 ref”这一步是模型在做决策。agent-desktop 负责把界面结构化地交出去，读懂 JSON、决定点哪个元素，都是调用方模型的工作。
agent-desktop 与 agent-browser 如何分工
两个项目同属 Vercel Labs，文档站也放在一起，但职责边界很清楚：
| 对比项 | agent-desktop | agent-browser |
|---|---|---|
| 目标 | 原生桌面应用（Finder、系统设置、原生客户端） | 网页与浏览器页面 |
| 观察方式 | OS 无障碍树 | 浏览器侧页面结构 |
| Chromium / Electron 应用 | 可通过 DevTools 端口交给 agent-browser | 适合接管这类应用的网页内容 |
| 是否含模型 | 不含 | 同样作为工具供 Agent 调用 |
| 典型命令 | snapshot、click、clipboard-set |
面向页面的导航与交互 |
一个比较实用的分工是：原生窗口、菜单栏、Dock、通知交给 agent-desktop；遇到网页或 Electron 应用里的 Web 内容，就通过 DevTools 端口切到 agent-browser。
agent-desktop 版本节点与事实来源
agent-desktop 迭代很快，几个关键版本都带来了行为变化，部分属于破坏性变更。下表按事实来源标注，“未知”表示官方资料暂未明确。
| 版本 / 日期 | 主要变化 | 来源 |
|---|---|---|
| 1.0.0（2026-10-27） | Linux 支持正式进入 1.0 | 官方 Changelog |
| 1.1.0（2026-11-02） | envelope 升级到 2.6；支持 macOS Dock 与 menu-bar-extras；身份证明相关破坏性变更 | 官方 Changelog |
| 1.2.0（2026-11-05） | 新增 MCP（agent-desktop mcp）；type / set-value / clipboard-set 支持 --stdin |
官方 Changelog |
| 1.3.0（2026-11-11） | 新增 agent-desktop sandbox 和 macOS sandbox provider；menu/menubar snapshot 不再带 data.window（破坏性） |
官方 Changelog |
| Windows / Linux 沙箱 | 是否会提供对应 provider | 未知 |
agent-desktop 快速上手
下面按“安装 → 授权 → 最小闭环 → MCP 接入”的顺序走一遍。
第 1 步：安装 agent-desktop
平台要求：macOS 13+；Windows 10 1809+（x64 / ARM64）；Linux 为 Ubuntu 24.04+（x86_64 / aarch64），X11 或 Wayland 都可以。安装方式任选一种：
- npm（需要 Node 18+，包内带各平台原生二进制）：
npm install -g agent-desktop - Homebrew（macOS / Linux，已进入 homebrew-core）：
brew install agent-desktop - 原生归档：从 GitHub Releases 下载，helper 需要放在可执行文件旁边
装好后先运行 agent-desktop status，确认二进制和当前平台环境正常。
第 2 步：agent-desktop 权限授权
macOS 上需要给终端或宿主进程开启“辅助功能”权限，否则读不到无障碍树。官方提供了引导命令：
agent-desktop permissions --guide：按提示在系统设置中完成辅助功能授权- 授权完成后再运行一次
agent-desktop status复核
需要注意，授权对象是“运行 agent-desktop 的那个进程”。如果你通过 Claude Code、某个 IDE 或 MCP 客户端间接调用它，可能需要给对应的宿主应用授权。
第 3 步：跑通 snapshot → click → snapshot 最小闭环
以 Finder 为例，三条命令就能构成一次完整的观察-行动-校验：
agent-desktop snapshot --app Finder -i：获取 Finder 的无障碍树，-i用于聚焦可交互元素，输出 JSON 中带有@s8f3k2p9:e8这类 refagent-desktop click @s8f3k2p9:e8：点击上一次 snapshot 中的目标元素，必须写完整 refagent-desktop snapshot --app Finder -i：再次观察，校验界面是否按预期变化
如果第 2 步报 STALE_REF 或 AMBIGUOUS_TARGET，说明界面已经变化，回到第 1 步重新 snapshot 即可。遇到需要真实指针或键盘事件的应用，可以加全局参数 --headed，切到物理输入模式。
对于元素很多的界面，一次性完整 snapshot 会很长，也浪费模型 Token。可以分两层获取：
agent-desktop snapshot --skeleton --app Finder：先拿骨架，看清大致区域agent-desktop snapshot --app Finder --root @<骨架中的 ref>：再从某个子树下钻
这个技巧能明显缩短送进模型的上下文。对调用方来说，上下文越短，按 Token 计费的成本越低。
第 4 步：通过 MCP 和 skills 接入 Agent
从 1.2.0 开始，agent-desktop 内置 MCP 服务，走 stdio，暴露 desktop_snapshot、desktop_click 等工具。不同客户端的配置格式略有差异，下面是示意：
- 启动命令：
agent-desktop mcp - 通用 JSON 配置示意：
{"mcpServers": {"agent-desktop": {"command": "agent-desktop", "args": ["mcp"]}}} - Claude Code 示意：
claude mcp add agent-desktop -- agent-desktop mcp
如果你的 Agent 支持 skills，还可以直接加载官方的使用说明，让模型知道该怎么调用：
agent-desktop skills get desktop、agent-desktop skills get platform：输出技能说明npx skills add https://github.com/vercel-labs/agent-desktop --skill agent-desktop：通过 skills.sh 安装
需要同进程调用的场景，也可以使用 C 库 libagent_desktop_ffi。
可选：1.3.0 的 agent-desktop sandbox
1.3.0 新增了 agent-desktop sandbox 子命令和 macOS sandbox provider，可以在本机签名的 macOS 虚拟机里运行自动化，把 Agent 的操作和你的真实桌面隔离开。这不是必需步骤，最小闭环不依赖它。如果你担心 Agent 误操作真实文件，或者想跑大量探索性任务，可以优先考虑。
🚀 快速开始：MCP 配好后，调用方 Agent 还需要一个能用的模型。官方推荐的做法是在 API易 apiyi.com 控制台创建令牌，再把 Agent 的 Base URL 指过去，一个 Key 就能在 Claude、GPT、Gemini 等模型之间切换对比。
给 agent-desktop 循环接上模型“大脑”
agent-desktop 只负责“眼睛和手”，决定点哪个 ref、判断任务是否完成的“大脑”在调用方。这个环节有两个关键配置：Base URL 和模型型号。
Base URL：带不带 /v1 要分清
调用方 Agent 通常走两类协议，Base URL 写法不同，写错是 404 最常见的原因：
- OpenAI 兼容协议（大多数自制脚本、OpenCode 的 OpenAI 兼容 provider）：
https://api.apiyi.com/v1，带/v1 - Anthropic 原生协议（Claude Code 等直接走 messages 接口的客户端）：
https://api.apiyi.com，不带/v1
以 Claude Code 为例，可以用环境变量示意配置：
export ANTHROPIC_BASE_URL=https://api.apiyi.comexport ANTHROPIC_AUTH_TOKEN=你的令牌
自制 Python 或 Node 脚本使用 OpenAI SDK 时，把 base_url 设为 https://api.apiyi.com/v1，model 填 claude-opus-5-5 即可。令牌在 api.apiyi.com/token 创建，详细配置可以参考 docs.apiyi.com/faq/base-url-config.md。
自制 Agent 的循环怎么写
不想依赖现成 Agent 时，自己写一个循环也不复杂。核心步骤如下：
- 运行
agent-desktop snapshot --app 目标应用 -i，读取 stdout 中的 JSON envelope - 把任务目标和 snapshot JSON 一起发给模型，要求它只返回下一步动作和完整 ref
- 执行模型给出的命令，例如
agent-desktop click @sxxxx:eN - 再次 snapshot，把新结果交给模型判断是否完成；收到
STALE_REF时直接重新观察 - 设置最大步数和人工确认点，避免死循环或越权操作
这里的第 2 步和第 4 步都会消耗 Token。前面提到的 --skeleton 加 --root 下钻方式，在这里会直接影响成本。
选型：claude-opus-5-5 与 claude-sonnet-5-5
两款 Claude 型号都已在 API易 型号总表上架，同时支持 chat 和 messages 端点。下表价格数据日期为 2026-11-13，单位为每 1M Tokens，型号与价格以平台型号列表为准。
| 型号 | 输入 | 输出 | 缓存读 | 适合的 agent-desktop 场景 | 可用平台 |
|---|---|---|---|---|---|
claude-opus-5-5 |
$4 | $20 | $0.2 | 多步骤、界面复杂、需要较强规划的任务 | API易 apiyi.com |
claude-sonnet-5-5 |
$2 | $10 | $0.1 | 步骤明确、重复性较强的日常操作 | API易 apiyi.com |
一个可行的思路是先用 claude-opus-5-5 跑通流程，确定提示词和步骤后，再评估能否把稳定环节切到 claude-sonnet-5-5。snapshot JSON 中会有大量重复的系统提示和工具说明，缓存读价格明显低于输入价格，所以开启提示缓存对长循环比较友好。最新价目请以 docs.apiyi.com/models 为准。
agent-desktop 排错：权限问题还是模型问题
agent-desktop 和模型属于两条独立链路，报错时先判断是哪一侧出了问题，可以少走很多弯路：
| 现象 | 所在链路 | 可能原因 | 处理方式 |
|---|---|---|---|
| snapshot 为空或读不到应用 | 工具侧 | 未授予辅助功能权限，或应用本身没有暴露无障碍树 | 运行 agent-desktop permissions --guide，检查宿主进程授权 |
INVALID_ARGS |
工具侧 | 只写了裸 ref，例如 @e8 |
使用完整 ref，例如 @s8f3k2p9:e8 |
STALE_REF / AMBIGUOUS_TARGET |
工具侧 | 界面已变化，ref 失效 | 重新 snapshot |
| 模型请求 401 | 模型侧 | 令牌错误、过期或环境变量没有生效 | 到 api.apiyi.com/token 核对令牌并重新导出 |
| 模型请求 404 | 模型侧 | Base URL 的 /v1 写错，或型号名拼写错误 |
OpenAI 兼容带 /v1，Anthropic 原生不带；型号对照总表 |
简单判断方法：只要 agent-desktop 命令能在终端里单独跑出 JSON，工具侧就没有问题，剩下的报错基本都在模型侧。模型侧的 401/404 可以对照 API易 apiyi.com 文档中心的 Base URL 配置说明逐项检查。
agent-desktop 权限与隐私风险
这一节讨论的是桌面自动化本身的风险，和账号无关，但开始使用前值得认真看一遍。
辅助功能授权的分量。 在 macOS 上开启辅助功能，意味着被授权的进程可以读取并操作其他应用的界面。授权给终端或某个 Agent 宿主后，这个进程里运行的任何程序都可能获得同等能力。建议只给必要的宿主授权，用完可以在系统设置中关闭。
snapshot、剪贴板和截图都可能包含隐私。 官方明确提示，snapshot、剪贴板内容、截图、通知和 debug HTML 都可能带有桌面上的敏感信息，比如聊天内容、邮件标题、文件名和密码管理器界面。这些数据会被调用方送进模型，所以不要公开上传调试日志，也不要在 issue 中直接贴完整 snapshot。
可选 helper 会联网。 原生 CLI 本身不要求远端模型服务，但如果启用了可选的 JEV helper，它会把目标与屏幕描述发送给你配置的模型供应商。是否开启、发给谁，都要自己心里有数。
操作后果由使用者承担。 Agent 可能点错按钮、删错文件、发出不该发的消息。可以采用这些做法降低风险：在 1.3.0 的 sandbox 中试跑，限制 --app 的范围，给删除、发送、支付这类高风险操作加人工确认。另外，无障碍树读不到的应用对 agent-desktop 不可见，这是能力边界，不要指望它一定能操作所有软件。
第三方 Agent 接网关是另一类风险。 把 Claude Code、OpenCode 等第三方 Agent 接到任何 API 网关时，都要注意令牌保管、额度上限和日志中是否会写入敏感内容。这和桌面自动化风险分开评估。建议为 Agent 单独建一个令牌并设置额度，出问题时可以单独作废。
常见问题 FAQ
Q1：什么是 agent-desktop？
agent-desktop 是 Vercel Labs 开源的 computer use CLI。它通过 OS 无障碍树，让 AI Agent 看见并操作 macOS、Windows、Linux 上的桌面应用，不依赖截图或像素匹配。它是工具而不是 Agent，本身不含模型。
Q2：agent-desktop 和截图式 computer use 有什么区别？
截图式方案依赖视觉模型理解像素再给出坐标，链路长，也容易受分辨率影响。agent-desktop 直接输出结构化 JSON 和 ref，模型按 ref 操作，默认 headless 运行，不抢指针和焦点。代价是只能看到暴露了无障碍信息的应用。
Q3：agent-desktop 目前是什么版本？
截至 2026-11-13，可见的最新版本节点是 1.3.0（2026-11-11），新增 sandbox。MCP 从 1.2.0（2026-11-05）开始提供，Linux 在 1.0.0（2026-10-27）正式进入 1.0。版本更新较快，请以 GitHub Releases 为准。
Q4：agent-desktop 适合哪些场景？
– **原生应用测试**：自动点击设置面板、校验界面状态
– **编程 Agent 扩展**：让 Claude Code 在写完代码后打开桌面应用验证效果
– **重复性桌面操作**：整理 Finder 文件、读取通知、读写剪贴板
网页相关任务请交给 agent-browser。
Q5：调用 agent-desktop 的 Agent 如何快速接上模型？
1. 在 API易 apiyi.com 注册并在令牌页创建 API Key，新用户有免费测试额度
2. OpenAI 兼容客户端把 Base URL 设为 `https://api.apiyi.com/v1`，Anthropic 原生客户端设为 `https://api.apiyi.com`
3. 模型选择 `claude-opus-5-5` 或 `claude-sonnet-5-5`，再运行本文的 snapshot 闭环
Q6：MCP 配好了，Agent 却报 401 或 404，是 agent-desktop 的问题吗？
通常不是。agent-desktop 不连接模型服务，401 一般是令牌问题，404 多半是 `/v1` 写错或型号名拼写错误。先在终端单独运行 `agent-desktop snapshot` 确认工具正常，再对照 API易 apiyi.com 的 Base URL 配置文档排查模型侧。
Q7：agent-desktop 有哪些已知限制？
– 无障碍树读不到的应用对它不可见
– 部分版本带有破坏性变更（如 1.1.0、1.3.0），升级前请阅读 Changelog
– sandbox provider 目前面向 macOS，其他平台是否跟进暂时未知
– 不做网页自动化，需要配合 agent-browser
agent-desktop 核心要点 Key Takeaways
- 工具不含模型：agent-desktop 只输出 JSON envelope，循环与决策在调用方
- 无截图 computer use：基于 AX、UI Automation、AT-SPI 无障碍树，按 ref 操作
- ref 必须完整：形如
@s8f3k2p9:e8，界面变化后需要重新 snapshot - 三平台可用：macOS 13+、Windows 10 1809+、Ubuntu 24.04+
- MCP 一行接入：1.2.0 起
agent-desktop mcp走 stdio - 网页交给 agent-browser：Electron 应用可以通过 DevTools 端口移交
- 大脑接入：调用方 Base URL 指向 API易 apiyi.com，选
claude-opus-5-5
总结
agent-desktop 的核心要点：
- 定位清楚：它是桌面应用的“眼睛和手”，不含模型，不做网页
- 闭环简单：安装 →
permissions --guide→ snapshot → click → 再 snapshot，配合--skeleton控制上下文长度 - 接入灵活：CLI、MCP、skills、FFI 都可以，1.3.0 的 sandbox 适合做隔离试跑
- 风险要管住：辅助功能授权和 snapshot 中的隐私内容，需要按桌面自动化的标准来管理
工具侧跑通之后，剩下的工作就是给循环配一个合适的大脑。推荐通过 API易 apiyi.com 创建令牌，把 Claude Code、OpenCode 或自制脚本的 Base URL 指过去，先用 claude-opus-5-5 验证流程，再按任务复杂度评估是否切换到 claude-sonnet-5-5。
📚 参考资料
- GitHub – agent-desktop：官方开源仓库，含 README、FAQ、Changelog
- 链接：
github.com/vercel-labs/agent-desktop -
说明： 版本变化、命令列表和隐私提示以此为准
-
agent-desktop 官方文档：概念与快速开始
- 链接：
agent-browser.dev/desktop、agent-browser.dev/desktop/quick-start -
说明： 安装、授权和最小闭环示例
-
npm – agent-desktop：npm 包页面
- 链接：
npmjs.com/package/agent-desktop -
说明： 查看当前发布版本
-
Vercel – What is computer use：computer use 概念介绍
- 链接：
vercel.com/i/what-is-computer-use -
说明： 理解无障碍树方案与截图方案的差异
-
API易 文档中心：型号总表、Base URL 配置、Claude 能力说明
- 链接：
docs.apiyi.com/models.md、docs.apiyi.com/faq/base-url-config.md、docs.apiyi.com/api-capabilities/claude.md - 说明： 型号与价格以平台型号列表为准
作者：APIYI 技术团队
技术交流：欢迎在 API易 apiyi.com 网站首页联系我们，更多资料可访问 docs.apiyi.com 文档中心
