OpenClaw 全局语音唤醒词机制:Gateway 统一持有与跨节点同步实战解析
OpenClaw 全局语音唤醒词机制:Gateway 统一持有与跨节点同步实战解析
导读
OpenClaw 的语音唤醒词(Voice Wake)采用一种"全局单一列表、由 Gateway 统一持有"的设计:整个网络(macOS 桌面端、iOS/Android 移动节点、WebChat 等所有 WebSocket 客户端)共享同一份唤醒词列表,任何一端修改都会由 Gateway 持久化并广播到全部设备,而每个设备仍然保留独立的"Voice Wake 启用/禁用"本地开关。本文以 docs/nodes/voicewake.md 为骨架,结合仓库中 Gateway 服务端、存储层与三端客户端的真实实现,完整讲解数据存储格式、RPC 协议、事件广播链路、各端同步代码路径与测试验证,帮助你理解并排查语音唤醒词的配置与同步问题。
设计模型:一份全局列表,本地只管开关
从架构上看,唤醒词是 Gateway 拥有的单一全局状态,核心约束有三条:
- 不存在按节点自定义的唤醒词——iOS、Android、macOS 看到的是同一份列表,没有 per-node 差异;
- 任意节点/应用 UI 都可以编辑该列表,改动由 Gateway 持久化并广播给所有人,而不是"谁改谁独有";
- 每台设备仍保留自己的 Voice Wake 开关(enabled/disabled),这是一个纯本地 UX 与权限状态,不属于全局同步范围。
这一设计在 macOS 端 AppState 中被清晰地实现为两个互相独立的属性:swabbleEnabled(本地开关,写入 UserDefaults)与 swabbleTriggerWords(全局列表,写入后触发 Gateway 同步)。从源码结构看(apps/macos/Sources/Clawdbot/AppState.swift),本地开关的变更只影响本机 VoiceWakeRuntime 是否运行,而触发词变更则同时刷新本机运行时并发起全局同步——这正好对应文档中"本地 UX + 权限分开"的表述。
存储层:voicewake.json 与原子写入
文件位置与数据结构
唤醒词持久化在 Gateway 宿主机上,路径为:
~/.openclaw/settings/voicewake.json
其 JSON 结构(与文档示例一致):
{
"triggers": ["clawd", "claude", "computer"],
"updatedAtMs": 1730000000000
}
triggers:当前生效的唤醒词字符串数组;updatedAtMs:最近一次成功修改的时间戳(毫秒),可用于判断配置新旧。
存储实现细节
src/infra/voicewake.ts 是这一存储层的唯一实现,几个值得注意的点:
- 默认值常量:
DEFAULT_TRIGGERS = <a href="https://link.gitcode.com/i/e5cd86a05e7693ed53a16452cf33ce85" target="_blank">"clawd", "claude", "computer"]([src/infra/voicewake.ts); - 文件不存在时的行为:
loadVoiceWakeConfig返回{ triggers: 默认列表, updatedAtMs: 0 },即"从未配置"与"配置成默认值"在读取层面等价; - 写入前的清洗:
sanitizeTriggers会对每个词做trim()、丢弃空串,若清洗后为空则整体回退到默认列表(src/infra/voicewake.ts); - 原子落盘:写入采用"临时文件 + rename"策略(
writeJSONAtomic),避免进程异常退出导致 JSON 文件损坏(src/infra/voicewake.ts); - 写锁串行化:模块内部用 Promise 链实现了一个简易互斥锁(
withLock),保证并发的voicewake.set不会产生覆盖写竞争(src/infra/voicewake.ts)。
对应的单元测试 src/infra/voicewake.test.ts 覆盖了三个关键场景:文件缺失返回默认值、清洗并持久化触发词、空列表回退默认值,可以直接作为存储层行为的可执行规格。
协议层:三个方法/事件构成完整同步契约
RPC 方法
文档定义了两个 Gateway 方法,仓库在 src/gateway/server-methods/voicewake.ts 与 src/gateway/server-methods-list.ts 中注册实现:
| 方法 | 请求参数 | 成功响应 | 说明 |
|---|---|---|---|
voicewake.get |
无 | { triggers: string[] } |
读取当前全局列表;读取失败返回 UNAVAILABLE 错误 |
voicewake.set |
{ triggers: string[] } |
{ triggers: string[] } |
校验、清洗、持久化,随后广播 voicewake.changed;triggers 不是数组时返回 INVALID_REQUEST |
触发词规范化与安全上限
Gateway 侧的清洗函数位于 src/gateway/server-utils.ts 的 normalizeVoiceWakeTriggers,它在存储层 sanitizeTriggers 之外额外追加了两道安全上限:
- 最多保留 32 个触发词(
slice(0, 32)); - 每个触发词最长 64 字符(
slice(0, 64))。
其余规则与存储层一致:逐词 trim、丢弃空串、清洗后为空则回退默认列表。这意味着无论哪个端发起 voicewake.set,到达 Gateway 后都会经历"规范化 + 上限裁剪"再落盘,非法或超限的输入不会被持久化。
事件广播
- 事件名:
voicewake.changed,payload 为{ triggers: string[] }; - 注册来源:事件在 src/gateway/server-methods-list.ts 的
GATEWAY_EVENTS白名单中声明; - 广播实现:
voicewake.set成功后会调用context.broadcastVoiceWakeChanged(cfg.triggers),其内部通过broadcast("voicewake.changed", { triggers }, { dropIfSlow: true })推送给所有 WebSocket 客户端(src/gateway/server.impl.ts)。dropIfSlow: true表示对消费速度跟不上的慢客户端允许丢事件,避免阻塞 Gateway 主循环。
错误语义
从 src/gateway/server-methods/voicewake.ts 可以看到两类明确的失败分支:
params.triggers不是数组 → 返回INVALID_REQUEST,附错误消息"voicewake.set requires triggers: string[]";- 读取或写入存储抛异常 → 返回
UNAVAILABLE,错误详情经formatForLog处理(只进日志,不回传给客户端明文异常)。
同步链路:从一次编辑到全端生效
以任意端在设置页修改唤醒词为例,完整链路如下:
- 客户端对本地列表做与 Gateway 一致的清洗(trim、去空、上限裁剪、空则回默认);
- 客户端通过 WebSocket 调用
voicewake.set; - Gateway 再次规范化 → 原子写入
~/.openclaw/settings/voicewake.json(更新updatedAtMs)→ 广播voicewake.changed; - 所有已连接的 WebSocket 客户端(macOS、WebChat 等)收到事件并应用新列表;
- 已连接的 iOS/Android 节点同样收到事件;新节点在连接握手时还会收到一次"当前状态快照"推送。
"节点连接即推送快照"这一行为在 src/gateway/server/ws-connection/message-handler.ts 中有明确实现:当节点完成 hello 握手后,Gateway 异步 loadVoiceWakeConfig(),并通过 nodeRegistry.sendEvent(nodeSession.nodeId, "voicewake.changed", { triggers }) 把当前列表作为初始状态推给该节点。读取失败仅记录 warning,不阻断握手流程。
这一点在端到端测试 src/gateway/server.models-voicewake-misc.e2e.test.ts 中被验证:
- 测试一(L140-L181):新 Gateway 上
voicewake.get返回默认["clawd", "claude", "computer"];voicewake.set传入[" hi ", "", "there"]后响应被清洗为["hi", "there"],同一连接随后收到voicewake.changed,且磁盘文件~/.openclaw/settings/voicewake.json中已写入清洗后的值与数值型updatedAtMs; - 测试二(L183-L229):以
role: "node"、platform: "ios"连接后,无需主动请求即可先收到一次包含默认触发词的voicewake.changed(快照推送),随后任意端voicewake.set触发广播,节点收到更新后的列表。
各端实现:macOS / iOS / Android 的同步代码路径
macOS 桌面端
- 设置 UI:apps/macos/Sources/Clawdbot/VoiceWakeSettings.swift 提供 "Trigger words" 编辑表格,支持逐词增删、空词禁用"Add word"、一键 "Reset defaults"(重置回
defaultVoiceWakeTriggers),并提示"触发词会出现在转写文本中,尽量短以避免误触发"; - 状态与同步:
AppState.swabbleTriggerWords的didSet会先刷新本机VoiceWakeRuntime,再调用scheduleVoiceWakeGlobalSyncIfNeeded()——该方法以 650ms 防抖 合并连续编辑,随后调用GatewayConnection.shared.voiceWakeSetTriggers(sanitized)(apps/macos/Sources/Clawdbot/AppState.swift); - 接收广播:apps/macos/Sources/Clawdbot/VoiceWakeGlobalSettingsSync.swift 监听
voicewake.changed并解码 payload,随后AppStateStore.shared.applyGlobalVoiceWakeTriggers(triggers)——该函数用suppressVoiceWakeGlobalSync标志抑制回环同步,避免"收到广播又发一次 set"造成死循环(apps/macos/Sources/Clawdbot/AppState.swift); - 运行时消费:
VoiceWakeRuntime将触发词封装进RuntimeConfig.triggers(apps/macos/Sources/Clawdbot/VoiceWakeRuntime.swift),识别引擎通过WakeWordGate匹配转写文本;仅命中触发词而无后续内容的场景(isTriggerOnly)也会走专门的暂停检查逻辑,避免误唤醒后长时间占用麦克风。
iOS 节点
- 本地偏好:apps/ios/Sources/Voice/VoiceWakePreferences.swift 统一定义了 iOS 端的默认值与上限——注意:iOS 本地初始默认是
["clawd", "claude"](注释明确"与 mac 端保持一致"的意图),maxWords = 32、maxWordLength = 64,与 Gateway 侧上限一致;sanitizeTriggerWords的清洗规则(trim、去空、prefix 裁剪、空则回默认)也与服务端对齐; - 设置页:apps/ios/Sources/Settings/VoiceWakeWordsSettingsView.swift 提供 Wake Words 编辑视图,提交时调用
commitTriggerWords():先saveTriggerWords落本地,再做 650ms 防抖,最后经NodeAppModel.setGlobalWakeWords(snapshot)发送; - 上行:apps/ios/Sources/Model/NodeAppModel.swift 的
setGlobalWakeWords将清洗后的列表编码为{"triggers": [...]},调用gateway.request(method: "voicewake.set", ..., timeoutSeconds: 12),异常按 best-effort 忽略; - 下行:
startVoiceWakeSync先voicewake.get拉一次当前值,再订阅voicewake.changed事件流持续更新(apps/ios/Sources/Model/NodeAppModel.swift);VoiceWakeManager使用VoiceWakePreferences.loadTriggerWords()作为检测触发词来源,从而让本地唤醒检测始终跟随全局列表。
Android 节点
- 设置入口:apps/android/app/src/main/java/com/clawdbot/android/ui/SettingsSheet.kt 提供 "Wake Words (comma-separated)" 输入框,编辑提交时解析并调用
viewModel.setWakeWords(parsed),另有 "Reset defaults" 按钮; - 同步实现:apps/android/app/src/main/java/com/clawdbot/android/NodeRuntime.kt 是 Android 侧的核心:
- 本地编辑后
scheduleWakeWordsSyncIfNeeded()以 650ms 防抖 组装{"triggers":[...]}并调用operatorSession.request("voicewake.set", params)(L777-L794); - 收到
voicewake.changed时解析triggers数组并applyWakeWordsFromGateway写回本地偏好,同时用suppressWakeWordsSync抑制回环(L753-L775); - 连接后通过
refreshWakeWordsFromGateway()主动voicewake.get拉取一次当前状态(L796-L807); setWakeWords/resetWakeWordsDefaults最终落到SecurePrefs,由 apps/android/app/src/main/java/com/clawdbot/android/voice/VoiceWakeManager.kt 消费做唤醒词检测。
- 本地编辑后
值得注意的是,三端在"上行防抖"上采用了完全一致的 650ms 等待窗口(macOS AppState.swift、iOS VoiceWakeWordsSettingsView.swift、Android NodeRuntime.kt),这保证了连续编辑时不会向 Gateway 发送大量中间态请求;而 suppressVoiceWakeGlobalSync / suppressWakeWordsSync 标志则是各端避免"收到广播 → 再次 set → 再次广播"回声环的统一手法。
运维与实践要点
- 手动编辑文件:
voicewake.json可以被直接编辑,但建议先停止相关客户端写入或接受"下一次 set 会覆盖手动改动"的事实;写入必须是合法 JSON,且triggers数组会被自动清洗; - 误删即回默认:把列表清空或只提交空白词,Gateway 会回退到
["clawd", "claude", "computer"],而不是得到一个空列表——这是刻意设计,防止"无法唤醒"的裸奔状态; - 长度即安全:32 词 × 64 字符的上限由服务端强制(
normalizeVoiceWakeTriggers),客户端(iOS 常量、各端 sanitize)也做了对齐,恶意或误填的超长输入不会进入持久化层; - 慢客户端不阻塞:
voicewake.changed广播带dropIfSlow语义,事件风暴时慢连接可能丢事件,但新连接/重连会通过快照推送重新获得当前状态,最终一致; - 排查思路:若某设备唤醒词与预期不符,优先检查该设备是否成功连接 Gateway(事件是否可达)、本地是否启用了 Voice Wake 开关(开关是本地状态,不影响全局列表)、以及
voicewake.get返回的列表是否与期望一致;服务端可在 e2e 测试 src/gateway/server.models-voicewake-misc.e2e.test.ts 中复现完整的"取默认值 → set → 广播 → 落盘"行为。
结语
OpenClaw 的全局语音唤醒词机制是一个"单一真源(Gateway 存储)+ 事件驱动广播 + 各端本地消费"的典型分布式设置同步模型:存储层用原子写入和写锁保证持久化安全,协议层用两个 RPC 方法加一个广播事件构成完整契约,三端客户端用统一的清洗规则、650ms 防抖与抑制回环标志保证同步的收敛与稳定。理解这条链路之后,无论是排查唤醒词不同步,还是为新的节点平台接入唤醒词同步,都可以直接对照 docs/nodes/voicewake.md、src/infra/voicewake.ts 与 src/gateway/server-methods/voicewake.ts 三份核心资料快速定位问题。