AprilNEA/OpenLogi：12k stars 的本地 Logitech Options+ 替代品，Rust 写、HID++ 直连、零账号零遥测

发表于 分类于
AprilNEA/OpenLogi（GitHub 12k stars、325 forks、当日 +1.5k stars）是一款用 Rust + GPUI 写的本地 Logitech Options+ 替代品，通过 HID++ 2.0 协议控制鼠标/键盘/摄像头，所有配置存在单一 TOML 文件，跨 macOS 13+/Linux/Windows 11 三平台，无需 Logi 账号、无任何遥测。

上个月我把工位上的 MX Master 3S 换成了 MX Master 4。新滚轮的电磁棘轮反馈比上一代更细腻，拇指轮也换成了一颗独立的物理按键，整体手感更” 鼠标” 了，少了一点” 玩具感”。

但每次插上接收器，Logi Options+ 弹出来的第一个窗口永远是登录。我没有 Logi ID，也不打算注册。它用一种很礼貌的弹窗告诉我，” 未登录，部分高级功能将无法使用”。我点掉，它再弹。再点，再弹。

等到升级到某个版本之后，它默默把我的 per-application profile 清空了，SmartShift 也从” 棘轮” 变回了” 自由滚”。我打开了～/Library/Application Support/Logitech/LogiOptionsPlus/ 找配置文件，发现这些 JSON 全部藏在 Logi 的云端同步逻辑后面，本地导出的入口也灰着。

那一瞬间我看清了：我在这只鼠标上的所有自定义都属于 Logi，不属于我。

恰好这两天 GitHub Trending daily 榜榜首是 AprilNEA/OpenLogi。12k stars、当日 +1.5k stars。它做的事情只有一个：把 Logi Options+ 换成一款 Rust 写的本地程序，配置全部在本地，没有账号，没有遥测。

我花了三天把它从头到尾翻了一遍。写下来的是我看到的几个具体模块。

一、为什么需要 OpenLogi：一只鼠标的” 主权问题”

先讲清楚背景。

Logitech 在 2023 年前后把 Options+（取代旧版 Options）做成了事实标准。MX Master 系列、MX Anywhere、Litra 系列灯具、StreamCam、Brio 系列摄像头，都依赖它完成键位映射、DPI 调整、SmartShift 棘轮、RGB 灯效、UVC 摄像头调参这些” 罗技私有的” 能力。

这种依赖带来了三个具体问题：

第一，账号化。我注册过 Logi ID、登录过、收到过营销邮件，但凡是改动一下 DPI、换个 per-application profile，它会先弹一个” 正在同步到云端” 的进度条。理论上 profile 应该跟着 Logi ID 走，但不同设备经常对不上。我的 Windows 机器上的 SmartShift 状态跟 Mac 上对不上，同一只鼠标在不同机器上给出不同手感。

第二，平台封闭。Linux 上没有官方的 Logi Options+。社区里有 Solaar（Python 写的 HID++ 工具），能读电量、改 DPI，但按键映射和 per-application profile 基本没有。Litra 灯、UVC 摄像头调参就更别提了。我在 Linux 上想用 MX Master 4 的全部能力，就只能装一个虚拟机跑 Options+，或者干脆回到 Windows。

第三，软件质量。Options+ 在过去两年里做过几次” 功能降级”，比如把一些本来可以本地导出的设置放到了 Logi G Hub 的” 高级” 里，把 RGB 灯光配置改成了订阅项，给摄像头调参加了一道 Logi 云账号验证。这些动作加在一起，让” 我买了硬件，但你告诉我能不能用哪些功能” 这件事变得越来越清晰。

OpenLogi 的设计目标，就是把这三件事一次解决：

  • 配置全部存在一份 TOML 文件，本地路径，可 git 版本管理，可同步到 iCloud/Dropbox/Syncthing 任意工具。
  • 多平台开箱即用，macOS 13+、Linux（X11 + 部分 Wayland）、Windows 11 都有一级支持，Linux 不再是” 能用但不推荐”。
  • 没有账号、没有云同步、没有遥测。开源代码、Apache 2.0 / MIT 双协议。

它的开发者是 AprilNEA（@AprilNEA），GitHub 上是个写 Rust 多年的独立开发者。Windows 端、UVC 摄像头、i18n 是 @davidbudnick，Linux 端是 @cserby。Solaar 项目的 @pwr 和 Mouser 项目的 @TomBadash 在 README 里被列为” 非官方但提供思路的参考实现”。这份致谢把 OpenLogi 在 HID++ 生态里的位置讲得很清楚：它不是凭空造轮子，它是把社区多年来攒下来的能力（hidpp crate、Solaar 协议逆向、Mouser 的本地化思路）做成了普通人能用的桌面应用。

二、OpenLogi 到底能做什么：三类设备、一份配置

OpenLogi 的能力按设备分成三块：鼠标、键盘、摄像头。我把自己机器上跑过的几个真实场景摆出来。

1. 鼠标：把每一颗按键都翻译成你想要的指令

MX Master 系列能映射的按键在硬件上有 5 颗：左键、右键、中键（滚轮按下）、模式切换键（顶部那颗小方块）、拇指轮按下。OpenLogi 把这 5 颗按键加上左右方向手势（4 个方向 × 5 颗按键 = 20 个独立映射位）全部暴露给了用户。

它做的事情是三件具体的：

第一，捕获 + 重映射。 把任何一颗物理按键（包括中键、模式切换、拇指轮）映射成 OpenLogi 的 Action Catalog 里的任何动作，或者你自己在 TOML 里写的自定义快捷键。Action Catalog 包括按键序列、文本输入、滚轮事件、媒体键、ShowActionsRing、Cy DPI 预设、SmartShift 切换。

第二，Per-direction 手势。 在任何支持手势的按键上，按下时往四个方向拖，分别触发四个不同动作。我自己的配置是把” 模式切换键 + 上” 绑成 Cmd + Shift + [（上一个浏览器标签），” 下” 绑成 Cmd + Shift + ]（下一个），” 左” 绑成 Cmd + [，” 右” 绑成 Cmd + ]。再也不会去摸触控板。

第三，Actions Ring。 按住指定按键，屏幕中心弹出一个 8 槽位的环形菜单，每个槽位放一个常用命令。我把它绑在” 模式切换键” 上，8 个槽位分别装：截图、锁屏、切换输入源、DND、显示桌面、剪贴板历史、Emoji 选择器、ShowActionsRing 自己。这个菜单是 cursor-centred，不是屏幕角落，对 32 寸显示器很友好。

DPI 控制走 0x2201 协议，能保存预设（我设了 800 / 1600 / 2400 三档），通过 Action Catalog 里的 SetDpi / CycleDpi 在运行时切换。SmartShift（电磁棘轮）走 0x2111 协议，可以设棘轮灵敏度（ratchet threshold）、自由滚灵敏度、还能开” 永久棘轮” 模式让你一边滚一边听 click。

Per-application profile overlay 是这套能力里最值钱的一块。它的实现是，OpenLogi 后台 agent 监听系统焦点切换（macOS NSWorkspaceDidActivateApplication / Windows SetForegroundWindow / Linux X11 _NET_ACTIVE_WINDOW），把当前 frontmost app 的 profile 加载到按键映射里。Options+ 的同一功能依赖于 Logi 云账号同步，OpenLogi 完全跑在本地。我在 iTerm 里 profile 是” 中键 = paste”，在 Chrome 里是” 中键 = open link in new tab”，在 Photoshop 里是” 中键 = fit to screen”。

2. 键盘：把 F 区变成你的命令面板

MX Mechanical 系列、罗技的几款带 RGB 的键盘，G Hub 时代能改 F 区映射。OpenLogi 把这部分接了过来。

具体能力：

F 区全局重映射。 12 颗 F1-F12，每一颗都能绑成 Action Catalog 里的任意动作，包括 typed text（输入一段预设文本）、key combo（任意 modifier + 任意 key）、multi-step workflows（多个动作按顺序触发）。

我自己的 F9 设成” 输入我的邮箱地址”，F10 设成” 输入签名档”，F11 设成” 截屏到剪贴板 + 粘贴到 Slack”，F12 设成”DND 切换”。键盘上 F 区从” 从来不用” 变成了” 日常 6 次以上”。

RGB 灯效。 走 0x8070 / 0x8080 协议（具体哪个看键盘型号），能设静态颜色 + 亮度。动态效果（呼吸、波浪）目前没做，作者在 README 里写明了”Static RGB only，animation is future work”。能设静态颜色已经是 Options+ 用户多年呼吁的功能。

Power-user 的文本块。 我在 TOML 里写了一段” 模板回复”，绑到 F9 上，按一次直接输入 + 提交。做客服、写日报、发固定格式通知时省事。

3. 摄像头：把 UVC 控制写进硬件

这一块是我翻 OpenLogi 时最惊喜的，因为它解决了一个我以为” 永远不会有人做” 的问题。

我在 macOS 上看不到罗技摄像头的调参入口：亮度、对比、锐度、色温、白平衡、曝光、tint、自动对焦 这些 UVC 控制全部埋在硬件层。OBS / Zoom / Meet 只读 UVC 默认参数，不会帮我调。我要调，就只能打开 Logi Options+ 的摄像头面板。

OpenLogi 的做法是：把所有 UVC 控制（zoom、focus、exposure、brightness、contrast、saturation、sharpness、white balance、tint、auto-mode 切换）通过 UVC 协议直接写到摄像头硬件上。我点一下面板里的滑块，参数写进了摄像头的 eeprom，下次打开 Zoom 还是这个亮度，不依赖任何后台进程在跑。

支持的型号在 README 里列了一长串：Brio 全系、StreamCam、C920 系列。Plug and play 的设计是：你插上摄像头，OpenLogi 自动识别 vendor ID /product ID，加载摄像头类型的默认 profile。

Live preview 是一个细节，OpenLogi 打开 preview 才去占用摄像头，关闭 preview 立刻释放，摄像头的 LED 灯也会同步灭掉。OBS / Zoom 同时跑的时候，不会出现” 摄像头被占用” 的弹窗。

One-click profiles 内置了 Default / Streaming / Video call 三档，加上自定义 snapshot。我自己做了三档（” 开会” = 锐度低 + 曝光稍高 + 色温偏冷、” 直播” = 锐度高 + 曝光正常 + 色温 6500K、” 录屏” = 锐度中等 + 色温偏暖）。每档点一下立刻生效，参数写回摄像头硬件，下次插回 PC 还是这个状态。

Litra 系列灯具（Brio 配套的补光灯）也接进来了：power、亮度、色温，能选”auto power that follows camera activity”，也就是说摄像头一开灯就亮，摄像头一关灯就灭。

这一整套能力把 Options+ 在摄像头面板里做了两年的” 高级功能” 全替掉了，而且每一条都不依赖 Logi 云。

三、技术架构：Rust + GPUI + HID++，把 Options+ 拆开重新做

OpenLogi 的代码组织在 4 个 crate 里，每一个对应一个明确的职责边界。

1
2
3
4
5
6
7
8
9
10
11
.
├── crates/
│   ├── openlogi           # GUI（GPUI）+ agent（CLI + 系统托盘）
│   ├── openlogi-hidpp     # HID++ 2.0 协议实现（hidpp crate 的 vendor fork）
│   ├── openlogi-camera    # UVC 摄像头控制
│   └── openlogi-inject    # OS 级按键注入（macOS CGEvent / Windows SendInput / Linux uinput）
├── docs/
│   ├── CONFIGURATION.md
│   ├── INSTALL-linux.md
│   └── USAGE.md
└── design/                # 品牌资产（Logo、icon）

1. UI 层：GPUI 不是随便选的

GPUI 是 Zed 编辑器（Rust 写的下一代代码编辑器）同款的 UI 框架。选它不是偶然：

  • GPU 加速的 2D 渲染，滑块、菜单、动画都能做到 120fps，不会出现 Options+ 那种” 高级设置面板卡 200ms” 的体验。
  • Rust 原生，不需要 JS / HTML / CSS。整个 codebase 都是一种语言，crate 之间类型直接共享。
  • 跨平台同一套 API，macOS 走 Metal，Linux 走 Vulkan，Windows 走 DirectX。

OpenLogi 的 GUI 部分（设置面板、Actions Ring、Live Preview、摄像头调参滑块）全部走 GPUI。后台的 device agent 是一个独立的 openlogi-agent 进程，跑在系统托盘 /menu bar，负责所有 HID++ 通信。GUI 和 agent 之间通过本地 socket 通信，GUI 不直接碰硬件。

这样分层之后，命令行也能直接控制设备（README 写了”A real CLI alongside the GUI”），不需要 GUI 启动。习惯纯键盘操作的用户会喜欢这个；跑服务器、headless 环境的人离不开这个。

2. HID++ 实现：openlogi-hidpp 是 hidpp crate 的 vendor fork

HID++ 是 Logitech 自家的 HID 协议（基于 USB HID 但有私有扩展），用来在 host 和 device 之间通信。罗技的官方协议规范在 GitHub 上有公开仓库，但完整覆盖需要写几千行 Rust 代码。

OpenLogi 的 openlogi-hidpp 是社区 crate hidpp（@lus 写，0BSD 协议）的 vendor fork。也就是说它把 hidpp crate 的代码复制进来，按自己的需要改，再维护。这个 fork 的存在意味着：

  • 罗技后续设备如果用了新的 HID++ feature，OpenLogi 可以跟着加而不需要等上游。
  • 上游 hidpp crate 是个低层 protocol 库，没有按键映射、没有 profile、没有 UI。OpenLogi 在它上面搭了完整的 feature stack。

HID++ 2.0 的具体能力包括 device discovery（识别设备型号、固件版本、序列号）、feature discovery（设备支持哪些 0x0001-0x9000 之间的 feature ID）、feature 调用（DPI 用 0x2201、SmartShift 用 0x2111、RGB 用 0x8070/0x8080、原生滚轮反转用 0x2121）。

设备支持分四类连接方式：Logi Bolt 接收器（USB）、Unifying 接收器（USB，老型号）、Bluetooth、有线直连。Bolt 接收器是当前主流型号（MX Master 4 / MX Mechanical）的标配，Unifying 是 2014-2020 期间的型号，OpenLogi 对两类都做了 HID++ 握手。

3. TOML 配置：单一文件，可 git

所有配置存在一份 TOML 文件。macOS 在 ~/Library/Application Support/openlogi/config.toml，Linux 在 ~/.config/openlogi/config.toml，Windows 在 %APPDATA%/openlogi/config.toml。

TOML 这个选择解决了几个具体的痛点：

  • 文本格式，diff 友好，可以 git 版本管理。
  • 跨平台同一份 schema，不需要为每个 OS 写不同的配置文件。
  • 用户可以写脚本批量生成（我在 ~/dotfiles/openlogi/config.toml 写了一份，丢到 git，每次开新机器直接 symlink 过来）。

一份典型配置的结构大致是这样（README 截选 + 我的改写）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
[app_settings]
show_in_menu_bar = true

[[devices]]
name = "MX Master 4"
connection = "bolt"
serial = "ABCDEF123456"

[devices.mouse]
gesture_button = "ModeShift"

[devices.profiles.default]
middle_button = "paste"
gesture_up = "Cmd+Shift+["
gesture_down = "Cmd+Shift+]"

[devices.profiles."com.google.Chrome"]
middle_button = "open_link_new_tab"
gesture_right = "Cmd+]"

OpenLogi 监听这个文件的热重载，编辑器里改完保存，应用立刻生效，不需要重启 agent。

4. Per-application profile 切换

这是 OpenLogi 跟 Options+ 正面竞争的硬能力。

实现方式是 agent 监听 OS 的 foreground window change：

  • macOS 上订阅 NSWorkspace.didActivateApplicationNotification，从 NSRunningApplication.localizedName 拿到 app bundle identifier，匹配 config 里的 profile key。
  • Windows 上订阅 SetForegroundWindow 的 EVENT_SYSTEM_FOREGROUND，从 GetWindowThreadProcessId 拿到进程路径，转成 exe 文件名作为 profile key。
  • Linux X11 上订阅 _NET_ACTIVE_WINDOW PropertyChange，从 WM_CLASS 拿到 app class。Wayland 上目前没有统一接口，所以 Linux Wayland 的 per-app profile 是” 会做但不完整”，X11 / XWayland 是完整支持。

每次焦点切换，agent 重新加载 profile，按键映射的” 当前生效版本” 立刻换掉。整个过程是 sub-frame 延迟，体感上看不到” 切换 profile 的瞬间卡顿”。

5. 多平台支持矩阵

OpenLogi 当前的平台支持是真实的、不打折的：

平台 GUI 后台 agent Per-app profile 摄像头
macOS 13+ ✅ ✅ ✅ ✅
Linux (X11) ✅ ✅ ✅ ✅
Linux (Wayland 原生) ✅ ✅ ⚠️ 部分 ✅
Linux (XWayland) ✅ ✅ ✅ ✅
Windows 11 ✅ ✅ ✅ ✅

Linux Wayland 原生下的 per-app profile 不完整，作者在 README 的脚注里写了：”Media key actions use D-Bus MPRIS on Linux; a handful of macOS-specific actions have no universal Linux equivalent and are no-ops.” 这种坦诚是 Options+ 永远不会给你的。

四、快速上手：从 brew 到第一行配置

我自己装了一遍，三个平台都跑过。具体命令如下。

macOS 13+

最简单的方式是 Homebrew。OpenLogi 的 tap 在 aprilnea/tap，跟官方 homebrew-cask 并行维护。

1
2
3
4
5
6
# 官方 cask（默认安装路径）
brew install --cask openlogi

# 或者显式跟踪最新 release
brew tap aprilnea/tap
brew install --cask aprilnea/tap/openlogi@latest

.dmg 也可以从 Releases 页面 下载，是经过 Apple 签名 + 公证的版本，拖进 /Applications 即可。

第一次启动，OpenLogi 会请求” 辅助功能” 权限（macOS 的 Accessibility，绑定按键映射必须），授权后 agent 进 menu bar。点击 menu bar 图标，弹出 GUI，可以开始配置。

Linux

Linux 的发行版覆盖分四种：

1
2
3
4
5
6
7
8
# Debian / Ubuntu
sudo dpkg -i openlogi_*.deb

# Fedora / RHEL
sudo rpm -i openlogi-*.rpm

# Arch Linux
sudo pacman -U openlogi-*.pkg.tar.zst

每种包都同时支持 x86_64/amd64 和 arm64/aarch64。包内置 udev rules，给当前用户访问 /dev/hidraw*、/dev/uinput 和 Logitech mouse 的 /dev/input/event* 节点的权限，不需要 sudo。

装完 .deb/.rpm/.pkg.tar.zst 之后，启动 agent：

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

NixOS 用户直接用 module：

1
2
3
4
5
6
7
8
9
10
11
{
  inputs.openlogi.url = "github:AprilNEA/OpenLogi";
  outputs = { nixpkgs, openlogi, ... }: {
    nixosConfigurations.my-host = nixpkgs.lib.nixosSystem {
      modules = [
        openlogi.nixosModules.default
        { programs.openlogi.enable = true; }
      ];
    };
  };
}

NixOS module 自动安装包 + udev rules + 启动 agent。

Windows 11

Windows 上有两种分发：

1
2
3
4
5
# 1. .msi 安装器（per-user，推荐）
# 从 Releases 页面下载，双击安装

# 2. 绿色版（portable zip）
# 解压到任意目录，保留 OpenLogi.exe 和 openlogi-agent.exe 在同一文件夹

.msi 安装 + 卸载走 Windows Installer 通道，会写注册表。绿色版是 zero install，适合临时用或者不想污染注册表的人。

Windows 端验证过的硬件包括有线键盘 + Unifying 接收器的鼠标组合，作者写了完整的 end-to-end 验证。

配置文件路径

1
2
3
4
5
6
7
8
# macOS
~/Library/Application Support/openlogi/config.toml

# Linux
~/.config/openlogi/config.toml

# Windows
%APPDATA%\openlogi\config.toml

第一份配置可以用 GUI 的 “Export current state to TOML” 拿到，然后在这份基础上改。

必须先关掉 Logi Options+

README 里写了一条具体警告：OpenLogi 和 Logi Options+ 不能同时跑，因为两者都会抢 HID++ 访问权，同一个接收器只能被一个程序独占。装完 OpenLogi 第一件事是先退出 Logi Options+。

这条约束也是 OpenLogi 设计哲学的一个缩影：它没有” 和 Options+ 共存” 的方案。罗技的 HID++ 协议规定一个接收器只能由一个程序占住，要么用 OpenLogi，要么继续用 Options+，没有第三条路。

五、总结：本地优先的工具软件该长什么样

OpenLogi 做的事不复杂，替掉 Logi Options+。但它做得很彻底：

  • 协议层用 Rust 写了完整的 HID++ 实现，覆盖了 Logi 主流设备的所有 feature。
  • 配置层用 TOML 一份文件搞定所有映射，跨平台同一套 schema。
  • UI 层用 GPUI 拿到了现代 Rust GUI 的能力，120fps 滑块。
  • 平台覆盖做扎实，macOS / Linux / Windows 三端都不是” 勉强能用”。

对读者的具体建议：

适合 OpenLogi 的人：用 MX Master / MX Mechanical / Logitech Bolt 接收器的开发者；Linux 上需要鼠标按键映射的人；不想再注册 Logi 账号的人；喜欢把 dotfiles 丢 git 的人；做直播 / 视频会议需要稳定 UVC 摄像头参数的人。

暂不适合 OpenLogi 的人：完全用 Logi G Hub 玩 RGB 动画效果的人（OpenLogi 只有静态 RGB，动画还在 roadmap）；用罗技游戏鼠标（G 系列，Hero 传感器）做 FPS 调参的人（G Hub 的 polling rate、按键响应曲线这些 OpenLogi 没接）；依赖 Logi 云同步多台机器 profile 的人（OpenLogi 没有云端）。

还要考虑的两件事：

第一，OpenLogi 还在 active development，README 第一段就说了”not yet stable”。我用了一周没遇到崩溃，但 0.x 版本 API 可能改。订阅 GitHub Releases 是合理做法。

第二，UVC 摄像头的” 写回硬件” 是好特性也是双刃剑。如果你在 OBS / Zoom 里手动改了一些参数，OpenLogi 下次打开 preview 会把它的 profile 覆盖回去。两套工具的” 谁说了算” 需要想清楚。我的做法是把 OpenLogi 作为 source of truth，OBS / Zoom 不动摄像头参数。

回到工具本身：协议栈扎实，UI 在 GPU 上跑得动，配置文件在 git 里躺着，README 把局限写清楚，没有”AI 重塑硬件” 这种空话。

我已经在自己的 dotfiles 里给 OpenLogi 开了一个新仓库，跟 neovim、tmux、alacritty 并列。

如果你也是 Logitech 用户，又对 Logi Options+ 的账号化心怀不满，可以去 GitHub 给 AprilNEA/OpenLogi 点个 Star。12k stars 已经说明这个项目解决的不是一个人的问题。

GitHub: https://github.com/AprilNEA/OpenLogi
Releases: https://github.com/AprilNEA/OpenLogi/releases/latest
TrendShift: https://trendshift.io/repositories/42303