> ## 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. Цель: сделать поведение голосового оверлея предсказуемым при наложении слова активации и режима «нажми и говори».

## Текущий замысел

* Если оверлей уже виден из-за слова активации и пользователь нажимает горячую клавишу, сессия горячей клавиши *принимает* существующий текст вместо его сброса. Оверлей остается видимым, пока горячая клавиша удерживается. Когда пользователь отпускает ее: отправить, если после обрезки пробелов есть текст, иначе закрыть.
* Только слово активации по-прежнему автоматически отправляет при тишине; режим «нажми и говори» отправляет сразу при отпускании.

## Реализовано (9 декабря 2025 г.)

* Сессии оверлея теперь несут токен для каждого захвата (слово активации или режим «нажми и говори»). Обновления partial/final/send/dismiss/level отбрасываются, если токен не совпадает, что предотвращает устаревшие обратные вызовы.
* Режим «нажми и говори» принимает любой видимый текст оверлея как префикс (поэтому нажатие горячей клавиши при открытом оверлее активации сохраняет текст и добавляет новую речь). Он ждет до 1,5 с финальную транскрипцию, прежде чем откатиться к текущему тексту.
* Логи звукового сигнала/оверлея выводятся на уровне `info` в категориях `voicewake.overlay`, `voicewake.ptt` и `voicewake.chime` (старт сессии, partial, final, send, dismiss, причина звукового сигнала).

## Следующие шаги

1. **VoiceSessionCoordinator (актор)**
   * Владеет ровно одной `VoiceSession` за раз.
   * API (на основе токенов): `beginWakeCapture`, `beginPushToTalk`, `updatePartial`, `endCapture`, `cancel`, `applyCooldown`.
   * Отбрасывает обратные вызовы с устаревшими токенами (предотвращает повторное открытие оверлея старыми распознавателями).
2. **VoiceSession (модель)**
   * Поля: `token`, `source` (wakeWord|pushToTalk), зафиксированный/изменяемый текст, флаги звукового сигнала, таймеры (auto-send, idle), `overlayMode` (display|editing|sending), срок окончания cooldown.
3. **Привязка оверлея**
   * `VoiceSessionPublisher` (`ObservableObject`) зеркалирует активную сессию в SwiftUI.
   * `VoiceWakeOverlayView` отображает состояние только через publisher; он никогда не изменяет глобальные singleton напрямую.
   * Действия пользователя в оверлее (`sendNow`, `dismiss`, `edit`) вызывают координатор с токеном сессии.
4. **Единый путь отправки**
   * При `endCapture`: если текст после обрезки пробелов пустой → закрыть; иначе `performSend(session:)` (один раз воспроизводит звуковой сигнал отправки, пересылает, закрывает).
   * Режим «нажми и говори»: без задержки; слово активации: опциональная задержка для auto-send.
   * Применить короткий cooldown к runtime слова активации после завершения режима «нажми и говори», чтобы слово активации не сработало повторно сразу.
5. **Логирование**
   * Координатор выводит логи `.info` в subsystem `ai.openclaw`, категории `voicewake.overlay` и `voicewake.chime`.
   * Ключевые события: `session_started`, `adopted_by_push_to_talk`, `partial`, `finalized`, `send`, `dismiss`, `cancel`, `cooldown`.

## Контрольный список отладки

* Потоково просматривайте логи при воспроизведении залипающего оверлея:

  ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
  sudo log stream --predicate 'subsystem == "ai.openclaw" AND category CONTAINS "voicewake"' --level info --style compact
  ```

* Проверьте, что активен только один токен сессии; устаревшие обратные вызовы должны отбрасываться координатором.

* Убедитесь, что отпускание в режиме «нажми и говори» всегда вызывает `endCapture` с активным токеном; если текст пустой, ожидайте `dismiss` без звукового сигнала или отправки.

## Шаги миграции (предлагаемые)

1. Добавить `VoiceSessionCoordinator`, `VoiceSession` и `VoiceSessionPublisher`.
2. Отрефакторить `VoiceWakeRuntime`, чтобы он создавал/обновлял/завершал сессии вместо прямого обращения к `VoiceWakeOverlayController`.
3. Отрефакторить `VoicePushToTalk`, чтобы он принимал существующие сессии и вызывал `endCapture` при отпускании; применять cooldown runtime.
4. Подключить `VoiceWakeOverlayController` к publisher; удалить прямые вызовы из runtime/PTT.
5. Добавить интеграционные тесты для принятия сессии, cooldown и закрытия при пустом тексте.

## Связанные материалы

* [Приложение macOS](/ru/platforms/macos)
* [Голосовая активация (macOS)](/ru/platforms/mac/voicewake)
* [Режим разговора](/ru/nodes/talk)