Wox

简体中文

English

简体中文

English

主题

常见问题

启动和日志

Wox 启动不了，先看哪里？

先打开 core 日志：

平台Core 日志
Windows%USERPROFILE%\.wox\log\wox.log
macOS~/.wox/log/wox.log
Linux~/.wox/log/wox.log

优先看最新的 core 日志。如果 UI 能打开但某个插件失败，再看同一数据目录下的插件日志。

如何重置 Wox？

退出 Wox 后删除用户数据目录：

平台数据目录
Windows%USERPROFILE%\.wox
macOS~/.wox
Linux~/.wox

这会删除设置、已安装插件、插件数据、缓存和日志。

搜索

为什么应用、文件或书签搜不到？

  • 新安装的应用可能需要几秒钟才完成索引。
  • 文件搜索只会返回配置根目录下、且 Wox 有权限读取的路径。
  • 浏览器书签来自受支持的浏览器 profile，浏览器同步可能有延迟。
  • 打开对应插件设置，确认插件处于启用状态。

为什么结果太杂？

明确使用插件关键字。例如 f report 搜文件，cb report 搜剪贴板。全局查询会让多个插件一起回答，这是预期行为。

插件

如何安装下载的 .wox 插件？

双击 .wox 文件。Wox 会打开插件安装界面，由你确认安装、升级、重装或降级。也可以先选中该文件再唤起 Wox，走的是同一套安装器。

Windows 和 Linux 上，安装或更新 Wox 后需要先启动一次，才会注册 .wox 文件关联。

插件安装失败怎么办？

  1. 确认能访问插件商店和插件 release 地址。
  2. 检查插件是否需要 Node.js 或 Python。
  3. 打开 Wox 日志目录，查看最新 core 日志和 plugin host 日志。
  4. 如果刚安装运行时，重启 Wox 后再执行一次 wpm。

如何更新插件？

运行 wpm，选中插件，在有可用更新时执行更新动作。也可以从插件管理器设置中管理已安装插件。

文件搜索

Wox 必须安装 Everything 吗？

不必须。Wox 有自己的 File 插件。在 Windows 上可以开启 Fast Indexing，技术和 Everything 一样，都是读 NTFS 的 MFT 和 USN 日志，因此可以索引整块磁盘，而不必遍历每个文件夹。macOS 和 Linux 仍使用常规的根目录索引。

只有当你想在 Wox 之外也使用 Everything 时，才需要安装 Everything。Fast Index 的设置见 文件搜索。

macOS 文件搜索为什么提示权限？

macOS 可能会限制 Desktop、Documents、Downloads、外置磁盘等位置。若搜索状态或日志提示权限问题，在 系统设置 -> 隐私与安全性 中给 Wox 对应的文件访问权限。

自定义

如何修改主题？

在 Wox 中运行 theme，或打开 设置 -> 主题。

如何修改快捷键？

打开 设置 -> 常规，编辑快捷键字段。快捷键查询、托盘查询和选中热键也在同一页。见 快捷键。

Explorer 去哪了？

文件资源管理器搜索已改名为 快速跳转，触发关键字是 jump。在资源管理器、Finder 或打开/保存对话框中打开 Wox，输入即可跳转。详见 快速跳转。

如何反馈问题？

查询 feedback 可以导出诊断信息、查看崩溃报告、清理日志，或打开 GitHub issue。也可以查询 doctor 做常见配置检查。

Wayland

在 Wayland 下如何使用双修饰键热键或 CapsLock 组合键？

在 Wayland 下，Wox 无法像在 X11 上那样通过显示服务器全局拦截原始按键事件。为了启用双修饰键热键（如 ctrl+ctrl、shift+shift）和 CapsLock 组合键热键（如 capslock+a），Wox 会直接从 Linux evdev 接口读取键盘事件。

所需权限取决于你要使用哪种热键：

双修饰键热键（如 ctrl+ctrl）— 只需要 input 组

这授予对 /dev/input/event* 设备的读权限。Wox 被动监听键盘事件，不会 grab 或重映射键盘。

bash
sudo usermod -aG input $USER

重新登录，然后重启 Wox。

CapsLock 组合键（如 capslock+a）— 需要 input 组，推荐 uinput 组

CapsLock 组合键需要 input 组（evdev 读取权限）来检测组合键。uinput 组不是注册或触发热键的必需条件——它仅在组合键触发后用于恢复 CapsLock 状态并删除多打的组合字符。

当 CapsLock 被用作组合键前缀时，由于 Wox 在 Wayland 下无法拦截原始事件，系统会切换 CapsLock 状态。Wox 通过 uinput 虚拟键盘注入一个 CapsLock 按键事件来撤销这个切换。如果没有 uinput，热键仍会触发，但大小写灯可能被切换，并可能在当前输入框里多输入一个字符。

要启用完整的 CapsLock 状态恢复，请将自己加入 uinput 组：

bash
getent group uinput >/dev/null || sudo groupadd -r uinput
sudo usermod -aG input,uinput "$USER"

然后确保 /dev/uinput 对组可写。许多原版发行版将 /dev/uinput 设为 crw------- root:root，仅加入组还不够——还需要一条 udev 规则：

bash
echo 'KERNEL=="uinput", MODE="0660", GROUP="uinput"' | sudo tee /etc/udev/rules.d/80-uinput.rules
sudo udevadm control --reload-rules

接着加载 uinput 内核模块，并应用设备权限。即使 /dev/uinput 文件已经存在，也不代表模块已加载：

bash
sudo modprobe uinput
sudo udevadm trigger --action=change /sys/class/misc/uinput
sudo udevadm settle

设置开机自动加载，避免重启后设备再次不可用：

bash
echo uinput | sudo tee /etc/modules-load.d/uinput.conf

注销整个桌面会话并重新登录，让新增的组成员资格生效，然后检查：

bash
id -nG
ls -l /dev/uinput
test -w /dev/uinput && echo "uinput writable"

id -nG 应包含 input 和 uinput，设备应显示 crw-rw---- root uinput，最后一条命令应输出 uinput writable。确认后重启 Wox，让它重新检测权限。

遇到错误时：

  • udevadm trigger 报 No such device：先执行 sudo modprobe uinput。检查 /sys/class/misc/uinput 是否存在，再触发上面的 udev 命令；仅创建组或写入规则不会加载模块。
  • modprobe 报 Module uinput not found：检查当前内核是否提供该模块。如果刚升级过内核，先重启到新内核再重试。
  • 设备仍是 root:root 或没有组写权限：检查 udev 规则是否保存正确，重新加载规则、触发设备事件并等待 udevadm settle 完成。
  • 设备权限正确但仍不可写：用不带用户名的 id -nG 检查当前会话的组。新增组后只重开终端可能不够，需要注销桌面再登录；如果只是修改设备权限，则无需重新登录，但仍需重启 Wox。

设置完成后，单独按下 CapsLock 时正常切换大小写；将 CapsLock 用作组合键前缀时，系统的 CapsLock 切换会被自动撤销。普通组合键热键（如 ctrl+space）不受此设置影响，始终通过 org.freedesktop.portal.GlobalShortcuts portal 工作。

注意： 上述系统配置需要 sudo，但 Wox 本身以普通用户运行，无需额外的系统守护进程。在 CapsLock 组合键流程中，Wox 被动读取 evdev 事件，并通过 uinput 恢复大小写状态、删除多打的组合字符。没有 uinput 时热键仍能触发，但这些恢复操作无法完成。

如何在 Wayland 下禁用 Wox 窗口动画？

在 Wayland 下，Wox 的主窗口是 layer-shell 表面（namespace 为 gtk-layer-shell），位于 overlay 层，并不是普通的 XDG 顶层窗口。因此，合成器中针对应用窗口（按 app id 或窗口 class 匹配）的动画规则对 Wox 不生效。要去除打开/关闭/调整大小时的过渡动画，需要配置针对 gtk-layer-shell namespace 的 layer 规则。

Hyprland

在 ~/.config/hypr/hyprland.conf（或对应的 Lua 配置）中添加 layer_rule：

ini
layerrule noanim, gtk-layer-shell

使用 Lua 配置（hyprland.lua）时：

lua
hl.layer_rule({
    name    = "wox-no-anim",
    match   = { namespace = "gtk-layer-shell" },
    no_anim = true,
})

Hyprland 会热重载配置，修改后立即生效。如果 Wox 当前已显示，切换一次让 layer 表面按新规则重新创建即可。

其他合成器

查阅你所使用的合成器文档中对应的 layer-surface 动画选项，并针对 gtk-layer-shell namespace 进行配置。Wox 本身无法从应用内部控制合成器侧的动画。

基于 GPL-3.0 许可发布

版权所有 © 2013-至今 Wox Launcher