OpenLogi 是一款采用 Rust 编写的开源罗技设备管理工具，旨在为用户提供轻量、隐私优先且无需联网的 Logitech Options+ 替代方案。它通过 HID++ 协议直接与硬件通信，支持按键重映射、DPI 调整、SmartShift 滚轮配置等功能。由于其"本地优先"的设计理念，所有配置均存储在本地 TOML 文件中，不含任何遥测或账号强制要求。

1. 核心特性

• 隐私性：零账号登录，零数据上传。
• 跨平台支持：原生支持 macOS (13+)、Windows (10/11) 以及 Linux。
• 灵活配置：支持基于应用的特定配置（Per-app Bindings）及长短按区分。
• 命令行集成：提供 openlogi CLI 工具，方便脚本自动化调用。

2. 环境准备与冲突处理

在安装 OpenLogi 之前，必须彻底关闭 Logitech Options+ 或 Linux 下的 Solaar。由于 HID++ 协议通常要求独占设备访问权，多个管理软件同时运行会导致设备识别失败或响应冲突。

3. 多平台安装指南

macOS

推荐使用 Homebrew 进行快速安装：

brew install --cask openlogi

初次启动时，系统会弹出权限请求。请务必在"系统设置"中授予 辅助功能 (Accessibility) 和 输入监控 (Input Monitoring) 权限，否则按键映射功能将无法拦截物理输入。

Windows

Windows 用户可以选择 .msi 安装包或免安装的 .zip 压缩包。若使用免安装版，请确保 OpenLogi.exe 与后台代理进程 openlogi-agent.exe 处于同一目录下。

Linux

OpenLogi 为主流发行版提供了预编译包（要求 GLIBC 2.35+）。安装后，系统会自动配置 udev 规则以确保用户无需 root 权限即可读写 /dev/hidraw。安装完成后，启用用户级服务：

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

4. 按键重映射配置

OpenLogi 的所有修改都会实时持久化到本地的 config.toml 文件中。你可以通过图形界面操作，也可以直接编辑配置文件。

基础映射示例

以下代码展示了如何在配置文件中为特定设备定义按键逻辑。我们将侧键设置为复制/粘贴，并为顶部按键增加长按区分：

# 配置文件路径参考:
# macOS/Linux: ~/.config/openlogi/config.toml
# Windows: %USERPROFILE%\.config\openlogi\config.toml

[devices."usb:046d:c548:slot:1".bindings]
Forward = "Paste"
Back = "Copy"
# 定义复杂动作：短按切换静音，长按打开任务管理器
TopButton = { short = "ToggleMute", long = "TaskView" }

应用感知映射 (Per-app Bindings)

你可以针对不同的应用程序定义不同的按键行为。例如，在浏览器中侧键用于切换标签页，而在 IDE 中用于撤销：

[[devices."usb:046d:c548:slot:1".per_app_bindings]]
match = "code" # 匹配 VS Code
[devices."usb:046d:c548:slot:1".per_app_bindings.bindings]
Back = "Undo"
Forward = "Redo"

[[devices."usb:046d:c548:slot:1".per_app_bindings]]
match = "chrome"
[devices."usb:046d:c548:slot:1".per_app_bindings.bindings]
Back = "PreviousTab"
Forward = "NextTab"

5. 高级硬件参数调优

DPI 与灵敏度

OpenLogi 允许设置多档 DPI 预设，并绑定按键循环切换：

[devices."usb:046d:c548:slot:1"]
dpi_active = 1200
dpi_list = [800, 1200, 2400, 4000]

SmartShift 滚轮控制

对于支持 SmartShift 的鼠标（如 MX Master 系列），你可以精细调节滚轮在棘轮模式（Ratchet）与自由旋转模式（Free-spin）之间的切换阈值：

[devices."usb:046d:c548:slot:1".wheel_settings]
smart_shift_enabled = true
threshold = 30 # 触发自由旋转的力度
default_mode = "ratchet"

6. 故障排查建议

现象	可能原因	对策
无法识别设备	HID 节点被独占	确认已退出 Logi Options+、G Hub 或 Solaar。
映射不生效 (Linux)	udev 权限缺失	尝试重新插拔接收器以激活 /etc/udev/rules.d/ 规则。
配置解析错误	TOML 语法无效	检查日志中的行号提示，OpenLogi 会在 .config/openlogi/backups 中保留历史备份。
输入延迟	代理进程挂起	使用 openlogi diag 检查后台进程通信状态。

7. CLI 常用指令

对于进阶用户，CLI 提供了快速诊断的能力：

• openlogi list：扫描并列出所有已连接的 HID++ 设备。
• openlogi diag features：查询特定设备支持的所有硬件特性。
• openlogi status：查看当前活动的配置 profile 及电量信息。