安装与权限 | agent-desktop

每个发布版本里都同时打包了 x64 与 ARM64 的原生二进制和平台辅助程序。装好之后， agent-desktop version 是最快的确认方式。

用包管理器安装

在 macOS、Windows 或 Linux 上都可以：

npm install -g agent-desktop

bun add -g agent-desktop

pnpm add -g agent-desktop

yarn global add agent-desktop

agent-desktop version

直接下载原生压缩包

不想引入 JavaScript 启动器时，从 GitHub Releases 下载对应平台的原生压缩包，把它的辅助程序和可执行文件放在同一个目录里，然后确认这个目录在 PATH 上。

发布页的校验和只能发现损坏，不能证明来源。需要验证来源时，用 GitHub 的构建证明：

gh attestation verify <downloaded-archive> --repo vercel-labs/agent-desktop

授予权限

三个平台的前置条件不一样。缺了可能返回 PERM_DENIED，也可能表现为读不到界面或元素，所以先跑一次权限检查。

需要「辅助功能」权限；截图额外需要「屏幕录制」，打开通知中心需要 System Events 的「自动化」权限。权限授予运行 agent-desktop 的终端或智能体宿主进程，不是二进制本身。

agent-desktop permissions          # 只报告状态，不弹窗
agent-desktop permissions --request # 请求缺失的权限
agent-desktop permissions --guide   # 打开系统设置

和终端同级完整性（integrity level）的应用无需额外授权。以管理员身份运行的应用可以读，但只有同样提权的智能体才能向它发送输入。

agent-desktop permissions

主要目标是 Ubuntu 24.04 及更高版本、GNOME 46，glibc 2.35 起。需要用户自己的图形会话，以及 at-spi2-core。会话总线不在时，AT-SPI 一棵树也读不出来。

sudo apt install at-spi2-core
agent-desktop status

X11 与 Wayland 的差别见 Linux 平台说明。

确认装好了

permissions 报出三项权限，每项是 granted、denied、not_required 或 unknown；缺失时附带 suggestion。

agent-desktop permissions

{
  "version": "2.6",
  "ok": true,
  "command": "permissions",
  "data": {
    "accessibility": { "state": "granted" },
    "screen_recording": { "state": "denied", "suggestion": "..." },
    "automation": { "state": "not_required" }
  }
}

status 在此基础上再报出适配器健康状态、平台、supported_surfaces、最近的快照（snapshot_id 与 ref_count）、session_id、tracing 和 state_root。

agent-desktop status

每条命令都打印这样一个信封，结构见 JSON 输出契约。

从源码构建

需要 Rust 1.89 或更新版本，外加平台工具链：macOS 13+ 上的 Xcode 命令行工具、 Windows 上的 MSVC 构建工具，或 Linux 上的 C 链接器。

git clone https://github.com/vercel-labs/agent-desktop && cd agent-desktop
cargo build --release -p agent-desktop

Linux 还要构建辅助程序，并让 agent-desktop-linux-clipboard-owner 和 CLI 放在同一目录：

cargo build --release -p agent-desktop-linux --bins

每个平台的适配器只能在它自己的操作系统上构建，所以测试和 lint 要把 cargo 的范围限制在宿主平台对应的包上。在 macOS 上：

HOST_PKGS=(-p agent-desktop-core -p agent-desktop-macos -p agent-desktop -p agent-desktop-ffi)
cargo test "${HOST_PKGS[@]}"
cargo clippy "${HOST_PKGS[@]}" --all-targets -- -D warnings

在 Windows 上，把列表里的 agent-desktop-macos 换成 agent-desktop-windows；在 Linux 上换成 agent-desktop-linux。所有关卡列在仓库的 CONTRIBUTING.md 里。

下一步

快速开始：跑通第一轮观察—操作—验证。
平台支持：三个平台各自的能力边界。