OpenLogi

配置

TOML 配置文件参考：位置、结构、全部键值、动作与手势绑定。

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

后台代理启动时读取配置，并在每次变更时原子性重写。请在 OpenLogi 完全退出时手工编辑，否则运行中的代理下次保存会覆盖你的改动。每个进程首次保存前，OpenLogi 会把旧文件复制为 config.toml.backup.1，并最多轮转到 config.toml.backup.5。

文件位置

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

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

顶层结构

schema_version = 4                             # 必填；版本号高于当前构建会被拒绝
selected_device = "receiver:aabbccdd:slot:1"   # 轮播中选中设备的物理键

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

[devices."receiver:aabbccdd:slot:1"]           # 每个物理设备一个块
# …

[keyboard.bindings]                            # 系统级功能键重映射
# …
  • schema_version —— 结构版本（当前为 4）。旧版本会在加载时迁移；声明了更高版本的文件会被直接拒绝，而不是被误读。v4 取消了「每台设备只能有一个手势键」的所有权锁（gesture_owner），v3 把设备表的键从型号改为物理设备身份，v2 把 button_bindings / gesture_bindings 合并为单一的 bindings。
  • selected_device —— 记住轮播上次停留的设备；未设置时省略。
  • [app_settings] —— 见下文；所有字段都是默认值时整块省略。
  • [devices.<key>] —— 按物理设备身份索引的每设备设置（见下文）。
  • [keyboard] —— 与设备无关的功能键重映射，走系统钩子而非 HID++。

设备键

自 v3 起，设备块按物理设备而非型号索引，两只同型号鼠标不会共用同一条设置：

形式适用于
receiver:<receiver-uid>:slot:<n>配对到 Bolt / Unifying / Lightspeed 接收器
direct:<vid>:<pid>:serial:<serial>（或 :unit:<hex>）蓝牙直连或 USB 有线的 HID++ 设备
raw:<vid>:<pid>:<usage-page>:<usage-id>:serial:<serial>原始 HID 设备，例如 Litra 补光灯

键一律使用小写十六进制。GUI 会替你写入正确的键，最可靠的做法是先在应用里配置一次该设备，再从 config.toml 里读回它的键。既没有序列号也没有 unit id 的设备没有稳定身份，OpenLogi 不会为它持久化设置。

[app_settings]

键默认值含义
launch_at_loginfalse登录时启动代理。macOS 上写入 LaunchAgent plist，Linux 上写入 systemd 用户单元。
check_for_updatesfalse需手动开启。每次启动向 GitHub 最新发行版发一次 HEAD 请求，记录是否有新版本，自身从不下载。
auto_install_updatesfalse需手动开启，且仅在 check_for_updates 打开时生效：后台下载并暂存新版本，下次重启时应用。
update_prompt_seenfalse首次运行的「是否检查更新？」提示被回答过后置为真，此后不再弹出。
show_in_menu_bartruemacOS 菜单栏状态项与 Windows 托盘图标；Linux 上忽略。
capture_mouse_eventstrue代理是否安装系统鼠标钩子。设为 false 后按键重映射停止、不再独占任何输入设备；DPI、SmartShift 等 HID++ 侧功能照常。重启代理后生效。
auto_download_assetstrue设备出现时自动获取设备渲染图。false 表示完全不发起资源网络请求；设置里的刷新资源仍可按需拉取。
asset_sourceautomatic资源镜像：automatic（并发竞速所有内置镜像）、openlogi、cloudflare 或 fastly。
language（跟随系统）界面语言，取自 20 种内置语言（en、de、pt-BR、zh-CN……）。未设置时跟随系统语言。
thumbwheel_sensitivity14拇指滚轮灵敏度，范围 1–100；默认值等于 1 倍原生滚动（只有离开默认值后滚轮才会被从原生滚动中接管）。
appearancesystemsystem、light 或 dark。
theme_light（品牌主题）浅色模式使用的主题名，例如 "OpenLogi Light"。
theme_dark（品牌主题）深色模式使用的主题名。
ui_radius（主题默认）圆角覆盖值（像素）；外观页提供 0 / 6 / 12。

每设备块

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

键类型含义
enabled布尔false 表示完全放任该设备：不建立 HID++ 捕获会话，重连时也不重新下发设置。默认 true。
bindings表把逻辑按键映射到绑定：单个动作，或按方向的手势子表（见按键与手势绑定）。
per_app_bindings表的表按应用 id 索引的叠加。该应用位于前台时其条目生效，其余回落到 bindings。
action_ring表Actions Ring 的开关、触感、默认布局与按应用布局。
dpi_presets整数数组有序 DPI 列表，供 CycleDpiPresets 循环、SetDpiPreset 按索引取用。
dpi整数已确认的传感器 DPI。该值存于设备内存，代理会在重连时重新下发。
smartshift表mode（ratchet / free）、auto_disengage、tunable_torque，重连时重新下发。
invert_scroll布尔反转本设备的原生滚轮方向，不影响系统触控板方向。
scroll_resolution字符串low 或 high。持久化的 HID++ 0x2121 滚轮分辨率。缺省表示不干预设备自身设置。
thumbwheel_sensitivity整数覆盖应用级的拇指滚轮灵敏度。
lighting表HID++ 键盘的静态 RGB，见下文。
light表独立补光灯（Litra）的开关、亮度、色温，见 Litra 补光灯。
camera_controls表摄像头 UVC 控制项，按控制名索引。
camera_profiles表的表用户保存的摄像头预设（名称 → 控制快照）。
camera_profile字符串GUI 上次应用的摄像头预设。
host_switch_targets设备键数组跟随该键盘 Easy-Switch 通道切换的鼠标设备键。
fn_lock布尔仅键盘。true 表示无需按住 Fn，F 区直接发送 F1–F12；缺省表示不改动键盘自身状态。重连时重新下发。
identity表由应用写入：最近一次的名称、类型与能力，让休眠设备也能渲染出对应面板。不建议手写。
disabled_gestures表由应用写入：手势模式当前关闭的按键的方向映射，重新开启时可原样恢复。

lighting

键默认值含义
enabledtrue是否应用静态颜色。
color"ffffff"六位十六进制 RRGGBB 静态颜色（不带 #）。
brightness1000–100，加载时裁剪。

light

键默认值含义
enabledtrue灯是否点亮。
auto_camerafalse任一摄像头启用时点亮，摄像头停用时熄灭（macOS）。
brightness_percent1000–100，映射到设备原生范围（例如 Litra 的 20–250 流明）。
temperature_kelvin（未设）色温，设备支持时可用（Litra：2700–6500 K，步进 100 K）。

按键

bindings 与 per_app_bindings 以逻辑按键为键。

鼠标控件：LeftClick、RightClick、MiddleClick、Back、Forward、DpiToggle（滚轮下方的模式切换键）、Thumbwheel（其点按）、ThumbwheelScrollUp、ThumbwheelScrollDown、GestureButton、HapticPanel（MX Master 4 的 Haptic Sense 触感面板）。

键盘 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、TypeText、RunAppleScript、RunShellCommand、Workflow

选择器中列出 44 个普通动作。ShowActionsRing 需要手写（它不在选择器里），带参数的动作则写成单键表：

MiddleClick = "MissionControl"                              # 普通动作
DpiToggle = { SetDpiPreset = 2 }                            # 预设索引
Back = { CustomShortcut = "Cmd+Shift+P" }                   # 组合键
Forward = { OpenApplication = { path = "~/Downloads", display_name = "Downloads" } }

OpenApplication 接受应用、文件夹、文件系统路径或 URL；执行时会展开开头的 ~。CustomShortcut 保存与平台无关的组合键文本，例如 Cmd+Shift+P、Ctrl+Alt+Left 或 F5。这些都可以在 GUI 中完成：自定义快捷键和打开应用在动作选择器里，TypeText / RunAppleScript / RunShellCommand / Workflow 在它的 Power User 子菜单里。

手势绑定

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

[devices."receiver:aabbccdd:slot:1".bindings.GestureButton]
Up = "MissionControl"
Down = "ShowDesktop"
Left = "PrevTab"
Right = "NextTab"
Click = "AppExpose"

专用手势键与 MX Master 4 的 Haptic Sense 面板通过 HID++ 原始 XY 捕获；中键 / 后退 / 前进的手势则走系统钩子。

[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 = 4
selected_device = "receiver:aabbccdd:slot:1"

[app_settings]
launch_at_login = true
language = "zh-CN"
thumbwheel_sensitivity = 14
appearance = "system"

# Bolt 接收器 1 号槽位上的 MX Master 4。
[devices."receiver:aabbccdd:slot:1"]
dpi_presets = [800, 1600, 3200]
dpi = 1600
invert_scroll = true
scroll_resolution = "high"

[devices."receiver:aabbccdd:slot:1".bindings]
Back = "BrowserBack"
Forward = "BrowserForward"
MiddleClick = "MissionControl"
HapticPanel = "ShowActionsRing"

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

# 仅当 VS Code 位于前台时，Back 变成撤销。
[devices."receiver:aabbccdd:slot:1".per_app_bindings."com.microsoft.VSCode"]
Back = "Undo"

[devices."receiver:aabbccdd:slot:1".smartshift]
mode = "ratchet"
auto_disengage = 16
tunable_torque = 0

[devices."receiver:aabbccdd:slot:1".action_ring]
enabled = true
haptics = true

[devices."receiver:aabbccdd:slot:1".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" }

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

[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

摄像头

预览罗技摄像头，并调节设备级 UVC 图像参数与预设。

路线图

逐项列出 OpenLogi 目前支持什么、还有什么在推进中的状态表。

本页目录

文件位置顶层结构设备键[app_settings]每设备块lightinglight按键动作手势绑定[keyboard]示例