OpenLogi 上手：十分钟完成安装、连接与第一次鼠标按键重映射-开发者社区

OpenLogi 上手：十分钟完成安装、连接与第一次鼠标按键重映射

【免费下载链接】OpenLogi⚡️A native, local-first alternative to Logitech Options+, written in Rust 🦀 — remap buttons, DPI, and SmartShift over HID++. No account, no telemetry.项目地址: https://gitcode.com/GitHub_Trending/op/OpenLogi

罗技鼠标的侧键和 DPI 一直听天由命？OpenLogi 用 Rust 直接走 HID++ 协议在本地接管罗技设备，无账号、无遥测。跟着做完，你能装好它、让设备上线，并完成第一次按键重映射。

看它替你省了什么

不用注册：Options+ 要账号，OpenLogi 的全部设置落在一个本地 TOML 文件里，GUI 每次原子写入，并在旁边保留config.toml.backup.1到config.toml.backup.5共 5 份备份，改错了能回滚
配置即文件：config.toml是明文，想跨机器同步直接拷贝
按钮想绑什么绑什么：内置动作目录加自定义快捷键，短按/长按分开发动作、"按住才触发"都支持
Linux 是一等公民：官方方案在 Linux 上缺位，OpenLogi 提供.deb/.rpm/.pkg.tar.zst
GUI 和 CLI 同一套能力：openlogi list、openlogi diag这类命令可以和图形界面并列使用，方便脚本化排查

开始前 30 秒 ⚠️

系统要求：

macOS 13 或更高
Linux：预编译包需要 GLIBC 2.35+（Ubuntu 22.04 起步），x86_64 与 arm64 均有
Windows：发布包提供 x86_64 与 arm64，README 说明在 Windows 11 上完成了整链路硬件验证

先退出 Logi Options+（Linux 上是 Solaar）再启动 OpenLogi。两者会争夺 HID++ 访问权，同一时刻只有一个程序能"独占"某个接收器，双开会导致设备丢失或功能异常——这是新手最常踩的坑。

装好它

macOS

brew install --cask openlogi

Homebrew cask 是默认安装路径；也可以从最新 release 下载签名.dmg，把OpenLogi.app拖进/Applications。

Linux

sudo dpkg -i openlogi-*.deb # Debian / Ubuntu sudo rpm -i openlogi-*.rpm # Fedora / RHEL sudo pacman -U openlogi-*.pkg.tar.zst # Arch

安装包会自动写入 udev 规则，让你的用户无需 sudo 访问/dev/hidraw*与/dev/uinput。随后启动后台代理：

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

NixOS 配置、源码构建等完整选项见 docs/INSTALL-linux.md。

Windows

Release 提供按用户安装的.msi与免安装.zip。免安装版必须把OpenLogi.exe（GUI）和openlogi-agent.exe（负责全部设备 I/O 的后台代理）放在同一目录，否则 GUI 没有设备数据可连。agent 常驻系统托盘，主窗口关掉后仍可唤回。

让设备上线，并验证连接

macOS：首次启动会请求辅助功能与输入监控权限，点"允许"——按钮重映射依赖这两个钩子
Linux：打开设置 → 权限页面，确认显示Granted；如果设备在 udev 规则装好之前就插上了，重新插拔接收器
验证：终端运行：

openlogi list

你应该看到已配对设备一行一个：插槽、代号、类型、在线状态和电池电量。看到这一行，连接就算通了。

第一次给鼠标按键重映射 🖱️

动作：选中按钮 → 位置：主窗口 → 设备详情 → Buttons 面板 → 结果：显示该按钮当前绑定的动作。点一下你要修改的物理按钮，例如侧键Back。

动作：从动作目录里挑一个 → 位置：绑定选择器 → 结果：选中即生效。目录是内置的：BrowserBack、PlayPause、Copy、ShowActionsRing、CycleDpiPresets等。给侧键选BrowserBack，按下去浏览器应立刻后退——第一次重映射完成。

动作：让同一个按钮两种用法 → 位置：config.toml 中该设备的 bindings → 结果：短按长按各干各的事。配置文件在 macOS / Linux 是~/.config/openlogi/config.toml，Windows 是%USERPROFILE%\.config\openlogi\config.toml。在设备对应段落里写：

DpiToggle = { short = "ShowDesktop", long = "MissionControl" }

500 ms 内松开触发short，按住满 500 ms 触发long一次。GUI 只显示这对绑定里的short动作，改它会整对替换，所以长短按绑定建议直接写 TOML。

动作：中键变"按住说话" → 位置：同一处 bindings → 结果：组合键保持按下直到松手。

MiddleClick = { HoldShortcut = "Ctrl+Space" }

HoldShortcut会把组合键一直保持按下，直到你松开物理按键，天然适合语音开麦。

动作：重载验证 → 位置：重新打开 GUI → 结果：agent 立即加载新文件。打开 GUI 本身就会通知常驻 agent 重载配置，然后按住中键确认组合键生效、松手即断。

进阶：

per_app_bindings让同一按钮在不同应用里做不同动作（macOS + Windows；Linux 仅 X11 / XWayland）
绑定ShowActionsRing后屏幕中央出现 8 个插槽的动作环，支持按应用换布局

完整字段与更多示例见 docs/config.example.toml 和 docs/CONFIGURATION.md。

顺手解锁两件事 ⚡

DPI 预设：在设备详情里设置当前 DPI 并保存多组预设，再把某个按钮绑到CycleDpiPresets，一键循环切换：

[devices."receiver:aabbccdd:slot:1"] dpi = 1600 dpi_presets = [800, 1600, 3200]

SmartShift 滚轮：档位切换、灵敏度调节，棘轮还是自由旋转由你定：

[devices."receiver:aabbccdd:slot:1".smartshift] mode = "ratchet"

卡住了怎么办 🛠️

症状	原因	动作
设备列表是空的	Options+ 还没退出，或接收器被别的程序占用	退出冲突程序，重插接收器，再跑`openlogi list`
Linux 装不上输入钩子	`/dev/uinput`、`/dev/hidraw*`权限没到位	到设置 → 权限核对状态，重新插拔设备
GUI 变只读并报错	TOML 写错了——拼写错误、超范围字段会阻止加载	界面会精确指出错误位置，改好重启即可，必要时用备份回滚
想看设备底层能力	——	运行`openlogi diag features`与`openlogi diag controls`