命令行

查询设备，并通过 OpenLogi 的 JSON API 在脚本中控制 DPI、SmartShift 与 Fn 锁定。

使用 openlogi 查询设备、诊断硬件和执行本地自动化。本页以 v0.8.11 为准；下文的 --save 选项需要更新的开发构建。

找到命令

Linux 安装包与 Windows MSI 会把 openlogi 加入 PATH。安装 MSI 后请打开新的终端。macOS 应用与 Windows 免安装包可直接运行内嵌的可执行文件：

# macOS，OpenLogi 已安装到 /Applications
/Applications/OpenLogi.app/Contents/MacOS/openlogi --version

# Windows 免安装包，在解压后的应用目录中运行
.\bin\openlogi.exe --version

下文中的 openlogi 可替换为对应的可执行文件路径。安装包与源码构建方式见安装。

常用命令

openlogi list
openlogi assets sync
openlogi --help

list 显示已连接的接收器、已配对设备与 Logitech 摄像头。有兼容的代理运行时读取代理的设备列表，否则直接枚举硬件。直接运行 openlogi 也会执行 list。扫描结果为空时，退出码为 2。

assets sync 下载设备图片。设置 OPENLOGI_LOG=debug 可启用详细日志；日志写入 stderr。

JSON 自动化

执行 openlogi api 前，请先启动 OpenLogi。这组命令需要正在运行且协议兼容的代理，不会启动代理或直接访问硬件。如果收到 version_mismatch，请使用配套的 CLI 与代理构建。

openlogi api status
openlogi api devices

status 返回代理状态与权限，devices 返回设备 ID、连接状态、电量和实测能力。操作设备前，inventory 必须为 "ready"；只有此时空数组才表示没有外设。scanning 表示仍在扫描，unavailable 表示设备列表不可用。这个 API 不包含摄像头。

从 api devices 中复制完整且非 null 的 id，替换以下示例中的 DEVICE_ID，并保留引号。DPI 与 SmartShift 使用鼠标的 ID，Fn 锁定使用兼容键盘的 ID。

openlogi api dpi --device "DEVICE_ID"
openlogi api smartshift --device "DEVICE_ID"
openlogi api fn-lock --device "DEVICE_ID"

ID 标识当前连接路径。重连或更新后请重新获取，不要按设备名称拼接 ID，也不要把 ID 当作配置键。一个 ID 对应多个设备时，命令会返回 ambiguous_device。ID 可能包含硬件身份信息，分享输出前请删除这些信息。电量或能力为 null 表示尚无实测值。

修改设置

上面的命令只读取设置。添加设置参数后，命令会立即应用更改：

openlogi api dpi --device "DEVICE_ID" --set 1200
openlogi api smartshift --device "DEVICE_ID" --mode free
openlogi api smartshift --device "DEVICE_ID" --mode ratchet --auto-disengage 255
openlogi api fn-lock --device "DEVICE_ID" --set on

**DPI：**从读取结果的 supported 数组中选择取值。不支持的数值会被拒绝，不会自动取整。
**SmartShift：**未指定的字段保留当前值。只传 --mode ratchet 会保留现有的自动释放阈值；永久棘轮模式还需传入 --auto-disengage 255。阈值 1–254 的固件单位为 0.25 转/秒，0 无效。
Fn 锁定：on 让功能键直接发送 F1–F12，off 使用键帽标注的媒体功能。

在 v0.8.11 中，API 写入返回 persistence: "not_saved"，不会修改 config.toml。重连、唤醒或配置变更后，代理可能重新应用已保存的设置。使用这个发行版时，请在桌面应用中保存偏好。

DPI 与 SmartShift 写入后会回读校验，Fn 锁定会检查固件响应。如果写入超时、断开连接或校验失败，请先重新读取设置，再决定是否重试；硬件可能已经发生变化。

JSON 与退出码

参数解析成功后，每次 API 调用向 stdout 写入一个 JSON 对象和换行。例如，扫描完成且未发现外设时返回：

{"schema_version":1,"ok":true,"data":{"inventory":"ready","devices":[]}}

运行时错误使用同一外层结构：

{"schema_version":1,"ok":false,"error":{"code":"inventory_not_ready","message":"agent inventory is not ready; no device operation was attempted"}}

退出码	`openlogi api` 的含义
`0`	成功，`ok` 为 `true`。
`1`	运行时失败，请检查 `error.code`。
`2`	参数无效，文字诊断信息写入 stderr。

脚本必须检查 schema_version 与 ok，忽略未知对象字段，并把未知错误码视为失败。按 error.code 判断错误类型；error.message 仅供阅读。--help 与 --version 返回文本；stdout 写入失败时无法保证返回 JSON。

在开发版本中保存设置

--save 从 v0.8.11 之后的 master 提交 4863a45e 开始可用。已发布的 v0.8.11 CLI 不接受这个选项。

在这些开发构建中，可为明确的 DPI、SmartShift 或 Fn 锁定更改添加 --save：

openlogi api dpi --device "DEVICE_ID" --set 1200 --save

命令先校验硬件结果，再保存该设置，并请求代理重新加载配置。成功时返回 persistence: "saved"。保存要求已探测到物理设备身份；如果同一设置存在按连接路径的覆盖，命令会拒绝保存。保存 SmartShift 时，阈值必须为 8–255。

硬件写入、文件保存与重新加载是分开的步骤，后续失败不会撤销硬件更改。保存或重新加载失败时，请检查 error.persistence：not_saved 表示文件未保存，saved 表示文件已保存但重新加载失败或结果未知。重新加载错误仍以 1 退出。冲突处理与错误码详见 CLI 参考。

硬件诊断

使用 openlogi diag --help 查看诊断命令。diag features 与 diag controls 报告设备能力。其他诊断可能写入硬件：默认情况下，diag dpi 与 diag smartshift 会先修改设置，并在成功完成后恢复；diag lighting 则应用指定颜色。日常脚本请使用上面的 API。

参考：v0.8.11 CLI 指南 · 开发版本 CLI 指南