Install The Linux Beta¶

Linux 测试版面向 x86_64 和 ARM64（aarch64）Linux：i3/X11 以及兼容的基于 wlroots 的 Wayland 合成器（如 Hyprland 或 Sway）。音频使用 ALSA，包括具有 ALSA 兼容性的 PipeWire 系统。推理在可用时使用 Vulkan，并可回退到 CPU。在转录过程中挂起或失败的 GPU 会被记录在其当前驱动程序下，自动模式会在该 GPU 上使用 CPU 进行转录，直到驱动程序更改。慢到无法满足流式截止日期的集成 GPU 会与 CPU 进行一次计时比较，自动模式会保留较快者。通用 › 高级 › 语音引擎 可选择自动、GPU 或 CPU（hex settings set transcription_device cpu）。即使使用 CPU 推理，窗口仍然需要 Vulkan 驱动程序；仅靠 vulkan-icd-loader 并不是驱动程序。请为你的 GPU 安装驱动程序，或安装软件 Vulkan 驱动程序。请参阅下面的 Wayland 要求。

x86_64 机器需要 2013 年或更新的、支持 AVX2 的处理器（Intel Haswell / AMD Excavator 或更高版本）；在较旧的处理器上，Hex 会显示一条消息并退出，而不是启动。

Linux 会打开与 macOS 和 Windows 相同的窗口：设置、模式和历史记录。会议功能仅限 macOS。在 Wayland 上，粘贴在合成器提供虚拟键盘协议（wlroots 合成器、niri）时使用 wtype，在其他地方（KDE、GNOME）使用桌面的 RemoteDesktop 门户。快捷键是通用的：当桌面具有全局快捷键门户时使用它，否则使用你桌面自己的、运行 hex 命令的键绑定（参见快捷键）。

对于 Nix/NixOS，请使用 Nix 指南。Nix 负责该安装的更新；Hex 的签名更新程序只负责下面的直接安装布局。

One Hex Process¶

Linux 上的 Hex 是每个用户一个进程（也是每个数据目录一个进程），而不是系统级/root 守护进程。它拥有麦克风、快捷键、模型下载和工作进程、声音、粘贴、历史记录、录制浮动条以及窗口。窗口是可选的：关闭它既不会停止听写，也不会停止模型下载，再次启动 Hex 会重新打开它。当桌面带有托盘（StatusNotifierItem 宿主，如 Waybar、KDE 或 Omarchy 的栏）时，Hex 会显示一个托盘图标：点击它打开窗口，或使用其菜单：显示 Hex、粘贴上次听写、已下载的语音模型、一旦更新就绪后的更新（重启以更新）、启用 / 禁用 Hex 和 退出 Hex；当 Hex 正在录音或转录时，菜单和工具提示会说明这一点。如果没有托盘，可通过窗口侧栏底部的 退出 Hex、启动器的 退出 Hex 操作，或 hex quit 退出。

窗口以 980×760 逻辑像素打开，并在没有窗口规则的平铺窗口管理器上浮动：它以最小尺寸等于最大尺寸的方式映射，sway、Hyprland、niri 以及 i3 等 X11 管理器会将其浮动，随后它降低最大尺寸，因此你可以将其缩小到 860×560 或放大到任意尺寸。macOS 和 Windows 打开相同的可调整大小窗口。

设置保存在 Hex 数据目录中的 settings.json 中，这是 macOS 和 Windows 使用的同一个文件。

hex                             # open the window, starting Hex if needed
hex start                       # start Hex in the background; no window
hex status [--json]             # query the running Hex, not an old log entry
hex quit [--force]              # finish accepted work, release the microphone, exit
hex restart [--force]           # restart the systemd unit in this desktop's environment
                                # (over SSH: the one it last ran in)
hex settings set sound_effects off   # every control command (docs/cli.md)
journalctl --user -u hex.service # diagnostics of the supervised process

hex app 与 hex 相同，hex start 在后台运行 hex app --hidden 并等待 Hex 响应，hex stop 与 hex quit 相同；较旧的桌面和自动启动条目在更新仅替换可执行文件后仍可继续使用。当听写正在录音或转录时，hex quit 和 hex restart 会拒绝执行，除非使用 --force。Linux 运行与 macOS 相同的控制命令（docs/cli.md）：settings、model、window、vocabulary、history clear、check-for-updates、onboarding reset、annotate status、launch-at-login（XDG 自动启动条目）、logs、commands init|check、history、meetings 和 mcp。

启动时首先通过套接字询问正在运行的 Hex。如果有响应，它会将 Activate 与启动器的 XDG_ACTIVATION_TOKEN 或 DESKTOP_STARTUP_ID 一起转发，并以 0 退出；正在运行的进程会打开或聚焦其窗口。如果没有运行中的实例，并且安装程序（或 Home Manager）的 hex.service 用户单元已加载，启动操作会写入一个仅属主的 session.env 并启动该单元，该单元在套接字响应后向 systemd 报告就绪（Type=notify），然后转发 Activate。否则（自定义数据目录、cargo run、没有 systemd 的桌面），启动进程本身成为 Hex。两个同时启动会产生一个 Hex；失败者转发并退出 0。

session.env 保存显示和会话变量、光标主题和输入法（XCURSOR_THEME、XCURSOR_SIZE、XMODIFIERS、GTK_IM_MODULE、QT_IM_MODULE），以及（若已设置）XDG_DATA_DIRS 和区域设置（LANG、LANGUAGE、LC_ALL、LC_CTYPE、LC_MESSAGES）。缺失的显示变量会显式清除用户管理器继承的过时 Wayland/X11 值；缺失的区域设置和数据目录变量则留给用户管理器处理。已保存的 XAUTHORITY 如果其文件已不存在（Xwayland 在每次登录时写入新的 cookie，因此重启会导致旧路径失效），会在启动时被用户管理器的当前值替换，或被丢弃以便 Xlib 使用 ~/.Xauthority。在完全没有显示的情况下启动的单元（桌面从未将其环境导入 systemd）会采用用户管理器的 WAYLAND_DISPLAY，否则采用你在 XDG_RUNTIME_DIR 中响应的最新 Wayland 套接字。Hyprland 默认不导入任何内容；请将以下内容添加到其配置中，以便服务、其粘贴辅助程序和 HUD 获取你的会话：

exec-once = dbus-update-activation-environment --systemd WAYLAND_DISPLAY XDG_CURRENT_DESKTOP

当 HUD 无法显示时，Hex 的日志会说明原因：没有显示、没有 layer-shell（也没有 XWayland），或叠加层无法打开并附有其错误信息。无需授予任何权限。该单元是 PartOf=graphical-session.target；管理自定义会话目标的桌面环境必须将其生命周期绑定到自身的登录/注销生命周期。Systemd 会重启崩溃的 Hex（Restart=on-failure），且不带有窗口；在更新之后，重启后的 Hex 会重新打开窗口。每个用户只有一个 Hex：从另一个桌面会话启动会重启新会话中受监督的单元，并拒绝接管不受监督的单元（请先退出它）。

该套接字位于 Hex 的数据目录中，仅所有者可访问，并具有同用户对端凭据、带版本的有界帧、有界队列和 I/O 截止时间。它不是网络 API，也不是 macOS 内嵌转录 SDK 服务。它承载 Activate、Status 以及 Annotate 的录制命令。hex 控制命令通过其本地 API 的 POST /control 到达 Hex；听写命令从那里直接发送到监听器，绝不经过窗口。本地 API 的 /dictations（TypeScript SDK 的 hex.dictation）也会在 Hex 监听时在监听器上录制，就像在 macOS 上一样：一次仅一个采集，因此客户端的听写和快捷键绝不会互相终止。

开发时，运行 cargo run --release。hex dictate 仍然是一个显式的前台诊断监听器，没有窗口或 HUD，并且无法与 Hex 的监听器共存。设置了 HEX_APPLICATION_SUPPORT_DIR 后，启动操作永远不会启动、停止或重启已安装的用户单元；它们会转发到使用该数据目录的 Hex，或者直接成为该 Hex。HEX_SYSTEMD_UNIT 为隔离测试指定另一个单元。hex logs -n 40 是诊断日志视图（hex status --lines 已移除）。

窗口基于 Rune 的应用生命周期（rune::App）运行：Hex 启动它时不带窗口，每次 Activate 都会使用转发来的令牌打开或聚焦该窗口（在 Wayland 上通过 xdg_activation_v1；没有令牌时，大多数合成器只会将其标记为紧急），关闭窗口则会保留窗口状态，以便下次打开。

安装已发布的构建¶

已发布的构建适用于 x86_64 和 ARM64，提供裸可执行文件、.deb 和 .rpm 三种形式。它们基于 Debian 12 构建，需要 glibc 2.36 或更高版本：Debian 12、Ubuntu 23.04、Fedora 37、当前的 Arch 或更新版本。ARM64 构建与 x64 一样使用 Vulkan，并在必要时回退到 CPU。

安装脚本¶

该脚本会将适用于你架构的裸可执行文件安装到用户本地的目录布局（~/.local/share/hex）中，该布局会自行更新。它会安装稳定版，或者在尚无稳定版时安装最新的开发版构建（位于 Dev 更新通道）；设置 HEX_INSTALL_CHANNEL=stable 或 =dev 来选择：

curl -fsSL https://anoma.ly/hex/files/install-linux.sh | sh

如果缺少某个运行时库，安装程序会指出需要安装的软件包（以 Arch 的包名给出）。然后从应用程序启动器打开 Hex，或运行 ~/.local/bin/hex；它首次运行时会下载语音模型。

若要预先安装依赖项，或在运行前检查安装程序：

sudo pacman -S --needed alsa-lib curl jq \
  libxkbcommon libxkbcommon-x11 libx11 libxcb openblas openssl util-linux \
  vulkan-icd-loader wl-clipboard wtype xxd
curl --proto '=https' --tlsv1.2 -fsSLO \
  https://anoma.ly/hex/files/install-linux.sh
less install-linux.sh
sh install-linux.sh
~/.local/bin/hex model install
~/.local/bin/hex

安装程序在安装前会验证已签名的发布源、确切的工件大小和 SHA-256。它不需要使用 root 权限。它会创建受管的版本布局、~/.local/bin/hex、桌面启动器、XDG 自启动项以及 hex.service 用户单元。它不会在安装期间开始录音。

通用 › 登录时启动 用于启用或禁用该自启动项（~/.config/autostart/anomaly.hex.desktop）；对于不是 Hex 自己写入的条目，Hex 不会去改动。在桌面提供 Background 门户（GNOME、KDE）时，Hex 会在启动时请求它在后台运行，“登录时启动”也会通过该门户实现：门户会写入和移除同一个自启动项（标记为 X-XDP-Autostart=anomaly.hex）。在其他环境中，Hex 会自己写入该条目。

下面的启动器条目仅在已安装的包或数据目录没有提供相应条目时才会写入，并且只要它启动的程序存在，就会保持原样。如果通过版本管理器（mise、asdf）安装，两个条目都会启动其 shim（~/.local/share/mise/shims/hex），该 shim 比每个版本都更持久，因此升级不会让这些条目失效。对于 Hex 写入的条目，如果其指向的程序已不存在，则在下次启动时会指向这个 Hex；一旦某个包自带该条目，该条目就会被移除。

启动器条目是 ~/.local/share/applications/anomaly.hex.desktop，以 Hex 的应用 ID anomaly.hex 命名，Hex 的窗口也会报告这个 ID。早期安装将这两个条目都命名为 hex.desktop；Hex 和安装程序会重命名 Hex 自己的条目。其图标是 anomaly.hex：软件包会将其安装到 hicolor 主题中；直接安装时，图标会在 Hex 首次启动时放入 ~/.local/share/icons/hicolor。

要删除应用程序但保留日志和设置，请运行：

curl -fsSL https://anoma.ly/hex/files/install-linux.sh | sh -s -- uninstall

或者，在已保存安装程序副本的情况下，运行 sh install-linux.sh uninstall。

从 2.3.1 升级¶

HEX 2.3.1 会读取 Wayland 上的每一个 /dev/input 设备，因此它需要 input 组。当前构建不再需要：它们使用 GlobalShortcuts 门户，或使用你在桌面环境中绑定的 hex 命令（参见快捷键）。不要授予输入访问权限；请安装新构建。

新构建是 ~/.local/share/hex 中的独立安装，不会从 2.3.1 的 ~/.local/share/voice-control 导入任何内容，因此需要重新设置模型和设置。安装程序拒绝替换 2.3.1 的文件，因此请先移除它们（以下路径假定使用默认的 XDG 目录）：

systemctl --user disable --now hex.service
rm -f ~/.config/systemd/user/hex.service ~/.local/bin/hex \
  ~/.local/share/applications/hex.desktop ~/.config/autostart/HEX.desktop
systemctl --user daemon-reload
rm -rf ~/.local/share/voice-control   # optional: 2.3.1's settings, logs, and models
curl -fsSL https://anoma.ly/hex/files/install-linux.sh | sh
~/.local/bin/hex model install
~/.local/bin/hex

在 Hyprland 上，按照快捷键中的描述在配置中绑定快捷键。

Debian、Ubuntu、Fedora 和 openSUSE¶

hex 包会安装 /usr/bin/hex、桌面条目和 systemd 用户单元 hex.service（与下面的 AUR 包文件相同）。请从 https://anoma.ly/hex/download/linux-x64-deb（linux-arm64-deb、linux-x64-rpm、linux-arm64-rpm）下载适合你架构的版本，然后：

sudo apt install ./hex.deb            # Debian, Ubuntu
sudo dnf install ./hex.rpm            # Fedora (zypper install on openSUSE)
systemctl --user enable hex.service   # optional: start Hex at login

目前还没有 apt 或 dnf 软件源。Hex 永远不会替换由软件包安装的可执行文件：当新的稳定版发布时，设置会显示下载并安装其软件包的命令。软件包安装遵循稳定频道，因此来自开发频道的软件包只会得知下一个稳定版。

AUR¶

从下一个版本开始，AUR 包 hex-bin 会将 /usr/bin/hex、桌面条目和 systemd 用户单元 hex.service 从同一个发布可执行文件安装到 x86_64 和 aarch64 架构。它目前还不在 AUR 上。使用 AUR 辅助工具：

yay -S hex-bin
systemctl --user enable hex.service   # optional: start Hex at login

pacman 会更新它；Hex 永远不会替换由软件包安装的可执行文件，并且设置会显示“已由你的软件包管理器更新”。它与官方的 hex 包（一个安装 /usr/bin/hx 的十六进制转储工具）无关。

从源码安装¶

安装原生依赖；如果是源码构建，还需安装 Rust 工具链：

sudo pacman -S --needed base-devel git rustup python alsa-lib curl jq openssl xxd \
  util-linux libxkbcommon libxkbcommon-x11 libx11 libxcb openblas \
  vulkan-headers vulkan-icd-loader \
  shaderc spirv-headers clang cmake pkgconf wl-clipboard wtype
rustup default stable

以你的桌面用户身份构建并安装 Hex：

git clone https://github.com/anomalyco/hex.git
cd hex
./scripts/install-linux.sh
~/.local/bin/hex model install
~/.local/bin/hex

不要以 root 身份运行安装程序。它会以与发布版构建相同的布局安装用户级二进制文件、桌面启动器和自动启动条目，并将版本标记为源码构建（可执行文件旁带有 source-build）。应用内更新程序永远不会替换源码构建；设置会显示“已从你的源码检出更新”，你只需拉取并再次运行安装程序即可更新。在其上安装发布版会切换回签名更新。如果设置了自定义的 HEX_APPLICATION_SUPPORT_DIR，cargo run --release 会运行一个不受管理的开发版 Hex；否则它会转发到已安装的 Hex。

听写¶

按住 Alt-Space，说话，然后松开。双击快捷键可保持录音，再按一次相同组合键即可结束。快捷键模式决定快捷键的触发方式：按住或双击（默认）、按住、单击（单击开始和停止）或双击（等待两次完整的点击，且需要带按键的快捷键）。Ctrl-Alt-V 可再次粘贴上一条听写内容。设置会显示监听器状态、开始/停止和运行错误。更改快捷键或监听器启动时读取的设置会暂时停止监听，并在编辑结束后恢复之前的运行状态。

模式会按应用或网站应用纠错、OpenCode 重写和转换；应用选择器会列出 .desktop 条目。在 X11 上，Hex 从活动窗口的进程名（code、chrome）读取当前聚焦的应用。在 Wayland 上，支持 foreign-toplevel 协议的合成器（如 Sway、niri、Hyprland 等 wlroots 合成器）会报告已激活窗口的 app ID，Hex 会通过其 .desktop 条目（google-chrome-stable、firefox）为其命名。GNOME 和 KDE 不报告该信息，因此那里会应用全局模式。

网站规则在 X11 和 Wayland 上通过 AT-SPI（桌面无障碍总线）读取当前聚焦页面的地址。只要无障碍总线在运行，Firefox 就会暴露该地址。Chrome 和其他 Chromium 浏览器只有在开启无障碍功能时才会暴露它：使用 --force-renderer-accessibility 启动它们（例如在 ~/.config/chrome-flags.conf 中），或运行屏幕阅读器。如果没有该地址，则使用应用规则。完成的听写会保存在历史记录中。

在不听写时关闭麦克风（通用）会在两次听写之间释放麦克风；之后在按下快捷键时它才会打开，且没有预卷。在听写期间 可以在一段按住超过 300 毫秒后，通过 wpctl（PipeWire）或 pactl（PulseAudio）静音默认输出，或通过 D-Bus 暂停正在播放的 MPRIS 媒体播放器；因此快捷键组合和短按绝不会触发这些操作；Hex 只恢复它自己更改的内容。取消快捷键捕获会保留旧绑定，除非新绑定已经保存；监听只有在之前正在运行时才会恢复。

蓝牙耳机¶

蓝牙耳机无法同时播放高质量音频（A2DP）和使用其麦克风。当任何应用从耳机麦克风录音时，PipeWire（WirePlumber）或耳机会将其切换到免提配置文件（HFP/HSP）：双向均为单声道、通话质量的音频。这就是蓝牙音频的工作方式，不是 Hex 的选择；耳机切换回来的速度取决于耳机和 WirePlumber 的设置。

如果 Hex 从耳机麦克风录音，在不听写时关闭麦克风 选项在开启和关闭时会有不同的权衡：

开启时，只有在你按下快捷键时才会打开麦克风，因此每次听写都会让耳机切换到免提模式再切回。切换期间播放会中断或暂停，麦克风打开的时间也会更长，因此前几个字可能会丢失。
关闭（默认）会保持麦克风打开，因此只要 Hex 在监听，耳机就会一直处于免提模式，播放音质为通话质量。

推荐的设置是使用单独的麦克风输入（笔记本电脑内置麦克风或 USB 麦克风），蓝牙耳机仅用于输出。在“通用”的 Microphone 列表中选择该麦克风，或将其设为系统默认输入（例如使用 wpctl set-default），这样就不会有任何操作去打开耳机的麦克风。

通用 › 高级中的蓝牙选项（avoid_bluetooth_microphone，默认开启）只能部分解决问题：

它仅在麦克风为系统默认且默认输入是蓝牙耳机时生效。你在设置中或通过 --device 选择的蓝牙麦克风始终会按其名称使用。
它还需要另一个不会被报告为已拔出的硬件输入，以及 pactl（PipeWire 的 PulseAudio 服务器或 PulseAudio）来迁移音频流。如果没有其他输入，Hex 会从耳机录音。
在 Linux 上，Hex 只能打开 ALSA 的默认设备（即蓝牙源），然后将其自身的音频流移动到另一个麦克风。音频流会先在耳机上短暂停留，因此耳机仍可能切换到免提模式，而 Hex 不会将配置文件切回。强制耳机的配置文件由你的声音设置决定。
它只改变 Hex 自身的录音，不会影响其他应用程序或系统默认设置。

要完全避免切换，请使用上文推荐的设置。

快捷键¶

Hex 通过三种方式之一获取其快捷键，所有方式都驱动相同的听写规则：

X11： Hex 获取设置中记录的快捷键。
Wayland 与 GlobalShortcuts 门户（例如 niri 搭配 xdg-desktop-portal-gnome、GNOME 或 KDE）：Hex 向桌面请求设置中记录的快捷键。桌面来决定：可能授予这些快捷键、分配另一个按键，或拒绝某个已被它或另一绑定使用的按键。设置会在桌面快捷键下列出桌面授予的快捷键，并对任何被拒绝的快捷键显示错误。当你录制新快捷键时，桌面可能保留较旧的绑定（KDE 就是这样）；在其门户支持的情况下，桌面快捷键 > 打开会显示桌面自己的 Hex 快捷键对话框，设置会跟随你在其中所做的选择。KDE 会在“Global Shortcuts Requested”对话框中询问一次；Hex 会等待你的回答，如果你取消，KDE 会在 Hex 下次绑定快捷键时再次询问。Hex 的快捷键列在系统设置 › 键盘 › 快捷键中的 Hex 下。门户通过 Hex 的应用 ID anomaly.hex、已安装的 anomaly.hex.desktop 条目以及检查 Hex 进程来识别 Hex。下载的可执行文件没有条目，因此 Hex 会写入一个最小的 ~/.local/share/applications/anomaly.hex.desktop 来运行它（受管安装会替换它）；如果门户仍然找不到它，请使用 systemctl --user restart xdg-desktop-portal 重启门户。直接运行 hex service：一个 setgid 包装器（如 newgrp，曾用于授予输入设备访问权限）会使门户拒绝 Hex。桌面将按键传递给 Hex，而不是聚焦的应用程序。在 GNOME 和 KDE Plasma 上，新环境使用 Ctrl+Alt+Space 进行听写，因为 GNOME 将 Alt+Space 保留给窗口菜单，Plasma 保留给 KRunner；当快捷键使用了 GNOME 为自己保留的按键时，设置会发出警告。你在 GNOME 设置 › 键盘中更改的按键会立即生效，Hex 的设置和 hex status --json 会显示它们。Annotate 的快捷键（默认 F9）位于通用中的听写快捷键之下。禁用（通用或托盘）会让 Hex 在重启后保持禁用，直到你重新启用。在 GNOME 上，禁用还会从设置 › 键盘 › 全局快捷键中移除 Hex 的条目；启用后又会要求你再次批准它们。Hex 还会移除 anomaly.hex 之前的版本在 hex ID 下留下的重复列表。
Hyprland 有门户，但它会接收每个快捷键而不分配按键，因此在你的配置中绑定按键之前不会发生任何事，设置中记录的按键也不会被使用。Hex 无法判断你的配置是否绑定了它。最好使用不带修饰键的按键，因为 Hyprland 会把你仍然按住的每个修饰键一并加入 Hex 的粘贴内容（参见原生 Wayland 要求）。绑定中也要避免 Alt：Hyprland 会接收按键（Space），但会让 Alt 传递给聚焦的窗口，因此带有隐藏菜单栏的 Electron 应用（Slack、Discord、VS Code）会看到 Alt 被单独按下并释放，将焦点移到其菜单，粘贴内容就会落在那里而不是消息框（#1023）。Hex 仍会将粘贴记录为已发送。Ctrl+Space 或不带修饰键的按键可以正常工作。Hyprland 将每个快捷键命名为 anomaly.hex:<shortcut>：anomaly.hex:dictation、anomaly.hex:paste-last、anomaly.hex:capture（Annotate）和 anomaly.hex:raw-dictation（不经过处理的 Dictate）。当你在设置中录制另一个按键时，这些名称保持不变（#1376），因此绑定会继续工作；hyprctl globalshortcuts 在 Hex 运行时列出它们。例如：

hl.bind("End", hl.dsp.global("anomaly.hex:dictation"))
hl.bind("F10", hl.dsp.global("anomaly.hex:paste-last"))

传统的 Hyprland 配置写作 bind = , End, global, anomaly.hex:dictation。早期构建会把录制的按键放入名称中（anomaly.hex:dictation-ALT-space），而绑定到 hex:dictation 或 hex:paste-last（在 Hex 的应用 ID 成为 anomaly.hex 之前的名称）则更旧；现在这两者都不再起作用，因此请替换它们。移除任何 cancel-dictation 绑定：Hex 不再有该功能。Hyprland 0.56 的 Lua 绑定在修饰键先于按键释放时（Alt 先于 Z）不会发送释放事件；0.57 修复了这个问题。在 0.56 上，Toggle 不受影响：下一次按下仍会完成操作。在 Hold 模式下，录音会持续到下一次按下并释放为止，因此请先松开按键，或改用 Toggle。对于不依赖门户释放事件的按住说话（hold-to-talk），请改为绑定 Hex 自己的命令（如下），例如 bind = , End, exec, hex dictation start 配合 bindr = , End, exec, hex dictation stop，或者单个 bind = , End, exec, hex dictation toggle。要向终端粘贴，需要 终端粘贴快捷键（Ctrl+Shift+V），除非终端接受 Ctrl+V。

没有门户的 Wayland（例如 Sway）：没有任何东西注册全局快捷键。设置会列出这些命令；请在你桌面自己的键盘配置中绑定它们：

hex dictation start     # bind to a key's press: start recording
hex dictation stop      # bind to the same key's release: stop and transcribe
hex dictation toggle    # one key: start, then stop and transcribe
hex paste-last          # paste the last dictation again
hex dictation toggle --raw  # dictate without processing: paste the words as heard

例如，在 Sway 中按住 F9 进行听写，以及在任意仅通过按键运行命令的桌面环境中进行切换：

bindsym F9 exec hex dictation start
bindsym --release F9 exec hex dictation stop
bindsym Ctrl+Alt+d exec hex dictation toggle

GNOME 46 及更早版本（Ubuntu 24.04）没有快捷键门户。在那里，设置 › 桌面快捷键 › 添加 GNOME 键盘快捷键 会将 Hex 自己的条目写入 GNOME 设置 › 键盘 › 自定义快捷键，包含你的快捷键：hex dictation toggle（GNOME 仅在按键按下时运行自定义快捷键，因此听写是切换式的）、hex paste-last，以及当 Annotate 开启时的 hex annotate toggle。Hex 会在自身被禁用时移除这些条目，并在你启用它时恢复它们；移除会永久删除它们。你在 GNOME 设置中更改的按键保持不变。Hex 从不触碰你的其他自定义快捷键。

hex dictation stop --print 以相同方式停止，然后最多等待 60 秒，并将转录文本写入 stdout，而不是粘贴它，经历了与粘贴相同的处理过程。只有该命令会等待；监听器会立即停止录音，因此后续的 start 不会被阻塞。没有语音时退出码为 4 且不打印任何内容；失败、取消或超时则不打印任何内容、退出码为 1，并且绝不粘贴。历史记录将文本保留为 Printed，并且 Paste Last 会跳过它。参见 docs/cli.md。

这些命令可以安全地绑定到任何地方，包括 X11 上存在抓取的情况。它们与正在运行的 Hex 通信，绝不会启动它：如果没有正在运行的 Hex，或 Hex 未在监听，它们会打印一行错误并以非零状态退出。在录音时启动、在空闲时停止都不会有任何效果，因此按键重复是无害的。启动和停止会绕过 Hold、Toggle 和双击：启动即录音，停止即结束。按下快捷键也能结束由命令启动的录音。

在 X11 上，Hex 仅在 Annotate 绘制期间抓取 Escape，此时按 Escape 会停止绘制。如果另一个应用程序持有该键，绘制会继续，Hex 会记录一次日志。

录音声音默认以 50% 音量启用，包括从旧设置升级时也是如此。当快捷键开始捕获时，会立即排队播放开始声音；停止声音表示保留录音的结束（而不是完成转录或粘贴）；取消声音确认活动捕获已被取消。短暂的按键仍会播放开始声音，但短于 300 毫秒的录音仍会被丢弃，且不播放停止声音。设置中的 声音音量 提供关闭、25%、50%、75% 和 100%；更改会立即保存，无需重启监听器，并预览开始声音（除非设为关闭）。hex dictate 使用相同的已保存音量。播放使用默认音频输出，通过有界后台工作线程进行；音频输出不可用不会阻止听写。

关闭窗口后，Hex 在 X11 和 Wayland 上都会继续运行。录音/处理提示条永远不会获得焦点或拦截点击，无论窗口是否打开：它是一个 Rune 覆盖层，在 Wayland 上是 layer-shell 表面，在 X11 上是 override-redirect 窗口。在没有 layer-shell 的 Wayland 合成器（GNOME）上，只有提示条会在 XWayland 上打开，即主显示器上一个具有空输入形状的 X11 窗口；Hex 的其余部分，包括窗口和门户快捷键，仍留在 Wayland 上。它需要窗口的事件循环，因此当窗口无法启动（没有显示器或 GPU）以及在 hex dictate 中时不可用。录制指示器 会将其放在屏幕顶部或底部，或者将其关闭。

对于新安装，插入使用剪贴板和 Ctrl-V。对于需要 Ctrl-Shift-V 的目标，请在设置中启用 终端粘贴快捷键。现有的 X11 设置会保留之前的 Ctrl-Shift-V 行为，直到被更改。目标应用程序必须接受所选的绑定。

粘贴后，Hex 会将之前的剪贴板内容放回去，就像在 macOS 上一样（#391）。在写入转录文本之前，它会在 1 秒内读取剪贴板提供的所有格式（文本、富文本、图像），最多 32 MiB；在粘贴快捷键触发后的 500 毫秒内，这些格式会再次由 Hex 提供，直到其他内容被复制。它只有在没有更新的内容在此期间替换转录文本时才会恢复：例如后来的听写、复制操作或其他应用程序。空剪贴板保持为空。如果剪贴板过大或无法读取，则会让转录文本留在其中，Hex 的日志会说明原因。当自动粘贴失败时，转录文本会留在剪贴板上，以便 Ctrl+V。没有任何机制确认目标已读取粘贴内容，因此一个停滞超过该延迟的目标可能会粘贴已恢复的剪贴板内容（参见 #24）。在 Wayland 上，恢复需要合成器的 ext-data-control 协议（KDE Plasma 6、最近的 wlroots 合成器）或 wlr-data-control（wlroots 合成器、niri、Hyprland）；如果两者都没有，转录文本会留在原处，设置 › 输出会说明情况。

GNOME 两者都不提供。在那里，你可以选择加入实验室 › 在 GNOME 上恢复剪贴板（hex labs on gnome-clipboard-restore，默认关闭）：然后 Hex 会通过 XWayland 读取并恢复剪贴板，GNOME 会将其与 Wayland 应用双向同步。它仅在 XWayland 已经在运行（有 X11 应用打开且设置了 DISPLAY）时有效；Hex 永远不会启动 XWayland，否则转录文本会留在原处，日志会说明原因。同样的规则适用：更新的内容永远不会被覆盖。

在 GNOME 上，Hex 通过 RemoteDesktop 门户进行粘贴；在该会话打开期间，GNOME 会显示其远程控制指示器。Hex 会在最后一次粘贴后 15 秒关闭该指示器，并在下一次粘贴时使用你已批准的授权重新打开它，因此你只需被询问一次。

原生 Wayland 要求¶

在启动环境中导出合成器的非空 WAYLAND_DISPLAY。即使同时存在 XWayland 的 DISPLAY，Hex 及其窗口（winit）也会选择相同的原生后端。仅凭 XDG_SESSION_TYPE 并不会选择 Wayland。
安装 wl-clipboard。Hex 复制每一份转录文本，然后通过两条通用路径之一发送 Ctrl+V（终端粘贴时为 Ctrl+Shift+V），路径在首次粘贴时选定：
- 当合成器提供虚拟键盘协议（zwp_virtual_keyboard_manager_v1；wlroots 合成器和 niri）且已安装 wtype 时，使用 wtype。
- 否则使用桌面的 RemoteDesktop 门户（org.freedesktop.portal.RemoteDesktop；KDE、GNOME）。首次粘贴会要求你允许 Hex 控制键盘；Hex 保存门户的恢复令牌（位于 Hex 数据文件夹中的 remote-desktop-token），因此只会询问一次。你可以在桌面的设置中撤销该授权。
- 如果两者都不可用，听写将失败并显示“已复制到剪贴板；按 Ctrl+V 粘贴”，且转录文本保留在剪贴板上。
  
  没有静默的 XWayland、直接键入、uinput 或特权输入注入后备方案；除 HUD 外，唯一会使用 XWayland 的场景是上文的可选剪贴板恢复和下文的可选浮动会议胶囊。转录文本通过 stdin 传输，而非命令行参数。
覆盖层使用 layer-shell。没有该协议时（例如 GNOME），只有 HUD 会在 XWayland 上作为 override-redirect、点击穿透且不获取焦点的窗口打开。会议胶囊会接收点击，因此在 GNOME 上，来电通知会改为打开会议窗格，除非你在 Labs › Floating meeting capsules 中选择启用（hex labs on gnome-meeting-capsules，默认关闭）。启用后，来电和录制胶囊会悬浮在通话之上（XWayland），其按钮接受点击但从不获得键盘焦点。它仅在 XWayland 已经在运行时才能工作；Hex 从不启动 XWayland。如果两者都不可用，设置会报告 HUD 不可用，而不会将普通的获取焦点窗口作为覆盖层呈现。
快捷键来自 GlobalShortcuts 门户，或来自你为 hex 命令配置的按键绑定（Shortcuts）。Hex 不读取任何输入设备，也不需要 input 组成员资格或其他设备权限。如果桌面关闭门户会话，监听器会因错误停止，正在进行的录制会被取消；可从设置或通过 hex start 重新启用。
Hex 无法在 Wayland 上看到哪些键被按下，部分合成器会将按住中的物理修饰键并入其粘贴：在 Hyprland 上，Alt+Z 中仍按住的 Alt 会把 wtype 的 Ctrl+V 变成 Ctrl+Alt+V；绑定到 Ctrl+Alt+V 的粘贴上一条会被 Hyprland 再次捕获，永远无法到达应用。RemoteDesktop 门户也以同样方式共享桌面的键盘。因此，当带修饰键的快捷键要求粘贴时，Hex 会等待其释放（门户的 Deactivated）再加 250 毫秒；若按下后释放一直未发生，则最多等待 2 秒。执行 hex 命令后（其按键绑定对 Hex 不可见），Hex 会等待 250 毫秒。超过该时间仍按住修饰键会改变粘贴内容，因此请绑定不带修饰键的按键（End、F 键），或在转录文本到达前松开修饰键。Hex 在发送粘贴快捷键后就将一次听写记录为已粘贴；它无法确认应用是否接受。将快捷键的 Alt 透传给应用的合成器（如 Hyprland）在 Alt 抬起时还可能打开 Electron 应用的菜单，从而抢走粘贴（见 Shortcuts）。

更新与验证¶

受管安装会在 Hex 启动时及此后每 24 小时检查签名更新，直到有可用更新为止。Hex 会下载、验证并激活可用的更新，然后在窗口中提供更新按钮，用于重启单元并重新打开窗口。之后通过 ~/.local/bin/hex 启动也会使用已激活的版本。签名更新路径已经实现，但仍需在受支持的 Arch/i3 主机上完成完整的跨版本验证。

工程契约及剩余验证工作见 plans/linux.md。原生 Wayland 实现基于 PR #28 中提议的功能，并包含独立的输入状态、生命周期和粘贴回归覆盖。发布之前，物理设备、合成器和目标应用的冒烟测试仍然是必要的。

scripts/test-wayland-paste.sh /path/to/compiled-test-executable /path/to/hex 会在隔离的无头 Sway 合成器下，针对 GTK 目标运行真实的粘贴辅助程序。它的第一次粘贴在另一个虚拟键盘按住 Ctrl 和 Alt 时运行。随后，它会检查粘贴后之前剪贴板的每种格式是否都恢复，以及空剪贴板是否保持为空。它还会启动一个隔离的 Hex，通过第二个 hex app 打开其窗口（该窗口必须属于同一进程），在窗口打开时重复粘贴，然后关闭窗口，检查同一进程是否仍然响应，再次打开窗口（HEX_WAYLAND_REOPEN=0 跳过此步），最后退出。它需要 GTK 开发库、Sway、wl-clipboard、wtype、dbus-run-session 以及 Vulkan 驱动（Mesa 的软件驱动即可），并且必须以非 root 用户身份运行。它使用隔离的应用数据，不使用麦克风；CI 会将其与无显示套件和 Xvfb 热键测试一起运行。

scripts/test-linux-dictation.sh /path/to/hex /path/to/parakeet-unified-en-0.6b-Q8_0.gguf /path/to/jfk.wav 使用私有的 PulseAudio 虚拟麦克风和 Xvfb 显示，检查完整的 X11 应用听写路径。它通过第二个 hex app 在运行中的 Hex 中打开窗口，重放 whisper.cpp 的公开 JFK 示例，按住并释放真实快捷键，在 GTK 编辑器中验证转写出的单词，并检查应用是否有序关闭以及麦克风是否释放。它需要 PulseAudio、其 ALSA 插件、xdotool、Xvfb、GTK 开发库，以及用于窗口的 Vulkan 驱动（Mesa 的软件驱动即可）。它以普通用户身份使用临时设置运行；不会使用物理音频设备或个人录音。CI 会为此检查下载并验证固定的模型和示例。

python3 scripts/test-linux-service.py /path/to/hex 是一种无显示、无设备的单实例检查：没有 Hex 时命令快速失败，hex start 变成 Hex，第二次启动（start、app --hidden、service、app）会转发并以 0 退出，无显示环境下的窗口请求只有窗口本身会失败，同用户套接字权限，版本 1 客户端收到错误，无效、超大和停滞的帧，崩溃/过期套接字恢复，两个竞争启动最终只会产生一个 Hex，hex quit 排空并移除套接字，使用自定义数据目录时绝不会运行 systemctl。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 hex19/hex