> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Голосовое пробуждение (macOS)

# Голосовое пробуждение и режим удержания клавиши для речи

## Требования

Для голосового пробуждения и режима удержания клавиши для речи требуется macOS 26 или новее. В более старых версиях macOS элементы управления скрыты со страницы настроек голоса, где отображается требование macOS 26.

## Режимы

* **Режим слова пробуждения** (по умолчанию): постоянно включенный распознаватель речи ждет триггерные слова (`swabbleTriggerWords`). При совпадении он начинает захват, показывает оверлей с промежуточным текстом и автоматически отправляет после тишины.
* **Удержание для речи (удержание правой Option)**: удерживайте правую клавишу Option, чтобы сразу начать захват — триггер не нужен. Оверлей появляется на время удержания; отпускание завершает ввод и пересылает его после короткой задержки, чтобы вы могли поправить текст.

## Поведение во время выполнения (слово пробуждения)

* Распознаватель речи находится в `VoiceWakeRuntime`.
* Триггер срабатывает только при **значимой паузе** между словом пробуждения и следующим словом (разрыв около 0,55 с). Оверлей/звуковой сигнал может запуститься на паузе еще до начала команды.
* Окна тишины: 2,0 с, когда речь продолжается, 5,0 с, если был услышан только триггер.
* Жесткая остановка: 120 с для предотвращения зависших сеансов.
* Антидребезг между сеансами: 350 мс.
* Оверлей управляется через `VoiceWakeOverlayController` с окраской для зафиксированного/изменяемого текста.
* После отправки распознаватель чисто перезапускается, чтобы слушать следующий триггер.

## Инварианты жизненного цикла

* Если голосовое пробуждение включено и разрешения выданы, распознаватель слова пробуждения должен слушать (кроме времени явного захвата через удержание клавиши для речи).
* Видимость оверлея (включая ручное закрытие кнопкой X) никогда не должна мешать возобновлению работы распознавателя.

## Предыдущий режим отказа с зависшим оверлеем

Раньше, если оверлей зависал в видимом состоянии и вы вручную закрывали его, голосовое пробуждение могло казаться «мертвым», потому что попытка перезапуска в runtime могла блокироваться видимостью оверлея, а последующий перезапуск не планировался.

Усиление надежности:

* Перезапуск runtime пробуждения больше не блокируется видимостью оверлея.
* Завершение закрытия оверлея запускает `VoiceWakeRuntime.refresh(...)` через `VoiceSessionCoordinator`, поэтому ручное закрытие через X всегда возобновляет прослушивание.

## Особенности удержания клавиши для речи

* Обнаружение горячей клавиши использует глобальный монитор `.flagsChanged` для **правой Option** (`keyCode 61` + `.option`). Мы только наблюдаем события (не перехватываем их).
* Конвейер захвата находится в `VoicePushToTalk`: сразу запускает Speech, передает промежуточные результаты в оверлей и вызывает `VoiceWakeForwarder` при отпускании.
* Когда начинается удержание клавиши для речи, мы приостанавливаем runtime слова пробуждения, чтобы избежать конкурирующих аудиопотоков; после отпускания он автоматически перезапускается.
* Разрешения: требуются микрофон и Speech; для получения событий нужно разрешение Accessibility/Input Monitoring.
* Внешние клавиатуры: некоторые могут не передавать правую Option ожидаемым образом — предложите резервное сочетание клавиш, если пользователи сообщают о пропусках.

## Пользовательские настройки

* Переключатель **Голосовое пробуждение**: включает runtime слова пробуждения.
* **Удерживать правую Option для речи**: включает монитор удержания клавиши для речи.
* Выбор языка и микрофона, индикатор уровня в реальном времени, таблица триггерных слов, тестер (только локально; не пересылает).
* Выбор микрофона сохраняет последний выбор, если устройство отключается, показывает подсказку об отключении и временно откатывается к системному микрофону по умолчанию, пока устройство не вернется.
* **Звуки**: сигналы при обнаружении триггера и при отправке; по умолчанию используется системный звук macOS "Glass". Для каждого события можно выбрать любой файл, загружаемый через `NSSound` (например MP3/WAV/AIFF), или выбрать **Без звука**.

## Поведение пересылки

* Когда голосовое пробуждение включено, расшифровки пересылаются активному gateway/agent (в том же локальном или удаленном режиме, который используется остальной частью приложения для Mac).
* Ответы доставляются в **последний использованный основной провайдер** (WhatsApp/Telegram/Discord/WebChat). Если доставка не удается, ошибка записывается в журнал, а запуск все равно виден через WebChat/журналы сеанса.

## Полезная нагрузка пересылки

* `VoiceWakeForwarder.prefixedTranscript(_:)` добавляет подсказку о машине перед отправкой. Используется совместно путями слова пробуждения и удержания клавиши для речи.

## Быстрая проверка

* Включите удержание клавиши для речи, удерживайте правую Option, говорите, отпустите: оверлей должен показать промежуточные результаты, а затем отправить.
* Во время удержания «уши» в строке меню должны оставаться увеличенными (использует `triggerVoiceEars(ttl:nil)`); они уменьшаются после отпускания.

## Связанные разделы

* [Голосовое пробуждение](/ru/nodes/voicewake)
* [Голосовой оверлей](/ru/platforms/mac/voice-overlay)
* [Приложение для macOS](/ru/platforms/macos)