OpenLogi 配置指南深入解析 config.toml 的 schema、字段与 Actions 绑定【免费下载链接】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 编写的本地优先local-first鼠标/键盘/摄像头配置工具全部设置以纯 TOML 形式存放在一个config.toml中GUI 与后台 Agent 共享同一份文件。本文以 docs/CONFIGURATION.md 为骨架结合 docs/config.example.toml 完整示例与openlogi-core的源码实现系统讲解配置文件的位置与读写机制、schema 结构、每个字段的取值范围与默认值、Actions 绑定语法以及 v1–v7 的迁移规则。读完本文你将能安全地手工编辑配置文件、理解 GUI 每次保存时发生了什么并正确写出可被加载的单键、长按对、手势方向表与 Actions Ring 布局。配置文件位置三平台统一遵循 XDG 规范OpenLogi 在所有平台包括 macOS 与 Windows上都遵循 XDG Base Directory 规范macOS 与 Linux$XDG_CONFIG_HOME/openlogi/config.toml通常是~/.config/openlogi/config.tomlWindows%USERPROFILE%\.config\openlogi\config.toml注意 macOS 刻意不使用其原生的~/Library/Application Support。这一设计在 crates/openlogi-core/src/paths.rs 中有明确注释说明Decision (#347)是刻意的最终决定而非权宜之计——因为一旦 Agent 已随 Windows 产物发布再迁移位置会让所有存量用户的config.toml与首启状态搁浅。源码层面paths::config_path()由xdg_config_home()拼上openlogi或开发构建的openlogi-dev子目录得到配置、数据、状态与运行时目录分别对应用途环境变量覆盖默认位置配置config.toml$XDG_CONFIG_HOME~/.config/openlogi数据设备渲染资源缓存等$XDG_DATA_HOME~/.local/share/openlogi状态Agent 轮转日志等$XDG_STATE_HOME~/.local/state/openlogi运行时Agent IPC socket—$XDG_RUNTIME_DIR/openlogi在 Windows 上$HOME会回退到%USERPROFILE%因此路径解析为%USERPROFILE%\.config\openlogi等。开发构建OPENLOGI_PROFILEdev或 macOS dev bundle 标识会使用独立的openlogi-dev目录避免开发 Agent 抢占已安装应用的 socket、锁、配置与资源缓存。编辑与恢复原子写入、轮转备份与冲突保护原子写入与 5 代备份GUI 保存配置时采用原子写入atomic write并保留config.toml.backup.1到config.toml.backup.5五份轮转备份。相关逻辑位于 crates/openlogi-core/src/config/file.rsbackup_config_once只会在每个进程生命周期内备份一次BACKED_UP_CONFIGS集合去重backup_existing_config先把旧备份向后顺延一代再把当前文件写入.backup.1。写入通过atomic_write_file完成Unix 下还显式设置0o600权限并关闭preserve_mode。更关键的是备份链不会把旧的.backup.1顺延覆盖.backup.5循环从CONFIG_BACKUP_GENERATIONS-1即 4 开始倒序保证第 15 代各有内容。保留注释与格式GUI 更新已知字段时不会把整个文件重写为机器生成的 TOML。render_config会把新配置序列化为字符串后与磁盘上的原文件做一次toml_edit文档合并reconcile_table/reconcile_item不存在的键被移除值被替换但原有注释、装饰与排版会被保留reconcile_item会从旧值上取下 decor 装饰重新贴到新值上。所以你可以放心在文件里写注释GUI 保存不会抹掉它们。严格 schema错误立即失败而不是悄悄吞掉配置文件的 schema 是严格的拼写错误的字段、已废弃的字段如 v2 之前的button_bindings、gesture_bindingsv3 之前的gesture_owner、超出取值范围的字段都会阻止配置加载而不是静默采用默认值或在下次保存时消失加载失败时 GUI 会以只读模式打开并显示精确的 TOML 错误信息ConfigError::Parse携带行列信息。修复文件后重新启动 OpenLogi 即可。顶层Config与AppSettings、DeviceConfig等均标注了#[serde(deny_unknown_fields)]这正是未知字段硬错误的机制来源。亮度、DPI、SmartShift 阈值等还带有自定义反序列化校验例如亮度超过 100、SmartShiftauto_disengage低于 8 都会被拒绝并给出具体错误消息。外部编辑的冲突保护如果在 GUI 打开期间你在编辑器中修改了文件下一次 GUI 保存会被拒绝ConfigError::Conflict而不会覆盖你的外部修改——因为ConfigFile::save会先比较磁盘当前内容与加载时记录的内容source不一致即拒绝。此时重启 OpenLogi 以加载新版本。另外打开 GUI 会通知常驻 Agent 重新加载当前文件ReloadConfig因此手工编辑与运行时行为能立即收敛无需重启 Agent。文件结构Shape顶层字段schema_version必填当前为7。加载时先读这个头部ConfigHeader再决定后续解析与迁移策略。selected_device可选当前选中设备的物理键physical device key持久化后重启会恢复上次浏览的设备视图缺失时回退到第一个设备。[app_settings]应用级全局偏好。[devices.physical-key]每个物理设备的配置。[keyboard.bindings]与设备无关的全局键盘触发绑定。[app_settings]应用级偏好AppSettings在 crates/openlogi-core/src/config/settings.rs 中定义字段全部带#[serde(default)]以保持向后兼容旧配置缺失新字段时沿用默认值。核心字段如下字段类型/取值范围默认值说明launch_at_loginbooltrue登录时启动后台 Agent。默认开启Agent 是保持按键映射生效的进程默认关闭等于重启即失效。macOS 上是沉没开关SMAppService 登录项始终注册可在系统设置 › 登录项撤销Linux/Windows 上 Agent 会同步 autostart 单元 / Run 键check_for_updatesboolfalse更新检查默认关闭以兑现无遥测、无自动更新轮询承诺。开启后每次启动只发一次HEAD请求并记录是否有新版本不自动下载auto_install_updatesboolfalse在check_for_updates为 true 且发现新版本时后台下载并暂存下次重启时应用绝不在会话中途应用、绝不自动重启。未签名开发构建中验证失败即关闭show_in_menu_barbooltruemacOS 菜单栏图标 / Windows 通知区托盘图标false时 Agent 无可见存在。Linux 忽略此字段capture_mouse_eventsbooltrue是否安装 OS 级鼠标钩子CGEventTap / 排他evdev抓取 /WH_MOUSE_LL拦截鼠标事件用于按键重映射。false是逃生舱完全不动输入设备Linux 不做排他抓取macOS 跳过启动时的辅助功能授权弹窗。HID 侧功能DPI、SmartShift、手势键、拇指滚轮不受影响。Agent 重启后生效smooth_scrollboolfalse是否把传统鼠标滚轮输入替换为有限平滑滚动动画。默认关闭开启后 OS 钩子仅在其非阻塞滚动 worker 接受事件后抑制物理滚轮事件。触控板等连续像素输入始终保持原生。Windows 低级钩子无法把滚轮消息归属到设备因此该偏好作用于所有传统滚轮消息vertical_scroll_sensitivity整数1–100141×传统纵向滚轮的距离倍率14为 1×。触控板等连续像素输入永不缩放。scroll_multiplier()计算为value / 14thumbwheel_sensitivity整数1–100141×拇指滚轮响应度同时影响连续滚动速度与自定义滚轮动作触发的旋转增量阈值action_threshold (2*14 - value).max(1)。仅在偏离默认值时才会把滚轮从原生滚动中接管auto_download_assetsbooltrue设备出现时是否自动下载设备图片资源false时完全不发起资源网络请求回退到内置美术与合成剪影Settings 中手动刷新资源仍可按需拉取asset_sourceautomatic/openlogi/cloudflare/fastlyautomatic资源下载镜像偏好automatic并发竞争所有内置镜像取首个健康源其余为固定来源。进程级环境变量OPENLOGI_ASSETS仍是开发/诊断用覆盖项language可选字符串如en、de、pt-BR、zh-CNNone跟随系统UI 语言BCP-47 风格 locale 码须匹配 GUI 内置 locales。存于此处使显式选择在重启后仍生效appearancesystem/light/darksystem跟随系统 / 强制浅色 / 强制深色ui_scalesmall/normal/large/extra_largenormal文本与 rem 间距比例90% / 100% / 110% / 125%device_view_modegrid/list/carouselgrid首页设备画廊布局app_iconopenlogi/prismopenlogi应用图标仅 macOS 生效Windows 图标编译时嵌入可执行文件Linux 由包安装固定图标theme_light/theme_dark可选主题名字符串None品牌默认主题浅/深色模式使用的主题名ui_radius可选0/6/12像素None主题自带圆角UI 圆角覆盖值得注意的细节smooth_scroll与两种 sensitivity 的取舍在源码中有明确意图——平滑滚动只处理传统滚轮输入触控板原生vertical_scroll_sensitivity只改滚动距离、永不变更自定义动作的触发阈值而thumbwheel_sensitivity两者都管。AppSettings::is_default会在全默认时把整个[app_settings]表从序列化结果中省略。[devices.physical-key]设备级配置设备表的键是物理设备键physical device key例如接收器设备形如receiver:receiver-id:slot:number直连direct、raw-HID 与摄像头设备使用其他生成的键。不要用模型 ID如2b042代替——schema 5 起设备按它是什么unit:hex或serial:s而不是通过哪条路由到达来定键设置会跟着设备在接收器与线缆之间移动而不会分裂成两条记录。一个没有 USB 序列号的摄像头没有唯一的端口稳定身份因此其custom_name键跟随 OS 捕获 ID使两台同型号摄像头可区分把它换到另一个 USB 端口可能需要重新命名。常用设备字段DeviceConfig见 crates/openlogi-core/src/config/device.rscustom_name、enabled默认truefalse时设备完全原生无捕获会话、不重放易失设置、dpi、dpi_presetsthumbwheel_sensitivity可选缺省回退到应用级值、invert_scroll仅纵向、仅当设备支持 HID 原生滚轮反转时、scroll_resolutionlow/high对应 HID0x2121 HiResWheel的逐棘轮报告 vs 棘轮间细粒度报告bindings按键映射见下文 Actions 一节per_app_bindings按应用覆盖的稀疏动作表键为 macOS bundle id、Linux application id、精确小写的 Windows 可执行路径或exe:filename.exeaction_ring默认与完整的按应用八槽布局lighting静态 RGB 颜色 亮度 开关颜色为 6 位十六进制RRGGBB无#前缀可容忍旧版带#前缀、smartshift、独立light如 Logitech Litra亮度存为归一化百分比以及摄像头控制/配置文件host_switch_targets与fn_lock兼容键盘前者是跟随该键盘切换主机的指向设备物理键列表键盘发起、先切目标再让键盘离开当前主机后者为 HID fn 反转状态0x40a2/0x40a3true表示无需按住 Fn 即可输出 F1–F12状态存设备 RAM 每主机一份Agent 重连时重放identity与disabled_gestures应用托管的元数据。identity是设备在线时捕获的静态模型快照名称/种类/能力使设备在休眠或冷启动未探测完成前仍能渲染卡片与正确面板disabled_gestures是关闭手势模式时暂存的定制方向表重新开启时原样恢复。SmartShift 的取值约束schema 中 smartshift段包含三个字段定义见settings.rs的SmartShiftmodefree自由旋转或ratchet棘轮/有刻度滚动auto_disengage智能释放阈值合法范围0x08–0xFE步进 0.25 转/秒0xFF表示永久啮合棘轮。低于 8 的值会被拒绝加载SMARTSHIFT_MIN_AUTO_DISENGAGE阈值过低会导致棘轮在日常滚动速度下就释放成自由旋转滚轮卡不住0同时是固件不修改哨兵值绝不能作为真实值存储。默认16≈4 转/秒tunable_torque固件可调扭矩等级1–255设备不支持时存0解析为None。这些值是易失的——写入设备 RAM 后掉电即失issue #189所以必须持久化以便重连时重放。settings.rs中的测试smartshift_rejects_values_outside_the_persisted_contract验证了边界低于最小值的拒绝、最小值与最大值0xff/0xff合法、扭矩 0 解析为不支持。[keyboard.bindings]全局键盘触发[keyboard.bindings]是独立于设备的全局按键触发映射例如f1或shiftcommandf5。支持的修饰键为shift、control、option、command并接受别名ctrl、alt、cmd。解析器crates/openlogi-core/src/config/key_trigger.rs按[mod]key格式解析所有段除最后一个是修饰键外最后一个必须是键名当前支持esc与f1–f19映射到 macOS 虚拟键码kVK_*。键名与修饰键都不支持未知值——未知修饰键/键会返回ParseTriggerError。Fn不出现在触发器中固件内部机制不能作为触发器。完整配置示例仓库中的 docs/config.example.toml 是经过测试的完整示例。官方建议只复制你需要的段落并把其中示例性的物理设备键替换为 OpenLogi 已为你的设备写入的真实键。下面完整呈现并分段注释# 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示例中值得注意的要点per_app_bindings的键是应用标识符来自 Agent 前台应用的 Profile 选择器——它是唯一保证能匹配的标识符集合因为四个平台对应用的命名各不相同在一个命名空间下编写的 profile 不会在另一个命名空间匹配links下的capabilities是按链路记录的同一设备在不同传输上可能暴露不同特性overrides则是用户刻意在该链路上做差异化的设置未覆盖的项回落到设备级值effective_*系列方法先查链路覆盖再回退设备值一个空links.receiver:…表也是必要的——链路键集合本身就是设备在休眠且仅知路由时用来识别设备的索引。Actions动作绑定详解动作名称是序列化后的 Rust 枚举变体名Action定义于 crates/openlogi-core/src/binding/action.rs例如Copy、BrowserBack、PlayPause、CycleDpiPresets、ShowActionsRing。变体名是稳定的磁盘 schema已有名字冻结新增变体只能追加在末尾删除或重命名必须伴随schema_version提升与迁移。带载荷的动作使用单键内联表Back { CustomShortcut CmdShiftP } Forward { HoldShortcut CtrlSpace } MiddleClick { OpenApplication { path ~/Downloads, display_name Downloads } } DpiToggle { short ShowDesktop, long MissionControl }动作的序列化采用 serde 外部标签external tagging无载荷变体序列化为裸字符串BrowserBack元组变体序列化为单键表{ CustomShortcut my chord }。完整动作词汇表无载荷变体动作按类别组织常用无载荷动作包括鼠标LeftClick、RightClick、MiddleClick、MouseBack真实鼠标第 4 键浏览器原生解释为后退优于发送 ⌘[ 的BrowserBack、MouseForward编辑Copy、Paste、Cut、Undo、Redo⌘⇧Z / CtrlShiftZ如需 CtrlY 用CustomShortcut兜底、SelectAll、Find、Save浏览器/导航BrowserBack、BrowserForward、NewTab、CloseTab、ReopenTab、NextTab、PrevTab、ReloadPage窗口/系统MissionControl、AppExpose、PreviousDesktop、NextDesktop、ShowDesktop、LaunchpadShow、LockScreen、Screenshot、CaptureRegion、Sleep、ShowActionsRing在当前指针位置打开 Actions Ring由 Agent 处理会话而非 OS 注入器媒体PlayPause、NextTrack、PrevTrack、VolumeUp、VolumeDown、MuteVolumeDPI/滚动CycleDpiPresets按序步进dpi_presets、ToggleSmartShift、ScrollUp、ScrollDown、HorizontalScrollLeft、HorizontalScrollRight无操作None完全抑制输入被捕获但不合成任何 OS 事件。带载荷变体SetDpiPreset(u8)跳到 DPI 预设列表中的第 N 档越界时触发时钳制、CustomShortcut(KeyCombo)、HoldShortcut(KeyCombo)、TypeText(String)逐字符键入 Unicode 字符串、RunAppleScript(String)osascript -e、RunShellCommand(String)/bin/sh -c、Workflow(VecWorkflowStep)按序执行带Delay的步骤序列、OpenApplication(ApplicationTarget)。其中TypeText、RunAppleScript、RunShellCommand、Workflow是面向高级用户的逃生舱动作不出现在默认目录中。CustomShortcut 与 HoldShortcut 的区别CustomShortcut立即发出按下/抬起key-down/key-up键对HoldShortcut保持和弦按下直到触发它的物理按键释放并且在捕获被中断、绑定失效或 Agent 关闭时也会释放。它适合**按住说话push-to-talk**以及其他按住激活型控制。OS 事件合成实际由openlogi-injectcrate 的execute完成如 macOSCGEventPostopenlogi-core保持平台无关。短按/长按对{ short ..., long ... }{ short ..., long ... }绑定会等待按键的结果而不是按下即触发500ms 之前释放 → 触发short按住达到 500ms → 恰好触发一次long随后的释放不再触发short若在任一结果产生前捕获被中断、绑定改变或 Agent 关闭则两个动作都不触发只能报告瞬时按键脉冲的输入源回退到shortlong本身可以是HoldShortcut此时它的和弦从 500ms 阈值起保持按下直到物理释放。阈值常量LONG_PRESS_THRESHOLD Duration::from_millis(500)定义于 crates/openlogi-core/src/binding/value.rs。在 crates/openlogi-core/src/binding/value.rs 中Binding是#[serde(untagged)]枚举Single(Action)序列化为裸动作、Gesture(BTreeMapGestureDirection, Action)序列化为方向名键表、LongPress(LongPressBinding)序列化为结构可区分的{ short ..., long ... }表——三个分支靠结构区分动作变体名与手势方向名零重叠长按表要求short/long两个小写字段并拒绝未知字段并有binding_untagged_*测试守卫这些路由不变量。重要限制长按对目前仅适用于设备级bindings且只能通过 TOML 编写。GUI 只呈现其中的short动作在 GUI 中更改该按钮会用所选单动作替换整个长按对。per_app_bindings与keyboard.bindings始终是单动作映射。手势方向表GestureButton等可手势按钮的绑定是一个方向键表方向包括Click、Up、Down、Left、Right。手势模式是每个按钮独立的事实自 v4 起不再有每设备一个手势拥有者的锁任何数量的按钮可同时处于手势模式各自拥有方向表。Binding::Gesture的Click条目持有普通点击不滑动的动作方向表支持fill_gesture_defaults用规范默认值填充未绑定的方向。Actions Ring 条目Actions Ring 条目包装一个动作并可选添加图标或字面标签Top { action { CustomShortcut CmdShiftP }, icon Keyboard, label Command Palette }Ring 有八个固定槽位顺时针自顶部起为Top、TopRight、Right、BottomRight、Bottom、BottomLeft、Left、TopLeftcrates/openlogi-core/src/binding/action_ring.rs 的ActionRingSlot槽位名是 TOML schema 的一部分必须保持稳定。RingAction包装动作并可携带iconActionRingIcon按动作推导或显式指定或label。ShowActionsRing被禁止放入 ring 槽位以防止递归 Ring。Ring 布局分默认布局与完整按应用布局两级[devices.….action_ring]下enabled/haptics控制开关与悬停/激活触感default.slots为默认八槽布局同时支持每个应用各自的完整布局。Config::set_action_ring_slot、set_action_ring_icon等 API 在 crates/openlogi-core/src/config.rs 中提供了编辑入口。Schema 迁移v1–v7加载器parse_config见 crates/openlogi-core/src/config/file.rs先读schema_version头schema_version为 0 或**大于当前版本7**的文件在字段解析前就被拒绝UnsupportedSchemaVersion绝不静默丢失设置已废弃字段在对应版本上出现时被拒绝reject_obsolete_fieldsv2 出现button_bindings/gesture_bindings、v4 出现gesture_owner都会报ObsoleteField错误支持版本1–7的旧文件在加载时逐级迁移迁移前的原文会在首次成功保存时以config.toml.vN.bak形式原子地复制旁置migration_backup_path追加而非替换扩展名确保键重写式迁移可恢复保存失败仍保留该副本只有首次成功保存后才清除债务。各版本迁移要点完整注释见 crates/openlogi-core/src/config.rs 的SCHEMA_VERSION文档v2合并每设备的button_bindingsgesture_bindings为统一bindings映射。v1 文件仍可加载RawDeviceConfig垫片把旧字段折叠进来并在下次保存时自愈为 v2 形状v3设备映射从模型键改为物理设备键。不迁移任何 v2 设备条目——模型作用域设置无法在存在两台相同设备时安全分配v2 模型键条目必须手工复制到生成的物理键上v4移除每设备一个手势按钮的 owner 锁。手势模式成为读自绑定形状的每按钮事实加载 v3 及更早文件时migrate_owner_locked_gestures解析旧 owner 并把形状重写为等价分派HID owner 缺省/单形状时物化种子方向表非 owner 的手势形状暂存进disabled_gestures并降级为Click单动作被消费的gesture_owner不再序列化v5从direct:键中去除传输前缀——direct:046d:c08d:unit:6be9d300同时命名了鼠标与它插着的线缆换到另一条路由就会静默孤立设置。migrate_transport_scoped_keys把这种键重写为裸身份片段unit:6be9d300包括selected_device与每个host_switch_targets条目并把被丢弃的路由保留为links条目两条 v4 直连条目重命名到同一身份键时执行折叠fold而非插入覆盖保证无损。receiver:键保持不动——磁盘上无从得知配对槽位上是什么设备因此它们在运行时折叠adopt_route即下一次设备在线且 GUI 运行时首次看见时折叠。同版本还加入应用级ui_scale偏好旧文件默认 100%。设备自定义名与 Home 画廊视图偏好是可选字段未触发版本号提升v6加入阈值式{ short ..., long ... }按键绑定v7使拇指滚轮滚动默认值与归一化物理方向对齐。pre-v7 在旧默认值上的显式拇指滚轮滚动对会在设备与按应用 profile 中被迁移migrate_thumbwheel_native_direction使它们保持原生方向而非变成反转旧默认对是 上→右/下→左v7 归一化极性后交换为 上→左/下→右仅重写有效对恰好等于旧默认的 profile混合/自定义对保持字面语义不动。加载迁移完成后还会执行repair_duplicate_routes并把内存中schema_version置为当前值。迁移的同时ConfigFile记录migrated_from首次保存时把迁移前原文原子复制为config.toml.vN.bak。实用技巧与常见陷阱设备键必须用真实键从~/.config/openlogi/config.toml或对应平台路径复制 OpenLogi 已生成的设备键不要手工编造或沿用模型 IDschema_version以外的任何未知字段都会导致整个文件无法加载。改完重启GUI 打开期间外部编辑会触发保存冲突Conflict错误重启以加载新版本重启 GUI 同时会让 Agent 立即重载当前文件手工改动与运行时行为即刻收敛。SmartShift 与 DPI 是易失设置写入设备 RAM 后掉电即失OpenLogi 在重连时按配置重放issue #189同理fn_lock状态每主机一份重连时重放。长按对目前仅 TOML 可写GUI 修改该按钮会整体替换为单动作per_app_bindings与keyboard.bindings不支持长按对。备份可救急GUI 每次会话首次保存前保留.backup.1–.backup.5轮转备份迁移另有config.toml.vN.bak出问题时可以从这些文件恢复。动作名称即 schema动作变体名冻结在磁盘格式中升级后旧动作名仍然有效同理 ring 槽位名与手势方向名也是 schema 的一部分。如需进一步验证字段行为可阅读 crates/openlogi-core/src/config/tests.rs文件级迁移与往返测试以及settings.rs/device.rs内置的边界测试SmartShift 契约、敏感性浮点钳制、host_switch_targets物理键往返等。【免费下载链接】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 配置指南：深入解析 config.toml 的 schema、字段与 Actions 绑定
OpenLogi 配置指南深入解析 config.toml 的 schema、字段与 Actions 绑定【免费下载链接】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 编写的本地优先local-first鼠标/键盘/摄像头配置工具全部设置以纯 TOML 形式存放在一个config.toml中GUI 与后台 Agent 共享同一份文件。本文以 docs/CONFIGURATION.md 为骨架结合 docs/config.example.toml 完整示例与openlogi-core的源码实现系统讲解配置文件的位置与读写机制、schema 结构、每个字段的取值范围与默认值、Actions 绑定语法以及 v1–v7 的迁移规则。读完本文你将能安全地手工编辑配置文件、理解 GUI 每次保存时发生了什么并正确写出可被加载的单键、长按对、手势方向表与 Actions Ring 布局。配置文件位置三平台统一遵循 XDG 规范OpenLogi 在所有平台包括 macOS 与 Windows上都遵循 XDG Base Directory 规范macOS 与 Linux$XDG_CONFIG_HOME/openlogi/config.toml通常是~/.config/openlogi/config.tomlWindows%USERPROFILE%\.config\openlogi\config.toml注意 macOS 刻意不使用其原生的~/Library/Application Support。这一设计在 crates/openlogi-core/src/paths.rs 中有明确注释说明Decision (#347)是刻意的最终决定而非权宜之计——因为一旦 Agent 已随 Windows 产物发布再迁移位置会让所有存量用户的config.toml与首启状态搁浅。源码层面paths::config_path()由xdg_config_home()拼上openlogi或开发构建的openlogi-dev子目录得到配置、数据、状态与运行时目录分别对应用途环境变量覆盖默认位置配置config.toml$XDG_CONFIG_HOME~/.config/openlogi数据设备渲染资源缓存等$XDG_DATA_HOME~/.local/share/openlogi状态Agent 轮转日志等$XDG_STATE_HOME~/.local/state/openlogi运行时Agent IPC socket—$XDG_RUNTIME_DIR/openlogi在 Windows 上$HOME会回退到%USERPROFILE%因此路径解析为%USERPROFILE%\.config\openlogi等。开发构建OPENLOGI_PROFILEdev或 macOS dev bundle 标识会使用独立的openlogi-dev目录避免开发 Agent 抢占已安装应用的 socket、锁、配置与资源缓存。编辑与恢复原子写入、轮转备份与冲突保护原子写入与 5 代备份GUI 保存配置时采用原子写入atomic write并保留config.toml.backup.1到config.toml.backup.5五份轮转备份。相关逻辑位于 crates/openlogi-core/src/config/file.rsbackup_config_once只会在每个进程生命周期内备份一次BACKED_UP_CONFIGS集合去重backup_existing_config先把旧备份向后顺延一代再把当前文件写入.backup.1。写入通过atomic_write_file完成Unix 下还显式设置0o600权限并关闭preserve_mode。更关键的是备份链不会把旧的.backup.1顺延覆盖.backup.5循环从CONFIG_BACKUP_GENERATIONS-1即 4 开始倒序保证第 15 代各有内容。保留注释与格式GUI 更新已知字段时不会把整个文件重写为机器生成的 TOML。render_config会把新配置序列化为字符串后与磁盘上的原文件做一次toml_edit文档合并reconcile_table/reconcile_item不存在的键被移除值被替换但原有注释、装饰与排版会被保留reconcile_item会从旧值上取下 decor 装饰重新贴到新值上。所以你可以放心在文件里写注释GUI 保存不会抹掉它们。严格 schema错误立即失败而不是悄悄吞掉配置文件的 schema 是严格的拼写错误的字段、已废弃的字段如 v2 之前的button_bindings、gesture_bindingsv3 之前的gesture_owner、超出取值范围的字段都会阻止配置加载而不是静默采用默认值或在下次保存时消失加载失败时 GUI 会以只读模式打开并显示精确的 TOML 错误信息ConfigError::Parse携带行列信息。修复文件后重新启动 OpenLogi 即可。顶层Config与AppSettings、DeviceConfig等均标注了#[serde(deny_unknown_fields)]这正是未知字段硬错误的机制来源。亮度、DPI、SmartShift 阈值等还带有自定义反序列化校验例如亮度超过 100、SmartShiftauto_disengage低于 8 都会被拒绝并给出具体错误消息。外部编辑的冲突保护如果在 GUI 打开期间你在编辑器中修改了文件下一次 GUI 保存会被拒绝ConfigError::Conflict而不会覆盖你的外部修改——因为ConfigFile::save会先比较磁盘当前内容与加载时记录的内容source不一致即拒绝。此时重启 OpenLogi 以加载新版本。另外打开 GUI 会通知常驻 Agent 重新加载当前文件ReloadConfig因此手工编辑与运行时行为能立即收敛无需重启 Agent。文件结构Shape顶层字段schema_version必填当前为7。加载时先读这个头部ConfigHeader再决定后续解析与迁移策略。selected_device可选当前选中设备的物理键physical device key持久化后重启会恢复上次浏览的设备视图缺失时回退到第一个设备。[app_settings]应用级全局偏好。[devices.physical-key]每个物理设备的配置。[keyboard.bindings]与设备无关的全局键盘触发绑定。[app_settings]应用级偏好AppSettings在 crates/openlogi-core/src/config/settings.rs 中定义字段全部带#[serde(default)]以保持向后兼容旧配置缺失新字段时沿用默认值。核心字段如下字段类型/取值范围默认值说明launch_at_loginbooltrue登录时启动后台 Agent。默认开启Agent 是保持按键映射生效的进程默认关闭等于重启即失效。macOS 上是沉没开关SMAppService 登录项始终注册可在系统设置 › 登录项撤销Linux/Windows 上 Agent 会同步 autostart 单元 / Run 键check_for_updatesboolfalse更新检查默认关闭以兑现无遥测、无自动更新轮询承诺。开启后每次启动只发一次HEAD请求并记录是否有新版本不自动下载auto_install_updatesboolfalse在check_for_updates为 true 且发现新版本时后台下载并暂存下次重启时应用绝不在会话中途应用、绝不自动重启。未签名开发构建中验证失败即关闭show_in_menu_barbooltruemacOS 菜单栏图标 / Windows 通知区托盘图标false时 Agent 无可见存在。Linux 忽略此字段capture_mouse_eventsbooltrue是否安装 OS 级鼠标钩子CGEventTap / 排他evdev抓取 /WH_MOUSE_LL拦截鼠标事件用于按键重映射。false是逃生舱完全不动输入设备Linux 不做排他抓取macOS 跳过启动时的辅助功能授权弹窗。HID 侧功能DPI、SmartShift、手势键、拇指滚轮不受影响。Agent 重启后生效smooth_scrollboolfalse是否把传统鼠标滚轮输入替换为有限平滑滚动动画。默认关闭开启后 OS 钩子仅在其非阻塞滚动 worker 接受事件后抑制物理滚轮事件。触控板等连续像素输入始终保持原生。Windows 低级钩子无法把滚轮消息归属到设备因此该偏好作用于所有传统滚轮消息vertical_scroll_sensitivity整数1–100141×传统纵向滚轮的距离倍率14为 1×。触控板等连续像素输入永不缩放。scroll_multiplier()计算为value / 14thumbwheel_sensitivity整数1–100141×拇指滚轮响应度同时影响连续滚动速度与自定义滚轮动作触发的旋转增量阈值action_threshold (2*14 - value).max(1)。仅在偏离默认值时才会把滚轮从原生滚动中接管auto_download_assetsbooltrue设备出现时是否自动下载设备图片资源false时完全不发起资源网络请求回退到内置美术与合成剪影Settings 中手动刷新资源仍可按需拉取asset_sourceautomatic/openlogi/cloudflare/fastlyautomatic资源下载镜像偏好automatic并发竞争所有内置镜像取首个健康源其余为固定来源。进程级环境变量OPENLOGI_ASSETS仍是开发/诊断用覆盖项language可选字符串如en、de、pt-BR、zh-CNNone跟随系统UI 语言BCP-47 风格 locale 码须匹配 GUI 内置 locales。存于此处使显式选择在重启后仍生效appearancesystem/light/darksystem跟随系统 / 强制浅色 / 强制深色ui_scalesmall/normal/large/extra_largenormal文本与 rem 间距比例90% / 100% / 110% / 125%device_view_modegrid/list/carouselgrid首页设备画廊布局app_iconopenlogi/prismopenlogi应用图标仅 macOS 生效Windows 图标编译时嵌入可执行文件Linux 由包安装固定图标theme_light/theme_dark可选主题名字符串None品牌默认主题浅/深色模式使用的主题名ui_radius可选0/6/12像素None主题自带圆角UI 圆角覆盖值得注意的细节smooth_scroll与两种 sensitivity 的取舍在源码中有明确意图——平滑滚动只处理传统滚轮输入触控板原生vertical_scroll_sensitivity只改滚动距离、永不变更自定义动作的触发阈值而thumbwheel_sensitivity两者都管。AppSettings::is_default会在全默认时把整个[app_settings]表从序列化结果中省略。[devices.physical-key]设备级配置设备表的键是物理设备键physical device key例如接收器设备形如receiver:receiver-id:slot:number直连direct、raw-HID 与摄像头设备使用其他生成的键。不要用模型 ID如2b042代替——schema 5 起设备按它是什么unit:hex或serial:s而不是通过哪条路由到达来定键设置会跟着设备在接收器与线缆之间移动而不会分裂成两条记录。一个没有 USB 序列号的摄像头没有唯一的端口稳定身份因此其custom_name键跟随 OS 捕获 ID使两台同型号摄像头可区分把它换到另一个 USB 端口可能需要重新命名。常用设备字段DeviceConfig见 crates/openlogi-core/src/config/device.rscustom_name、enabled默认truefalse时设备完全原生无捕获会话、不重放易失设置、dpi、dpi_presetsthumbwheel_sensitivity可选缺省回退到应用级值、invert_scroll仅纵向、仅当设备支持 HID 原生滚轮反转时、scroll_resolutionlow/high对应 HID0x2121 HiResWheel的逐棘轮报告 vs 棘轮间细粒度报告bindings按键映射见下文 Actions 一节per_app_bindings按应用覆盖的稀疏动作表键为 macOS bundle id、Linux application id、精确小写的 Windows 可执行路径或exe:filename.exeaction_ring默认与完整的按应用八槽布局lighting静态 RGB 颜色 亮度 开关颜色为 6 位十六进制RRGGBB无#前缀可容忍旧版带#前缀、smartshift、独立light如 Logitech Litra亮度存为归一化百分比以及摄像头控制/配置文件host_switch_targets与fn_lock兼容键盘前者是跟随该键盘切换主机的指向设备物理键列表键盘发起、先切目标再让键盘离开当前主机后者为 HID fn 反转状态0x40a2/0x40a3true表示无需按住 Fn 即可输出 F1–F12状态存设备 RAM 每主机一份Agent 重连时重放identity与disabled_gestures应用托管的元数据。identity是设备在线时捕获的静态模型快照名称/种类/能力使设备在休眠或冷启动未探测完成前仍能渲染卡片与正确面板disabled_gestures是关闭手势模式时暂存的定制方向表重新开启时原样恢复。SmartShift 的取值约束schema 中 smartshift段包含三个字段定义见settings.rs的SmartShiftmodefree自由旋转或ratchet棘轮/有刻度滚动auto_disengage智能释放阈值合法范围0x08–0xFE步进 0.25 转/秒0xFF表示永久啮合棘轮。低于 8 的值会被拒绝加载SMARTSHIFT_MIN_AUTO_DISENGAGE阈值过低会导致棘轮在日常滚动速度下就释放成自由旋转滚轮卡不住0同时是固件不修改哨兵值绝不能作为真实值存储。默认16≈4 转/秒tunable_torque固件可调扭矩等级1–255设备不支持时存0解析为None。这些值是易失的——写入设备 RAM 后掉电即失issue #189所以必须持久化以便重连时重放。settings.rs中的测试smartshift_rejects_values_outside_the_persisted_contract验证了边界低于最小值的拒绝、最小值与最大值0xff/0xff合法、扭矩 0 解析为不支持。[keyboard.bindings]全局键盘触发[keyboard.bindings]是独立于设备的全局按键触发映射例如f1或shiftcommandf5。支持的修饰键为shift、control、option、command并接受别名ctrl、alt、cmd。解析器crates/openlogi-core/src/config/key_trigger.rs按[mod]key格式解析所有段除最后一个是修饰键外最后一个必须是键名当前支持esc与f1–f19映射到 macOS 虚拟键码kVK_*。键名与修饰键都不支持未知值——未知修饰键/键会返回ParseTriggerError。Fn不出现在触发器中固件内部机制不能作为触发器。完整配置示例仓库中的 docs/config.example.toml 是经过测试的完整示例。官方建议只复制你需要的段落并把其中示例性的物理设备键替换为 OpenLogi 已为你的设备写入的真实键。下面完整呈现并分段注释# 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示例中值得注意的要点per_app_bindings的键是应用标识符来自 Agent 前台应用的 Profile 选择器——它是唯一保证能匹配的标识符集合因为四个平台对应用的命名各不相同在一个命名空间下编写的 profile 不会在另一个命名空间匹配links下的capabilities是按链路记录的同一设备在不同传输上可能暴露不同特性overrides则是用户刻意在该链路上做差异化的设置未覆盖的项回落到设备级值effective_*系列方法先查链路覆盖再回退设备值一个空links.receiver:…表也是必要的——链路键集合本身就是设备在休眠且仅知路由时用来识别设备的索引。Actions动作绑定详解动作名称是序列化后的 Rust 枚举变体名Action定义于 crates/openlogi-core/src/binding/action.rs例如Copy、BrowserBack、PlayPause、CycleDpiPresets、ShowActionsRing。变体名是稳定的磁盘 schema已有名字冻结新增变体只能追加在末尾删除或重命名必须伴随schema_version提升与迁移。带载荷的动作使用单键内联表Back { CustomShortcut CmdShiftP } Forward { HoldShortcut CtrlSpace } MiddleClick { OpenApplication { path ~/Downloads, display_name Downloads } } DpiToggle { short ShowDesktop, long MissionControl }动作的序列化采用 serde 外部标签external tagging无载荷变体序列化为裸字符串BrowserBack元组变体序列化为单键表{ CustomShortcut my chord }。完整动作词汇表无载荷变体动作按类别组织常用无载荷动作包括鼠标LeftClick、RightClick、MiddleClick、MouseBack真实鼠标第 4 键浏览器原生解释为后退优于发送 ⌘[ 的BrowserBack、MouseForward编辑Copy、Paste、Cut、Undo、Redo⌘⇧Z / CtrlShiftZ如需 CtrlY 用CustomShortcut兜底、SelectAll、Find、Save浏览器/导航BrowserBack、BrowserForward、NewTab、CloseTab、ReopenTab、NextTab、PrevTab、ReloadPage窗口/系统MissionControl、AppExpose、PreviousDesktop、NextDesktop、ShowDesktop、LaunchpadShow、LockScreen、Screenshot、CaptureRegion、Sleep、ShowActionsRing在当前指针位置打开 Actions Ring由 Agent 处理会话而非 OS 注入器媒体PlayPause、NextTrack、PrevTrack、VolumeUp、VolumeDown、MuteVolumeDPI/滚动CycleDpiPresets按序步进dpi_presets、ToggleSmartShift、ScrollUp、ScrollDown、HorizontalScrollLeft、HorizontalScrollRight无操作None完全抑制输入被捕获但不合成任何 OS 事件。带载荷变体SetDpiPreset(u8)跳到 DPI 预设列表中的第 N 档越界时触发时钳制、CustomShortcut(KeyCombo)、HoldShortcut(KeyCombo)、TypeText(String)逐字符键入 Unicode 字符串、RunAppleScript(String)osascript -e、RunShellCommand(String)/bin/sh -c、Workflow(VecWorkflowStep)按序执行带Delay的步骤序列、OpenApplication(ApplicationTarget)。其中TypeText、RunAppleScript、RunShellCommand、Workflow是面向高级用户的逃生舱动作不出现在默认目录中。CustomShortcut 与 HoldShortcut 的区别CustomShortcut立即发出按下/抬起key-down/key-up键对HoldShortcut保持和弦按下直到触发它的物理按键释放并且在捕获被中断、绑定失效或 Agent 关闭时也会释放。它适合**按住说话push-to-talk**以及其他按住激活型控制。OS 事件合成实际由openlogi-injectcrate 的execute完成如 macOSCGEventPostopenlogi-core保持平台无关。短按/长按对{ short ..., long ... }{ short ..., long ... }绑定会等待按键的结果而不是按下即触发500ms 之前释放 → 触发short按住达到 500ms → 恰好触发一次long随后的释放不再触发short若在任一结果产生前捕获被中断、绑定改变或 Agent 关闭则两个动作都不触发只能报告瞬时按键脉冲的输入源回退到shortlong本身可以是HoldShortcut此时它的和弦从 500ms 阈值起保持按下直到物理释放。阈值常量LONG_PRESS_THRESHOLD Duration::from_millis(500)定义于 crates/openlogi-core/src/binding/value.rs。在 crates/openlogi-core/src/binding/value.rs 中Binding是#[serde(untagged)]枚举Single(Action)序列化为裸动作、Gesture(BTreeMapGestureDirection, Action)序列化为方向名键表、LongPress(LongPressBinding)序列化为结构可区分的{ short ..., long ... }表——三个分支靠结构区分动作变体名与手势方向名零重叠长按表要求short/long两个小写字段并拒绝未知字段并有binding_untagged_*测试守卫这些路由不变量。重要限制长按对目前仅适用于设备级bindings且只能通过 TOML 编写。GUI 只呈现其中的short动作在 GUI 中更改该按钮会用所选单动作替换整个长按对。per_app_bindings与keyboard.bindings始终是单动作映射。手势方向表GestureButton等可手势按钮的绑定是一个方向键表方向包括Click、Up、Down、Left、Right。手势模式是每个按钮独立的事实自 v4 起不再有每设备一个手势拥有者的锁任何数量的按钮可同时处于手势模式各自拥有方向表。Binding::Gesture的Click条目持有普通点击不滑动的动作方向表支持fill_gesture_defaults用规范默认值填充未绑定的方向。Actions Ring 条目Actions Ring 条目包装一个动作并可选添加图标或字面标签Top { action { CustomShortcut CmdShiftP }, icon Keyboard, label Command Palette }Ring 有八个固定槽位顺时针自顶部起为Top、TopRight、Right、BottomRight、Bottom、BottomLeft、Left、TopLeftcrates/openlogi-core/src/binding/action_ring.rs 的ActionRingSlot槽位名是 TOML schema 的一部分必须保持稳定。RingAction包装动作并可携带iconActionRingIcon按动作推导或显式指定或label。ShowActionsRing被禁止放入 ring 槽位以防止递归 Ring。Ring 布局分默认布局与完整按应用布局两级[devices.….action_ring]下enabled/haptics控制开关与悬停/激活触感default.slots为默认八槽布局同时支持每个应用各自的完整布局。Config::set_action_ring_slot、set_action_ring_icon等 API 在 crates/openlogi-core/src/config.rs 中提供了编辑入口。Schema 迁移v1–v7加载器parse_config见 crates/openlogi-core/src/config/file.rs先读schema_version头schema_version为 0 或**大于当前版本7**的文件在字段解析前就被拒绝UnsupportedSchemaVersion绝不静默丢失设置已废弃字段在对应版本上出现时被拒绝reject_obsolete_fieldsv2 出现button_bindings/gesture_bindings、v4 出现gesture_owner都会报ObsoleteField错误支持版本1–7的旧文件在加载时逐级迁移迁移前的原文会在首次成功保存时以config.toml.vN.bak形式原子地复制旁置migration_backup_path追加而非替换扩展名确保键重写式迁移可恢复保存失败仍保留该副本只有首次成功保存后才清除债务。各版本迁移要点完整注释见 crates/openlogi-core/src/config.rs 的SCHEMA_VERSION文档v2合并每设备的button_bindingsgesture_bindings为统一bindings映射。v1 文件仍可加载RawDeviceConfig垫片把旧字段折叠进来并在下次保存时自愈为 v2 形状v3设备映射从模型键改为物理设备键。不迁移任何 v2 设备条目——模型作用域设置无法在存在两台相同设备时安全分配v2 模型键条目必须手工复制到生成的物理键上v4移除每设备一个手势按钮的 owner 锁。手势模式成为读自绑定形状的每按钮事实加载 v3 及更早文件时migrate_owner_locked_gestures解析旧 owner 并把形状重写为等价分派HID owner 缺省/单形状时物化种子方向表非 owner 的手势形状暂存进disabled_gestures并降级为Click单动作被消费的gesture_owner不再序列化v5从direct:键中去除传输前缀——direct:046d:c08d:unit:6be9d300同时命名了鼠标与它插着的线缆换到另一条路由就会静默孤立设置。migrate_transport_scoped_keys把这种键重写为裸身份片段unit:6be9d300包括selected_device与每个host_switch_targets条目并把被丢弃的路由保留为links条目两条 v4 直连条目重命名到同一身份键时执行折叠fold而非插入覆盖保证无损。receiver:键保持不动——磁盘上无从得知配对槽位上是什么设备因此它们在运行时折叠adopt_route即下一次设备在线且 GUI 运行时首次看见时折叠。同版本还加入应用级ui_scale偏好旧文件默认 100%。设备自定义名与 Home 画廊视图偏好是可选字段未触发版本号提升v6加入阈值式{ short ..., long ... }按键绑定v7使拇指滚轮滚动默认值与归一化物理方向对齐。pre-v7 在旧默认值上的显式拇指滚轮滚动对会在设备与按应用 profile 中被迁移migrate_thumbwheel_native_direction使它们保持原生方向而非变成反转旧默认对是 上→右/下→左v7 归一化极性后交换为 上→左/下→右仅重写有效对恰好等于旧默认的 profile混合/自定义对保持字面语义不动。加载迁移完成后还会执行repair_duplicate_routes并把内存中schema_version置为当前值。迁移的同时ConfigFile记录migrated_from首次保存时把迁移前原文原子复制为config.toml.vN.bak。实用技巧与常见陷阱设备键必须用真实键从~/.config/openlogi/config.toml或对应平台路径复制 OpenLogi 已生成的设备键不要手工编造或沿用模型 IDschema_version以外的任何未知字段都会导致整个文件无法加载。改完重启GUI 打开期间外部编辑会触发保存冲突Conflict错误重启以加载新版本重启 GUI 同时会让 Agent 立即重载当前文件手工改动与运行时行为即刻收敛。SmartShift 与 DPI 是易失设置写入设备 RAM 后掉电即失OpenLogi 在重连时按配置重放issue #189同理fn_lock状态每主机一份重连时重放。长按对目前仅 TOML 可写GUI 修改该按钮会整体替换为单动作per_app_bindings与keyboard.bindings不支持长按对。备份可救急GUI 每次会话首次保存前保留.backup.1–.backup.5轮转备份迁移另有config.toml.vN.bak出问题时可以从这些文件恢复。动作名称即 schema动作变体名冻结在磁盘格式中升级后旧动作名仍然有效同理 ring 槽位名与手势方向名也是 schema 的一部分。如需进一步验证字段行为可阅读 crates/openlogi-core/src/config/tests.rs文件级迁移与往返测试以及settings.rs/device.rs内置的边界测试SmartShift 契约、敏感性浮点钳制、host_switch_targets物理键往返等。【免费下载链接】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），仅供参考