Nodes and media
语音唤醒
唤醒词是由 Gateway 网关管理的单一全局列表——不存在各节点自定义列表。任何节点或应用 UI 都可以编辑该列表；Gateway 网关会持久化更改，并将其广播给每个已连接的客户端。
- macOS：本地 Voice Wake 启用/禁用开关。需要 macOS 26+；有关运行时/PTT 的详细信息，请参阅 Voice Wake（macOS）。
- iOS：设置中的本地 Voice Wake 启用/禁用开关。
- Android：Settings → Voice 中的本地 Voice Wake 启用/禁用开关和唤醒词编辑器。需要 Android 设备端语音识别。
存储
唤醒词和路由规则存储在 Gateway 网关状态数据库中，默认位于 ~/.openclaw/state/openclaw.sqlite（可通过 OPENCLAW_STATE_DIR 覆盖），使用表 voicewake_triggers、voicewake_routing_config、voicewake_routing_routes。旧版 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 } |
voicewake.routing.set |
{ config: VoiceWakeRoutingConfig } |
{ 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、手动听写、语音留言录制或消息语音占用音频时，识别会暂停。
