> For the complete documentation index, see [llms.txt](https://book.bsdcn.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://book.bsdcn.org/openbsd/install-and-configure/x11.md).

# X Window System

## Synopsis

X Window System（通常称为 X11）提供 OpenBSD 使用的图形用户界面框架，支持大量图形硬件、输入设备与窗口管理器。X11 通过特定文件集集成进基本系统。本章讲解 X 的安装、配置与运行，包括用 `xenodm(1)` 与 `startx(1)` 管理会话、用户会话设置、桌面环境、字体与输入配置、通过 `drm(4)` 与 `wscons(4)` 提供的硬件支持、多显示器配置、远程 X 访问以及故障排查。

## X 的安装与配置

安装时，OpenBSD 安装程序会提示选择文件集。要使用 X，必须包含以下文件集：`xbase`、`xshare`、`xfont` 与 `xserv`，分别提供核心二进制、共享资源、字体与 X 服务器。若安装时未选，可后续用 `sysupgrade(8)` 或从安装介质中解包文件集来手动添加图形环境。注意，`sysupgrade` 需要网络连接或可访问已挂载的安装文件集。

检查这些文件集是否已安装：

```sh
$ pkg_info | grep xbase
```

若未安装 X，也可通过软件包安装 Xorg 组件：

```sh
# pkg_add xorg-server xorg-fonts xorg-apps xrandr
```

其中包含 X 服务器、常用字体以及 `xterm` 等核心工具。

安装后，二进制文件位于 **/usr/X11R6**，配置文件位于 **/etc/X11**。X 通常通过 `drm(4)` 与 `wscons(4)` 自动配置硬件，很少需要手动配置。

手动生成并测试配置：

```sh
$ X -configure
$ X -config ~/xorg.conf.new
```

成功后安装该配置：

```sh
# mv ~/xorg.conf.new /etc/X11/xorg.conf
```

平台相关说明见 **/usr/X11R6/README**。

## 图形会话管理

OpenBSD 启动 X 有两种主要方式：通过 `xenodm(1)`，或手动用 `startx(1)`。

使用显示管理器 `xenodm(1)`：

```sh
# rcctl enable xenodm
# rcctl start xenodm
```

这会在启动时启用图形登录。会话根据用户的 `.xsession` 文件启动。可在 **/etc/X11/xenodm/** 下自定义外观与登录行为。

使用 `startx(1)` 时，先在虚拟终端登录，再运行：

```sh
$ startx
```

这会执行用户主目录下的 `.xinitrc`。若该文件不存在，默认启动 `xterm`。

**注意：** 若 `startx` 出现权限相关问题，参见故障排查一节中关于组成员与设备访问的说明。

## 用户会话配置

在用户主目录下创建 `.xinitrc` 或 `.xsession`，用于启动窗口管理器或桌面环境。

`cwm(1)` 的 `.xinitrc` 示例：

```sh
export ENV=$HOME/.kshrc
xsetroot -solid steelblue
exec cwm
```

`xfce` 的 `.xsession` 示例：

```sh
exec startxfce4
```

编辑前先备份已有的 `.xinitrc` 或 `.xsession`，以免破坏图形会话：

```sh
$ cp ~/.xinitrc ~/.xinitrc.bak
```

为主窗口管理器失效时设置回退：

```sh
if command -v i3 >/dev/null 2>&1; then
    exec i3
else
    exec xterm
fi
```

`.xinitrc` 由 `startx(1)` 使用；`.xsession` 由 `xenodm(1)` 使用。

## 桌面环境与窗口管理器

OpenBSD 默认附带 `ctwm(1)` 窗口管理器，其他桌面环境可从软件包安装。

安装并配置常见桌面环境：

XFCE：

```sh
# pkg_add xfce
$ echo "exec startxfce4" > ~/.xsession
```

GNOME：

```sh
# pkg_add gnome
$ echo "exec gnome-session" > ~/.xsession
```

KDE：

```sh
# pkg_add kde-plasma
$ echo "exec startplasma-x11" > ~/.xsession
```

轻量级选择包括 `cwm`、`fvwm`、`fluxbox` 与 `i3`。

安装后说明参见 **/usr/local/share/doc/pkg-readmes**。GNOME 与 KDE 等环境需要 D-Bus 或 `polkit` 等额外服务才能完整运行。内存较小的系统上，重型桌面可能不实用。

## 显示管理器替代方案

`xenodm` 是默认管理器，已包含在 `xbase` 中；也可安装 `slim` 或 `sddm` 等替代方案：

```sh
# pkg_add slim
# rcctl enable slim
# rcctl start slim
```

启用其他显示管理器前，先禁用当前正在运行的管理器：

```sh
# rcctl disable xenodm
```

`sddm` 通常配合 KDE Plasma 使用，用于其他环境可能需要额外配置。某些硬件配置下的兼容性可能有所不同。

这些管理器的配置文件通常位于 **/etc/** 或 **/usr/local/share/examples/**。

## 字体与输入设备

X 使用 fontconfig 与 `fc-list(1)` 查询字体可用性。

安装字体：

```sh
# pkg_add font-awesome font-cantarell
$ fc-cache -fv
```

注意：字体较多的系统上，重建字体缓存可能需要一些时间。

查询或测试输入设备：

```sh
$ xinput list
$ xinput test <device-id>
```

永久性输入配置可放在 **/etc/X11/xorg.conf.d/**。

禁用 Caps Lock 的 `10-keyboard.conf` 示例：

```
Section "InputClass"
    Identifier "keyboard overrides"
    MatchIsKeyboard "on"
    Option "XkbOptions" "ctrl:nocaps"
EndSection
```

运行时重映射按键：

```sh
$ setxkbmap -option ctrl:nocaps
```

## 图形硬件支持

现代图形由 `drm(4)` 子系统支持，包括 `amdgpu(4)`、`radeondrm(4)` 与 `intel(4)`，检测到受支持硬件时自动加载。

查看驱动状态：

```sh
$ dmesg | grep drm
```

帧缓冲设备与控制台切换由 `wscons(4)` 框架提供。`wsdisplay(4)` 驱动提供 VT 切换与控制台渲染。

较旧硬件可能需要 `xf86-video-vesa` 或 `xf86-video-nouveau` 等传统驱动，可从软件包安装。

注意：解读 `dmesg` 输出可能需要熟悉内核使用的驱动名称。

## 使用多台显示器

用 `xrandr(1)` 查询并配置显示器。

列出活动输出：

```sh
$ xrandr
```

将副显示器配置在主显示器右侧：

```sh
$ xrandr --output HDMI-1 --right-of eDP-1 --auto
```

镜像输出：

```sh
$ xrandr --output HDMI-1 --same-as eDP-1 --auto
```

缩放 HiDPI 显示器：

```sh
$ xrandr --output eDP-1 --scale 1.5x1.5
```

将持久配置加入 `.xsession` 或 `.xinitrc`。

用图形工具配置布局：

```sh
# pkg_add arandr
$ arandr
```

## 远程 X11 访问

远程 X 会话可通过 SSH 安全转发。直接通过 TCP 访问 X 因固有安全风险而强烈不建议。

启用安全的 X11 转发：

```sh
$ ssh -X user@host.example.org
```

对部分旧应用使用可信转发：

```sh
$ ssh -Y user@host.example.org
```

在远程系统上，确保 **/etc/ssh/sshd\_config** 包含：

```
X11Forwarding yes
```

验证转发：

```sh
$ echo $DISPLAY
localhost:10.0
```

避免使用 `xhost +`，它会关闭所有访问控制，使显示器暴露给远程连接。

若不需要，禁用 X 的 TCP 监听，例如在 `.xserverrc` 或显示管理器配置中：

```
exec X -nolisten tcp
```

**安全提示：** `-Y` 选项关闭访问控制检查，仅在必要时使用。X11 转发在高延迟连接上可能很慢或无响应。

若本地网络环境必须直接访问，请配置 `xauth(1)` 并严格执行防火墙规则。

## 故障排查

若 X 无法启动，查看 **/var/log/Xorg.0.log**：

```sh
$ grep EE /var/log/Xorg.0.log
$ grep WW /var/log/Xorg.0.log
```

检查系统日志中的驱动或设备错误：

```sh
$ dmesg | grep drm
```

测试最小 X 环境：

```sh
$ X -retro &
$ xterm
```

显示管理器问题：

```sh
$ cat /var/log/xenodm.log
```

确保只启用一个显示管理器：

```sh
# rcctl disable slim
# rcctl enable xenodm
```

使用 `startx(1)` 时，确认用户属于 `video` 组：

```sh
# usermod -G video youruser
```

输入设备缺失时，在 `xorg.conf` 中添加基本的 `InputDevice` 段：

```
Section "InputDevice"
    Identifier "Keyboard0"
    Driver "kbd"
EndSection
```

窗口管理器或桌面无法启动时，回退到 `xterm`：

```sh
exec xterm
```

确认所需驱动或固件已安装，并与内核匹配。驱动与运行中内核不兼容可能导致 X 静默失败或报出晦涩错误后退出。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://book.bsdcn.org/openbsd/install-and-configure/x11.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.