故障排查

按症状排查 OpenLogi 的连接、权限、配置和后台服务问题，再提交问题报告。

按下面的症状查找可能原因和已验证的处理步骤。收集诊断信息前，先检查对应的连接、权限或配置步骤。

设备连接和后台服务

设备未显示

**原因：**Logi Options+ 或其他 HID++ 管理器可能独占接收器或设备。

处理：

先退出 Logi Options+，包括其后台代理。
在 Linux 上，也退出 Solaar 和其他 Logitech 管理器。
打开设置（Settings）> 权限（Permissions），检查设备访问状态。
如果设备连接期间安装了 udev 规则，请重新连接接收器或让无线设备重新上电。

无法连接后台服务

**原因：**GUI 无法连接负责设备 I/O 和输入捕获的代理。

处理：

保持 OpenLogi 打开，等待它重试连接。

在 Linux 上，检查并启动用户服务：

systemctl --user enable --now openlogi-agent.service

在 macOS 上，检查下面的登录项处理步骤。
如果问题持续存在，请重新安装 OpenLogi。

设备扫描不可用

**原因：**后台服务无法扫描设备。

处理：

检查需要日志中的代理日志。
检查本页适用的 macOS 或 Linux 权限步骤。
修复访问问题后，重新连接接收器或设备。

macOS 权限

授予辅助功能后按键仍无法重映射

原因：代理需要辅助功能（Accessibility）来捕获系统可见的鼠标按键并执行绑定。

处理：

在 macOS「系统设置」中打开「辅助功能」列表。
启用 OpenLogi Agent，而不是 OpenLogi GUI。
如果条目已存在，请移除该条目，再重新添加 OpenLogi Agent。

已授予输入监控，但仍无法打开设备

原因：读取 HID++ 数据需要输入监控（Input Monitoring），包括蓝牙直连的鼠标。

处理：

退出 Logi Options+ 和其他设备管理器。
确认 OpenLogi Agent 已获得输入监控。
如果访问仍不可用，请退出 macOS 后重新登录。

登录项已在「系统设置」中被关闭（Login item disabled in System Settings）

**原因：**已关闭的登录项会阻止后台代理运行。

处理：

打开 macOS「系统设置」。
打开登录项（Login Items）。
开启 OpenLogi 登录项。

Linux 设备访问和 Wayland

udev 规则没有授予鼠标输入访问权限

**原因：**OpenLogi 需要 /dev/hidraw* 的读写权限。它需要 /dev/uinput 的写入权限。它还需要读取鼠标 /dev/input/event* 节点。其他管理器留下的规则通常只覆盖前两类节点。

处理：

安装 OpenLogi 提供的 udev 规则。参见安装。

重新加载规则并触发 udev：

sudo udevadm control --reload-rules
sudo udevadm trigger

拔下并重新连接接收器，或让无线设备重新上电。
再次检查设置 > 权限。

Flatpak 安装显示为空设备列表

**原因：**Flatpak 无法自行安装所需的主机 udev 规则。

处理：

在主机上安装应用内置规则：

flatpak run --command=cat org.openlogi.OpenLogi \
  /app/share/openlogi/udev/70-openlogi.rules |
  sudo tee /etc/udev/rules.d/70-openlogi.rules >/dev/null

sudo udevadm control --reload-rules
sudo udevadm trigger

重启 Flatpak：
```
flatpak kill org.openlogi.OpenLogi
```
再次启动 OpenLogi。

Wayland 下鼠标配置跟随了错误的应用

**原因：**Wayland 不支持按指针位置选择鼠标配置。OpenLogi 会改为跟随焦点应用。

**处理：**使用绑定前，先让目标应用获得焦点。键盘配置始终跟随焦点，因此不受此限制。

更改和输入捕获

设备离线且更改待应用

**原因：**设备离线时，OpenLogi 无法应用设备设置。

**处理：**重新连接设备。设备重新连接后，OpenLogi 会应用待处理的更改。

没有捕获按键

**原因：**代理只在启动时读取 capture_mouse_events。设为 false 会关闭系统鼠标钩子。DPI 和 SmartShift 等 HID++ 设置仍可使用。

处理：

在 config.toml 中确认已启用此设置：

[app_settings]
capture_mouse_events = true

重启 OpenLogi Agent。
在 macOS 上，为 OpenLogi Agent 授予辅助功能。
在 Linux 上，安装覆盖鼠标事件节点的 OpenLogi udev 规则。

另一个应用正在拦截鼠标输入

**原因：**另一个 macOS 事件拦截器可能导致指针卡顿或按键重复触发。

处理：在设置 > 诊断（Diagnostics）> 输入拦截（Input interception）中识别列出的应用。退出该应用后，再次检查状态。

设备显示两次，或接收器保留旧配对

**原因：**接收器可能在设备不再使用的槽位中保留配对记录。

**处理：**打开当前设备卡片的菜单，选择 Remove old pairings…。这会释放未使用的接收器槽位。它不会移除设备或其设置。如果你之后切换到已移除的通道，请重新配对设备。

配置文件错误

OpenLogi 打开只读错误页面

**原因：**TOML 架构会拒绝未知、过时、格式错误或超出范围的值。OpenLogi 不会静默修改这些值。

处理：

从错误页面打开配置文件夹。
在 config.toml 中修复报告的值。
保存文件后重新启动 OpenLogi。
必要时，检查配置文件旁的 config.toml.backup.1 至 config.toml.backup.5。只恢复你已经审阅的备份。

外部编辑后 GUI 拒绝保存

**原因：**编辑器可能在 GUI 加载文件后修改文件。此时，OpenLogi 会拒绝下一次保存。这样可以避免 GUI 覆盖外部版本。

**处理：**保留外部编辑，然后重新启动 OpenLogi 以加载该版本。不要重试已被拒绝的 GUI 保存。

更新后需要重新启动

OpenLogi 已更新（OpenLogi was updated）

**原因：**更新后，已打开的窗口仍在运行旧版本。

处理：选择重新启动 OpenLogi（Relaunch OpenLogi）。重新启动会加载更新后的 GUI。

日志和问题报告

需要日志

在启动受影响的 CLI、GUI 或代理进程前设置 OPENLOGI_LOG=debug。此设置会启用详细跟踪。CLI 日志会写入 stderr。

代理会写入按日轮转的 agent.<date>.log 文件，并最多保留 7 个文件。

平台	代理日志目录
macOS / Linux	`$XDG_STATE_HOME/openlogi`（默认 `~/.local/state/openlogi`）
Windows	`%USERPROFILE%\.local\state\openlogi`

症状与硬件能力有关时，可使用以下诊断命令：

openlogi diag --help
openlogi diag features
openlogi diag controls

openlogi diag features 会报告活动设备提供的 HID++ 功能。openlogi diag controls 会报告可重新编程的控件。它还会报告能力标志。

报告问题

处理：

在设置中打开关于（About），然后选择复制诊断信息（Copy Diagnostics）。
对受影响设备运行 openlogi diag features。
从复制的诊断信息和命令输出中删除设备 ID 和序列号。
在 OpenLogi 问题跟踪器提交报告。

本页目录