配置

OpenLogi 把一切都保存在一个 TOML 文件里。这个文件由 GUI 负责写入——主窗口编辑按键与手势绑定、DPI 预设、SmartShift 与灯效，设置窗口（⌘,）则涵盖应用级偏好——但它是纯文本，可以放心手动编辑。按应用配置层目前还没有专门的编辑界面，需要在这里直接手写。

OpenLogi 在启动时读取配置，并在每次更改时原子化重写。请在应用已退出时手动编辑，否则下次 GUI 保存时会覆盖你的改动。

文件位置

平台	路径
macOS / Linux	`$XDG_CONFIG_HOME/openlogi/config.toml`（默认 `~/.config/openlogi/config.toml`）
Windows	`%USERPROFILE%\.config\openlogi\config.toml`

文件以原子方式写入（临时文件 + 重命名），在 Unix 上权限为 0600。

顶层结构


schema_version = 2            # 必填；版本无法识别时会拒绝读取
selected_device = "2b042"     # 轮播中所选设备的 HID++ 键
 
[app_settings]                # 应用级偏好（全为默认值时整块省略）
# …
 
[devices.2b042]               # 每台设备一个块，以 HID++ id 为键
# …

schema_version —— 结构版本（当前为 2）。v1 文件（分离的 button_bindings / gesture_bindings 表）仍可读取，并在下次保存时迁移到统一的 bindings 映射；版本无法识别的文件会被拒绝，而非被误读。
selected_device —— 记住轮播停留在哪台设备；未设置时省略。
[app_settings] —— 见下文；当每个字段都是默认值时整块省略。
[devices.<key>] —— 按设备的设置，以每台设备的 HID++ 标识为键（例如 MX Master 4 为 2b042）。

`[app_settings]`

键	默认值	含义
`launch_at_login`	`false`	登录时启动 OpenLogi——macOS 上是 LaunchAgent plist，Linux 上是 systemd 用户单元。
`check_for_updates`	`false`	需手动开启。每次启动向 GitHub 最新发行版发送一个 `HEAD` 请求；仅记录是否存在新版本——绝不下载。默认关闭以保持零遥测。
`show_in_menu_bar`	`true`	仅 macOS。`true` → 菜单栏状态图标（窗口关闭时无 Dock 图标）；`false` → 普通 Dock 应用。
`language`	（跟随系统）	界面语言，20 种内置语言之一（`en`、`de`、`pt-BR`、`zh-CN` 等）。未设置时跟随系统语言。
`thumbwheel_sensitivity`	`14`	拇指轮灵敏度，`1`–`100`；默认值对应 1× 原生滚动（仅当偏离默认值时才会把拇指轮从原生滚动中接管过来）。

设备块

每个 [devices.<key>] 块保存一台物理设备的设置。键是设备的 HID++ 标识——与 GUI 使用的 config_key 相同。

键	类型	含义
`bindings`	表	把逻辑按键映射到绑定：单个动作，或按方向的手势子表（见按键与手势绑定）。
`per_app_bindings`	表的表	以应用标识为键的覆盖层（如 `"com.microsoft.VSCode"`）。该应用在前台时其条目优先；其余回落到 `bindings`。
`gesture_owner`	字符串	哪个按键承担手势角色：一个按键名或 `"Off"`。缺省表示「自动推断」——有拇指键时由拇指键承担。
`dpi_presets`	整数数组	有序的 DPI 值，由 `CycleDpiPresets` 循环、由 `SetDpiPreset` 按索引选取。
`lighting`	表	有线 G 系列键盘的按设备 RGB——见下文。

`lighting`

键	默认值	含义
`enabled`	`true`	是否应用静态颜色。
`color`	`"ffffff"`	六位十六进制 `RRGGBB`（不带 `#` 前缀）的静态颜色。
`brightness`	`100`	`0`–`100`；读取时收敛到范围内。

按键

bindings 与 per_app_bindings 以逻辑按键为键：

LeftClick、RightClick、MiddleClick、Back、Forward、DpiToggle（滚轮下方的模式切换键）、Thumbwheel（拇指轮按下）、ThumbwheelScrollUp、ThumbwheelScrollDown、GestureButton。

动作

绑定值是原样书写的动作名：

抑制 —— None（捕获输入但不做任何事）
鼠标 —— LeftClick、RightClick、MiddleClick、MouseBack、MouseForward（真实的额外按键事件，多数应用将其原生识别为后退/前进）
编辑 —— Copy、Paste、Cut、Undo、Redo、SelectAll、Find、Save
浏览器与标签页 —— BrowserBack、BrowserForward、NewTab、CloseTab、ReopenTab、NextTab、PrevTab、ReloadPage
窗口与桌面（macOS） —— MissionControl、AppExpose、PreviousDesktop、NextDesktop、ShowDesktop、LaunchpadShow
系统 —— LockScreen、Screenshot
媒体 —— PlayPause、NextTrack、PrevTrack、VolumeUp、VolumeDown、MuteVolume
DPI 与滚轮 —— CycleDpiPresets、SetDpiPreset、ToggleSmartShift
滚动 —— ScrollUp、ScrollDown、HorizontalScrollLeft、HorizontalScrollRight
自定义 —— CustomShortcut，录制的组合键

SetDpiPreset（预设索引）与 CustomShortcut（录制的组合键）携带额外数据，建议通过 GUI 的动作选择器设置，而非手写。

手势绑定

处于手势模式的按键不再绑定单个动作，而是按方向绑定：它在 bindings 中的条目变为以 Up、Down、Left、Right、Click 为键的子表（Click 是不滑动的普通按下）。哪个按键处于手势模式——拇指键或其他支持的按键——由 gesture_owner 或 GUI 的手势键选择器决定。

示例


schema_version = 2
selected_device = "2b042"
 
[app_settings]
launch_at_login = true
language = "zh-CN"
thumbwheel_sensitivity = 14
 
# MX Master 4（HID++ 键 2b042）
[devices.2b042]
gesture_owner = "GestureButton"
dpi_presets = [800, 1600, 3200]
 
[devices.2b042.bindings]
Back = "BrowserBack"
Forward = "BrowserForward"
MiddleClick = "MissionControl"
 
# 手势键按方向绑定；Click 是普通按下。
[devices.2b042.bindings.GestureButton]
Left = "PrevTab"
Right = "NextTab"
Click = "PlayPause"
 
# 仅当 VS Code 在前台时，Back 变为 Undo。
[devices.2b042.per_app_bindings."com.microsoft.VSCode"]
Back = "Undo"
 
# 有线 G 系列键盘，使用它自己的 HID++ 设备键
# （此处的 `g513` 代指该键）。
[devices.g513.lighting]
enabled = true
color = "ff0000"
brightness = 80

来源： CONFIGURATION.md