参见设置
本文是 /settings/ 端点返回的所有设置 键, 类型(type_hint 标准)， 约束条件(metadata.constraint.range 以及（如适用） locked 与（标准）一起列出。
locked 设置是 运行时只读是。配置文件或 Haply Hub 虽然可以通过“设置”页面进行更改，但要使更改生效， 必须完全重启该服务. 这些设置见下表 启动显示为。
构成
在服务启动过程中，用于覆盖设置的配置文件位于以下位置：
| 平台 | 位置 |
|---|---|
| Windows | C:\ProgramData\Haply\Inverse\haply-inverse-service-config.json |
| macOS | /Library/Application Support/Haply/Inverse/haply-inverse-service-config.json |
| Linux | /etc/haply-inverse-service/haply-inverse-service-config.json |
配置文件是将配置键映射到重写值的 扁平化 JSON 对象是。键是 /settings/ 必须是 HTTP 路由返回的有效配置键（API 参考 （注）未指定的键将使用服务的默认值。
例如，网络配置的重定义如下：
{
"communication/http/port": 8400,
"communication/websocket/port": 8500,
"communication/events/port": 9000,
"communication/bind_all_interfaces": true
}
是否显示及筛选
/settings 列表端点(GET /settings, GET /settings/)基本上是 基本（basic） 仅返回设置。若要包含指定了 advanced 标志的设置，请 ?advanced=true如果要包含带有“已弃用”标记的别名，请 ?deprecated=true请传递该参数。隐藏设置仅供内部使用， POST /settings/misc/hidden_settings通过 misc/hidden_settings仅当已设置时才会显示（目前没有相应的查询参数）。过滤器标志以“AND”条件组合。 advanced哇 hidden 所有标志均已设置的密钥必须同时满足两个门限条件。针对已知密钥的POST和DELETE操作不受门限限制。
如果正确使用规范键（canonical key），则单键查询（GET /settings/<key>) 可绕过 advanced/deprecated 门。这对具备相关知识的客户端非常有用。隐藏密钥仍受该门的限制。
有三种运行时开关用于设置网关的初始值，该值在服务生命周期内保持不变：
| 键 | 类型 | 约束条件 | 说明 |
|---|---|---|---|
misc/advanced_settings | bool | — | GET /settings 在列表中 advanced 包含已标记的设置（默认值 false). 对于所有请求， ?advanced=true这相当于传递…… |
misc/deprecated_settings | bool | — | GET /settings 在列表中 deprecated 包含已标记的设置（默认值 false). 对于所有请求， ?deprecated=true这相当于传递…… |
类型映射
API 返回的类型提示对应于以下 JSON 格式：
STRING→stringBOOL→boolINT→intFLOAT→floatARR_STRING→string[]VEC3→vec3({x, y, z}（具有属性的对象）GENERIC→json(任意结构化值)
communication/…
HTTP、WebSocket 和事件流服务器的网络端口及绑定地址。其中大部分项仅在启动时使用。
| 键 | 类型 | 约束条件 | 说明 |
|---|---|---|---|
communication/serial/enabled | bool | — | 启用或禁用串行设备通信。 |
communication/bind_address | string | 启动 | 这是 HTTP 和 WebSocket 服务器将绑定的 IP 地址。 |
communication/bind_all_interfaces | bool | 启动 | 使用服务器代替 localhost 0.0.0.0绑定到。 |
communication/http/port | int | 启动 | HTTP REST API 端口（默认值 10000). |
communication/websocket/port | int | 启动 | v3.1 WebSocket 默认端口（默认值 10001). |
communication/websocket/legacy_port | int | 启动 | Legacy v3.0 WebSocket 端口（默认值 10000). |
communication/events/port | int | 启动 | 事件流 WebSocket 端口（默认值 10020). |
devices/…
devices/detection/…
这是串行端口扫描策略。所有项目均属于高级（advanced）设置。
| 键 | 类型 | 约束条件 | 说明 |
|---|---|---|---|
devices/detection/scan_period_ms | int | 范围 100–10000；启动时 | 串行端口扫描间隔（毫秒）。 |
devices/detection/handshake_timeout_s | int | 范围 1–15 | 各端口的握手超时（秒）。 |
devices/detection/max_retries | int | 范围 1–10 | 每个端口的最大握手重试次数。 |
devices/detection/failure_log_delay_s | int | 范围 1–60 | 在再次记录检测失败之前的时间延迟（秒）。 |
devices/detection/block_looping_ports | bool | — | 一旦检测到环路端口，将阻止设备进入就绪状态。 |
devices/detection/excluded_ports | json | — | 检测时应跳过的串行端口路径。 |
devices/detection/additional_ports | string[] | — | 无需任何条件即可进行扫描的额外串行端口路径。 |
devices/detection/allowed_vendor_id_filter | string[] | — | 列举端口时允许的 USB 供应商 ID。 |
devices/detection/port_name_substring_filter | string[] | — | 要与各平台进行匹配的端口名称的子字符串。 |
devices/detection/wireless_verse_grip_description_filter | string[] | — | 用于无线 VerseGrip 检测的端口说明部分的字符串。 |
devices/detection/inverse3x_description_filter | string[] | — | Inverse3x 检测端口说明中的部分字符串。 |
devices/detection/extra_ports （已停用） | string[] | — | 相反 devices/detection/additional_ports。读写操作会通过正式密钥以透明方式进行。 |
devices/*inverse/…
这是适用于所有Inverse3 系列设备的全局默认值。若在会话中进行了覆盖，则以会话设置为准。
在 3.5.1 版本中更名为
在 3.5.0 版本中，通配符模式 devices/inverse*/…并且，先行 *现在 inverse 位于前面。使用旧字面量的配置文件在 3.5.1 版本中会因绑定失败而无法运行，请进行更新。除此之外，该键本身并未发生任何变化。
| 键 | 类型 | 约束条件 | 说明 |
|---|---|---|---|
devices/*inverse/filters/force_scale/gain | float | 范围 0.0–2.0 | 适用于所有设备的全局力输出倍率。 |
devices/*inverse/filters/force_gate/gain | float | 范围 0.0–1.0 | 新会话的默认功率门增益。 |
devices/*inverse/control_timeout_ms | int | 范围 50–10000 | 在解除设备控制锁定之前的超时时间（毫秒）。 |
devices/*inverse/query_orientation_on_idle | bool | — | 当设备处于空闲状态时，固件会查询机身的方向。 |
devices/*inverse/safeties/expose_in_snapshot | bool | — | GET /devices/{id} 在快照中包含各设备的安全标记。 |
devices/presets
| 键 | 类型 | 约束条件 | 说明 |
|---|---|---|---|
devices/presets | json | — | 按设备类型划分的默认设备配置预设（inverse_arm_front_*, inverse_led_front_*, minverse_*, verse_grip_default, wireless_verse_grip_default, custom_verse_grip_default（如坐标系转换、基等）。 |
devices/wireless_verse_grip/…
| 键 | 类型 | 约束条件 | 说明 |
|---|---|---|---|
devices/wireless_verse_grip/battery/low_threshold | int | — | 触发低电量警告的电池电量（%）阈值。 |
devices/wireless_verse_grip/battery/critical_threshold | int | — | 触发电池危险警告的电池电量（%）阈值。 |
devices/wireless_verse_grip/battery/reset_margin | int | — | 在解除电池警告之前的滞后裕量值。 |
devices/wireless_verse_grip/filters/orientation_filter | json | 启动时 | 针对无线 VerseGrip 方向的 One Euro Filter 配置。 |
features/…
features/calibration/…
| 键 | 类型 | 约束条件 | 说明 |
|---|---|---|---|
features/calibration/hall_threshold | int | 范围 1–32 | 校准过程中，判断为已安装笔的孔传感器水准。 |
features/grip_hook/…
这是一种自动握钩功能，可在直握握把时固定光标位置。
| 键 | 类型 | 约束条件 | 说明 |
|---|---|---|---|
features/grip_hook/enabled | bool | — | 当将握把竖直握持时，将激活握把钩自动锁定功能。 |
features/grip_hook/use_hall | bool | — | 在握持检测中，使用孔传感器阈值而非方向。 |
features/grip_hook/hall | int | 范围 1–32 | 触发夹持锁定的霍尔传感器值阈值。 |
features/grip_hook/hold_duration | int | 范围 10–1000 | 触发后保持锁定的时间（毫秒）。 |
features/navigation/bubble/…
这是气泡导航模块的默认值。 bubble 该操作在首次激活时会被传递给会话。每个字段的运行时行为是 导航模块 请参阅该页面。
| 键 | 类型 | 约束条件 | 说明 |
|---|---|---|---|
features/navigation/bubble/center | vec3 | — | 这是气泡的默认中心位置。 |
features/navigation/bubble/center_enabled | bool | — | 在首次启用气泡操作时设置的 center应用。 |
features/navigation/bubble/rotation_enabled | bool | — | 将工作空间旋转应用于导航方向。 |
features/navigation/bubble/scale_enabled | bool | — | 将工作区比例应用于导航速度。 |
features/navigation/bubble/center_drift_speed | float | ≥ 0 | auto_follow 这是中心模式下的漂移速度（m/s）。 |
features/navigation/bubble/max_velocity | float | — | 这是该速度区间内的最大导航速度（m/s）。 |
features/navigation/bubble/velocity_zone_width | float | — | 这是气泡表面外侧速度区域的宽度（米）。 |
features/navigation/bubble/reset_velocity_on_entry | bool | — | 当光标进入气泡时，将速度重置为0。 |
features/navigation/bubble/spring_inner | float | — | 这是气泡中心的弹簧刚度（N/m）。 |
features/navigation/bubble/spring_surface | float | — | 这是气泡表面的弹簧刚度（N/m）。 |
features/navigation/bubble/spring_outer | float | — | 这是外边界处的弹簧刚度（N/m）。 |
features/navigation/bubble/damping_inner | float | — | 这是气泡中心处的衰减系数（Ns/m）。 |
features/navigation/bubble/damping_surface | float | — | 这是气泡表面的衰减系数（Ns/m）。 |
features/navigation/bubble/damping_outer | float | — | 这是外边界处的衰减系数（Ns/m）。 |
features/navigation/bubble/wall_stiffness | float | — | 这是位于外边界处的刚性壁的刚度（N/m）。 |
features/navigation/bubble/bump_width | float | — | 这是气泡表面上触觉凸起的宽度（m）。 |
features/navigation/bubble/bump_stiffness | float | — | 这是气泡表面触觉凸起处的刚度（N/m）。 |
features/navigation/bubble/stop_at_collision | bool | — | 当碰撞处于活动状态时，阻止气泡中心沿碰撞方向漂移。 |
features/navigation/bubble/collision_threshold | float | > 0 | 这是用于检测碰撞的外力大小（N）。 |
features/navigation/bubble/collision_inflate_scale | float | ≥ 1 | 在冲突处于活动状态期间 velocity_zone_width这是乘以的倍率。 |
features/navigation/bubble/collision_exit_ratio | float | 范围 (0,1] | 这是滞后比。 |ext_force|a collision_threshold × this 向下坠落时，将解除碰撞状态。 1.0这将禁用滞后效应。 |
features/navigation/bubble/avatar_boundary_enabled | bool | — | 将化身的世界位置设置为 avatar_boundary 限制在 SDF 形状内。 |
features/safe_trajectory/…
这是用于末端执行器动作的速度限制器。
| 键 | 类型 | 约束条件 | 说明 |
|---|---|---|---|
features/safe_trajectory/enabled | bool | — | 启用“安全轨迹（safe-trajectory）”限速器。 |
features/safe_trajectory/max_vel | float | 范围 0.01–2.0 | 这是允许的最大末端执行器速度（m/s）。 |
features/screensaver/…
当会话未进行控制时，Inverse3 设备上播放的空闲动画。
| 键 | 类型 | 约束条件 | 说明 |
|---|---|---|---|
features/screensaver/enabled | bool | — | Inverse3 在设备上启用空闲时的屏幕保护程序动画。 |
features/screensaver/speed | float | 范围 0.001–0.2 | 这是屏幕保护程序动画的速度。 |
features/screensaver/distracted_speed | float | 范围 0.001–0.2 | 这是当用户在附近但未进行交互时的动画速度。 |
features/sdf/…
这是带符号距离场（SDF）触觉效果模块（SDF HFX）。
| 键 | 类型 | 约束条件 | 说明 |
|---|---|---|---|
features/sdf/enabled | bool | — | 启用或禁用 SDF 触觉效果模块。 |
features/sdf/state_output | bool | — | 默认情况下，设备输出有效载荷中包含 SDF 状态。 |
features/sdf/max_count | int | 范围 0–128 | 活动 SDF 效果的最大数量（0 = 无限制）です。 |
features/sdf/events/created | bool | — | 当生成新的 SDF 效果时，会触发该事件。 |
features/sdf/events/deleted | bool | — | 当 SDF 效果被移除时，会触发该事件。 |
features/sdf/events/updated | bool | — | 当 SDF 效果更新时，会触发该事件。 |
features/sdf/probe_on_zero_force/enabled | bool | — | 当施加的力接近0时，会自动探测SDF场。 |
features/sdf/probe_on_zero_force/delay | float | 范围 0.001–60.0 | 这是能量降至0后，直至开始自动探测所经历的延迟时间（秒）。 |
features/verse_grip_pairing/…
Inverse3 这是一项用于跟踪设备与（有线或无线）Verse Grip 之间连接/断开状态的功能。它是Haply Hub 配对用户界面的基础。
| 键 | 类型 | 约束条件 | 说明 |
|---|---|---|---|
features/verse_grip_pairing/enabled | bool | — | 启用配对及连接/断开跟踪功能。 |
features/verse_grip_pairing/hall_threshold_vg | int | 范围 1–32 | 根据有线VerseGrip连接判断的孔位级别。 |
features/verse_grip_pairing/hall_threshold_wvg | int | 范围 1–32 | 这是根据无线 VerseGrip 连接判断的孔位级别。 |
features/verse_grip_pairing/detach_debounce_ms | int | 范围 0–1000 | 这是在确定分离之前反跳的时间段（毫秒）。 |
features/verse_grip_pairing/heartbeat_ms | int | 范围 100–10000 | 强制重新提醒之间的间隔（毫秒）。 |
features/verse_grip_pairing/force_attached | bool | — | 绕过霍尔传感器来检测连接状态 true将其永久固定（用于绕过硬件故障）。 |
session/serialization/…
“Transform” 输出格式 — 会影响 WebSocket 和 HTTP JSON 负载。为了反映按会话范围的特性，这些键在 3.5.1 版本中 serialization/*在……中 session/serialization/*已重定向至该地址。原有路径仍可通过“已弃用（deprecated）”别名进行解析。
| 键 | 类型 | 约束条件 | 说明 |
|---|---|---|---|
session/serialization/explicit_fields | bool | — | 在序列化输出中包含与恒等默认值相同的 transform 字段（例如： position: {0,0,0}, rotation: {w:1,…}). 当客户端要求所有字段都必须明确存在时，此选项非常有用。默认值： false. |
session/serialization/force_complete_transforms | bool | — | 包括方向专用设备（Verse Grip、Wireless Verse Grip）在内的所有 transform 输出 position, rotation, 还有 scale总是输出。否则，这些设备会 rotation仅输出。 session/serialization/explicit_fields包括。默认值： false. |
serialization/explicit_fields （停止支持） | bool | — | 相反 session/serialization/explicit_fields。读写操作会通过正式密钥以透明方式进行。 |
serialization/force_complete_transforms （停止支持） | bool | — | 相反 session/serialization/force_complete_transforms。读写操作会通过正式密钥以透明方式进行。 |
session/…
这是会话调度程序。
| 键 | 类型 | 约束条件 | 说明 |
|---|---|---|---|
session/min_simulation_rate_hz | int | 范围 20–500 | 这是触发警告前的设备模拟速度（Hz）的最低允许值。 |
rate/…
这是服务分批处理。该功能在 3.5.1 版本中引入——以下四个 rate/websocket/* 基此前曾 session/commands/* 它位于下方，而原有路径仍可通过“已弃用（deprecated）”别名进行解析。
| 键 | 类型 | 约束条件 | 说明 |
|---|---|---|---|
rate/websocket/zoh_window_ms | int | — | 零阶保持（zero-order-hold）窗口——抑制在此窗口内接收到的探针（毫秒）。 |
rate/websocket/drop_warning_threshold | int | — | 这是在触发警告之前，在窗口中拖放的命令数量。 |
rate/websocket/drop_warning_window_ms | int | — | 这是用于聚合已丢弃命令的滑动窗口大小（毫秒）。 |
rate/websocket/tick_on_empty_batch | bool | 高级 | 即使整个 WebSocket 批处理被丢弃， main_loop 预约Tik。 |
session/commands/zoh_window_ms （停止支持） | int | — | 相反 rate/websocket/zoh_window_ms使用。读写操作会以透明的方式进行转发。 |
session/commands/drop_warning_threshold （停止支持） | int | — | 相反 rate/websocket/drop_warning_threshold使用。读写操作会以透明的方式进行转发。 |
session/commands/drop_warning_window_ms （停止支持） | int | — | 相反 rate/websocket/drop_warning_window_ms使用。读写操作会以透明的方式进行转发。 |
session/commands/tick_on_empty_batch （停止支持） | bool | — | 相反 rate/websocket/tick_on_empty_batch使用。读写操作会以透明的方式进行转发。 |
仅限内部使用的设置
在 3.5.1 版本中，有多个设置系列 hidden以……形式提供，并保留作内部使用—— rate/dispatch/*(AIMD 发送速率上限及背压阈值)， session/freeform/*（基于行为的指纹识别）， session/serialization/preview/*（包括欧拉四元数输出和 Wireless VerseGrip 路由等发布前的串行化实验）。为了调试， misc/hidden_settings虽然可以通过该方式访问，但后续的小版本更新中可能会将其升级、更名或移除，因此请勿将客户端的行为固定在此设置上。