TOML 配置文件完全解析：OpenLogi 的 config.toml 结构与 5 个必备字段

TOML 配置文件完全解析：OpenLogi 的 config.toml 结构与 5 个必备字段

【免费下载链接】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

OpenLogi 是一款用 Rust 编写的本地优先外设管理软件，是 Logitech Options+ 的免费替代方案：按钮重映射、DPI 调节、SmartShift 滚轮模式全部通过 HID++ 协议直连硬件，无需注册账号、没有遥测、设置完全离线。它的全部设置都保存在一个纯文本 TOML 文件里——config.toml。这篇文章带你完整看懂 OpenLogi 的 config.toml：它藏在哪里、由哪 5 个必备字段组成、以及如何安全地手动编辑它。

一、config.toml 在哪里？各平台路径速查

OpenLogi 的 GUI 和后台 agent 读取的是同一个文件，路径遵循各平台规范（见 crates/openlogi-core/src/paths.rs）：

💡 找不到文件？用任意文本编辑器直接创建该目录和文件即可，从官方示例里复制你需要的段落。完整的可运行示例位于仓库的docs/config.example.toml，说明文档在docs/CONFIGURATION.md。

二、先认识 config.toml 的顶层骨架

一个最小可用的 OpenLogi 配置长这样：

schema_version = 6 selected_device = "receiver:aabbccdd:slot:1" [app_settings] language = "zh-CN" appearance = "system" [devices."receiver:aabbccdd:slot:1"] custom_name = "办公鼠标" dpi = 1600 dpi_presets = [800, 1600, 3200] [keyboard.bindings] f1 = "MissionControl"

整个文件由5 个必备（核心）字段组成，下面逐一拆解 🧩

三、5 个必备字段逐个讲透

1️⃣schema_version：配置文件的"版本号"

schema_version = 6

这是 config.toml 中唯一强制要求的顶层字段（定义于crates/openlogi-core/src/config.rs）。OpenLogi 读取时先检查它：

• 版本过旧（如 v1–v5）→ 自动迁移升级，保存时自愈为新格式；
• 版本过新（比当前程序还新）→ 直接拒绝加载，防止悄悄弄丢你的绑定；
• 版本号填 0 或未知 → 报错，而不是用默认值糊弄过去。

📌 手动新建配置时，照抄当前版本的数字即可，不要乱填。

2️⃣selected_device：记住你上次在操作哪台设备

可选字段。它保存的是"当前活动设备"的物理设备键，重启 OpenLogi 后界面会直接定位到这台设备，而不是永远回到列表第一台。

设备键的两种常见形态：

• receiver:<接收器ID>:slot:<槽位号>—— 通过接收器配对的设备；
• unit:<十六进制ID>或serial:<序列号>—— 直连 USB 的设备（v5 起改用"设备是什么"而非"从哪个口接入"来标识，换线/换口设置也不丢）。

⚠️ 常见错误：用型号 ID（如2b042）当键名。请只复制 OpenLogi 已经为你的设备写好的键。

3️⃣[app_settings]：全局偏好设置区

不属于任何一台设备的应用级开关都住在这里（结构定义见crates/openlogi-core/src/config/settings.rs）：

所有字段都有默认值，缺什么就用什么默认值，文件可以非常精简。

4️⃣[devices."<设备键>"]：每台设备的私人定制区

这是整个 config.toml 的"主菜"，结构定义在crates/openlogi-core/src/config/device.rs。常用字段：

[devices."receiver:aabbccdd:slot:1"] custom_name = "办公鼠标" dpi = 1600 dpi_presets = [800, 1600, 3200] invert_scroll = false scroll_resolution = "high" thumbwheel_sensitivity = 20 [devices."receiver:aabbccdd:slot:1".bindings] Back = "BrowserBack" MiddleClick = { HoldShortcut = "Ctrl+Space" } DpiToggle = { short = "ShowDesktop", long = "MissionControl" } [devices."receiver:aabbccdd:slot:1".smartshift] mode = "ratchet" auto_disengage = 16

几个高频用法：

• dpi+dpi_presets：传感器 DPI 存在设备 RAM 里，断电即重置，所以 OpenLogi 每次重连都会重新写入——这也是它必须持久化的原因；
• bindings按钮重映射：支持三种形态——直接一个动作（Back = "BrowserBack"）、按住型快捷键（HoldShortcut，适合语音对讲，松开物理键自动释放）、以及短按/长按分离（short/long，以 500ms 为分界，长按满 500ms 触发一次long，之后的松手不会再触发short）；
• per_app_bindings：按前台应用覆盖动作，如"在 VSCode 里 Back 键变成撤销"：

Back = "Undo"

• smartshift：滚轮模式（ratchet棘轮 /free自由悬停）+ 自动悬停阈值（8–255，默认16，低于 8 会被拒绝）。

5️⃣[keyboard.bindings]：全局功能键重映射

与具体设备无关的键盘触发器，独立成区：

[keyboard.bindings] f1 = "MissionControl" "shift+command+f5" = "ShowDesktop"

支持shift、control、option、command四个修饰键（ctrl、alt、cmd等别名也可识别）。动作名是英文变体名，如Copy、BrowserBack、PlayPause、CycleDpiPresets；需要参数的动作用单键内联表，例如：

Back = { CustomShortcut = "Cmd+Shift+P" }

四、安全编辑 config.toml 的 3 个实用技巧

1. 改之前看一眼备份机制：GUI 是原子写入，并自动保留config.toml.backup.1到.backup.5共 5 份备份，已知字段的更新还会保留你写的注释与格式；
2. schema 是严格的：拼错字段、超范围数值（比如brightness = 120）会直接拒绝加载，而不是静默吞掉——此时 GUI 进入只读模式并给出精确的 TOML 报错位置，按提示修好再重启即可；
3. GUI 开着时别手改：文件在编辑器中被外部修改时，GUI 的下一次保存会被拒绝以避免互相覆盖；手动改完后重新打开 GUI，后台 agent 会立即重载，手改设置即时生效。

五、获取官方示例与延伸阅读

如果手边没有现成的配置文件，可以克隆源码仓库，其中docs/config.example.toml是一份经过完整测试的示例，按需只复制你需要的段落：

git clone https://gitcode.com/GitHub_Trending/op/OpenLogi

相关源码与文档位置（均为仓库内相对路径）：

• 配置示例：docs/config.example.toml
• 配置说明文档：docs/CONFIGURATION.md
• 配置结构定义与版本迁移逻辑：crates/openlogi-core/src/config.rs
• 全局偏好字段（灵敏度、外观、语言等）：crates/openlogi-core/src/config/settings.rs
• 每设备配置字段（DPI、bindings、SmartShift 等）：crates/openlogi-core/src/config/device.rs
• 各平台路径规则：crates/openlogi-core/src/paths.rs

总结

OpenLogi 的 config.toml 用 5 个核心字段撑起了全部功能：schema_version管版本兼容、selected_device记住当前设备、[app_settings]管全局开关、[devices."…"]管每台的 DPI/按钮/滚轮/灯效、[keyboard.bindings]管全局热键。纯文本、无账号、全离线——把它复制一份、改几行、重启应用，就是最直接的定制方式 ⌨️

【免费下载链接】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