跳转至

语音唤醒

唤醒词是由 Gateway 持有的一个全局列表——不存在按节点自定义的列表。任何节点或应用 UI 都可以编辑该列表；Gateway 会持久化更改并将其广播到每个已连接的客户端。

  • 控制界面：位于 Settings → Talk 下的唤醒词编辑器。
  • macOS：本地 Voice Wake 启用/禁用开关。需要 macOS 26 及以上；运行/PTT 细节见 语音唤醒（macOS）。
  • iOS：设置中的本地 Voice Wake 启用/禁用开关。
  • Android：设置 → Voice 中的本地 Voice Wake 启用/禁用开关和唤醒词编辑器。需要 Android 设备端语音识别。

存储

唤醒词和路由规则存储在 Gateway 状态数据库中，默认位于 ~/.openclaw/state/openclaw.sqlite（可通过 OPENCLAW_STATE_DIR 覆盖），存放在 config_machine_state 的 voicewake.triggers 和 voicewake.routing 键下。下面的状态键和 Gateway 方法将唤醒词列表命名为 triggers。旧的 settings/voicewake.json 和 settings/voicewake-routing.json 仅作为 openclaw doctor --fix 的迁移输入——运行时从不读取它们。

协议

触发器列表

方法 参数 结果
voicewake.get 无 { triggers: string[] }
voicewake.set { triggers: string[] } { triggers: string[] }

voicewake.set 会对输入进行规范化：去除首尾空白，丢弃空条目，最多保留 32 个触发器，并将每个触发器截断为 64 个 UTF-16 代码单元而不拆分代理对。结果为空时回退到内置默认值（openclaw、claude、computer）。

路由（触发器到目标）

方法 参数 结果
voicewake.routing.get 无 { config: VoiceWakeRoutingConfig } 
{
  "version": 1,
  "defaultTarget": { "mode": "current" },
  "routes": [{ "trigger": "robot wake", "target": { "sessionKey": "agent:main:main" } }],
  "updatedAtMs": 1730000000000
}

每条路由的 target 仅支持以下之一：

  • { "mode": "current" }
  • { "agentId": "main" }
  • { "sessionKey": "agent:main:main" }

限制：最多 32 条路由，触发器文本最多 64 个字符。路由触发器的匹配和重复检测通过以下方式规范化：转为小写、去掉每个词首尾的标点、压缩空白（"Hey, Bot!!" 和 "hey bot" 会匹配并计为重复）——这比上面全局触发器列表所用的简单修剪更严格。

事件

事件 载荷
voicewake.changed { triggers: string[] }
voicewake.routing.changed { config: VoiceWakeRoutingConfig }

两者都会广播给所有具有读取范围的 WebSocket 客户端（macOS 应用、WebChat 等）以及每个已连接的节点。节点在连接后还会立即收到两者的初始快照推送。

客户端行为

  • macOS：调用 voicewake.set/voicewake.get 并监听 voicewake.changed，以与其他客户端保持同步。
  • iOS：调用 voicewake.set/voicewake.get 并监听 voicewake.changed，以保持本地唤醒词检测的响应性。
  • Android：调用 voicewake.set/voicewake.get，监听 voicewake.changed，并在启用时广播 voiceWake。识别保持在设备端且仅在前台运行；当 Talk、手动听写、语音备忘录采集或消息语音占用音频时会暂停。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw