OpenLogi 完全指南基于 Rust 的本地优先 Logitech Options 替代方案【免费下载链接】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/OpenLogiOpenLogi 是一个用 Rust 编写的原生、本地优先的 Logitech Options 替代品通过 HID 与 UVC 协议解锁罗技鼠标、键盘与网络摄像头的完整功能无需账号、无遥测。本文基于官方 READMEdocs/README.ko.md为核心骨架结合仓库源码crates/深入剖析其架构、功能、安装、CLI 使用与配置方法帮助开发者快速上手并理解其底层实现原理。为什么选择 OpenLogi超越 Options 的边界OpenLogi 的设计哲学是「本地优先」local-first所有数据与配置都保存在本机所有功能都通过本地 HID 与 UVC 协议直接与设备通信。官方文档中明确列出了 Options 无法做到而 OpenLogi 可以做到的能力轻量原生使用原生 Rust GPUI 构建无 Electron 等重型运行时。Linux 一等公民Linux 是 OpenLogi 的一级支持平台而 Options 不提供 Linux 支持。任意按钮手势自由指定可以将手势角色赋予任何物理按钮也可以完全关闭手势。纯文本配置所有设置集中在一个 TOML 文件中可以通过任何方式在设备间同步。可脚本化除了 GUI还提供真正的 CLIcrates/openlogi-cli。从源码结构看crates/openlogi-core/src/config/file.rsOpenLogi 的配置系统采用严格 schema 校验拼写错误、废弃字段或超范围字段会导致配置加载失败而不是静默采用默认值这保证了配置的可移植性与可预测性。功能全景从鼠标、键盘到摄像头的完整控制通用能力设备接入方式支持 Logi Bolt 接收器、Unifying 接收器、蓝牙和有线连接并显示电池百分比与充电状态。按钮重映射通过 OS 输入钩子实现内置动作目录 用户自定义键盘快捷键在 TOML 中编写支持独立的短按/长按动作对以及按住直到释放的按键组合用于一键通 push-to-talk¹。应用级配置文件按应用焦点自动切换的配置文件覆盖层macOS WindowsLinux 仅 X11 / XWayland。Litra 照明控制电源、亮度、色温控制可选的跟随摄像头活动的自动开关。¹ Linux 的媒体键动作使用 D-Bus MPRIS少数 macOS 专属动作在 Linux 上没有通用对应会静默无操作。Windows 在可用时会将平台动作映射到原生等效功能。鼠标专属按键捕获与重映射中键、模式切换键、拇指滚轮按键的捕获与重映射中键全平台支持其余取决于设备是否暴露。手势绑定按方向上/下/左/右绑定的手势支持实时捕获可设置在任意支持的按钮上。Actions Ring以光标为中心的八槽位动作覆盖层ShowActionsRing支持按应用布局crates/openlogi-overlay。DPI 控制预设 循环 / 指定预设动作HID 特性0x2201见 crates/openlogi-hidpp/src/feature/adjustable_dpi.rs 与 extended_dpi.rs。SmartShift 滚轮模式切换、灵敏度、永久棘轮面板0x2111见 smartshift_enhanced.rs。原生滚轮反转按设备原生滚动方向反转0x2121支持设备。键盘专属F 键全局重映射与鼠标相同的动作目录外加文本输入、键组合、多步骤工作流等高级用户动作macOS Windows。静态 RGB 照明0x8070/0x8080支持设备见 color_led_effects.rs 与 rgb_effects.rs。摄像头专属即插即用支持所有 Logitech UVC 摄像头Brio、StreamCam、C920 系列等。实时预览仅在观看时打开摄像头离开后完全释放摄像头LED 熄灭。图像控制直接写入 UVC 硬件缩放、对焦、曝光、亮度、对比度、饱和度、锐度、白平衡、色调等支持对焦 / 曝光 / 白平衡的自动模式切换这些设置直接生效于 Meet / Zoom / OBS 等所有使用摄像头的应用。一键配置文件内置默认 / 直播 / 视频通话三种模式 用户自定义快照设置按摄像头保存下次观看时写回硬件。安装指南[!IMPORTANT] 安装前请先退出Logi Options两个应用会竞争 HID 访问权一个接收器同一时刻只能被一方拥有。macOS需 macOS 13 及以上从最新 Release 下载已签名并公证的.dmg将OpenLogi.app拖入/Applications。或使用 Homebrewbrew install --cask openlogi官方 Homebrew cask 是默认安装路径。若要显式追踪 GitHub 最新 Release由aprilnea/tap提供brew tap aprilnea/tap brew install --cask aprilnea/tap/openlogilatest注意openlogi与openlogilatest只能安装其中一个。Linux下载对应发行版的.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 基线。所有 Linux 包都会安装 udev 规则使你的用户无需sudo即可访问/dev/hidraw*、/dev/uinput以及罗技鼠标的/dev/input/event*节点。安装后为用户启用后台代理systemctl --user enable --now openlogi-agent.service手动 / 源码安装与没有 systemd 的发行版请参考 docs/INSTALL-linux.md。NixOS 用户可以直接导入仓库的 Flake 模块packaging/linux/nixos-module.nix它会安装软件包、udev 规则并在图形会话中自动启动代理{ inputs.nixpkgs.url github:NixOS/nixpkgs/nixos-unstable; inputs.openlogi { url github:AprilNEA/OpenLogi; inputs.nixpkgs.follows nixpkgs; }; outputs { nixpkgs, openlogi, ... }: { nixosConfigurations.my-host nixpkgs.lib.nixosSystem { system x86_64-linux; # or aarch64-linux modules [ openlogi.nixosModules.default { programs.openlogi.enable true; } ]; }; }; }Windows每个 Release 都附带签名便携版.zip与用户级.msi安装包x86_64 与 arm64。两者都包含 GUIOpenLogi.exe与持有全部设备 I/O 的后台代理openlogi-agent.exe。使用便携版 zip 时两个文件必须放在同一目录否则 GUI 没有可连接的代理。Windows 支持已在 Windows 11 真实硬件有线键盘 Unifying 接收器鼠标上完成端到端验证包括 MSI 安装、原地升级与卸载。代理会显示系统托盘图标显示主窗口 / 退出关闭主窗口后仍可访问应用。要在 Windows 上禁用托盘图标请在 TOML 的[app_settings]块中设置show_in_menu_bar false并重启代理GUI 开关目前仅限 macOS。CLI 使用指南openlogi命令行工具是 OpenLogi 的「真正 CLI」定义在 crates/openlogi-cliopenlogi二进制只是调用 crates/openlogi-cli/src/lib.rs 中run()的薄包装。完整使用说明见 docs/USAGE.md。openlogi list # 已配对设备槽位、代号、类型、在线状态、电量 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。设置OPENLOGI_LOGdebug可在 CLI、GUI 或代理中输出详细追踪日志。资产同步会并发探测assets.openlogi.org、带版本号的 Cloudflare Pages Release 别名以及固定的 jsDelivr npm release 镜像第一个返回有效目录的镜像为该次同步提供全部文件。设置OPENLOGI_ASSETS或传递openlogi assets sync --base URL可使用统一资产源而不是自动镜像选择。从源码看crates/openlogi-cli/src/cmd/mod.rs 中的命令树还包含backlight键盘背光HID0x1982、snapshot抓取一帧摄像头画面为 PNG、camera读写 UVC 图像控制与light独立罗技灯等子命令。CLI 测试crates/openlogi-cli/src/lib.rs验证了参数解析的严格性——例如diag smartshift --sensitivity 0必须解析失败NonZeroU8类型约束、未知背光动作必须被拒绝这保证了 CLI 永远不会意外写入设备。配置详解纯文本 TOML配置文件位置OpenLogi 将设置存储为纯 TOMLGUI 与代理读取同一个文件macOS 与 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 手势所有者布局会在加载时迁移v3 物理设备键转换无法在存在两台相同设备时安全分配旧模型范围的设备设置因此 v2 模型键条目必须手动复制到生成的物理键上。pre-v7 拇指滚轮滚动对在设备与按应用配置文件中都会迁移以保持其原生方向。配置结构schema_version 7schema_version为必需字段当前为7见 crates/openlogi-core/src/config/settings.rs 相关测试 crates/openlogi-core/src/config/tests.rs。selected_device是可选物理设备键。[app_settings]包含全局偏好启动、更新、菜单栏 / 托盘、输入捕获与资产下载开关asset_sourceautomatic、openlogi、cloudflare或fastlylanguage、appearance、device_view_modegrid、list或carousel、可选主题名与可选 UI 圆角smooth_scroll为传统鼠标滚轮输入启用有限动画vertical_scroll_sensitivity1到10014为 1×连续触控板输入保持原生thumbwheel_sensitivity1到10014为 1×[devices.physical-key]包含每设备状态。接收器键形如receiver:receiver-id:slot:number直连、raw-HID 与摄像头设备使用其他生成的键。不要用型号 ID如2b042代替。没有 USB 序列号的摄像头没有唯一的端口稳定身份因此其custom_name键跟随 OS 捕获 ID使两台同型号摄像头保持可区分将其移到另一个 USB 端口可能需要重新命名。常见设备字段custom_name、enabled、dpi、dpi_presets、拇指滚轮灵敏度、滚轮反转与滚动分辨率bindings按钮映射到单个动作、独立的短按/长按动作对或手势方向映射。Thumbwheel是拇指滚轮的电容式轻触——它没有 GUI 控件除非在此绑定否则保持惰性因为滚轮既会报告有意轻触也会报告无意拇指接触per_app_bindings稀疏动作覆盖层键为 macOS bundle id、Linux 应用 ID、小写的 Windows 可执行文件完整路径或exe:filename.exe。Buttons 面板在其 Profile 选择器下编辑这些配置选择器提供代理曾置于前台的应用——这是唯一保证匹配的标识符因为四个平台对应用命名不同在一个命名空间下编写的配置不会在另一个命名空间下匹配。覆盖层每个按钮保存一个动作手势方向映射保存在bindings中action_ring默认与完整的按应用八槽位布局lighting、smartshift、独立light与摄像头控制 / 配置兼容键盘的host_switch_targets与fn_lockidentity与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 ... }绑定会等待按钮的结果而不是按下即触发500ms 前释放触发short按住 500ms 恰好触发一次long之后的释放不会再次触发short。若在任一结果出现前捕获中断、绑定改变或代理关闭则两个动作都不会触发。只能报告瞬时脉冲的输入源回退到short。long本身可以是HoldShortcut此时其组合键从 500ms 阈值起保持按下直到物理释放。长按动作对目前适用于全局设备bindings在 TOML 中编写GUI 只展示其short动作在 GUI 中更改该按钮会用选中的单个动作替换整个动作对。per_app_bindings与keyboard.bindings保持为单动作映射。Actions Ring 条目包裹动作并可添加图标或文字标签Top { action { CustomShortcut CmdShiftP }, icon Keyboard, label Command Palette }ShowActionsRing会被拒绝出现在环槽位内以防止递归环。完整示例配置以下为 docs/config.example.toml 的完整内容按需复制即可# OpenLogi configuration example. Copy only the sections you need. schema_version 7 selected_device receiver:aabbccdd:slot:1 [app_settings] launch_at_login true check_for_updates false auto_install_updates false show_in_menu_bar true capture_mouse_events true smooth_scroll false vertical_scroll_sensitivity 14 auto_download_assets true asset_source automatic language en thumbwheel_sensitivity 14 appearance system ui_scale normal device_view_mode grid # macOS only: openlogi (the signed icon) or prism. app_icon openlogi [devices.receiver:aabbccdd:slot:1] custom_name Office mouse dpi 1600 dpi_presets [800, 1600, 3200] thumbwheel_sensitivity 20 invert_scroll false scroll_resolution high [devices.receiver:aabbccdd:slot:1.bindings] Back BrowserBack Forward BrowserForward # Hold the chord for exactly as long as the physical button is held. MiddleClick { HoldShortcut CtrlSpace } # Release before 500 ms runs short; reaching 500 ms runs long once. DpiToggle { short ShowDesktop, long MissionControl } # The thumb wheels capacitive tap. Inert unless set here; the wheel also # reports taps from incidental thumb contact. Thumbwheel AppExpose [devices.receiver:aabbccdd:slot:1.bindings.GestureButton] Click MissionControl Up MissionControl Down AppExpose Left PreviousDesktop Right NextDesktop [devices.receiver:aabbccdd:slot:1.per_app_bindings.com.microsoft.VSCode] Back Undo [devices.receiver:aabbccdd:slot:1.per_app_bindings.exe:sharex.exe] MiddleClick { CustomShortcut F1 } [devices.receiver:aabbccdd:slot:1.action_ring] enabled true haptics true [devices.receiver:aabbccdd:slot:1.action_ring.default.slots] Top { action Copy, icon Keyboard } Right { action { OpenApplication { path /Applications/Safari.app, display_name Safari } }, icon Applications } Bottom { action ShowDesktop, label Desktop } [devices.receiver:aabbccdd:slot:1.lighting] enabled true color ff0000 brightness 80 [devices.receiver:aabbccdd:slot:1.smartshift] mode ratchet auto_disengage 16 tunable_torque 50 # Put host-switch links on the keyboards physical entry. [devices.receiver:aabbccdd:slot:2] host_switch_targets [receiver:aabbccdd:slot:1] fn_lock false [devices.receiver:aabbccdd:slot:2.bindings] KeySearch MissionControl KeyScreenCapture Sleep # Since schema 5 a device is keyed by what it *is* — unit:hex or # serial:s — rather than by the route it was reached on, so its settings # follow it between its receiver and a cable instead of splitting into two # entries. receiver:… entries above are the pre-5 shape; they are folded onto # an identity key the first time the device is seen online with the GUI running. [devices.unit:6be9d300] dpi 1600 # Every route this device has been seen on. The set of keys is also the index # that identifies the device while it is asleep and only the route is known, # which is why a route with nothing special about it is still written out as an # empty table. [devices.unit:6be9d300.links.receiver:aabbccdd:slot:3] # Capabilities as measured on one link. A device can genuinely expose different # features per transport — a G502 LIGHTSPEED publishes hi-res wheel over its # receiver and not over USB — so this is recorded per link, not per device. [devices.unit:6be9d300.links.direct:046d:c08d.capabilities] buttons true pointer true lighting false scroll_inversion true hires_wheel false # Settings deliberately made different on this link. Anything not overridden # here falls through to the device-level value above. [devices.unit:6be9d300.links.direct:046d:c08d.overrides] dpi 800 # Global function-key remapping, independent of a device. [keyboard.bindings] f1 MissionControl shiftcommandf5 ShowDesktop设备键与链路模型schema 5 关键设计从上述示例可以看到OpenLogi 自 schema 5 起以设备「是什么」unit:hex或serial:s而非「通过什么路由到达」作为设备键因此设置会在接收器与有线之间跟随设备而不会分裂成两个条目。links表记录设备出现过的所有路由——这组键同时是设备休眠期间仅知道路由时的索引因此即使某路由没有特殊配置也会写成空表。能力capabilities按链路记录因为设备可能在不同传输上暴露不同特性如 G502 LIGHTSPEED 通过接收器而非 USB 发布高分辨率滚轮overrides允许在某链路上做出与设备级值不同的设置。Linux 深度安装udev 规则与权限Linux 支持仍在积极开发中。HID 设备枚举支持Logi BoltUSB PID0xC548、Logi UnifyingPID0xC52B等接收器以及蓝牙直连设备。完整说明见 docs/INSTALL-linux.md。前置条件启动 OpenLogi 前先退出Solaar或其他罗技管理器——两个应用会竞争 HID 访问权支持hidraw与uinput模块的内核所有主流发行版均支持systemdudevUbuntu、Fedora、Arch、Debian、openSUSE 等标配预构建包需要 GLIBC 2.35 或更新Ubuntu 22.04 基线OpenLogi 需要三种设备访问权/dev/uinput写权限——创建虚拟输入设备以进行按钮重映射/dev/hidraw*读写权限——向 Bolt 接收器或通过蓝牙配对的设备本身发送 HID 命令鼠标/dev/input/event*节点的读权限——钩子在此抓取指针以捕获按键。蓝牙鼠标需要捆绑规则其事件节点挂在/devices/virtual/misc/uhid下没有 seatlogind不会单独授予 ACL安装捆绑的 udev 规则packaging/linux/udev/70-openlogi.rules无需sudo或组成员身份即可授予活动 seat 用户访问权需要systemd-logindsudo cp packaging/linux/udev/70-openlogi.rules /etc/udev/rules.d/ sudo udevadm control --reload-rules sudo udevadm trigger验证访问应无错误打开# 检查 uinput openlogi-agent --check-uinput 2/dev/null || \ test -w /dev/uinput echo uinput OK # 检查 hidraw 节点 ls -la /dev/hidraw* # 检查鼠标的 event 节点——查找模式中的 ACL或 ACL 中的你的用户。 # 缺少时代理会记录 could not install OS mouse hook。 getfacl /dev/input/event*设备已连接udevadm trigger会重新评估规则但不会在安装规则时已打开的节点上重新授予uaccessACL。若仍被拒绝访问请拔插接收器或鼠标无线设备断电重启让 udev 在重新连接时应用新规则。无 systemd 的系统SysV init、OpenRC将规则文件中的TAGuaccess替换为MODE0660, GROUPinput然后将用户加入input组sudo usermod -aG input $USER # 重新登录使组变更生效GUI 的 设置 → 权限 页面显示实时的Granted/Not granted指示器安装规则后无需重启即可查看。后台代理openlogi-agent必须运行GUI 与 CLI 才能显示已连接的设备。为用户会话启用systemctl --user enable --now openlogi-agent.service或通过 GUI 的 设置 → 常规 → 登录时启动 切换——它会自动将单元写入~/.config/systemd/user/openlogi-agent.service。从源码构建与开发工具链稳定版 RustEdition 2024MSRV 1.98macOSXcode 26 及可选的Metal Toolchain组件GPUI 的gpui_macos构建脚本用它编译着色器LinuxDebian/Ubuntusudo apt-get install libudev-dev gcc g clang libfontconfig-dev libwayland-dev libxkbcommon-x11-dev libx11-xcb-dev libssl-dev libzstd-dev pkg-config打包 macOS DMG 需要create-dmgbrew install create-dmg完整开发工作流见 docs/DEVELOPMENT.md。构建并运行# rustup 安装 rust-toolchain.toml 中固定的稳定工具链 curl --proto https --tlsv1.2 -sSf https://sh.rustup.rs | sh git clone https://github.com/AprilNEA/OpenLogi cd OpenLogi cargo run -p openlogi --release -- list cargo run -p openlogi-desktop --release将 CLI 二进制安装到PATHcargo install --path crates/openlogi无硬件开发 GUIopenlogi-agent-mock从脚本化的内存清单提供真实代理 IPC 契约因此无需连接任何罗技设备即可开发桌面应用cargo run -p openlogi-agent --bin openlogi-agent-mock # 然后在另一个终端 OPENLOGI_DEV_AGENT0 cargo run -p openlogi-desktop该脚本覆盖在线鼠标DPI 与 SmartShift 写入持久化并可读回、电池消耗使轮询驱动的重绘可见、离线鼠标、支持照明的键盘、直连设备以及完整的 Bolt 配对流程发现 → 口令 → 已配对。这只是开发工具永远不会被打包。项目布局crates/ openlogi/ openlogi 二进制——openlogi-cli 的薄包装 openlogi-core/ 类型、配置TOML、路径、按钮 动作目录——无 HID、无异步 openlogi-inject/ OS 输入合成CGEvent、uinput/MPRIS、SendInput openlogi-hidpp/ vendored HID 协议 crate库名 hidpp openlogi-hid/ 设备发现、HID 读写、基于 async-hid 的控件捕获 openlogi-assets/ 设备渲染注册表 schema 来自 OpenLogi 资产镜像的缓存 HTTP 获取 openlogi-cli/ CLI 实现命令树 run()由 openlogi 二进制调用 openlogi-agent-core/ 共享编排 代理/GUI IPC 契约 openlogi-agent/ openlogi-agent 二进制——持有设备 I/O 与钩子的后台代理 openlogi-hook/ OS 鼠标钩子macOS CGEventTap、Linux evdev/uinput、Windows WH_MOUSE_LL openlogi-ui/ 两个 GPUI 进程共享的表示层环几何/图标、GPUI 资产源、语言协商 openlogi-desktop/ openlogi-desktop 二进制——GPUI gpui-component IPC 客户端 openlogi-overlay/ openlogi-overlay 二进制——以光标为中心的 Actions Ring常见问题与已知限制限制状态Wayland按应用配置文件切换需要 XWaylandWM_CLASS查找使用 X11按钮捕获中键 / 模式切换 / 拇指滚轮目前仅侧键总结OpenLogi 以「本地优先」为核心设计通过 Rust 原生实现、纯 TOML 配置、真正的 CLI 与跨平台macOS / Linux / Windows支持为 Logitech Options 提供了开源替代方案。无论是按钮重映射、手势、DPI、SmartShift、Actions Ring、键盘 F 键重映射、静态 RGB 照明还是 UVC 摄像头控制都可以在 docs/README.ko.md 与 crates/ 源码中找到完整实现。若你正在寻找一个可脚本化、可同步、无账号无遥测的罗技外设管理方案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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考