Documentation Index
Fetch the complete documentation index at: https://openclaw.zhcndoc.com/llms.txt
Use this file to discover all available pages before exploring further.
语音唤醒与按住说话
模式
- 唤醒词模式（默认）：始终开启的语音识别器等待触发标记（
swabbleTriggerWords）。匹配后它会开始捕获，显示带有部分文本的浮层，并在静音后自动发送。 - 按住说话（按住右侧 Option）：按住右侧 Option 键即可立即捕获——无需触发词。按住时浮层会出现；松开后会完成并在短暂延迟后转发，以便你调整文本。
运行时行为（唤醒词）
- 语音识别器运行在
VoiceWakeRuntime中。 - 只有在唤醒词和下一个词之间存在有意义的停顿时才会触发（约 0.55s 的间隔）。浮层/提示音可以在停顿时开始，甚至早于命令开始之前。
- 静音窗口：当语音持续流动时为 2.0s；如果只听到触发词，则为 5.0s。
- 强制停止：120s，防止会话失控持续。
- 会话之间的防抖：350ms。
- 浮层由
VoiceWakeOverlayController驱动，带有已提交/临时内容的着色。 - 发送后，识别器会干净地重启，以监听下一个触发词。
生命周期不变量
- 如果启用了 Voice Wake 且权限已授予，唤醒词识别器应保持监听状态（显式按住说话捕获期间除外）。
- 浮层可见性（包括通过 X 按钮手动关闭）绝不能阻止识别器恢复运行。
卡住的浮层失败模式（之前）
之前，如果浮层卡住可见，而你手动关闭了它，Voice Wake 可能会看起来“失效”，因为运行时的重启尝试会被浮层可见性阻止，并且不会安排后续重启。 加固措施：- 唤醒运行时的重启不再被浮层可见性阻止。
- 浮层关闭完成后会通过
VoiceSessionCoordinator触发VoiceWakeRuntime.refresh(...)，因此手动点击 X 关闭后总会恢复监听。
按住说话细节
- 热键检测使用全局的
.flagsChanged监视器来监听右侧 Option（keyCode 61+.option）。我们只观察事件，不会吞掉事件。 - 捕获管线位于
VoicePushToTalk：立即启动 Speech，向浮层流式输出部分识别结果，并在松开时调用VoiceWakeForwarder。 - 当按住说话开始时，我们会暂停唤醒词运行时，以避免两个音频 tap 竞争；松开后会自动重启。
- 权限：需要麦克风 + Speech；要看到事件还需要 Accessibility/Input Monitoring 许可。
- 外接键盘：某些设备可能不会按预期暴露右侧 Option——如果用户报告漏检，请提供备用快捷键。
面向用户的设置
- Voice Wake 开关：启用唤醒词运行时。
- 按住 Cmd+Fn 说话：启用按住说话监视器。macOS < 26 上禁用。
- 语言和麦克风选择器、实时电平表、触发词表、测试器（仅本地；不会转发）。
- 如果设备断开，麦克风选择器会保留上次选择，显示断开提示，并暂时回退到系统默认值，直到设备恢复。
- 声音：在触发检测和发送时播放提示音；默认使用 macOS 的“Glass”系统声音。你可以为每个事件选择任意可被
NSSound加载的文件（例如 MP3/WAV/AIFF），或者选择 无声音。
转发行为
- 启用 Voice Wake 时，转写结果会转发到当前活动的网关/代理（与 mac 应用其他部分使用的本地/远程模式相同）。
- 回复会发送到最后使用的主提供方（WhatsApp/Telegram/Discord/WebChat）。如果发送失败，会记录错误，但运行记录仍可通过 WebChat/会话日志查看。
转发载荷
VoiceWakeForwarder.prefixedTranscript(_:)在发送前会添加机器提示信息。唤醒词和按住说话路径共用。
快速验证
- 打开按住说话，按住 Cmd+Fn，说话，松开：浮层应先显示部分结果，然后发送。
- 按住时，菜单栏耳朵图标应保持放大（使用
triggerVoiceEars(ttl:nil)）；松开后会恢复。