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

# Risveglio vocale (macOS)

# Risveglio vocale e premi per parlare

## Requisiti

Risveglio vocale e premi per parlare richiedono macOS 26 o versioni successive. Nelle versioni precedenti di macOS,
i controlli sono nascosti dalla pagina delle impostazioni Voce, che mostra il requisito di macOS 26.

## Modalità

* **Modalità parola di attivazione** (predefinita): il riconoscitore vocale sempre attivo attende i token di attivazione (`swabbleTriggerWords`). Quando trova una corrispondenza avvia la cattura, mostra l'overlay con testo parziale e invia automaticamente dopo il silenzio.
* **Premi per parlare (tieni premuto Option destro)**: tieni premuto il tasto Option destro per catturare immediatamente, senza attivazione necessaria. L'overlay appare mentre il tasto è premuto; il rilascio finalizza e inoltra dopo un breve ritardo, così puoi correggere il testo.

## Comportamento runtime (parola di attivazione)

* Il riconoscitore vocale risiede in `VoiceWakeRuntime`.
* L'attivazione scatta solo quando c'è una **pausa significativa** tra la parola di attivazione e la parola successiva (intervallo di \~0,55 s). L'overlay/il segnale acustico possono partire sulla pausa anche prima dell'inizio del comando.
* Finestre di silenzio: 2,0 s quando il parlato sta proseguendo, 5,0 s se è stata rilevata solo l'attivazione.
* Arresto forzato: 120 s per prevenire sessioni incontrollate.
* Debounce tra le sessioni: 350 ms.
* L'overlay è gestito tramite `VoiceWakeOverlayController` con colorazione committed/volatile.
* Dopo l'invio, il riconoscitore si riavvia in modo pulito per ascoltare l'attivazione successiva.

## Invarianti del ciclo di vita

* Se Risveglio vocale è abilitato e le autorizzazioni sono concesse, il riconoscitore della parola di attivazione dovrebbe essere in ascolto (tranne durante una cattura esplicita premi per parlare).
* La visibilità dell'overlay (inclusa la chiusura manuale tramite il pulsante X) non deve mai impedire la ripresa del riconoscitore.

## Modalità di errore dell'overlay bloccato (precedente)

In precedenza, se l'overlay rimaneva bloccato visibile e lo chiudevi manualmente, Risveglio vocale poteva sembrare "morto" perché il tentativo di riavvio del runtime poteva essere bloccato dalla visibilità dell'overlay e non veniva pianificato alcun riavvio successivo.

Rafforzamento:

* Il riavvio del runtime di risveglio non è più bloccato dalla visibilità dell'overlay.
* Il completamento della chiusura dell'overlay attiva un `VoiceWakeRuntime.refresh(...)` tramite `VoiceSessionCoordinator`, quindi la chiusura manuale con X riprende sempre l'ascolto.

## Dettagli del premi per parlare

* Il rilevamento della scorciatoia usa un monitor globale `.flagsChanged` per **Option destro** (`keyCode 61` + `.option`). Osserviamo solo gli eventi (senza intercettarli).
* La pipeline di cattura risiede in `VoicePushToTalk`: avvia subito Speech, trasmette i parziali all'overlay e chiama `VoiceWakeForwarder` al rilascio.
* Quando premi per parlare si avvia, mettiamo in pausa il runtime della parola di attivazione per evitare tap audio concorrenti; si riavvia automaticamente dopo il rilascio.
* Autorizzazioni: richiede Microfono + Riconoscimento vocale; per vedere gli eventi serve l'approvazione di Accessibilità/Monitoraggio input.
* Tastiere esterne: alcune potrebbero non esporre Option destro come previsto; offri una scorciatoia alternativa se gli utenti segnalano mancate rilevazioni.

## Impostazioni visibili all'utente

* Interruttore **Risveglio vocale**: abilita il runtime della parola di attivazione.
* **Tieni premuto Option destro per parlare**: abilita il monitor premi per parlare.
* Selettori di lingua e microfono, misuratore di livello in tempo reale, tabella delle parole di attivazione, tester (solo locale; non inoltra).
* Il selettore del microfono conserva l'ultima selezione se un dispositivo si disconnette, mostra un suggerimento di disconnessione e ripiega temporaneamente sul valore predefinito di sistema finché non torna disponibile.
* **Suoni**: segnali acustici al rilevamento dell'attivazione e all'invio; l'impostazione predefinita è il suono di sistema macOS "Glass". Puoi scegliere qualsiasi file caricabile da `NSSound` (ad es. MP3/WAV/AIFF) per ogni evento oppure scegliere **Nessun suono**.

## Comportamento di inoltro

* Quando Risveglio vocale è abilitato, le trascrizioni vengono inoltrate al gateway/agente attivo (la stessa modalità locale o remota usata dal resto dell'app Mac).
* Le risposte vengono recapitate all'**ultimo provider principale usato** (WhatsApp/Telegram/Discord/WebChat). Se il recapito non riesce, l'errore viene registrato e l'esecuzione resta comunque visibile tramite WebChat/log di sessione.

## Payload di inoltro

* `VoiceWakeForwarder.prefixedTranscript(_:)` antepone il suggerimento della macchina prima dell'invio. Condiviso tra i percorsi parola di attivazione e premi per parlare.

## Verifica rapida

* Attiva premi per parlare, tieni premuto Option destro, parla, rilascia: l'overlay dovrebbe mostrare i parziali e poi inviare.
* Durante la pressione, le orecchie nella barra dei menu dovrebbero restare ingrandite (usa `triggerVoiceEars(ttl:nil)`); tornano normali dopo il rilascio.

## Correlati

* [Risveglio vocale](/it/nodes/voicewake)
* [Overlay vocale](/it/platforms/mac/voice-overlay)
* [App macOS](/it/platforms/macos)