OpenLogi：用 Rust 重写罗技鼠标管理工具，隐私优先、无需账号

罗技的 Options+ 越来越重——300MB 的 Electron 应用、强制注册账号、后台遥测不断。如果你只是想改个鼠标按键、调个 DPI，凭什么要装这么个庞然大物？OpenLogi 用 Rust 给出了一个干净的答案：5MB 原生二进制、纯本地 TOML 配置、零网络依赖，十天内从 v0.1 冲到 v0.6，GitHub 星标破 4400。

<img src=“openlogi-icon.png” alt=“OpenLogi 官方图标” width=“200” />

一、为什么需要 OpenLogi

用过罗技鼠标的人大概都经历过这个流程：买鼠标 → 装 Options+ → 注册账号 → 等它更新 → 终于能改按键了。整个过程充满了不必要的摩擦：

• 体积膨胀：Options+ 是 Electron 应用，安装包 300MB+，吃内存、占磁盘
• 强制账号：不登录就不让你改按键，你的鼠标配置被绑在罗技的云端
• 遥测收集：后台持续收集使用数据，关闭选项藏得很深
• 更新干扰：频繁弹更新提示，有时候更新完反而出 bug

对于开发者和注重隐私的用户来说，这些都是减分项。而 Solaar 虽然开源，但只支持 Linux，且 GUI 用的是 GTK，功能也比较基础。

OpenLogi 的定位很明确：一个纯本地、轻量、开源的罗技设备管理工具。它通过 HID++ 协议直接与鼠标通信，不经过任何云端服务。

二、HID++ 协议：OpenLogi 的技术根基

要理解 OpenLogi 为什么能做到“纯本地”，得先了解 HID++ 协议。

HID++（Human Interface Device++）是罗技在标准 HID 协议基础上的私有扩展。它允许主机与罗技设备之间交换更丰富的控制信息——比如调整 DPI、切换滚轮模式、重映射按键等。这些功能在标准 HID 协议中是做不到的。

消息格式

HID++ 有两种消息格式：

每条消息包含设备索引、功能 ID、函数 ID、参数等字段。设备通过功能表（Feature Table）暴露它支持哪些能力，主机按需查询。

功能系统

HID++ 2.0 采用功能索引机制：每个功能有一个全局 ID（如 0x2201 是可调 DPI，0x2111 是 SmartShift），设备通过 IRoot（0x0000）功能查询功能表，再用索引号访问具体功能。

OpenLogi 实现了以下关键功能：

三、Rust 九个 Crate 的工程设计

OpenLogi 的代码组织非常清晰，整个项目拆成 9 个 crate，每个有单一职责：

核心层

• openlogi-core：类型定义、TOML 配置读写、39+ 动作枚举、按钮 ID 映射。不涉及 HID 和异步，纯数据层
• openlogi-hidpp：HID++ 协议实现（fork 自 lus/hidpp）。包含消息通道管理、功能注册表、设备抽象
• openlogi-hid：HID 传输层，封装 async-hid 库，负责底层的 HID report 读写

功能层

• openlogi-gui：桌面 GUI，基于 Zed 编辑器的 GPUI 框架（GPU 加速渲染）。提供鼠标示意图、可点击热点、设备轮播、设置窗口
• openlogi-cli：命令行工具，支持 list（列出设备）、资产同步、设备诊断
• openlogi-agent：后台守护进程，通过 tarpc IPC 与 GUI 通信
• openlogi-hook：事件钩子。macOS 上用 CGEventTap 拦截鼠标事件，检测前台应用实现按应用配置切换
• openlogi-assets：设备渲染图管理，从 assets.openlogi.org 拉取并缓存
• brand：品牌资产映射

安全设计

项目在 workspace 级别设置了 unsafe_code = "deny"，只有在 FFI 调用（macOS Dock 通知、CGS 热键等）的受控模块中才允许 unsafe。这保证了大部分代码的安全性。

配置文件是纯 TOML 格式，存储在 ~/.config/openlogi/config.toml，按设备 HID++ ID 分节。你可以手动编辑，也可以用 GUI 修改。

四、实际功能一览

按键重映射

支持 10 个可映射按键（左/右/中/后退/前进/DPI 切换/拇指滚轮/拇指上下/手势按钮），内置 39+ 动作：

• 编辑类：复制、粘贴、剪切、撤销、重做、全选、查找、保存
• 浏览器类：后退、前进、新标签、关闭标签、恢复标签、切换标签、刷新
• 窗口管理：Mission Control、应用 Exposé、桌面切换、显示桌面、启动台
• 媒体控制：播放/暂停、上/下一曲、音量增减、静音
• 系统操作：锁屏、截图、自定义快捷键录制

DPI 控制

通过 HID++ 0x2201 功能直接读写 DPI 预设值。支持循环切换预设、设置特定预设。

SmartShift 滚轮

针对 MX Master 系列的无级滚轮：可以切换棘轮模式（逐格滚动）和自由旋转模式，调节灵敏度阈值。

手势按钮

侧键支持按方向绑定不同动作——上滑、下滑、左滑、右滑、点击各对应一个独立动作。

按应用配置

macOS 上通过 CGEventTap 检测前台应用，自动切换鼠标配置。比如在 VS Code 里后退键映射为“撤销”，在 Chrome 里映射为“页面后退”。

设备发现

支持三种连接方式：Logi Bolt 接收器、蓝牙直连、USB 有线。目前不支持 Unifying 接收器，这是社区呼声最高的功能请求之一。

五、安装与使用

macOS（主力平台）

1
2
3
4
5

# Homebrew 安装（推荐）
brew install --cask openlogi

# 或者最新版 tap
brew tap aprilnea/tap && brew install --cask aprilnea/tap/openlogi@latest

也可以直接从 GitHub Releases 下载签名的 DMG。

Linux（CLI 预览）

1
2
3
4
5
6
7

git clone https://github.com/AprilNEA/OpenLogi
cd OpenLogi
cargo build -p openlogi

# 安装 udev 规则
sudo cp udev/70-openlogi.rules /etc/udev/rules.d/
sudo udevadm control --reload-rules && sudo udevadm trigger

Linux 上目前只有 CLI，GUI 支持还在开发中。CLI 可以列出设备信息、检查电池状态。

从源码构建

1
2
3
4

git clone https://github.com/AprilNEA/OpenLogi
cd OpenLogi
cargo run -p openlogi-gui --release   # GUI
cargo run -p openlogi --release -- list  # CLI

需要 Rust 1.85+，macOS 需要 Xcode 16+。

注意：运行前必须退出 Logitech Options+，两者会冲突（都试图访问 HID++ 设备）。

六、开发速度：十天 v0.1 到 v0.6

OpenLogi 的迭代速度令人印象深刻：

十天时间从零到支持蓝牙、多语言、键盘 RGB、后台守护进程——这个节奏在开源项目里相当少见。

七、局限性

OpenLogi 目前还处于快速迭代阶段，有几个明确的限制：

1. 仅支持 Logi Bolt 接收器：Unifying 接收器不支持，这影响了大量老设备用户
2. Windows 未支持：目前只有 macOS（完整）和 Linux（CLI 预览），Windows 的事件钩子还是 stub
3. 不支持固件更新：如果需要更新鼠标固件，还得装回 Options+
4. 设备类型有限：目前主要支持鼠标，G 系列键盘只支持 RGB 灯光控制
5. 品牌资产受限：design/ 目录下的 logo 和图标是 “all rights reserved”，使用需授权

其中 Unifying 接收器支持是 Issue #185 中讨论最多的话题。考虑到 Unifying 协议与 Bolt 协议的差异，这不是一个简单的适配工作。

八、为什么是 Rust

OpenLogi 选择 Rust 不只是“因为流行”。在这个场景下，Rust 有几个实际优势：

• 内存安全：直接操作 HID 设备需要处理底层 buffer，Rust 的所有权系统能在编译期捕获常见的内存错误
• 零运行时：不依赖 GC 或虚拟机，最终产物是一个 5MB 左右的原生二进制
• 异步生态：Tokio 提供了高效的异步 I/O，适合处理 HID 设备的请求-响应模式
• 跨平台抽象：通过 trait 系统隔离平台相关代码（CGEventTap / uinput），核心逻辑跨平台复用

GUI 框架选用 Zed 的 GPUI 也是一个有意思的选择——GPUI 是 GPU 加速的原生 UI 框架，比 Electron 轻量得多，但生态还不够成熟。OpenLogi 同时依赖了 gpui-component（来自 Longbridge 龙证券的开源组件库），说明 GPUI 生态正在逐步形成。

九、与生态的关系

OpenLogi 的出现不是孤立事件。它反映了开发者工具领域的一个趋势：用现代语言重写老旧的系统工具，追求本地优先、隐私优先。

类似的项目有 jj（用 Rust 重写版本控制理念）、ruff（用 Rust 重写 Python linter）、uv（用 Rust 重写 Python 包管理器）。这些项目的共同点是：不是简单地重写，而是用新的语言特性和工程实践重新思考工具应该怎么设计。

对于罗技用户来说，OpenLogi 提供了一个实际可用的替代方案。虽然它还不能完全替代 Options+（缺少固件更新和 Unifying 支持），但对于只需要改按键和 DPI 的用户，它已经够用了。

相关链接

• GitHub 仓库
• HID++ 2.0 协议规范
• Solaar（Linux 罗技设备管理）
• Zed GPUI 框架