配置

OpenLogi 把所有设置存放在一个 TOML 文件里。GUI 会替你写入：主窗口负责按键绑定、Actions Ring、DPI 预设、SmartShift、滚轮、灯光与摄像头控制，设置窗口（⌘,）负责应用级偏好，但这个文件是纯文本，可以放心手工编辑。Buttons 工作区也有 Profile 选择器，可以编辑按应用叠加。

文件位置

配置结构采用严格解析。未知、过时、格式错误或超出范围的值会阻止文件加载，而不会悄悄恢复默认。GUI 会打开只读错误页，显示 TOML 错误，并提供打开配置目录和修复后重启的按钮。每个进程首次保存前，OpenLogi 会把旧文件复制为 config.toml.backup.1，并轮转到 config.toml.backup.5；迁移旧结构时还会创建 config.toml.v4.bak 这样的版本备份。文件以原子方式写入，在 Unix 上权限为 0600。

顶层结构

schema_version = 7                 # 必填；0 或高于当前构建的版本会被拒绝
selected_device = "unit:6be9d300"  # 当前选中设备的物理键

[app_settings]                                 # 应用级偏好（全为默认值时整块省略）
# …

[devices."unit:6be9d300"]          # 每个物理设备一个块
# …

[keyboard.bindings]                            # 系统级功能键重映射
# …

• schema_version —— 结构版本（当前为 7）。受支持的旧文件会在加载时迁移；更高版本会在解析字段前被拒绝。v5 让设备自身身份不再依赖连接方式，v6 加入短按 / 长按组合，v7 归一化拇指滚轮方向。更早的迁移仍涵盖 v4 取消手势所有权锁、v3 改用物理设备键，以及 v2 合并为单一 bindings。
• selected_device —— 记住上次选中的设备；未设置时省略。
• [app_settings] —— 见下文；所有字段都是默认值时整块省略。
• [devices.<key>] —— 按物理设备身份索引的每设备设置（见下文）。
• [keyboard] —— 与设备无关的功能键重映射，走系统钩子而非 HID++。

设备键

设备块按物理身份而非型号索引，两只同型号鼠标不会共享设置。自结构 v5 起，只要 HID++ 设备身份已知，设置就不再依赖连接方式：

GUI 若先后通过 Bolt 接收器和线缆观察到同一个 unit:6be9d300，会把两条连接合并到同一设备项，连接则保留为 link 键：

[devices."unit:6be9d300".links."receiver:aabbccdd:slot:1"]

[devices."unit:6be9d300".links."direct:046d:c08d".capabilities]
buttons = true
pointer = true

因此能力与有意设置的连接差异可以按 link 保存，而普通设置会随同一物理设备跨连接方式生效。不要手工拼接设备键：先在应用里配置或重命名一次设备，再从 config.toml 复制生成的键。既无序列号、unit id 又全为零的直连 HID++ 设备无法获得稳定持久身份。没有 USB 序列号的摄像头改用操作系统捕获 id，换 USB 端口后可能需要重新命名。

[app_settings]

mouse_profile_target 决定鼠标按键配置使用哪个应用。默认值 pointer 在 macOS、Windows 与 X11 上跟随指针所在窗口；Wayland 等不支持的会话使用焦点应用。设为 focused 可在所有平台上跟随键盘焦点。键盘配置与 Actions Ring 布局始终跟随焦点应用。

在支持指针目标的平台上，pointer 模式会在指针位于桌面背景时使用全局鼠标绑定。OpenLogi 不会为了发送快捷键而激活后台窗口：目标窗口没有焦点时，会跳过发送按键或运行工作流的鼠标绑定。示例见按应用配置。

每设备块

每个 [devices.<key>] 块保存一台物理设备的设置。

lighting

light

按键

bindings 与 per_app_bindings 以逻辑按键为键。

鼠标控件：LeftClick、RightClick、MiddleClick、Back、Forward、DpiToggle（滚轮下方的模式切换键）、Thumbwheel（其电容触碰）、ThumbwheelScrollUp、ThumbwheelScrollDown、GestureButton、HapticPanel（MX Master 4 的 Haptic Sense 触感面板）、WheelTiltLeft 与 WheelTiltRight。Thumbwheel 实际表示噪声较多的电容触碰，而不是机械点击；默认不执行动作，GUI 也不提供该控件。

键盘 F 区控件，只有绑定后才会通过 HID++ 接管：KeySearch、KeyDictation、KeyEmoji、KeyScreenCapture、KeyMicMute、KeyPlayPause、KeyMute、KeyVolumeDown、KeyVolumeUp。参见键盘。

动作

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

• 屏蔽 —— 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、CaptureRegion、Sleep、ShowActionsRing、OpenApplication
• 媒体 —— PlayPause、NextTrack、PrevTrack、VolumeUp、VolumeDown、MuteVolume
• DPI 与滚轮 —— CycleDpiPresets、SetDpiPreset、ToggleSmartShift
• 滚动 —— ScrollUp、ScrollDown、HorizontalScrollLeft、HorizontalScrollRight
• 进阶 —— CustomShortcut、HoldShortcut、TypeText、RunAppleScript、RunShellCommand、Workflow

ShowActionsRing 可直接在动作选择器中选取。带参数的动作写成单键表：

HapticPanel = "ShowActionsRing"                            # 普通动作
DpiToggle = { SetDpiPreset = 2 }                            # 预设索引
Back = { CustomShortcut = "Cmd+Shift+P" }                   # 组合键
Forward = { OpenApplication = { path = "~/Downloads", display_name = "Downloads" } }
MiddleClick = { HoldShortcut = "Ctrl+Space" }               # 持续到物理按键松开

OpenApplication 接受应用、文件夹、文件系统路径或 URL；执行时会展开开头的 ~。CustomShortcut 保存与平台无关的组合键文本，例如 Cmd+Shift+P、Ctrl+Alt+Left 或 F5。不同编辑器对带参数动作的 GUI 支持并不相同；鼠标检查器的动作选择器只显示普通目录，手写绑定仍可使用这些表形态。HoldShortcut 还有下文所述的额外限制。

短按 / 长按与持续快捷键

设备级按键可使用小写 short / long 组合：

DpiToggle = { short = "ShowDesktop", long = "MissionControl" }
Back = { short = "MouseBack", long = { HoldShortcut = "Ctrl+Space" } }

在 500 毫秒前松开会执行 short；达到 500 毫秒会执行一次 long，之后松开不会再执行 short。若在得出结果前捕获中断、绑定变化或代理退出，两者都不会执行。只能报告瞬时脉冲的来源会回退到 short。

CustomShortcut 会立即按下并松开组合键；HoldShortcut 会保持按下，直到发起它的物理按键松开，也会在捕获取消、绑定失效或代理退出时释放。它适合按住说话；作为 long 动作时，会从 500 毫秒阈值开始保持到物理松开。

GUI 目前只显示组合中的 short 动作；在选择器中修改会把整个组合替换成单动作。短按 / 长按组合与 HoldShortcut 暂时请在 TOML 中编写。per_app_bindings 与 keyboard.bindings 仍是单动作映射。

手势绑定

任何受支持的按键都可以处于手势模式：它在 bindings 里的条目从单个动作变成以 Up、Down、Left、Right、Click（不含滑动的单纯按下）为键的子表。自 v4 起这是每个按键各自的状态，可以同时有多个按键处于手势模式，设备级的 gesture_owner 键已经取消（加载 v3 文件时，旧的所有权会被迁移成等价的绑定形态）。

[devices."unit:6be9d300".bindings.GestureButton]
Up = "MissionControl"
Down = "ShowDesktop"
Left = "PrevTab"
Right = "NextTab"
Click = "AppExpose"

GUI 可为后退、前进、DPI/ModeShift、专用手势键与 MX Master 4 的 Haptic Sense 面板新建手势。后退 / 前进走系统钩子；三个专用 HID++ 控件走原始 XY 接管，其中 DPI/ModeShift 只有在设备实测支持原始 XY 后才可开启。v0.8.0 写入的中键手势图会被保留，在关闭前仍可编辑，但 GUI 无法再次开启。手势方向图始终是设备级的；按应用的单动作覆盖会在该应用里暂时取代整个手势键。

[keyboard]

面向任意键盘的功能键重映射，与设备无关，由系统钩子驱动。键为 [修饰键+]…按键 形式，修饰键有 shift、control（ctrl）、option（alt）、command（cmd），按键为 esc 与 f1–f19：

[keyboard.bindings]
f1 = "MissionControl"
"shift+f2" = "ShowDesktop"
"cmd+f5" = { CustomShortcut = "Cmd+Shift+P" }

它与罗技键盘在 [devices.<key>.bindings] 下的 HID++ F 区绑定是两件事，如何取舍见键盘。

示例

schema_version = 7
selected_device = "unit:6be9d300"

[app_settings]
launch_at_login = true
language = "zh-CN"
thumbwheel_sensitivity = 14
smooth_scroll = false
vertical_scroll_sensitivity = 14
appearance = "system"
ui_scale = "normal"
device_view_mode = "grid"

# 同一只鼠标，无论通过接收器还是线缆连接。
[devices."unit:6be9d300"]
custom_name = "办公鼠标"
dpi_presets = [800, 1600, 3200]
dpi = 1600
invert_scroll = true
scroll_resolution = "high"

[devices."unit:6be9d300".bindings]
Back = "MouseBack"
Forward = { short = "MouseForward", long = "MissionControl" }
MiddleClick = { HoldShortcut = "Ctrl+Space" }
HapticPanel = "ShowActionsRing"
ThumbwheelScrollUp = "HorizontalScrollLeft"
ThumbwheelScrollDown = "HorizontalScrollRight"

# 手势键按方向绑定；Click 是单纯按下。
[devices."unit:6be9d300".bindings.GestureButton]
Left = "PrevTab"
Right = "NextTab"
Click = "PlayPause"

# VS Code 必须是鼠标目标且具有焦点，才能执行撤销。
[devices."unit:6be9d300".per_app_bindings."com.microsoft.VSCode"]
Back = "Undo"

[devices."unit:6be9d300".smartshift]
mode = "ratchet"
auto_disengage = 16
tunable_torque = 0

[devices."unit:6be9d300".action_ring]
enabled = true
haptics = true

[devices."unit:6be9d300".action_ring.default.slots]
Top = { action = "Cut" }
TopRight = { action = "Copy" }
Right = { action = "Paste", label = "Paste It" }
BottomRight = { action = "BrowserForward" }
Bottom = { action = "PlayPause" }
BottomLeft = { action = "BrowserBack" }
Left = { action = "Undo" }
TopLeft = { action = "Redo" }

# 由应用管理的同一物理鼠标连接。
[devices."unit:6be9d300".links."receiver:aabbccdd:slot:1"]
[devices."unit:6be9d300".links."direct:046d:c08d"]

# Signature 系列键盘：F 区通过 HID++ 接管，Fn-lock 关闭。
[devices."receiver:aabbccdd:slot:2"]
fn_lock = false
host_switch_targets = ["unit:6be9d300"]

[devices."receiver:aabbccdd:slot:2".bindings]
KeySearch = "MissionControl"
KeyScreenCapture = "CaptureRegion"

[devices."receiver:aabbccdd:slot:2".lighting]
enabled = true
color = "ff0000"
brightness = 80

# 一只 Litra Glow，按其原始 HID 身份索引。
[devices."raw:046d:c900:ff43:0202:serial:YOUR-SERIAL".light]
enabled = true
auto_camera = true
brightness_percent = 65
temperature_kelvin = 4600

来源： CONFIGURATION.md