AprilNEA/OpenLogi · 上手攻略

仓库：AprilNEA/OpenLogi
链接：https://github.com/AprilNEA/OpenLogi
分类：ai
作者：Jay
更新：2026-07-12

这是什么

OpenLogi 是一个用 Rust 编写的 Logitech 鼠标/键盘配置工具，目标是替代 Logitech 官方的 Options+ 软件。它完全本地运行（local-first）、无账号体系、不上报遥测数据，配置以明文 TOML 文件存储，支持 macOS、Linux 和 Windows。

核心定位：一个永远属于你的鼠标配置文件——不依赖云端、不被软件更新绑架、不需要注册账号。

注：Windows 支持为"未测试预览"状态（README 原文：untested preview），signed builds 随 release 附带；macOS 和 Linux 为成熟平台。

解决什么问题

Logitech Options+ 是闭源软件，存在几个长期痛点：

强制账号：新版 Options+ 越来越依赖 Logitech 账号登录
遥测数据：官方软件会上报设备使用数据
Linux 缺席：Options+ 根本没有 Linux 版
配置不透明：官方软件用私有格式存储配置，无法版本控制
Electron 负担：部分用户反映官方软件资源占用高

OpenLogi 用纯 Rust + GPUI（Parade 的原生 GPU 渲染 UI 框架）替代 Electron，提供轻量、跨平台、本地优先的体验。

快速安装

macOS（推荐）

方式一：Homebrew（推荐）

brew install --cask openlogi

方式二：手动安装

去 Releases 页面下载 .dmg
拖入 /Applications

⚠️ 前置条件：确保 Logitech Options+ 已完全退出——两个程序同时竞争 HID++ 访问会导致行为异常。

Linux

Debian / Ubuntu：

sudo dpkg -i openlogi_*.deb

Fedora / RHEL：

sudo rpm -i openlogi-*.rpm

包同时发布 x86_64/amd64 和 arm64/aarch64 架构。

安装后启用后台 agent：

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

如需手动或无 systemd 安装，参见 docs/INSTALL-linux.md。

Windows（预览阶段）

从 Releases 下载 portable .zip 或 per-user .msi（x86_64 + arm64 均提供）。

portable zip：解压后需把 GUI（OpenLogi.exe）和 agent（openlogi-agent.exe）放在同一目录，否则 GUI 找不到 agent
MSI：标准 Windows 安装程序，支持升级和卸载
agent 在系统托盘显示图标（"显示主窗口"/"退出"）

⚠️ README 标注 Windows 为 untested preview，核心功能已端到端验证（Windows 11 + 有线键盘 + Unifying 接收器鼠标），但遇到问题请提 Issue。

核心用法

GUI 界面（macOS / Linux）

启动后可以看到：

设备轮播：同时管理多台 Logitech 设备，实时切换
鼠标交互图：点击热区设置按钮动作，直观
DPI 预设：创建预设并绑定到按钮或 SmartShift
SmartShift 面板：滚轮模式切换、灵敏度设置、常驻棘轮模式
应用配置覆盖：焦点切换到特定 App 时自动切换配置文件
设置窗口：开机自启、更新检查、菜单栏显示、语言切换（20 种语言，含中文简繁体）

按钮动作

内置 41 种动作（部分）：

复制/剪切/粘贴/全选（macOS 专属）
Mission Control / Launchpad（macOS 专属，Linux 下为 no-op）
媒体控制（播放/暂停/音量）
DPI 切换（循环预设 / 切换到指定预设）
SmartShift 开关
键盘快捷键（自定义按键序列）
打开 URL / App
手势按钮（上下左右滑动 + 按住可设不同动作）

手勢按钮支持自定义绑定到哪个物理按钮（不只是专用 Gesture Button，也可以绑 middle/back/forward）。

CLI（macOS / Linux）

# 列出已配对设备
openlogi list

# 诊断 HID++ 特性
openlogi diag <device_id>

# 预取设备图标资源（离线可用）
openlogi sync-assets

Windows CLI 尚未成熟。

配置文件格式

OpenLogi 的配置存储在明文 TOML 文件中（路径因平台而异），可以：

直接编辑、版本控制（Git）
多机器同步（复制粘贴即可）
在不同机器间迁移

示例配置结构（详见 CONFIGURATION.md）：

# 每设备一个 [device] 节
# 每个按钮可以绑定内置动作或自定义快捷键

[[actions]]
id = "my-shortcut"
type = "keyboard_shortcut"
keys = ["Cmd", "C"]  # macOS; Linux 为 ["Super", "C"]

[[profiles]]
name = "coding"
app = "Code"  # 自动切换到该 App 时激活此配置
dpi = 800

[[profiles.actions]]
button = "back"
action = "my-shortcut"

详细字段说明参考 CONFIGURATION.md。

典型适用场景

Linux 用户：官方 Options+ 完全不存在，OpenLogi 是目前最完整的替代方案
隐私敏感用户：不想装 Logitech 账号、不想让软件上报数据
配置版本控制：用 Git 管理 .toml 配置文件，换机器一键同步
多设备管理：同时使用多个 Logitech 设备，需要快速切换配置
开发者：CLI + TOML 配置文件可接入自动化（脚本化管理多台机器）

坑与注意

⚠️ 与 Options+ 互斥

同一 HID++ receiver 同时只能被一个程序控制。macOS / Linux 务必先完全退出 Options+（包括后台进程），再启动 OpenLogi。

⚠️ Linux 应用切换仅支持 X11

per-app profile overlay 在 Linux 上仅 X11 支持，Wayland 会话下无法按应用自动切换配置（macOS 正常）。这是因为 X11 有标准的应用焦点 API，Wayland 无等效方案。

⚠️ Linux 部分 macOS 专属动作无等效

Mission Control、Launchpad 等 macOS 特有操作在 Linux 上是 no-op（什么都不做）
Media key actions 在 Linux 上通过 D-Bus MPRIS 实现（需要支持 MPRIS 的媒体播放器）

⚠️ Windows 仍为预览

README 标注 untested preview，生产环境使用可能遇到未记录的问题，请关注 release notes 和 GitHub Issues。

⚠️ 手势按钮硬件捕获尚在开发

当前状态下 side buttons（侧键）可捕获，middle button / mode-shift / thumbwheel 的硬件捕获pending（配置可用，但按键捕获可能不完整）。

⚠️ 更新检查默认关闭

更新检查默认禁用。如需自动提示新版本，在 Settings 中开启 update check（网络请求发送到 GitHub）。

与同类对比

工具	平台	语言	账号/遥测	配置文件	备注
OpenLogi	macOS / Linux / Win	Rust + GPUI	无	明文 TOML	功能完整度高，Rust 实现轻量
Logitech Options+	macOS / Win	闭源 Electron	有	私有格式	官方软件，功能最全但有隐私代价
Solaar	Linux	Python	无	私有格式	Linux 老牌替代，界面较朴素，HID++ 支持深
Mouser	macOS	Swift	无	私有格式	macOS 轻量替代，功能较少

结论：Linux 用户首选 OpenLogi（或 Solaar）；macOS 如果你不需要隐私保护，Options+ 功能更全；如果你想完全掌控配置、避免账号体系，OpenLogi 是目前最值得尝试的方案。

一句话结论

OpenLogi 是 Logitech 外设在 Linux/macOS 上的最强本地替代——Rust 实现轻量无 Electron，明文 TOML 配置可版本控制，无账号无遥测，适合隐私敏感用户和 Linux 玩家；Windows 支持尚在预览阶段。

来源：仓库 README 及文档（https://github.com/AprilNEA/OpenLogi）、docs/INSTALL-linux.md、docs/CONFIGURATION.md、docs/USAGE.md。