配置
schema 11 TOML 配置参考:文件恢复、应用设置、设备、绑定、配置文件、Actions Ring 布局和 Flow。
OpenLogi 把共享设置保存到一个 TOML 文件。GUI 与后台代理读取同一个文件。GUI 会写入支持的更改,你也可以直接编写这个文件。
文件与安全编辑
| 平台 | 路径 |
|---|---|
| macOS / Linux | $XDG_CONFIG_HOME/openlogi/config.toml(默认:~/.config/openlogi/config.toml) |
| Windows | %USERPROFILE%\.config\openlogi\config.toml |
配置结构采用严格解析。未知、过时、格式错误或超出范围的值会阻止文件加载。你必须修复文件并重启 OpenLogi,GUI 才会退出只读错误页。
| 情况 | OpenLogi 的行为 |
|---|---|
| GUI 保存 | 以原子方式写入文件。仍存在的字段会保留原有注释与格式。 |
| 备份 | 每个进程首次保存前,轮转 config.toml.backup.1 至 config.toml.backup.5 共 5 份备份。 |
| 结构迁移 | 首次成功保存还会把旧文件复制为 config.toml.v<version>.bak。 |
| 符号链接 | 写入解析后的目标文件,并保留链接。缺失的目标目录会自动创建。 |
| 符号链接锁 | 持久 .lock 辅助文件位于目标文件旁。指向同一目标的链接共用该锁。 |
| 外部编辑 | GUI 的下一次保存会被拒绝,避免覆盖外部编辑。你必须重启 OpenLogi 以加载修改。 |
| 打开 GUI | GUI 会要求常驻代理重新加载当前文件。 |
在 Unix 上,OpenLogi 创建的文件权限为 0600。大规模手工编辑前,应该另存一份副本。严格解析错误会阻止 OpenLogi 悄悄用默认值替换文件。
文档结构与迁移
schema_version 必填。本版本写入结构版本 11。值为 0 或高于正在运行构建版本的文件,会在解析其他字段前被拒绝。
schema_version = 11
selected_device = "unit:6be9d300"
[app_settings]
# 应用级偏好。
[flow]
# 跨电脑的 Flow 切换。
[devices."unit:6be9d300"]
# 一台物理设备。
[keyboard.bindings]
# 任意键盘的功能键重映射。
[apps.chrome]
# 可选的跨平台应用别名。| 顶层键 | 类型 | 含义 |
|---|---|---|
schema_version | 整数 | 必填的结构版本。使用 11。 |
selected_device | 物理设备键或省略 | GUI 上次选中的设备。 |
app_settings | 表 | 应用级偏好。 |
flow | 表 | Flow 电脑、屏幕边缘与设备。为默认值时省略。 |
devices | 表的表 | 以物理设备键索引的设置。 |
keyboard | 表 | 全局功能键绑定。 |
apps | 表的表 | 配置文件可用的应用别名。 |
加载器接受版本 1 至 11。加载时会迁移受支持的结构。
| 版本 | 更改与迁移 |
|---|---|
| v1 | 使用独立的 button_bindings 与 gesture_bindings 映射。 |
| v2 | 把两个映射合并为 bindings。保存 v1 文件时会改写为这个结构。 |
| v3 | 把设备项从型号键改为物理设备键。若有同型号设备,你必须手工复制 v2 型号键项。 |
| v4 | 移除设备级 gesture_owner。手势模式改为每个按键各自的绑定结构。 |
| v5 | 将直连设备设置移到设备身份,将路由保留在 links,并添加 ui_scale。 |
| v6 | 添加 { short = ..., long = ... } 按键绑定。 |
| v7 | 归一化拇指滚轮方向。设备与按应用绑定中的显式旧默认组合会迁移。 |
| v8 | 添加滚轮按住绑定与每设备 smooth_wheel 开关。 |
| v9 | 添加 [apps] 别名与 app:<alias> 配置文件键。v8 文件的其他部分不变,仍可加载。 |
| v10 | 添加每设备 disabled_keys 策略。旧版本会在解析字段前拒绝 v10 文件。v9 文件不变,仍可加载。 |
| v11 | 添加 [flow] 一节。v10 构建会在版本检查时拒绝 v11 文件。v10 文件不变,仍可加载,Flow 为关闭状态。 |
应用设置
所有值均为默认值时,[app_settings] 会被省略。下表是结构默认值,不是从已连接设备推断出的 GUI 状态。
| 键 | 类型 | 默认值 | 含义 |
|---|---|---|---|
launch_at_login | 布尔 | true | 登录后启动后台代理。 |
check_for_updates | 布尔 | false | 每次启动应用时检查一次 GitHub 最新发行版。 |
auto_install_updates | 布尔 | false | 在已启用的更新检查发现新版本后下载并暂存。重启时应用更新。 |
update_prompt_seen | 布尔 | false | 记录首次更新提示已经收到答复。 |
show_in_menu_bar | 布尔 | true | 显示 macOS 菜单栏项与 Windows 通知区域图标。Linux 会忽略它。 |
capture_mouse_events | 布尔 | true | 安装系统鼠标钩子以重映射鼠标。更改后必须重启代理。 |
smooth_scroll | 布尔 | false | 平滑符合条件的传统鼠标滚轮输入。原生触控板输入保持原生。 |
vertical_scroll_sensitivity | 整数 | 14 | 传统垂直滚轮距离,范围为 1 至 100。14 为 1 倍。 |
auto_download_assets | 布尔 | true | 设备出现时下载设备资源。手动刷新资源仍会下载。 |
asset_source | 枚举 | automatic | 资源来源:automatic、openlogi、cloudflare 或 fastly。 |
language | 字符串或省略 | 系统区域设置 | 内置界面区域设置,例如 en 或 zh-CN。 |
thumbwheel_sensitivity | 整数 | 14 | 拇指滚轮灵敏度,范围为 1 至 100。14 为 1 倍。 |
momentum_scrolling | 表 | 关闭 | 所有开启 smooth_wheel 的鼠标的惯性滚动。键:enabled、pixels_per_notch、glide_shape、max_glide_speed、glide_ms 和 repeat_boost。见滚动。 |
appearance | 枚举 | system | 界面外观:system、light 或 dark。 |
ui_scale | 枚举 | normal | 界面缩放:small(90%)、normal(100%)、large(110%)或 extra_large(125%)。 |
device_view_mode | 枚举 | grid | 首页布局:grid、list 或 carousel。 |
app_icon | 枚举 | openlogi | macOS 应用图标:openlogi 或 prism。其他平台会忽略它。 |
theme_light | 字符串或省略 | 品牌浅色主题 | 浅色模式的主题名。 |
theme_dark | 字符串或省略 | 品牌深色主题 | 深色模式的主题名。 |
ui_radius | 整数或省略 | 主题圆角 | 以像素为单位的圆角覆盖值。界面提供 0、6 与 12。 |
mouse_profile_target | 枚举 | pointer | 鼠标配置文件目标:pointer 或 focused。 |
low_battery_notifications | 布尔 | true | 每次放电仅显示一次低电量提示。 |
lock_key_notifications | 布尔 | true | 显示兼容键盘的锁定键状态提示。 |
设为 capture_mouse_events = false 后,按键重映射停止,OpenLogi 不会独占输入设备。DPI 和 SmartShift 等 HID++ 功能继续工作。smooth_wheel 设备设置也需要启用鼠标捕获。
mouse_profile_target = "pointer" 在 macOS、Windows 与 X11 上跟随指针下的窗口。Wayland 与无法识别的表面使用焦点应用。桌面使用全局鼠标绑定。
OpenLogi 不会为了发送快捷键而让后台窗口获得焦点。鼠标绑定若生成按键输入或执行工作流,而焦点应用对该按键的绑定相同,就会发送到焦点应用。按应用配置文件使绑定不同时,只有指针下的窗口已获得焦点才会执行。键盘配置文件与 Actions Ring 布局始终跟随焦点应用。
低电量表示非充电状态下电量低于或等于 20%,或者设备未报告百分比但报告低或严重状态。提示会在 8 秒后关闭,也可以点击关闭。锁定键提示需要 HID++ 0x4220;macOS 不显示 Num Lock 与 Scroll Lock 提示。
设备身份与路由
[devices.<key>] 使用物理身份,而不是型号 id。因此两只同型号鼠标会保留独立设置。让 OpenLogi 创建设备键,再从 config.toml 复制。
| 键形式 | 用途 |
|---|---|
unit:6be9d300 | 非零的四字节 HID++ unit id。 |
serial:abc123 | 非空设备序列号,保存为小写。 |
receiver:aabbccdd:slot:1 | 接收器 UID 与配对槽位。它标识接收器配对的设备。 |
direct:046d:c08d:serial:abc123 | 直连 HID++ 设备。在其设置移到裸 serial: 或 unit: 身份前使用。 |
raw:046d:c900:ff43:0202:serial:your-serial | 有序列号的独立原始 HID 设备,例如 Litra 灯。驱动提供时 stable:<id> 也有效。 |
camera:046d:0893:serial:abc123 | 有 USB 序列号的摄像头。 |
camera:046d:0893 | 无 USB 序列号的摄像头。同型号摄像头会共用此设置键。 |
一台设备可以有多条路由。links 会在物理设备项下记录每条路由。capabilities 记录在该路由上测得的功能,overrides 则有意覆盖该路由支持的设置。
[devices."unit:6be9d300".links."receiver:aabbccdd:slot:1"]
[devices."unit:6be9d300".links."direct:046d:c08d".capabilities]
buttons = true
pointer = true
[devices."unit:6be9d300".links."direct:046d:c08d".overrides]
dpi = 800| 路由表 | 字段 |
|---|---|
capabilities | 应用测得的能力表。不要手工编写。 |
overrides | 可选的 dpi、invert_scroll、scroll_resolution、lighting 与 smartshift。 |
没有序列号的摄像头无法跨 USB 端口区分同型号设备。它的 GUI 卡片仍使用操作系统捕获 id,但设置键仍以型号为范围。只有 unit:00000000 的直连设备没有持久身份。
每设备字段
每个 [devices.<key>] 表保存一台物理设备的设置。可选值在你设置前会被省略。
| 键 | 类型 | 默认值 | 含义 |
|---|---|---|---|
enabled | 布尔 | true | false 表示保持设备原生。OpenLogi 停止捕获与重连后重新下发设置。 |
custom_name | 字符串或省略 | 省略 | 用户指定的设备名称。 |
identity | 表 | 省略 | 由应用管理的型号名、类型与能力快照。 |
links | 表 | 空 | 由应用管理的路由索引、路由能力与路由覆盖。 |
bindings | 表 | 空 | 逻辑控件到绑定的映射。 |
disabled_gestures | 表 | 空 | 由应用管理的已保存手势图,适用于当前未处于手势模式的控件。 |
per_app_bindings | 表的表 | 空 | 按应用的稀疏按键→动作叠加。 |
action_ring | 表 | 默认值 | Actions Ring 开关、触感、大小、默认布局与完整的按应用布局。 |
dpi_presets | 整数数组 | 空 | CycleDpiPresets 使用的 DPI 列表,以及零基 SetDpiPreset 索引。 |
dpi | 整数或省略 | 省略 | 传感器 DPI。代理会在重连后重新下发。 |
lighting | 表或省略 | 省略 | 静态 HID++ 键盘 RGB 设置。 |
light | 表或省略 | 省略 | 独立补光灯设置。 |
smartshift | 表或省略 | 省略 | SmartShift 滚轮设置。 |
camera_controls | 字符串到整数的表或省略 | 省略 | 原始 UVC 值,例如 brightness、focus 或 focus_auto。 |
camera_profiles | 表的表 | 空 | 已命名的摄像头控制快照。 |
camera_profile | 字符串或省略 | 省略 | GUI 上次应用的摄像头配置文件。 |
thumbwheel_sensitivity | 整数或省略 | 应用设置 | 范围为 1 至 100 的每设备覆盖。 |
invert_scroll | 布尔 | false | 反转本设备的垂直滚轮,不改变触控板方向。 |
scroll_resolution | 枚举或省略 | 省略 | HID++ 0x2121 分辨率:low 或 high。省略时保持设备设置。 |
smooth_wheel | 布尔 | false | 在软件中平滑此鼠标的主滚轮。 |
momentum_scrolling | 表或省略 | 应用设置 | 这只鼠标单独的惯性滚动,键与应用设置相同。省略的键取默认值。 |
host_switch_targets | 物理设备键数组 | 空 | 此键盘离开 Easy-Switch 主机前先切换的指点设备。 |
fn_lock | 布尔或省略 | 省略 | true 表示 F 区无需 Fn 直接发送 F1–F12。 |
keep_os_layout | 布尔或省略 | true | 保持兼容键盘使用主机操作系统布局。 |
report_rate | 整数或省略 | 省略 | 鼠标回报率,单位为 Hz。代理只在该路由提供此速率时应用。 |
force_sensing | 整数或省略 | 省略 | 软件可修改的力感按键的按压力度(HID++ 0x19c0,即 MX Master 4 的触感面板)。它是没有单位的设备原始值,越小按起来越轻。代理会把它限制在设备上报的范围内,并在设备连接时写入。省略时保留设备自身的力度。 |
没有 backlight 配置字段。背光状态由键盘保存。lighting 是受支持 HID++ 键盘的静态 RGB 表。
禁用按键
键盘提供用户可配置的 HID++ 0x4521 时,设备页才显示卡片。应用排除隐藏功能和工程功能。卡片只显示固件支持的以下按键:
- Caps Lock
- Num Lock
- Scroll Lock
- Insert
- Windows;macOS 显示为 Command
**开启开关表示禁用按键。**这个设置改变键盘固件行为,不是按键重映射。禁用 Caps Lock 也可能阻止输入语言切换等主机动作。
在已有的物理设备项下添加这个字段:
disabled_keys = ["caps_lock", "windows_command"]其他有效名称为 num_lock、scroll_lock 和 insert。省略字段表示停止管理这个设置。disabled_keys = [] 表示启用全部受支持的已知按键。OpenLogi 会保留固件支持的未知禁用位。
控件需要在线键盘、持久身份和可写配置。控件还需要成功读取设备状态。代理写入完整掩码,然后重新读取。应用只保存已确认的已知按键。
错误或超时不能证明键盘状态没有变化。应用会丢弃旧快照,并在新读取成功前禁用控件。点击读取失败提示,可以重新发起读取。Save Retry 重试保存,Reload Retry 重试代理加载。这两种重试不重发手动写入请求。
每次保存都必须确认自己的文件版本。多个变更共用加载请求时,仍分别确认。新版本的成功回执不确认旧版本。
外部编辑后,应用刷新文件,不覆盖外部内容。Save Retry 或其他设置的保存发现外部编辑时,也按这个规则处理。代理必须确认这个精确版本。随后,每个键盘都要重新读取设备,才开放编辑。刷新或代理加载失败时,控件保持禁用。Reload Retry 继续协调文件版本。
仅重新读取设备,不能确认文件版本。应用也处理协调期间再次发生的外部编辑。
恢复提示留在设备卡片内,并使用共享控件。卡片渲染时,从当前语言目录解析文案。所有界面语言都已翻译这些文案。技术错误写入应用日志,不作为普通恢复文案显示。开关和恢复动作按物理设备隔离身份。开关的读屏名称包含禁用动作和按键名。
代理会在发现、重连和唤醒后重新应用配置。如果手动写入未确认,代理会调度最近确认的选择。这个选择可以是应用尚未保存的状态。更新的待处理请求具有优先权。恢复写入开始后, 应用会重新读取键盘,并显示恢复后的按键。
移除策略或停止设备管理会撤销过期排队任务。这不保证撤销已经写入的固件值。确认重试有延迟和次数上限。枚举失败不算确认成功。
代理持有已提交报告的资源,直到原生操作完成。这个保证包含功能发现和读取回执。取消只停止后续报告,不撤销已提交报告。
请求者收到成功结果后,结果才成为恢复基线。未读取的结果仍未确认。设备读取排在已调度的策略写入之后。原生操作若永不完成,后续写入可能持续等待。请求在第一个报告前被取消时,立即离开队列。
已知 unit ID 或序列号改变时,代理识别设备替换。这适用于接收器槽位和直连键盘。代理撤销旧请求,并重置发现重试预算。补全原先缺失的身份时,代理保留活动任务。补全身份也保留剩余预算。
如果两个快照都缺少这些标识,槽位不能证明替换。这是身份数据的限制,不是替换检测保证。直连键盘没有非零 unit ID 时,身份变化按新设备处理。
快速重试耗尽后,普通恢复仍保留待确认工作。无法连接的键盘可能无法接受写入。
禁用按键功能在 schema 10 中加入。schema 9 的文件仍可加载。早于 schema 10 的版本会先拒绝保存后的文件,不会解析文件字段。降级前,必须保留兼容旧版的配置备份。
lighting、light 与 smartshift
| 表 | 键 | 默认值 | 含义 |
|---|---|---|---|
lighting | enabled | true | 应用静态颜色。 |
lighting | color | "ffffff" | 6 位十六进制 RRGGBB。也可加载前导 #。 |
lighting | brightness | 100 | 亮度范围为 0 至 100。 |
light | enabled | true | 打开或关闭独立补光灯。 |
light | auto_camera | false | 让独立补光灯跟随所有摄像头的使用状态。 |
light | brightness_percent | 100 | 亮度范围为 0 至 100。 |
light | temperature_kelvin | 省略 | 设备支持时,请求的色温。 |
light | color | 省略 | 驱动支持时,请求的 RGB 颜色。 |
smartshift | mode | 必填 | ratchet 或 free。 |
smartshift | auto_disengage | 必填 | 8 至 254,单位为每秒 0.25 圈;255 表示永久棘轮。 |
smartshift | tunable_torque | 省略 | 1 至 100%,硬件未报告扭矩等级时使用 0。 |
smooth_wheel 鼠标会接管 HID++ 0x2121 报告,并发送缓动滚动。它会应用反转与垂直灵敏度。它需要输入捕获,并且在 macOS 上需要辅助功能权限。关闭它、禁用设备或停止代理都会让滚轮恢复原生报告。
绑定控件
bindings 与 per_app_bindings 使用逻辑控件名作为键。鼠标控件必须使用以下拼写:
| 鼠标控件 |
|---|
LeftClick、RightClick、MiddleClick、Back、Forward、DpiToggle、Thumbwheel、ThumbwheelScrollUp、ThumbwheelScrollDown、GestureButton、HapticPanel、WheelTiltLeft、WheelTiltRight |
Thumbwheel 是电容轻触报告,不是机械点击。除非你绑定它,否则它不会执行操作。它可能报告无意的拇指接触。
键盘控件是 HID++ 0x1b04 控件。已知控件使用目录名。任何可转移的未列出控件使用 control:0x<cid>。
| 已知键盘控件名 |
|---|
KeyBrightnessDown、KeyBrightnessUp、KeyBacklightDown、KeyBacklightUp、KeyMissionControl、KeyLaunchpad、KeyShowDesktop、KeySearch、KeyDictation、KeyEmoji、KeyScreenCapture、KeyPrintScreen、KeyMicMute、KeyPreviousTrack、KeyPlayPause、KeyPlayPauseTrack、KeyNextTrack、KeyMute、KeyVolumeDown、KeyVolumeUp、KeyCalculator、KeyLock、KeyDoNotDisturb、KeyEmojiHeartEyes、KeyEmojiCrying、KeyEmojiSmiley、KeyEmojiTears、KeyLookUp、KeyAppSwitch、KeyAppSwitchLaunchpad、KeyHome、KeyEnd、KeyPageUp、KeyPageDown、KeyMultiPlatformAppSwitch、KeyMultiPlatformHome、KeyMultiPlatformMenu、KeyMultiPlatformInsert、KeyLanguageSwitch、KeyCircle、KeyTriangle、KeyDiamond、KeyStar |
键盘按键在你绑定前保持固件功能。显式 None 绑定会转移已经绑定的键盘控件,但不执行操作。这与删除条目不同,删除条目会让按键恢复固件功能。
动作
绑定值使用序列化的 Rust 动作名。下表列出 schema 11 的全部动作。带负载的动作使用单键 TOML 表,不使用字符串。
| 分组 | 动作 |
|---|---|
| 屏蔽 | None |
| 鼠标 | LeftClick、RightClick、MiddleClick、MouseBack、MouseForward |
| 编辑 | Copy、Paste、Cut、Undo、Redo、SelectAll、Find、Save |
| 浏览器 | BrowserBack、BrowserForward、NewTab、CloseTab、ReopenTab、NextTab、PrevTab、ReloadPage |
| 导航 | 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、TapKeyHoldingModifiers、TypeText、RunAppleScript、RunShellCommand、Workflow |
Back = "BrowserBack"
DpiToggle = { SetDpiPreset = 2 }
Forward = { CustomShortcut = "Cmd+Shift+P" }
MiddleClick = { HoldShortcut = "Ctrl+Space" }
GestureButton = { TapKeyHoldingModifiers = "Cmd+Tab" }
HapticPanel = { OpenApplication = { path = "~/Downloads", display_name = "Downloads" } }SetDpiPreset 使用零基索引。OpenApplication 接受应用、文件夹、文件系统路径或 URL。动作执行时会展开开头的 ~。
CustomShortcut、HoldShortcut 与 TapKeyHoldingModifiers 接受含一个普通按键的组合键。修饰键为 Cmd、Ctrl、Alt、Shift 与 Super。Command 是 Cmd 的别名,Control 是 Ctrl 的别名,Option 是 Alt 的别名,Win 与 Meta 是 Super 的别名。
Cmd 是跨平台的主修饰键。它在 macOS 上是 Command,在 Linux 与 Windows 上是 Control。Super 始终按下徽标键:macOS 上是 Command,Windows 上是 Windows 键,Linux 上是 KEY_LEFTMETA。
按键结构
全局设备绑定可以是单个动作、短按和长按组合、滚轮按住或手势图。按应用项与 [keyboard.bindings] 项始终只使用单个动作。
# 在 500 ms 前松开执行 `short`;达到 500 ms 执行 `long`。
DpiToggle = { short = "ShowDesktop", long = "MissionControl" }
# 动作会保持到物理按键松开。
MiddleClick = { HoldShortcut = "Ctrl+Space" }
# 保持修饰键,并只轻点一次 Tab。这会保持应用切换器打开。
Forward = { TapKeyHoldingModifiers = "Cmd+Tab" }
# 按住 Back 或 Forward 时,主滚轮变为虚拟拇指滚轮。
Back = { click = "BrowserBack", wheel = "HorizontalScroll" }短按和长按组合等待按键松开。在 500 ms 前松开会执行 short。达到 500 ms 会执行一次 long,之后松开不会执行 short。如果捕获结束、绑定改变或代理先停止,两个动作都不会执行。
CustomShortcut 会立即按下并松开整个组合键。HoldShortcut 会保持整个组合键直到松开。TapKeyHoldingModifiers 只保持修饰键,并轻点一次普通按键。Cmd+Tab、Alt+Tab 或其他应用切换器应使用后者。
滚轮按住仅适用于 Back 与 Forward,并且硬件必须报告原始滚轮支持。未移动滚轮就松开会执行 click。已滚动的按下不会执行点击动作。启用 invert_scroll 时,滚动方向会反转。
手势图
手势图是以 Up、Down、Left、Right 与 Click 为键的设备级绑定表。Click 表示不滑动的普通按下。
[devices."unit:6be9d300".bindings.GestureButton]
Up = "MissionControl"
Down = "ShowDesktop"
Left = "PrevTab"
Right = "NextTab"
Click = "AppExpose"每个受支持控件的手势模式相互独立。MiddleClick、Back 与 Forward 使用系统钩子。DpiToggle、GestureButton 与 HapticPanel 需要设备路由支持原始 XY。
中键手势图在 schema 11 中有效。你可以在 TOML 中编写或保留中键手势图。按应用的单个动作会在该应用中暂时替换完整手势图。
键盘、配置文件与 Actions Ring
全局功能键绑定
[keyboard.bindings] 映射任意键盘的功能键触发器。触发器形式为 [modifier+]…key。有效修饰键是 shift、control(ctrl)、option(alt)与 command(cmd)。有效按键是 esc 与 f1 至 f19。
[keyboard.bindings]
f1 = "MissionControl"
"shift+f2" = "ShowDesktop"
"cmd+f5" = { CustomShortcut = "Cmd+Shift+P" }此映射不同于 Logitech 键盘在 [devices.<key>.bindings] 下的 HID++ 控件绑定。keyboard.bindings 不接受短按和长按组合、手势图或滚轮按住。
应用别名与配置文件
per_app_bindings 是稀疏叠加。未列出的控件继续使用设备级 bindings 值。action_ring.per_app 则选择完整布局。
你可以直接使用平台标识符,或定义 [apps.<alias>] 并使用 app:<alias>。别名只能包含 ASCII 字母、数字、- 与 _。每个平台字段接受一个标识符或一个数组。
[apps.chrome]
name = "Google Chrome"
macos = "com.google.Chrome"
linux = ["google-chrome", "Google-chrome"]
windows = "exe:chrome.exe"
[devices."unit:6be9d300".per_app_bindings."app:chrome"]
Back = "PrevTab"| 标识符来源 | 可接受形式 |
|---|---|
| macOS | Bundle id,或没有 bundle id 时的精确可执行文件路径。 |
| Linux | X11 WM_CLASS 或 Wayland xdg app_id。 |
| Windows | 精确的小写可执行文件路径,或 exe:<filename>.exe。 |
最具体的匹配配置文件按以下顺序优先:
- 精确的平台标识符。
- Windows
exe:<filename>.exe兜底。 - 列出精确标识符的别名。
- 列出
exe:<filename>.exe兜底的别名。
若 app: 键指向未定义别名,文件无法加载。若两个别名列出同一平台标识符、标识符为空、标识符以 app: 开头,或 Windows 标识符含大写字母,文件也无法加载。
Actions Ring 布局
轮盘使用 8 个格位:Top、TopRight、Right、BottomRight、Bottom、BottomLeft、Left 与 TopLeft。每个已填充格位包含 action,并可选 icon 与 label。省略一个格位即可留空。
| 键 | 默认值 | 含义 |
|---|---|---|
enabled | true | 允许 ShowActionsRing 打开此设备的轮盘。 |
haptics | true | 悬停与激活时播放设备触感。 |
size | medium | 轮盘大小:small、medium 或 large。适用于该设备的所有布局。 |
default | 默认布局 | 前台应用没有布局时使用的布局。 |
per_app | 空 | 以应用选择器为键的完整布局。 |
None 与 ShowActionsRing 都不能用作格位动作。Actions Ring 不能包含空动作,也不能递归打开另一个轮盘。
[devices."unit:6be9d300".action_ring]
enabled = true
haptics = true
size = "large"
[devices."unit:6be9d300".action_ring.default.slots]
Top = { action = "Copy" }
Right = { action = { OpenApplication = { path = "/Applications/Safari.app", display_name = "Safari" } }, icon = "Applications" }
Bottom = { action = "ShowDesktop", label = "Desktop" }
[devices."unit:6be9d300".action_ring.per_app."app:chrome".slots]
Top = { action = "Cut" }
TopRight = { action = "Copy" }
Right = { action = "Paste" }
BottomRight = { action = "BrowserForward" }
Bottom = { action = "PlayPause" }
BottomLeft = { action = "BrowserBack" }
Left = { action = "Undo" }
TopLeft = { action = "Redo" }默认轮盘按格位顺序包含 Cut、Copy、Paste、Browser Forward、Play/Pause、Browser Back、Undo 与 Redo。按应用布局会完整替换默认布局。它不是稀疏叠加。
Flow
[flow] 保存 Flow 设置:已配对的电脑、通往每台电脑的屏幕边缘,以及随鼠标切换的设备。Flow 窗口中的配对会写入电脑条目,窗口也会写入边缘与通道。这一节为默认值时会被省略。
[flow]
enabled = true
require_modifier = false
[[flow.peers]]
name = "work-laptop"
public_key = "ed25519:0f1e2d3c4b5a69780f1e2d3c4b5a69780f1e2d3c4b5a69780f1e2d3c4b5a6978"
addresses = ["work-laptop.tailnet.example", "10.0.0.7"]
[[flow.layout]]
edge = "right"
peer = "work-laptop"
[[flow.devices]]
key = "unit:0f1e2d3c"
peer_channels = { self = 0, "work-laptop" = 1 }| 键 | 类型 | 默认值 | 含义 |
|---|---|---|---|
enabled | 布尔 | false | 开启 Flow。 |
require_modifier | 布尔 | false | 鼠标越过边缘时需要按住 Control,所有平台相同。 |
peers | 表数组 | 空 | 已配对的电脑:name、public_key 与可选的 addresses。 |
peers[].name | 字符串 | 必填 | 非空,无首尾空白或控制字符,且不能是 self。 |
peers[].public_key | 字符串 | 必填 | ed25519: 加 64 位小写十六进制数字。 |
peers[].addresses | 字符串数组 | 空 | mDNS 无法找到该电脑时尝试的主机名或 IP 地址。未写端口时使用 UDP 42424。 |
layout | 表数组 | 空 | 屏幕边缘:edge(left、right、top 或 bottom)与 peer。 |
devices | 表数组 | 空 | 参与切换的设备:key 与 peer_channels。 |
devices[].key | 物理设备键 | 必填 | serial: 或 unit: 身份键。路由键会被拒绝。 |
devices[].peer_channels | 字符串到整数的表 | 必填 | 从 0 开始的 Easy-Switch 通道,范围为 0 至 2。self 表示本机,且必须提供。 |
两台电脑使用相同名称或公钥、一个边缘出现两次,或布局、设备条目引用未知电脑时,文件无法加载。设备重复使用同一通道时,文件也无法加载。本机私钥不在此文件中。
有效的 schema 11 示例
这个完整示例只使用物理设备键。请复制结构,再替换为 OpenLogi 为你的设备生成的键与路径。
schema_version = 11
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
mouse_profile_target = "pointer"
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"
app_icon = "openlogi"
low_battery_notifications = true
lock_key_notifications = true
[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"
smooth_wheel = true
[devices."receiver:aabbccdd:slot:1".bindings]
Back = { click = "BrowserBack", wheel = "HorizontalScroll" }
Forward = { TapKeyHoldingModifiers = "Cmd+Tab" }
MiddleClick = { HoldShortcut = "Ctrl+Space" }
DpiToggle = { short = "ShowDesktop", long = "MissionControl" }
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."app:chrome"]
Back = "PrevTab"
Forward = "NextTab"
[devices."receiver:aabbccdd:slot:1".action_ring]
enabled = true
haptics = true
size = "medium"
[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
[devices."receiver:aabbccdd:slot:2"]
host_switch_targets = ["receiver:aabbccdd:slot:1"]
fn_lock = false
keep_os_layout = true
[devices."receiver:aabbccdd:slot:2".bindings]
KeySearch = "MissionControl"
KeyScreenCapture = "Sleep"
KeyCalculator = { OpenApplication = { path = "/System/Applications/Calculator.app", display_name = "Calculator" } }
"control:0x01f3" = { CustomShortcut = "Cmd+Shift+4" }
[devices."raw:046d:c900:ff43:0202:serial:your-serial".light]
enabled = true
auto_camera = false
brightness_percent = 65
temperature_kelvin = 4600
color = "ffffff"
[keyboard.bindings]
f1 = "MissionControl"
"shift+command+f5" = "ShowDesktop"
[apps.chrome]
name = "Google Chrome"
macos = "com.google.Chrome"
linux = ["google-chrome", "Google-chrome"]
windows = "exe:chrome.exe"
[flow]
enabled = true
require_modifier = false
[[flow.peers]]
name = "work-laptop"
public_key = "ed25519:0f1e2d3c4b5a69780f1e2d3c4b5a69780f1e2d3c4b5a69780f1e2d3c4b5a6978"
[[flow.layout]]
edge = "right"
peer = "work-laptop"
[[flow.devices]]
key = "unit:6be9d300"
peer_channels = { self = 0, "work-laptop" = 1 }