---
read_when:
    - 处理语音唤醒或 PTT 路径
summary: Mac 应用中的语音唤醒和按住说话模式以及路由详情
title: 语音唤醒（macOS）
x-i18n:
    generated_at: "2026-05-06T05:29:56Z"
    model: gpt-5.5
    provider: openai
    source_hash: 312895b5767c447233bd77cbcd48ea81bb6c700080abc31974188b610a1b1ef0
    source_path: platforms/mac/voicewake.md
    workflow: 16
---

# 语音唤醒与按键通话

## 模式

- **唤醒词模式**（默认）：始终开启的 Speech 识别器会等待触发词（`swabbleTriggerWords`）。匹配后开始采集，显示带有部分文本的浮层，并在静音后自动发送。
- **按键通话（按住右 Option 键）**：按住右 Option 键即可立即采集，无需触发词。按住时会显示浮层；松开后会完成采集，并在短暂延迟后转发，方便你微调文本。

## 运行时行为（唤醒词）

- Speech 识别器位于 `VoiceWakeRuntime`。
- 只有在唤醒词和下一个词之间存在**有意义的停顿**（约 0.55 秒间隔）时才会触发。即使命令尚未开始，浮层/提示音也可以在停顿时启动。
- 静音窗口：语音连续输入时为 2.0 秒；如果只听到触发词，则为 5.0 秒。
- 硬停止：120 秒，用于防止失控会话。
- 会话之间的防抖：350 毫秒。
- 浮层通过 `VoiceWakeOverlayController` 驱动，并使用已提交/易变着色。
- 发送后，识别器会干净地重启，以监听下一个触发词。

## 生命周期不变量

- 如果语音唤醒已启用且权限已授予，唤醒词识别器应处于监听状态（显式按键通话采集期间除外）。
- 浮层可见性（包括通过 X 按钮手动关闭）绝不能阻止识别器恢复。

## 粘滞浮层故障模式（以前）

以前，如果浮层卡住并保持可见，而你手动关闭了它，语音唤醒可能会看起来“失效”，因为运行时的重启尝试可能会被浮层可见性阻塞，并且不会安排后续重启。

加固：

- 唤醒运行时重启不再被浮层可见性阻塞。
- 浮层关闭完成后会通过 `VoiceSessionCoordinator` 触发 `VoiceWakeRuntime.refresh(...)`，因此手动点击 X 关闭始终会恢复监听。

## 按键通话细节

- 热键检测使用全局 `.flagsChanged` 监视器监听**右 Option**（`keyCode 61` + `.option`）。我们只观察事件（不吞掉事件）。
- 采集管线位于 `VoicePushToTalk`：立即启动 Speech，将部分结果流式传输到浮层，并在松开时调用 `VoiceWakeForwarder`。
- 按键通话开始时，我们会暂停唤醒词运行时，以避免音频 tap 相互竞争；松开后它会自动重启。
- 权限：需要麦克风 + Speech；看到事件需要辅助功能/输入监控批准。
- 外接键盘：某些键盘可能不会按预期暴露右 Option，如果用户报告漏检，请提供备用快捷键。

## 面向用户的设置

- **语音唤醒**开关：启用唤醒词运行时。
- **按住 Cmd+Fn 说话**：启用按键通话监视器。在 macOS < 26 上禁用。
- 语言和麦克风选择器、实时电平表、触发词表、测试器（仅本地；不会转发）。
- 麦克风选择器会在设备断开连接时保留上次选择，显示断开连接提示，并临时回退到系统默认设备，直到该设备恢复。
- **声音**：在检测到触发词和发送时播放提示音；默认使用 macOS “Glass” 系统声音。你可以为每个事件选择任何可由 `NSSound` 加载的文件（例如 MP3/WAV/AIFF），也可以选择**无声音**。

## 转发行为

- 启用语音唤醒后，转录文本会转发到活动的 Gateway 网关/智能体（使用与 Mac 应用其余部分相同的本地与远程模式）。
- 回复会投递到**上次使用的主提供商**（WhatsApp/Telegram/Discord/WebChat）。如果投递失败，错误会被记录，并且运行仍可通过 WebChat/会话日志查看。

## 转发载荷

- `VoiceWakeForwarder.prefixedTranscript(_:)` 会在发送前添加机器提示。唤醒词路径和按键通话路径共享该逻辑。

## 快速验证

- 打开按键通话，按住 Cmd+Fn，说话，然后松开：浮层应显示部分结果，然后发送。
- 按住期间，菜单栏耳朵图标应保持放大（使用 `triggerVoiceEars(ttl:nil)`）；松开后它们会恢复。

## 相关内容

- [语音唤醒](/zh-CN/nodes/voicewake)
- [语音浮层](/zh-CN/platforms/mac/voice-overlay)
- [macOS 应用](/zh-CN/platforms/macos)