---
title: "Linux"
description: "AT-SPI 总线、X11 与 Wayland 的差别，以及 wl-clipboard 什么时候必须装。"
---

> Documentation Index
> Fetch the complete documentation index at: https://agent-desktop.ndjp.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Linux

Linux 上 agent-desktop 走 AT-SPI。它比其他两个平台多两处需要留意的地方：可访问性总线
是否起来了，以及你用的是 X11 还是 Wayland。

## 系统要求

Ubuntu 24.04 或更高，x86_64 或 aarch64（glibc 2.35 起），运行在用户自己的图形会话里，
并且有一条工作中的 AT-SPI 总线。

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

> **总线不在，一棵树也读不出来**
>
> AT-SPI 总线没有运行时，可访问性树是空的。这通常不是 agent-desktop 的问题，
> 而是会话或桌面环境的配置问题。先确认 `at-spi2-core` 装好、会话是图形会话。

## X11 与 Wayland

| 能力 | X11 | Wayland |
|---|:---:|:---:|
| 键盘 | 支持 | 走 AT-SPI / GNOME 路径 |
| 鼠标输入 | 支持，`--headed` | 拒绝（`ACTION_NOT_SUPPORTED`） |
| 截图 | 窗口截图 | 门户（portal） |
| 剪贴板 | 支持 | 支持，需要 `wl-clipboard` |
| 窗口控制 | 支持 | 不支持原生窗口控制 |
| 通知 | GNOME Shell | GNOME Shell，指针操作被拒绝 |

Wayland 把输入和抓屏都收拢到合成器与门户后面，所以一部分能力的实现路径和 X11 不同。
`--headed` 下的鼠标输入依赖 X11；Wayland 会话上截图走门户，剪贴板需要装 `wl-clipboard`。

```bash
sudo apt install wl-clipboard
```

具体的边界以本机能力表为准：

```bash
agent-desktop skills get platform
```

## 能力表

| 能力 | 状态 |
|---|---|
| 可访问性树 | 支持（AT-SPI） |
| 点击 / 输入 / 键盘 | AT-SPI；X11 / GNOME 按键 |
| 鼠标输入 | X11，`--headed` |
| 截图 | X11 窗口；Wayland 门户 |
| 剪贴板 | 支持；Wayland 需要 `wl-clipboard` |
| 应用与窗口管理 | 启动/列出；X11 窗口控制 |
| 通知 | GNOME Shell |
| 外壳界面 | 仅 `system-tray` 与 `action-center` 可用 |

外壳界面这条限制得细说：`system-tray` 需要存在 StatusNotifierWatcher，否则返回 `watcher: absent`；
`action-center` 需要可证明的角色祖先。`taskbar` 永远拒绝，`start-menu` 与
`system-tray-overflow` 不受支持——即使 `--help` 把它们列了出来。

X11 与 Wayland 的完整说明在仓库的 `docs/install.md#platform-notes`。

- [安装与权限](/start/install/)
- [平台支持总览](/platforms/)

Source: https://agent-desktop.ndjp.net/platforms/linux/index.mdx