agent-desktop 中文文档：安装与快速入门

非官方中文翻译。AI 翻译，未经人工逐项校对。 本页翻译原项目 README 中的安装和快速入门章节；其他章节请查看原文。

agent-desktop 是面向 AI 智能体的计算机操作工具，可通过操作系统的无障碍树读取和操作 macOS、Windows 和 Linux 桌面应用。它提供 CLI 和 C 库；操作过程由智能体负责，agent-desktop 本身不包含模型。

快照、剪贴板读取结果、截图、命令输出和调试产物可能包含私人桌面内容，应避免将它们放入公开日志或上传。

原始仓库：vercel-labs/agent-desktop
原文：README.md 的安装与快速入门
对应 commit：ab7dfb218cddc1594aa1d87a5bfcd0ac76da2276
README 原文 SHA-256：373b4616cbdb558318b5ad7b70b0a7086e58833d60646c36a81deae655d82365
翻译章节原文 SHA-256：9734bc0b077da8134b4e5f0799065cbab597556780ab58b8cfc5bd20175e9d12
翻译及同步时间：2026-11-10 11:36 UTC
原项目作者：Vercel Labs；原文标注 Apache License 2.0。本页为翻译后的修改版本。

安装

bash

npm install -g agent-desktop
agent-desktop status                # platform, permissions, supported surfaces
agent-desktop permissions --guide   # macOS: walks you through the Accessibility grant

Bun、Yarn 和 pnpm 也可以安装同一个包。该包包含适用于 x64 和 ARM64 的原生二进制文件及平台辅助程序。

如需不通过 JavaScript 启动器直接运行，请从 GitHub Releases 下载对应的原生归档文件，并将辅助程序放在可执行文件旁边。

在 macOS 和 Linux 上也可以使用 Homebrew：brew install agent-desktop。目前还没有官方 Scoop 包。仓库已不再维护自定义 Homebrew tap 或 Scoop bucket。

发布归档和从源代码构建的说明请参阅安装文档。

快速入门

bash

agent-desktop snapshot --app Finder -i      # interactive elements, each with a ref
agent-desktop click @s8f3k2p9:e8            # act on a ref from that snapshot
agent-desktop snapshot --app Finder -i      # observe again to verify

每个命令输出一个 JSON 结果。以下是精简后的快照：

json

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

引用标识属于各自的快照。 单独的 @e8 会被拒绝并返回 INVALID_ARGS。界面变化后，操作可能返回 STALE_REF 或 AMBIGUOUS_TARGET；请获取新快照并使用其中的引用。
多个窗口会产生 AMBIGUOUS_TARGET；snapshot 在 error.details 中列出候选窗口 ID。可通过 --window-id 指定其中一个。
内容密集的应用： 先用 snapshot --skeleton --app Slack -i --compact 获取概览，再用 snapshot --root @s8f3k2p9:e3 -i --compact 深入查看某个区域。
默认无头操作。 引用操作使用无障碍 API，不移动指针或获取焦点。全局标志 --headed 允许物理输入。
操作后的等待会观察引用所属的原始进程。窗口所属的引用始终固定在原窗口，包括从 sheet、alert、popover、聚焦视图或 Linux 菜单获取的引用。macOS 应用程序菜单保留其应用所属的界面，不需要文档窗口。等待过程读取整个固定窗口，因此叠加层选择器也在这个范围内。有关选择器限制，参见等待范围与结果。
type、set-value 和 clipboard-set 接受 --stdin 传入管道文本，避免文本出现在进程参数中。涉及密钥的步骤应作为独立命令运行；批量 JSON 文本会出现在进程参数中。
PowerShell： 为每个引用加引号（'@s8f3k2p9:e8'），因为裸露的 @token 会被视为 splatting 运算符。

完整的操作说明请参阅快速入门。

agent-desktop 中文文档：安装与快速入门 ​

安装 ​

快速入门 ​

实用工具

agent-desktop 中文文档：安装与快速入门

安装

快速入门