14.3 语音唤醒

语音唤醒功能让 OpenClaw macOS 应用能够通过唤醒词或按键语音(Push-to-Talk)接收语音命令。

工作模式

唤醒词模式(默认)

始终开启的语音识别器等待触发令牌(swabbleTriggerWords)。匹配时开始捕获,显示带部分文本的叠加层,并在静音后自动发送。

按键语音(右 Option 键)

按住右 Option 键立即捕获——无需触发词。按住期间显示叠加层;松开后完成并在短暂延迟后转发,以便您可以调整文本。

运行时行为(唤醒词)

语音识别器运行在 VoiceWakeRuntime 中。触发仅在唤醒词和下一个词之间有有意义的停顿(约0.55秒间隔)时触发。叠加层/提示音可以在停顿时开始,甚至在命令开始前。

静音窗口

• 语音流动时:2.0秒
• 仅听到触发词:5.0秒
• 硬停止:120秒(防止失控会话)
• 会话间防抖:350毫秒

叠加层通过 VoiceWakeOverlayController 驱动,带有已提交/易变着色。发送后,识别器干净重启以监听下一个触发。

生命周期不变性

如果启用语音唤醒并授予权限,唤醒词识别器应该在监听(除了明确的按键语音捕获期间)。叠加层可见性(包括通过 X 按钮手动关闭)绝不能阻止识别器恢复。

粘性叠加层故障模式(之前)

以前,如果叠加层卡住并且您手动关闭它,语音唤醒可能显得"死了",因为运行时的重启尝试可能被叠加层可见性阻止,并且没有安排后续重启。

加固措施

• 唤醒运行时重启不再被叠加层可见性阻止
• 叠加层关闭完成通过 VoiceSessionCoordinator 触发 VoiceWakeRuntime.refresh(...),因此手动 X 关闭始终恢复监听

按键语音细节

热键检测使用全局 .flagsChanged 监视器监听右 Option 键(keyCode 61 + .option)。我们只观察事件(不吞咽)。

捕获管道运行在 VoicePushToTalk 中:立即启动语音,将部分文本流式传输到叠加层,并在松开时调用 VoiceWakeForwarder。

按键语音启动时,我们暂停唤醒词运行时以避免音频捕获冲突;松开后自动重启。

权限要求

• 麦克风 + 语音识别
• 查看事件需要辅助功能/输入监控批准

外接键盘

某些外接键盘可能不会按预期暴露右 Option 键——如果用户报告未命中,提供回退快捷键。

用户设置

• 语音唤醒切换:启用唤醒词运行时
• 按住 Cmd+Fn 说话:启用按键语音监视器。在 macOS < 26 上禁用
• 语言和麦克风选择器
• 实时音量计
• 触发词表格
• 测试器(仅本地;不转发)

麦克风选择器

如果设备断开连接,麦克风选择器会保留上次选择,显示断开提示,并临时回退到系统默认值,直到设备返回。

提示音

触发检测和发送时的提示音;默认为 macOS "Glass" 系统音效。您可以为每个事件选择任何 NSSound 可加载的文件(例如 MP3/WAV/AIFF)或选择无声音。

转发行为

启用语音唤醒时,转录会转发到活动的网关/代理(应用其他部分使用的相同本地 vs 远程模式)。回复传递到最后使用的主提供商(WhatsApp/Telegram/Discord/WebChat)。如果传递失败,错误会被记录,运行仍可通过 WebChat/会话日志查看。

转发载荷

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

快速验证

打开按键语音,按住 Cmd+Fn,说话,松开:叠加层应显示部分文本然后发送。按住期间,菜单栏耳朵应保持放大状态(使用 triggerVoiceEars(ttl:nil));松开后下降。

常见问题

• 唤醒词不响应:检查麦克风权限和设备选择
• 按键语音无法触发:验证辅助功能权限已授予
• 叠加层卡住:手动关闭应自动恢复监听
• 音频冲突:按键语音会暂停唤醒词运行时
• 识别不准确:尝试调整麦克风或使用不同的语言模型