工具介绍
关于 agent-desktop 的定位、能力与适用场景
agent-desktop 是 Vercel Labs 开源的 computer use 工具,Apache-2.0 协议,给 AI Agent 补上「操作桌面应用」这一段能力。它走的不是截图加视觉模型的路子:直接读操作系统的辅助功能树(macOS 的 AX API、Windows 的 UI Automation、Linux 的 AT-SPI),把当前界面转成 JSON,每个可操作元素都带一个 ref,Agent 对着 ref 点击或输入,再读一次界面确认结果。
注意它本身没有模型。工具只负责「看见」和「操作」,观察—动作—再观察的循环写在你的 Agent 里。官方把这个设计讲得很直白:agent-desktop 不是 Agent,是 Agent 的手和眼。
为什么不用截图
截图方案要靠视觉模型认元素、算坐标,界面一密集就容易点偏,还要来回传图、烧 token。走辅助功能树拿到的是一份结构化的控件清单,角色、名称、可用动作都在,定位更接近程序员的思路而不是「看图猜」。副作用是默认 headless:通过辅助功能 API 操作,不移动鼠标、不抢焦点,可以后台批量跑;需要真实鼠标事件时再加 --headed。
怎么用
先装:npm install -g agent-desktop,macOS 和 Linux 也可以用 Homebrew。装完跑 agent-desktop status 看平台、权限和支持的界面,macOS 上还需要用 agent-desktop permissions --guide 走一遍辅助功能授权。
典型循环就三步:snapshot --app Finder -i 拿到带 ref 的元素,click @s8f3k2p9:e8 操作其中一个,再 snapshot 一次核对结果。ref 属于它所在的那次快照,界面变了会返回 STALE_REF 或 AMBIGUOUS_TARGET,重新拍一张换新 ref 就行。
61 个命令,一个 MCP 入口
命令分成十组:观察(snapshot、find、get、is、screenshot 等)、ref 操作(click、type、set-value、toggle、scroll 等)、键盘鼠标、应用与窗口(launch、focus-window、resize-window 等)、通知、剪贴板、等待、会话、沙箱和系统。官方统计 61 个命令名,其中 57 个可直接运行,key-down/up、mouse-down/up 四个要等守护进程就绪。
更省事的是 MCP:agent-desktop mcp 会把每个命令都暴露成 MCP 工具(desktop_snapshot、desktop_click 这样命名),在配置里加一段 mcpServers 就能接进 Claude Code 一类的 Agent 工具。它还自带技能说明,agent-desktop skills get desktop 和 skills get platform 会按版本给出循环规则和平台差异,也可以直接 npx skills add 装进 Agent 环境。
平台与形态
macOS 13 起(Intel 与 Apple Silicon)、Windows 10 1809 起(x64 / ARM64)、Ubuntu 24.04 起(x86_64 / aarch64,X11 或 Wayland)都有支持,每个平台各用自家的辅助功能接口。形态上提供 CLI,也随每个版本发布 libagent_desktop_ffi C 库,非 Node 进程可以直接通过 FFI 嵌进去用。
安全上要留意一点:快照、剪贴板读取、截图、命令输出和调试产物都可能包含桌面上的隐私内容,官方明确建议不要把它们放进公开日志或上传。项目当前 24.3k 星、1.8k fork,348 次提交。


