OpenClaw 全局语音唤醒词机制:Gateway 统一持有与跨节点同步实战解析

原创2026-10-14 11:07:271,726 阅读
文章标签:人工智能AI Agent多智能体交互助手AI 技能AI 插件本地部署API网关语音CLI

OpenClaw 全局语音唤醒词机制:Gateway 统一持有与跨节点同步实战解析

导读

OpenClaw 的语音唤醒词(Voice Wake)采用一种"全局单一列表、由 Gateway 统一持有"的设计:整个网络(macOS 桌面端、iOS/Android 移动节点、WebChat 等所有 WebSocket 客户端)共享同一份唤醒词列表,任何一端修改都会由 Gateway 持久化并广播到全部设备,而每个设备仍然保留独立的"Voice Wake 启用/禁用"本地开关。本文以 docs/nodes/voicewake.md 为骨架,结合仓库中 Gateway 服务端、存储层与三端客户端的真实实现,完整讲解数据存储格式、RPC 协议、事件广播链路、各端同步代码路径与测试验证,帮助你理解并排查语音唤醒词的配置与同步问题。

设计模型:一份全局列表,本地只管开关

从架构上看,唤醒词是 Gateway 拥有的单一全局状态,核心约束有三条:

  1. 不存在按节点自定义的唤醒词——iOS、Android、macOS 看到的是同一份列表,没有 per-node 差异;
  2. 任意节点/应用 UI 都可以编辑该列表,改动由 Gateway 持久化并广播给所有人,而不是"谁改谁独有";
  3. 每台设备仍保留自己的 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 处理(只进日志,不回传给客户端明文异常)。

同步链路:从一次编辑到全端生效

以任意端在设置页修改唤醒词为例,完整链路如下:

  1. 客户端对本地列表做与 Gateway 一致的清洗(trim、去空、上限裁剪、空则回默认);
  2. 客户端通过 WebSocket 调用 voicewake.set;
  3. Gateway 再次规范化 → 原子写入 ~/.openclaw/settings/voicewake.json(更新 updatedAtMs)→ 广播 voicewake.changed;
  4. 所有已连接的 WebSocket 客户端(macOS、WebChat 等)收到事件并应用新列表;
  5. 已连接的 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 节点

值得注意的是,三端在"上行防抖"上采用了完全一致的 650ms 等待窗口(macOS AppState.swift、iOS VoiceWakeWordsSettingsView.swift、Android NodeRuntime.kt),这保证了连续编辑时不会向 Gateway 发送大量中间态请求;而 suppressVoiceWakeGlobalSync / suppressWakeWordsSync 标志则是各端避免"收到广播 → 再次 set → 再次广播"回声环的统一手法。

运维与实践要点

  1. 手动编辑文件:voicewake.json 可以被直接编辑,但建议先停止相关客户端写入或接受"下一次 set 会覆盖手动改动"的事实;写入必须是合法 JSON,且 triggers 数组会被自动清洗;
  2. 误删即回默认:把列表清空或只提交空白词,Gateway 会回退到 ["clawd", "claude", "computer"],而不是得到一个空列表——这是刻意设计,防止"无法唤醒"的裸奔状态;
  3. 长度即安全:32 词 × 64 字符的上限由服务端强制(normalizeVoiceWakeTriggers),客户端(iOS 常量、各端 sanitize)也做了对齐,恶意或误填的超长输入不会进入持久化层;
  4. 慢客户端不阻塞:voicewake.changed 广播带 dropIfSlow 语义,事件风暴时慢连接可能丢事件,但新连接/重连会通过快照推送重新获得当前状态,最终一致;
  5. 排查思路:若某设备唤醒词与预期不符,优先检查该设备是否成功连接 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 三份核心资料快速定位问题。

登录后查看全文
openclaw-cn