OpenLogi 使用指南用 Rust 打造原生、本地优先的 Logitech Options 替代方案HID 与 UVC 深度解析【免费下载链接】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本文基于仓库中的德语版项目文档 docs/README.de.md并结合openlogi-cli、openlogi-core、openlogi-hidpp等 crate 的源码实现完整介绍 OpenLogi 的定位、功能全景、三平台安装方式、CLI 与明文 TOML 配置。读完本文你将掌握如何在不同操作系统上正确安装并避免与 Logitech Options 冲突、如何用openlogi命令行完成设备盘点与 HID 写入路径的诊断、以及如何通过config.toml精细定制按键、DPI、SmartShift、RGB 与摄像头控制。OpenLogi 是一个用 Rust 编写的原生、本地优先local-first的 Logitech Options 替代品通过 HID 协议与 Logitech 鼠标、键盘、接收器通信并通过 UVC 协议控制 Logitech 网络摄像头。项目不要求注册账号、不收集遥测数据配置文件是纯文本 TOML可跨机器自由同步。需要提醒的是项目仍处于活跃开发阶段功能与配置结构可能继续变化且 Logitech Options 与 OpenLogi 会争夺 HID 设备访问权二者不能同时运行。项目定位Options 之外的另一条路文档开篇即给出了项目的核心主张——受够了 Options试试 OpenLogi并列出 Options 做不到的几件事保持轻量原生 Rust GPUI 实现没有 Electron 级别的运行时开销完整支持 LinuxLinux 在 OpenLogi 中是一等公民平台而非事后移植自由选择手势键可以把手势Gesture角色绑定到任意合适的物理按键也可以彻底关闭手势明文配置全部设置集中在一份 TOML 文件中可以随意在机器间同步可脚本化除了图形界面还提供真正的命令行工具CLI。从仓库结构看项目是一个多 crate 的 Rust workspace核心逻辑位于 crates/openlogi-coreHID 协议实现位于 crates/openlogi-hidpp负责常驻后台的设备 I/O 与输入钩子位于 crates/openlogi-agent桌面 GUI 位于 crates/openlogi-desktopCLI 位于 crates/openlogi-cli。功能全景鼠标、键盘与摄像头通用能力设备接入支持 Logi Bolt 接收器、Unifying 接收器、蓝牙直连与有线连接并能显示电池电量与充电状态按键重映射通过操作系统输入钩子OS input hook拦截并重映射按键内置动作目录Aktionskatalog也支持在 TOML 中自定义快捷键组合应用级 Profile 覆盖按应用App-Fokus自动切换按键配置支持 macOS 与 WindowsLinux 目前仅限 X11 / XWaylandLitra 补光灯控制开关、亮度与色温并可选择自动跟随摄像头活动打开摄像头时自动开灯。鼠标专属能力中键、Mode-Shift 与拇指滚轮Daumenrad的捕获与重映射中键全设备可用其余取决于设备是否提供相应硬件手势按方向绑定支持实时捕获Live-Erfassung可放在任意合适的按键上Actions Ring以光标为中心的八槽位动作浮层对应ShowActionsRing动作支持按应用定制布局DPI 控制预设值 Cycle / Set Preset 动作HID 功能0x2201AdjustableDpi更新的鼠标仅提供0x2202ExtendedAdjustableDpi详见 crates/openlogi-cli/src/cmd/diag/dpi.rsSmartShift 滚轮模式、灵敏度与永久棘轮模式0x2111原生滚动方向反转按设备生效0x2121取决于设备支持。键盘专属能力全局 F 键重映射与鼠标共享同一动作目录另加高级用户动作——文本输入、快捷键组合、多步骤工作流macOS Windows静态 RGB 背光0x8070/0x8080取决于设备支持。摄像头专属能力任何 Logitech UVC 摄像头即插即用Brio、StreamCam、C920 系列等实时预览只在查看时打开摄像头——离开预览即完全释放设备并熄灭 LED图像调节直接写入 UVC 硬件缩放、对焦、曝光、亮度、对比度、饱和度、锐度、白平衡、色相并带对焦 / 曝光 / 白平衡的自动开关设置会作用于 Meet、Zoom、OBS 等任何使用该摄像头的应用一键 Profile内置 标准 / 直播 / 视频通话 三档外加自建快照设置按摄像头分别保存下次查看时自动写回硬件。平台行为差异文档脚注Linux 下媒体键动作走 D-Bus MPRIS部分 macOS 专属动作在 Linux 上没有通用对应物表现为空操作No-opWindows 在可用时会把平台动作映射为原生对应实现。安装指南[!IMPORTANT] 安装与使用前请先退出 Logi Options——两个应用会争夺 HID 访问权一个接收器同一时刻只能属于其中一个。macOS要求macOS 13 或更新。安装方式有两种从最新 Release 下载已签名并公证notarized的.dmg把OpenLogi.app拖入/Applications通过 Homebrew 安装官方 caskbrew install --cask openlogi若希望显式跟踪最新 GitHub Release而非等待官方 cask 的 autobump可通过aprilnea/tap安装brew tap aprilnea/tap brew install --cask aprilnea/tap/openlogilatestopenlogilatest由 OpenLogi 的发布工作流维护可能比官方 cask 的自动更新更早可用。请只安装openlogi或openlogilatest二者之一不要同时安装。Linux从最新 Release 下载.deb或.rpm或使用发行版包管理器# 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两种架构包体基于 GLIBC 2.35 或更新版本Ubuntu 22.04 基线。软件包会自动安装 udev 规则使当前用户无需sudo即可访问/dev/hidraw*与/dev/uinput。安装后为用户启用常驻后台代理systemctl --user enable --now openlogi-agent.service系统单元文件位于 packaging/linux/systemd/openlogi-agent.serviceudev 规则位于 packaging/linux/udev/70-openlogi.rules。需要手动安装、源码编译或使用非 systemd 发行版SysV init / OpenRC时请参见 docs/INSTALL-linux.md——该文档还提供了 NixOS Flake 模块配置、udev 权限验证命令openlogi-agent --check-uinput、getfacl /dev/input/event*以及安装/卸载脚本packaging/linux/install.sh、packaging/linux/uninstall.sh。Linux 平台下 HID 设备枚举支持Logi BoltUSB PID0xC548与Logi UnifyingPID0xC52B等接收器以及蓝牙直连设备。Windows每个 Release 附带已签名的便携版.zip压缩包与按用户安装的.msi安装器x86_64 与 arm64。两者都包含 GUIOpenLogi.exe与后台代理openlogi-agent.exe——全部设备 I/O 归代理所有。若使用便携版请保持两个文件相邻否则 GUI 将没有通信对象。Windows 支持已在真实 Windows 11 硬件上完整验证有线键盘 Unifying 接收器鼠标覆盖安装、就地升级与 MSI 卸载该移植比 macOS 版本新遇到问题可在 Issue 中反馈。关闭主窗口后代理会在通知区域托盘保留图标显示主窗口 / 退出保证应用仍然可达。若想在 Windows 下禁用托盘图标需在 TOML 的[app_settings]块中设置show_in_menu_bar false并重启代理GUI 里的对应开关目前只有 macOS 提供。命令行使用CLIopenlogi命令行工具用于设备盘点、诊断与资产同步完整命令说明见 docs/USAGE.md。文档给出的常用命令openlogi list # 已配对设备slot、代号、类型、在线状态、电量 openlogi assets sync # 从最快的可用镜像预取设备渲染图 openlogi diag features # 导出活动设备上报的全部 HID 功能 openlogi diag controls # 导出可编程控件与能力标志 openlogi diag dpi # 读 → 写 → 读回 → 还原 DPI冒烟测试 openlogi diag smartshift # 切换 SmartShift 并还原冒烟测试 openlogi diag lighting ff0000 # 有线 RGB 键盘纯色背光任意 RRGGBB 十六进制不带子命令运行openlogi时默认执行list。CLI、GUI 或代理中可用OPENLOGI_LOGdebug开启详细日志。从源码看CLI 实际注册的子命令比 USAGE.md 列举的更多。查看 crates/openlogi-cli/src/cmd/mod.rs 可以看到完整枚举list列出连接的 HID 设备与 Logitech 摄像头默认子命令backlight读写键盘背光HID0x1982snapshot从 Logitech 摄像头抓取一帧保存为 PNGcamera读写摄像头设备级 UVC 图像控件assets子命令资产同步diag子命令对真实设备的 HID 写入路径冒烟测试light子命令检查与控制独立补光灯如 Litra。其中diag的子命令定义在 crates/openlogi-cli/src/cmd/diag.rsfeatures转储全部 HID 功能、controls转储0x1b04可编程控件与能力标志、battery读取0x1004/0x1000原始电量报告、dpi读 → 写入小增量 → 读回 → 还原 → 报告、smartshift读 → 切换 → 读回 → 切回、lighting有线 RGB 键盘纯色、wheel读写0x2121滚轮上报分辨率。diag的定位是诊断而非持久配置——它不触碰config.toml不经过 GUI全部走 GUI 同款的openlogi_hidAPI因此 diag 全绿即代表该主机的 GUI 写入路径可用。以diag dpi为例crates/openlogi-cli/src/cmd/diag/dpi.rs它会先用0x2201/0x2202过滤掉不支持的设备如键盘自动选择目标读取当前 DPI 与设备上报的 DPI 列表写入一个目标值后读回校验最后恢复原值并输出✓ DPI round-trip OK。list命令crates/openlogi-cli/src/cmd/list.rs优先读取运行中代理的快照代理才持有设备权限避免二次打开同一 HID 节点无代理可达时直接枚举硬件当既无 HID 设备也无摄像头时返回退出码 2方便脚本区分无硬件与枚举失败。资产同步openlogi assets sync见 crates/openlogi-cli/src/cmd/assets/sync.rs会并发探测多个资产镜像assets.openlogi.org、带版本的 Cloudflare Pages 发布别名、固定的 jsDelivr npm 发布。首个返回有效 catalog 的镜像为整次同步提供全部文件也可用OPENLOGI_ASSETS环境变量或openlogi assets sync --base URL指定统一资产源。同步默认输出到crates/openlogi-desktop/assets支持 sha256 比较的缓存命中跳过并会清理 registry 中已不存在的旧 depot。配置明文 TOMLGUI 与后台代理读取同一份配置文件位置见 docs/CONFIGURATION.mdmacOS 与 Linux$XDG_CONFIG_HOME/openlogi/config.toml通常是~/.config/openlogi/config.tomlWindows%USERPROFILE%\.config\openlogi\config.toml。完整且经过测试的示例位于 docs/config.example.toml建议只复制需要的段落并把其中的示例物理设备键替换为 OpenLogi 为你自己的设备实际生成的键。编辑与恢复机制GUI 采用原子写入并保留config.toml.backup.1至config.toml.backup.5五份备份更新已知字段时保留既有注释与格式Schema 严格拼写错误、已废弃字段、越界值都会导致配置加载失败而不是静默回退默认值或在下一次保存时消失。此时 GUI 会以只读模式打开并显示精确的 TOML 错误修好文件后重新启动即可若 GUI 运行期间配置在外部编辑器中被修改下一次 GUI 保存会被拒绝而不是覆盖外部改动需重启以加载新版本打开 GUI 也会通知常驻代理重新加载当前文件使手改配置与运行时行为立即收敛高于当前构建版本的 schema 会在字段解析前被拒绝v1 绑定映射与 v2–v3 的手势所有者布局会在加载时迁移。pre-v7 的拇指滚轮滚动对会在设备级与应用级 Profile 中迁移以保持原生滚动方向。配置结构schema_version为必填字段当前为7selected_device是可选物理设备键。[app_settings]保存应用级偏好对应源码结构 crates/openlogi-core/src/config/settings.rs启动项、更新检查、菜单栏 / 托盘、输入捕获、资产下载等开关asset_sourceautomatic、openlogi、cloudflare或fastlylanguage、appearancesystem/light/dark、device_view_modegrid/list/carousel、可选主题名与可选 UI 圆角smooth_scroll为传统鼠标滚轮输入启用有限动画vertical_scroll_sensitivity1到10014为 1×触控板连续输入保持原生thumbwheel_sensitivity1到10014为 1×。源码中vertical_scroll_sensitivity只改变滚动距离而thumbwheel_sensitivity还会影响自定义滚轮动作触发的旋转增量阈值见 settings.rs 中action_threshold的计算。值得注意的默认值launch_at_login默认开启否则重映射在重启后静默失效check_for_updates与auto_install_updates默认关闭兑现无遥测、无自动更新轮询的承诺——开启后每次启动仅发一次更新检查请求绝不自动下载。[devices.physical-key]保存每个设备的独立状态。接收器键形如receiver:receiver-id:slot:number直连、raw-HID 与摄像头设备使用其他生成的键。不要用型号 ID如2b042替代物理键。设备公共字段包括custom_name、enabled、dpi、dpi_presets、拇指滚轮灵敏度、滚动方向反转、滚动分辨率bindings一个按键映射到一个动作、独立的短按/长按动作对或一个手势方向映射表其中Thumbwheel是拇指滚轮的电容轻触默认无 GUI 控件未在此绑定前保持惰性——因为滚轮会把无意触碰也上报为轻触per_app_bindings按 macOS bundle id、Linux application id、Windows 小写精确可执行文件路径或exe:文件名.exe键控的稀疏动作覆盖层action_ring默认与按应用的八槽位布局lighting、smartshift、独立light、摄像头控制与 Profile兼容键盘的host_switch_targets与fn_lock以及应用托管的identity与disabled_gestures元数据。[keyboard.bindings]保存全局按键触发如f1或shiftcommandf5。支持的触发修饰键为shift、control、option、command同时接受ctrl、alt、cmd等别名。动作Actions写法动作名即 Rust 枚举变体名的序列化形式包括Copy、BrowserBack、PlayPause、CycleDpiPresets、ShowActionsRing等。带载荷的动作使用单键内联表Back { CustomShortcut CmdShiftP } Forward { HoldShortcut CtrlSpace } MiddleClick { OpenApplication { path ~/Downloads, display_name Downloads } } DpiToggle { short ShowDesktop, long MissionControl }CustomShortcut立即发出一组按下/松开按键事件HoldShortcut按住和弦直到源物理按键松开若捕获被中断、绑定失效或代理关闭也会释放适合按键通话push-to-talk等按住激活场景{ short ..., long ... }绑定等待按键结果而非按下即触发。500 ms 内松开触发short按住满 500 ms 触发一次long之后的松开不再补发short。若在两种结果产生前捕获中断、绑定变化或代理关闭则两个动作都不触发。只能上报瞬时脉冲的信号源回退为short。long本身也可以是HoldShortcut此时其和弦从 500 ms 阈值起保持直到物理松开。长按对目前仅适用于全局设备bindings且需手写 TOMLGUI 展示其short动作若在 GUI 中改动该键整个动作对会被替换为所选单个动作。per_app_bindings与keyboard.bindings保持单动作映射。Actions Ring 条目包装动作并可附加图标或字面标签Top { action { CustomShortcut CmdShiftP }, icon Keyboard, label Command Palette }为防止递归环形菜单ShowActionsRing不允许出现在环形槽位内部。开发与构建开发指引见 docs/DEVELOPMENT.md。源码编译Linux 示例使用稳定版 Rust 工具链cargo build --release -p openlogi -p openlogi-desktop -p openlogi-agent编译后在target/release/下得到四个生产可执行文件二进制职责openlogiCLI——设备盘点、诊断、资产同步openlogi-desktop桌面 GUIopenlogi-overlayActions Ring 浮层辅助进程openlogi-agent后台代理——HID 主循环、输入钩子致谢、许可与商标Windows、摄像头与 i18n由 davidbudnick 贡献——键盘 RGB、Windows 支持、Logitech 摄像头支持Linux 移植由 cserby 完成致敬开源 HID 实现 Solaar 与本地 Options 替代品 Mouser此二处为文档中列出的外部项目仅作致谢引用。代码采用双重许可Apache License 2.0LICENSE-APACHE或 MITLICENSE-MIT二选一。crates/openlogi-hidpp是hidpp© 2026 AprilNEA 保留所有权利不属于上述 MIT / Apache 许可范围详见 design/LICENSE——分叉代码并不授予使用 OpenLogi 名称、Logo 或图标的权利。本项目与 Logitech 无隶属关系Logitech、MX Master、Options 均为 Logitech International S.A. 的商标。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
OpenLogi 使用指南：用 Rust 打造原生、本地优先的 Logitech Options+ 替代方案（HID++ 与 UVC 深度解析）
OpenLogi 使用指南用 Rust 打造原生、本地优先的 Logitech Options 替代方案HID 与 UVC 深度解析【免费下载链接】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本文基于仓库中的德语版项目文档 docs/README.de.md并结合openlogi-cli、openlogi-core、openlogi-hidpp等 crate 的源码实现完整介绍 OpenLogi 的定位、功能全景、三平台安装方式、CLI 与明文 TOML 配置。读完本文你将掌握如何在不同操作系统上正确安装并避免与 Logitech Options 冲突、如何用openlogi命令行完成设备盘点与 HID 写入路径的诊断、以及如何通过config.toml精细定制按键、DPI、SmartShift、RGB 与摄像头控制。OpenLogi 是一个用 Rust 编写的原生、本地优先local-first的 Logitech Options 替代品通过 HID 协议与 Logitech 鼠标、键盘、接收器通信并通过 UVC 协议控制 Logitech 网络摄像头。项目不要求注册账号、不收集遥测数据配置文件是纯文本 TOML可跨机器自由同步。需要提醒的是项目仍处于活跃开发阶段功能与配置结构可能继续变化且 Logitech Options 与 OpenLogi 会争夺 HID 设备访问权二者不能同时运行。项目定位Options 之外的另一条路文档开篇即给出了项目的核心主张——受够了 Options试试 OpenLogi并列出 Options 做不到的几件事保持轻量原生 Rust GPUI 实现没有 Electron 级别的运行时开销完整支持 LinuxLinux 在 OpenLogi 中是一等公民平台而非事后移植自由选择手势键可以把手势Gesture角色绑定到任意合适的物理按键也可以彻底关闭手势明文配置全部设置集中在一份 TOML 文件中可以随意在机器间同步可脚本化除了图形界面还提供真正的命令行工具CLI。从仓库结构看项目是一个多 crate 的 Rust workspace核心逻辑位于 crates/openlogi-coreHID 协议实现位于 crates/openlogi-hidpp负责常驻后台的设备 I/O 与输入钩子位于 crates/openlogi-agent桌面 GUI 位于 crates/openlogi-desktopCLI 位于 crates/openlogi-cli。功能全景鼠标、键盘与摄像头通用能力设备接入支持 Logi Bolt 接收器、Unifying 接收器、蓝牙直连与有线连接并能显示电池电量与充电状态按键重映射通过操作系统输入钩子OS input hook拦截并重映射按键内置动作目录Aktionskatalog也支持在 TOML 中自定义快捷键组合应用级 Profile 覆盖按应用App-Fokus自动切换按键配置支持 macOS 与 WindowsLinux 目前仅限 X11 / XWaylandLitra 补光灯控制开关、亮度与色温并可选择自动跟随摄像头活动打开摄像头时自动开灯。鼠标专属能力中键、Mode-Shift 与拇指滚轮Daumenrad的捕获与重映射中键全设备可用其余取决于设备是否提供相应硬件手势按方向绑定支持实时捕获Live-Erfassung可放在任意合适的按键上Actions Ring以光标为中心的八槽位动作浮层对应ShowActionsRing动作支持按应用定制布局DPI 控制预设值 Cycle / Set Preset 动作HID 功能0x2201AdjustableDpi更新的鼠标仅提供0x2202ExtendedAdjustableDpi详见 crates/openlogi-cli/src/cmd/diag/dpi.rsSmartShift 滚轮模式、灵敏度与永久棘轮模式0x2111原生滚动方向反转按设备生效0x2121取决于设备支持。键盘专属能力全局 F 键重映射与鼠标共享同一动作目录另加高级用户动作——文本输入、快捷键组合、多步骤工作流macOS Windows静态 RGB 背光0x8070/0x8080取决于设备支持。摄像头专属能力任何 Logitech UVC 摄像头即插即用Brio、StreamCam、C920 系列等实时预览只在查看时打开摄像头——离开预览即完全释放设备并熄灭 LED图像调节直接写入 UVC 硬件缩放、对焦、曝光、亮度、对比度、饱和度、锐度、白平衡、色相并带对焦 / 曝光 / 白平衡的自动开关设置会作用于 Meet、Zoom、OBS 等任何使用该摄像头的应用一键 Profile内置 标准 / 直播 / 视频通话 三档外加自建快照设置按摄像头分别保存下次查看时自动写回硬件。平台行为差异文档脚注Linux 下媒体键动作走 D-Bus MPRIS部分 macOS 专属动作在 Linux 上没有通用对应物表现为空操作No-opWindows 在可用时会把平台动作映射为原生对应实现。安装指南[!IMPORTANT] 安装与使用前请先退出 Logi Options——两个应用会争夺 HID 访问权一个接收器同一时刻只能属于其中一个。macOS要求macOS 13 或更新。安装方式有两种从最新 Release 下载已签名并公证notarized的.dmg把OpenLogi.app拖入/Applications通过 Homebrew 安装官方 caskbrew install --cask openlogi若希望显式跟踪最新 GitHub Release而非等待官方 cask 的 autobump可通过aprilnea/tap安装brew tap aprilnea/tap brew install --cask aprilnea/tap/openlogilatestopenlogilatest由 OpenLogi 的发布工作流维护可能比官方 cask 的自动更新更早可用。请只安装openlogi或openlogilatest二者之一不要同时安装。Linux从最新 Release 下载.deb或.rpm或使用发行版包管理器# 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两种架构包体基于 GLIBC 2.35 或更新版本Ubuntu 22.04 基线。软件包会自动安装 udev 规则使当前用户无需sudo即可访问/dev/hidraw*与/dev/uinput。安装后为用户启用常驻后台代理systemctl --user enable --now openlogi-agent.service系统单元文件位于 packaging/linux/systemd/openlogi-agent.serviceudev 规则位于 packaging/linux/udev/70-openlogi.rules。需要手动安装、源码编译或使用非 systemd 发行版SysV init / OpenRC时请参见 docs/INSTALL-linux.md——该文档还提供了 NixOS Flake 模块配置、udev 权限验证命令openlogi-agent --check-uinput、getfacl /dev/input/event*以及安装/卸载脚本packaging/linux/install.sh、packaging/linux/uninstall.sh。Linux 平台下 HID 设备枚举支持Logi BoltUSB PID0xC548与Logi UnifyingPID0xC52B等接收器以及蓝牙直连设备。Windows每个 Release 附带已签名的便携版.zip压缩包与按用户安装的.msi安装器x86_64 与 arm64。两者都包含 GUIOpenLogi.exe与后台代理openlogi-agent.exe——全部设备 I/O 归代理所有。若使用便携版请保持两个文件相邻否则 GUI 将没有通信对象。Windows 支持已在真实 Windows 11 硬件上完整验证有线键盘 Unifying 接收器鼠标覆盖安装、就地升级与 MSI 卸载该移植比 macOS 版本新遇到问题可在 Issue 中反馈。关闭主窗口后代理会在通知区域托盘保留图标显示主窗口 / 退出保证应用仍然可达。若想在 Windows 下禁用托盘图标需在 TOML 的[app_settings]块中设置show_in_menu_bar false并重启代理GUI 里的对应开关目前只有 macOS 提供。命令行使用CLIopenlogi命令行工具用于设备盘点、诊断与资产同步完整命令说明见 docs/USAGE.md。文档给出的常用命令openlogi list # 已配对设备slot、代号、类型、在线状态、电量 openlogi assets sync # 从最快的可用镜像预取设备渲染图 openlogi diag features # 导出活动设备上报的全部 HID 功能 openlogi diag controls # 导出可编程控件与能力标志 openlogi diag dpi # 读 → 写 → 读回 → 还原 DPI冒烟测试 openlogi diag smartshift # 切换 SmartShift 并还原冒烟测试 openlogi diag lighting ff0000 # 有线 RGB 键盘纯色背光任意 RRGGBB 十六进制不带子命令运行openlogi时默认执行list。CLI、GUI 或代理中可用OPENLOGI_LOGdebug开启详细日志。从源码看CLI 实际注册的子命令比 USAGE.md 列举的更多。查看 crates/openlogi-cli/src/cmd/mod.rs 可以看到完整枚举list列出连接的 HID 设备与 Logitech 摄像头默认子命令backlight读写键盘背光HID0x1982snapshot从 Logitech 摄像头抓取一帧保存为 PNGcamera读写摄像头设备级 UVC 图像控件assets子命令资产同步diag子命令对真实设备的 HID 写入路径冒烟测试light子命令检查与控制独立补光灯如 Litra。其中diag的子命令定义在 crates/openlogi-cli/src/cmd/diag.rsfeatures转储全部 HID 功能、controls转储0x1b04可编程控件与能力标志、battery读取0x1004/0x1000原始电量报告、dpi读 → 写入小增量 → 读回 → 还原 → 报告、smartshift读 → 切换 → 读回 → 切回、lighting有线 RGB 键盘纯色、wheel读写0x2121滚轮上报分辨率。diag的定位是诊断而非持久配置——它不触碰config.toml不经过 GUI全部走 GUI 同款的openlogi_hidAPI因此 diag 全绿即代表该主机的 GUI 写入路径可用。以diag dpi为例crates/openlogi-cli/src/cmd/diag/dpi.rs它会先用0x2201/0x2202过滤掉不支持的设备如键盘自动选择目标读取当前 DPI 与设备上报的 DPI 列表写入一个目标值后读回校验最后恢复原值并输出✓ DPI round-trip OK。list命令crates/openlogi-cli/src/cmd/list.rs优先读取运行中代理的快照代理才持有设备权限避免二次打开同一 HID 节点无代理可达时直接枚举硬件当既无 HID 设备也无摄像头时返回退出码 2方便脚本区分无硬件与枚举失败。资产同步openlogi assets sync见 crates/openlogi-cli/src/cmd/assets/sync.rs会并发探测多个资产镜像assets.openlogi.org、带版本的 Cloudflare Pages 发布别名、固定的 jsDelivr npm 发布。首个返回有效 catalog 的镜像为整次同步提供全部文件也可用OPENLOGI_ASSETS环境变量或openlogi assets sync --base URL指定统一资产源。同步默认输出到crates/openlogi-desktop/assets支持 sha256 比较的缓存命中跳过并会清理 registry 中已不存在的旧 depot。配置明文 TOMLGUI 与后台代理读取同一份配置文件位置见 docs/CONFIGURATION.mdmacOS 与 Linux$XDG_CONFIG_HOME/openlogi/config.toml通常是~/.config/openlogi/config.tomlWindows%USERPROFILE%\.config\openlogi\config.toml。完整且经过测试的示例位于 docs/config.example.toml建议只复制需要的段落并把其中的示例物理设备键替换为 OpenLogi 为你自己的设备实际生成的键。编辑与恢复机制GUI 采用原子写入并保留config.toml.backup.1至config.toml.backup.5五份备份更新已知字段时保留既有注释与格式Schema 严格拼写错误、已废弃字段、越界值都会导致配置加载失败而不是静默回退默认值或在下一次保存时消失。此时 GUI 会以只读模式打开并显示精确的 TOML 错误修好文件后重新启动即可若 GUI 运行期间配置在外部编辑器中被修改下一次 GUI 保存会被拒绝而不是覆盖外部改动需重启以加载新版本打开 GUI 也会通知常驻代理重新加载当前文件使手改配置与运行时行为立即收敛高于当前构建版本的 schema 会在字段解析前被拒绝v1 绑定映射与 v2–v3 的手势所有者布局会在加载时迁移。pre-v7 的拇指滚轮滚动对会在设备级与应用级 Profile 中迁移以保持原生滚动方向。配置结构schema_version为必填字段当前为7selected_device是可选物理设备键。[app_settings]保存应用级偏好对应源码结构 crates/openlogi-core/src/config/settings.rs启动项、更新检查、菜单栏 / 托盘、输入捕获、资产下载等开关asset_sourceautomatic、openlogi、cloudflare或fastlylanguage、appearancesystem/light/dark、device_view_modegrid/list/carousel、可选主题名与可选 UI 圆角smooth_scroll为传统鼠标滚轮输入启用有限动画vertical_scroll_sensitivity1到10014为 1×触控板连续输入保持原生thumbwheel_sensitivity1到10014为 1×。源码中vertical_scroll_sensitivity只改变滚动距离而thumbwheel_sensitivity还会影响自定义滚轮动作触发的旋转增量阈值见 settings.rs 中action_threshold的计算。值得注意的默认值launch_at_login默认开启否则重映射在重启后静默失效check_for_updates与auto_install_updates默认关闭兑现无遥测、无自动更新轮询的承诺——开启后每次启动仅发一次更新检查请求绝不自动下载。[devices.physical-key]保存每个设备的独立状态。接收器键形如receiver:receiver-id:slot:number直连、raw-HID 与摄像头设备使用其他生成的键。不要用型号 ID如2b042替代物理键。设备公共字段包括custom_name、enabled、dpi、dpi_presets、拇指滚轮灵敏度、滚动方向反转、滚动分辨率bindings一个按键映射到一个动作、独立的短按/长按动作对或一个手势方向映射表其中Thumbwheel是拇指滚轮的电容轻触默认无 GUI 控件未在此绑定前保持惰性——因为滚轮会把无意触碰也上报为轻触per_app_bindings按 macOS bundle id、Linux application id、Windows 小写精确可执行文件路径或exe:文件名.exe键控的稀疏动作覆盖层action_ring默认与按应用的八槽位布局lighting、smartshift、独立light、摄像头控制与 Profile兼容键盘的host_switch_targets与fn_lock以及应用托管的identity与disabled_gestures元数据。[keyboard.bindings]保存全局按键触发如f1或shiftcommandf5。支持的触发修饰键为shift、control、option、command同时接受ctrl、alt、cmd等别名。动作Actions写法动作名即 Rust 枚举变体名的序列化形式包括Copy、BrowserBack、PlayPause、CycleDpiPresets、ShowActionsRing等。带载荷的动作使用单键内联表Back { CustomShortcut CmdShiftP } Forward { HoldShortcut CtrlSpace } MiddleClick { OpenApplication { path ~/Downloads, display_name Downloads } } DpiToggle { short ShowDesktop, long MissionControl }CustomShortcut立即发出一组按下/松开按键事件HoldShortcut按住和弦直到源物理按键松开若捕获被中断、绑定失效或代理关闭也会释放适合按键通话push-to-talk等按住激活场景{ short ..., long ... }绑定等待按键结果而非按下即触发。500 ms 内松开触发short按住满 500 ms 触发一次long之后的松开不再补发short。若在两种结果产生前捕获中断、绑定变化或代理关闭则两个动作都不触发。只能上报瞬时脉冲的信号源回退为short。long本身也可以是HoldShortcut此时其和弦从 500 ms 阈值起保持直到物理松开。长按对目前仅适用于全局设备bindings且需手写 TOMLGUI 展示其short动作若在 GUI 中改动该键整个动作对会被替换为所选单个动作。per_app_bindings与keyboard.bindings保持单动作映射。Actions Ring 条目包装动作并可附加图标或字面标签Top { action { CustomShortcut CmdShiftP }, icon Keyboard, label Command Palette }为防止递归环形菜单ShowActionsRing不允许出现在环形槽位内部。开发与构建开发指引见 docs/DEVELOPMENT.md。源码编译Linux 示例使用稳定版 Rust 工具链cargo build --release -p openlogi -p openlogi-desktop -p openlogi-agent编译后在target/release/下得到四个生产可执行文件二进制职责openlogiCLI——设备盘点、诊断、资产同步openlogi-desktop桌面 GUIopenlogi-overlayActions Ring 浮层辅助进程openlogi-agent后台代理——HID 主循环、输入钩子致谢、许可与商标Windows、摄像头与 i18n由 davidbudnick 贡献——键盘 RGB、Windows 支持、Logitech 摄像头支持Linux 移植由 cserby 完成致敬开源 HID 实现 Solaar 与本地 Options 替代品 Mouser此二处为文档中列出的外部项目仅作致谢引用。代码采用双重许可Apache License 2.0LICENSE-APACHE或 MITLICENSE-MIT二选一。crates/openlogi-hidpp是hidpp© 2026 AprilNEA 保留所有权利不属于上述 MIT / Apache 许可范围详见 design/LICENSE——分叉代码并不授予使用 OpenLogi 名称、Logo 或图标的权利。本项目与 Logitech 无隶属关系Logitech、MX Master、Options 均为 Logitech International S.A. 的商标。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
