12.6 语音唤醒

OpenClaw 提供语音唤醒功能,允许用户通过唤醒词或按键与 AI 助手进行语音交互。

概述

OpenClaw 将唤醒词作为由网关拥有的全局列表进行管理:

• 没有每节点自定义唤醒词
• 任何节点/应用 UI 都可以编辑列表
• 更改由网关持久化并广播给所有人
• 每个设备仍保留自己的语音唤醒启用/禁用开关(本地 UX + 权限不同)

存储位置(网关主机)

唤醒词存储在网关机器上:

~/.openclaw/settings/voicewake.json

数据结构

{
  "triggers": ["openclaw", "claude", "computer"],
  "updatedAtMs": 1730000000000
}

协议

方法

• voicewake.get → { triggers: string[] }
• voicewake.set 参数 { triggers: string[] } → { triggers: string[] }

触发词会被规范化(修剪空格,删除空值)。空列表回退到默认值。为安全起见会强制执行限制(数量/长度上限)。

事件

• voicewake.changed 负载 { triggers: string[] }

接收者

• 所有 WebSocket 客户端(macOS 应用、WebChat 等)
• 所有连接的节点(iOS/Android),以及节点连接时作为初始"当前状态"推送

macOS 语音唤醒与按键对讲

模式

• 唤醒词模式(默认) - 始终开启的语音识别器等待触发词。匹配时开始捕获,显示带有部分文本的覆盖层,并在静音后自动发送
• 按键对讲(按住右侧 Option 键) - 按住右侧 Option 键立即捕获,无需触发词。按住时显示覆盖层; 释放后完成并转发,延迟一小段时间以便您可以调整文本

运行时行为(唤醒词)

• 语音识别器位于 VoiceWakeRuntime 中
• 只有在唤醒词和下一个词之间有有意义的停顿时才会触发(约 0.55 秒间隔)
• 静音窗口: 语音流动时 2.0 秒,仅听到触发词时 5.0 秒
• 硬停止: 120 秒以防止失控会话
• 会话间防抖: 350 毫秒
• 覆盖层通过 VoiceWakeOverlayController 驱动,带有已提交/易失性着色
• 发送后,识别器干净地重启以监听下一个触发器

生命周期不变量

• 如果启用语音唤醒并授予权限,唤醒词识别器应该正在监听(显式按键对讲捕获期间除外)
• 覆盖层可见性(包括通过 X 按钮手动关闭)绝不能阻止识别器恢复

按键对讲详情

• 热键检测使用全局 .flagsChanged 监视器监视右侧 Option 键(keyCode 61 + .option)
• 捕获管道位于 VoicePushToTalk 中: 立即启动语音,将部分内容流式传输到覆盖层,并在释放时调用 VoiceWakeForwarder
• 按键对讲启动时暂停唤醒词运行时以避免音频采集冲突; 释放后自动重启
• 权限: 需要麦克风 + 语音; 查看事件需要辅助功能/输入监控批准
• 外部键盘: 某些可能不会按预期公开右侧 Option 键 - 如果用户报告遗漏,请提供回退快捷方式

用户设置

• 语音唤醒开关 - 启用唤醒词运行时
• 按住 Cmd+Fn 对讲 - 启用按键对讲监视器。macOS < 26 时禁用
• 语言和麦克风选择器、实时音量表、触发词表、测试器(仅本地; 不转发)
• 麦克风选择器在设备断开连接时保留上次选择,显示断开连接提示,并临时回退到系统默认值直到它返回
• 声音 - 检测到触发器和发送时的提示音; 默认为 macOS "Glass" 系统声音。您可以为每个事件选择任何 NSSound 可加载的文件(例如 MP3/WAV/AIFF)或选择无声音

转发行为

• 启用语音唤醒时,转录文本会转发到活动的网关/代理(与 mac 应用其余部分使用的本地或远程模式相同)
• 回复会发送到上次使用的主要提供商(WhatsApp/Telegram/Discord/WebChat)
• 如果传递失败,会记录错误,并且运行仍然可以通过 WebChat/会话日志查看

转发负载

VoiceWakeForwarder.prefixedTranscript(_:) 在发送前添加机器提示。在唤醒词和按键对讲路径之间共享。

客户端行为

macOS 应用

• 使用全局列表来控制 VoiceWakeRuntime 触发器
• 在语音唤醒设置中编辑"触发词"会调用 voicewake.set,然后依赖广播保持其他客户端同步

iOS 节点

• 使用全局列表进行 VoiceWakeManager 触发器检测
• 在设置中编辑唤醒词会调用 voicewake.set(通过网关 WS),并且还保持本地唤醒词检测响应

Android 节点

• 在设置中公开唤醒词编辑器
• 通过网关 WS 调用 voicewake.set,以便编辑在所有地方同步

快速验证

# 按键对讲测试
1. 打开按键对讲
2. 按住 Cmd+Fn
3. 说话
4. 释放

# 预期结果
- 覆盖层应显示部分内容然后发送
- 按住时,菜单栏耳朵应保持放大(使用 triggerVoiceEars(ttl:nil))
- 释放后它们会下降