> ## 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.

## Режими

* **Режим wake-word** (типовий): постійно ввімкнений розпізнавач мовлення очікує тригерні токени (`swabbleTriggerWords`). У разі збігу він починає захоплення, показує оверлей із частковим текстом і автоматично надсилає після тиші.
* **«Натисни й говори» (утримання правої Option)**: утримуйте праву клавішу Option, щоб одразу почати захоплення — тригер не потрібен. Оверлей з’являється під час утримання; відпускання завершує запис і пересилає після короткої затримки, щоб ви могли підправити текст.

## Поведінка під час виконання (wake-word)

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

## Інваріанти життєвого циклу

* Якщо Голосове пробудження ввімкнено й дозволи надано, розпізнавач wake-word має слухати (крім часу явного захоплення «натисни й говори»).
* Видимість оверлею (включно з ручним закриттям кнопкою X) ніколи не має перешкоджати відновленню роботи розпізнавача.

## Режим збою із застряглим оверлеєм (раніше)

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

Посилення:

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

## Особливості «натисни й говори»

* Виявлення гарячої клавіші використовує глобальний монітор `.flagsChanged` для **правої Option** (`keyCode 61` + `.option`). Ми лише спостерігаємо події (без перехоплення).
* Конвеєр захоплення працює в `VoicePushToTalk`: негайно запускає Speech, транслює часткові результати в оверлей і викликає `VoiceWakeForwarder` під час відпускання.
* Коли запускається «натисни й говори», ми призупиняємо wake-word runtime, щоб уникнути конкуруючих аудіовідводів; він автоматично перезапускається після відпускання.
* Дозволи: потрібні Microphone + Speech; для отримання подій потрібне схвалення Accessibility/Input Monitoring.
* Зовнішні клавіатури: деякі можуть не передавати праву Option очікуваним способом — запропонуйте резервне скорочення, якщо користувачі повідомляють про пропуски.

## Налаштування для користувача

* Перемикач **Voice Wake**: вмикає wake-word runtime.
* **Hold Right Option to talk**: вмикає монітор «натисни й говори».
* Вибір мови й мікрофона, живий індикатор рівня, таблиця тригерних слів, тестер (лише локально; не пересилає).
* Вибір мікрофона зберігає останній вибір, якщо пристрій від’єднується, показує підказку про від’єднання й тимчасово повертається до системного типового пристрою, доки він не повернеться.
* **Звуки**: дзвінки під час виявлення тригера та надсилання; типово використовується системний звук macOS «Glass». Для кожної події можна вибрати будь-який файл, який завантажує `NSSound` (наприклад, MP3/WAV/AIFF), або вибрати **Без звуку**.

## Поведінка пересилання

* Коли Голосове пробудження ввімкнено, транскрипти пересилаються активному Gateway/агенту (той самий локальний чи віддалений режим, який використовує решта застосунку для Mac).
* Відповіді доставляються до **останнього використаного основного провайдера** (WhatsApp/Telegram/Discord/WebChat). Якщо доставка не вдається, помилка записується в журнал, а запуск усе одно видно через WebChat/журнали сеансу.

## Корисне навантаження пересилання

* `VoiceWakeForwarder.prefixedTranscript(_:)` додає підказку про машину перед надсиланням. Спільне для шляхів wake-word і «натисни й говори».

## Швидка перевірка

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

## Пов’язано

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