Sintesi vocale

OpenClaw converte le risposte in uscita in audio tramite 14 provider vocali: messaggi vocali nativi su Feishu, Matrix, Telegram e WhatsApp; allegati audio ovunque altrove; e flussi PCM/Ulaw per la telefonia e Talk.

La sintesi vocale (TTS) costituisce la componente di output vocale della modalità stt-tts di Talk (talk.speak utilizza questo stesso percorso di sintesi). Le sessioni Talk realtime native del provider sintetizzano la voce all'interno del provider in tempo reale; le sessioni transcription non sintetizzano mai una risposta vocale dell'assistente.

Avvio rapido

{  messages: {    tts: {      auto: "always",      provider: "elevenlabs",    },  },}

Provider supportati

Se sono configurati più provider, viene utilizzato prima quello selezionato e gli altri fungono da opzioni di ripiego. Il riepilogo automatico utilizza summaryModel (o agents.defaults.model.primary), pertanto anche tale provider deve essere autenticato se i riepiloghi rimangono abilitati.

Configurazione

La configurazione TTS si trova in messages.tts all'interno di ~/.openclaw/openclaw.json. Scegliere una preimpostazione e adattare il blocco del provider. I campi speakerVoice/speakerVoiceId mostrati di seguito sono quelli canonici; i nomi dei campi voice/voiceId/ voiceName specifici di ciascun provider continuano a funzionare come alias legacy.

{messages: {tts: {  auto: "always",  provider: "azure-speech",  providers: {    "azure-speech": {      apiKey: "${AZURE_SPEECH_KEY}",      region: "eastus",      speakerVoice: "en-US-JennyNeural",      lang: "en-US",      outputFormat: "audio-24khz-48kbitrate-mono-mp3",      voiceNoteOutputFormat: "ogg-24khz-16bit-mono-opus",    },  },},},}

{messages: {tts: {  auto: "always",  provider: "elevenlabs",  providers: {    elevenlabs: {      apiKey: "${ELEVENLABS_API_KEY}",      model: "eleven_multilingual_v2",      speakerVoiceId: "EXAVITQu4vr4xnSDxMaL",    },  },},},}

{messages: {tts: {  auto: "always",  provider: "google",  providers: {    google: {      apiKey: "${GEMINI_API_KEY}",      model: "gemini-3.1-flash-tts-preview",      speakerVoice: "Kore",      // Prompt di stile facoltativi in linguaggio naturale:      // audioProfile: "Parla con un tono calmo da conduttore di podcast.",      // speakerName: "Alex",    },  },},},}

{messages: {tts: {  auto: "always",  provider: "gradium",  providers: {    gradium: {      apiKey: "${GRADIUM_API_KEY}",      speakerVoiceId: "YTpq7expH9539ERJ",    },  },},},}

{messages: {tts: {  auto: "always",  provider: "inworld",  providers: {    inworld: {      apiKey: "${INWORLD_API_KEY}",      modelId: "inworld-tts-1.5-max",      speakerVoiceId: "Sarah",      temperature: 0.7,    },  },},},}

{messages: {tts: {  auto: "always",  provider: "tts-local-cli",  providers: {    "tts-local-cli": {      command: "say",      args: ["-o", "{{OutputPath}}", "{{Text}}"],      outputFormat: "wav",      timeoutMs: 120000,    },  },},},}

{messages: {tts: {  auto: "always",  provider: "microsoft",  providers: {    microsoft: {      enabled: true,      speakerVoice: "en-US-MichelleNeural",      lang: "en-US",      outputFormat: "audio-24khz-48kbitrate-mono-mp3",      rate: "+0%",      pitch: "+0%",    },  },},},}

{messages: {tts: {  auto: "always",  provider: "minimax",  providers: {    minimax: {      apiKey: "${MINIMAX_API_KEY}",      model: "speech-2.8-hd",      speakerVoiceId: "English_expressive_narrator",      speed: 1.0,      vol: 1.0,      pitch: 0,    },  },},},}

{messages: {tts: {  auto: "always",  provider: "openai",  summaryModel: "openai/gpt-4.1-mini",  modelOverrides: { enabled: true },  providers: {    openai: {      apiKey: "${OPENAI_API_KEY}",      model: "gpt-4o-mini-tts",      speakerVoice: "alloy",    },    elevenlabs: {      apiKey: "${ELEVENLABS_API_KEY}",      model: "eleven_multilingual_v2",      speakerVoiceId: "EXAVITQu4vr4xnSDxMaL",      voiceSettings: { stability: 0.5, similarityBoost: 0.75, style: 0.0, useSpeakerBoost: true, speed: 1.0 },      applyTextNormalization: "auto",      languageCode: "en",    },  },},},}

{messages: {tts: {  auto: "always",  provider: "openrouter",  providers: {    openrouter: {      apiKey: "${OPENROUTER_API_KEY}",      model: "hexgrad/kokoro-82m",      speakerVoice: "af_alloy",      responseFormat: "mp3",    },  },},},}

{messages: {tts: {  auto: "always",  provider: "volcengine",  providers: {    volcengine: {      apiKey: "${VOLCENGINE_TTS_API_KEY}",      resourceId: "seed-tts-1.0",      speakerVoice: "en_female_anna_mars_bigtts",    },  },},},}

{messages: {tts: {  auto: "always",  provider: "xai",  providers: {    xai: {      apiKey: "${XAI_API_KEY}",      speakerVoiceId: "eve",      language: "en",      responseFormat: "mp3",    },  },},},}

{messages: {tts: {  auto: "always",  provider: "xiaomi",  providers: {    xiaomi: {      apiKey: "${XIAOMI_API_KEY}",      model: "mimo-v2.5-tts",      speakerVoice: "mimo_default",      format: "mp3",    },  },},},}

Per Xiaomi mimo-v2.5-tts-voicedesign, omettere speakerVoice e impostare style sul prompt di progettazione vocale. OpenClaw invia tale prompt come messaggio TTS user e non invia audio.voice per il modello voicedesign.

Override vocali per agente

Usare agents.list[].tts quando un agente deve parlare con un provider, una voce, un modello, una persona o una modalità TTS automatica diversi. Il blocco dell'agente viene unito in profondità sopra messages.tts, quindi le credenziali del provider possono rimanere nella configurazione globale del provider:

{  messages: {    tts: {      auto: "always",      provider: "elevenlabs",      providers: {        elevenlabs: { apiKey: "${ELEVENLABS_API_KEY}", model: "eleven_multilingual_v2" },      },    },  },  agents: {    list: [      {        id: "reader",        tts: {          providers: {            elevenlabs: { speakerVoiceId: "EXAVITQu4vr4xnSDxMaL" },          },        },      },    ],  },}

Per fissare una persona per agente, impostare agents.list[].tts.persona insieme alla configurazione del provider: sostituisce il valore globale messages.tts.persona solo per quell'agente.

Ordine di precedenza per le risposte automatiche, /tts audio, /tts status e lo strumento agente tts:

1. messages.tts
2. agents.list[].tts attivo
3. override del canale, quando il canale supporta channels.<channel>.tts
4. override dell'account, quando il canale passa channels.<channel>.accounts.<id>.tts
5. preferenze /tts locali per questo host
6. direttive [[tts:...]] inline quando gli override determinati dal modello sono abilitati

Gli override di canale e account usano la stessa struttura di messages.tts e vengono uniti in profondità sopra i livelli precedenti, quindi le credenziali condivise del provider possono rimanere in messages.tts, mentre un canale o un account bot modifica solo la voce del parlante, il modello, la persona o la modalità automatica:

{  messages: {    tts: {      provider: "openai",      providers: {        openai: { apiKey: "${OPENAI_API_KEY}", model: "gpt-4o-mini-tts" },      },    },  },  channels: {    feishu: {      accounts: {        english: {          tts: {            providers: {              openai: { speakerVoice: "shimmer" },            },          },        },      },    },  },}

Persone

Una persona è un'identità vocale stabile che può essere applicata in modo deterministico tra diversi provider. Può preferire un provider, definire l'intento del prompt indipendentemente dal provider e contenere associazioni specifiche del provider per voci, modelli, modelli di prompt, seed e impostazioni vocali.

Persona minima

{  messages: {    tts: {      auto: "always",      persona: "narrator",      personas: {        narrator: {          label: "Narratore",          provider: "elevenlabs",          providers: {            elevenlabs: {              speakerVoiceId: "EXAVITQu4vr4xnSDxMaL",              modelId: "eleven_multilingual_v2",            },          },        },      },    },  },}

Persona completa (prompt indipendente dal provider)

{  messages: {    tts: {      auto: "always",      persona: "alfred",      personas: {        alfred: {          label: "Alfred",          description: "Narratore maggiordomo britannico, asciutto e cordiale.",          provider: "google",          fallbackPolicy: "preserve-persona",          prompt: {            profile: "Un brillante maggiordomo britannico. Asciutto, arguto, cordiale, affascinante, emotivamente espressivo, mai generico.",            scene: "Uno studio silenzioso a tarda notte. Narrazione ravvicinata al microfono per un operatore fidato.",            sampleContext: "Il parlante risponde a una richiesta tecnica privata con sicurezza concisa e asciutta cordialità.",            style: "Raffinato, misurato, lievemente divertito.",            accent: "Inglese britannico.",            pacing: "Misurato, con brevi pause drammatiche.",            constraints: ["Non leggere ad alta voce i valori di configurazione.", "Non spiegare la persona."],          },          providers: {            google: {              model: "gemini-3.1-flash-tts-preview",              speakerVoice: "Algieba",              promptTemplate: "audio-profile-v1",            },            openai: { model: "gpt-4o-mini-tts", speakerVoice: "cedar" },            elevenlabs: {              speakerVoiceId: "voice_id",              modelId: "eleven_multilingual_v2",              seed: 42,              voiceSettings: {                stability: 0.65,                similarityBoost: 0.8,                style: 0.25,                useSpeakerBoost: true,                speed: 0.95,              },            },          },        },      },    },  },}

Risoluzione della persona

La persona attiva viene selezionata in modo deterministico:

1. Preferenza locale /tts persona <id>, se impostata.
2. messages.tts.persona, se impostata.
3. Nessuna persona.

La selezione del provider dà precedenza alle impostazioni esplicite:

1. Override diretti (CLI, Gateway, Talk, direttive TTS consentite).
2. Preferenza locale /tts provider <id>.
3. provider della persona attiva.
4. messages.tts.provider.
5. Selezione automatica dal registro.

Per ogni tentativo del provider, OpenClaw unisce le configurazioni nel seguente ordine:

1. messages.tts.providers.<id>
2. messages.tts.personas.<persona>.providers.<id>
3. Override della richiesta attendibile
4. Override consentiti delle direttive TTS emesse dal modello

Come i provider usano i prompt delle persone

I campi del prompt della persona (profile, scene, sampleContext, style, accent, pacing, constraints) sono indipendenti dal provider. Ogni provider decide come usarli:

Criterio di fallback

fallbackPolicy controlla il comportamento quando una persona non dispone di alcuna associazione per il provider su cui viene effettuato il tentativo:

L'intera richiesta TTS non riesce solo quando tutti i provider tentati vengono saltati o non riescono.

La selezione del provider per una sessione Talk è limitata alla sessione. Un client Talk deve scegliere gli ID dei provider, dei modelli e delle voci e le impostazioni locali da talk.catalog e passarli tramite la sessione Talk o la richiesta di passaggio. L'apertura di una sessione vocale non deve modificare messages.tts né i valori predefiniti globali dei provider Talk.

Direttive determinate dal modello

Per impostazione predefinita, l'assistente può emettere direttive [[tts:...]] per sostituire voce, modello o velocità per una singola risposta, oltre a un blocco facoltativo [[tts:text]]...[[/tts:text]] per indicazioni espressive che devono comparire solo nell'audio:

Ecco fatto. [[tts:speakerVoiceId=pMsXgVXv3BLzUgSXRplE model=eleven_v3 speed=1.1]][[tts:text]](ride) Leggi la canzone ancora una volta.[[/tts:text]]

Quando messages.tts.auto è "tagged", le direttive sono obbligatorie per attivare l'audio. La consegna dei blocchi in streaming rimuove le direttive dal testo visibile prima che il canale le riceva, anche quando sono suddivise tra blocchi adiacenti.

provider=... viene ignorato a meno che modelOverrides.allowProvider: true. Quando una risposta dichiara provider=..., le altre chiavi della direttiva vengono analizzate solo da quel provider; le chiavi non supportate vengono rimosse e segnalate come avvisi relativi alle direttive TTS.

Chiavi di direttiva disponibili:

• provider (ID del provider registrato; richiede allowProvider: true)
• speakerVoice / speakerVoiceId (alias precedenti: voice, voiceName, voice_name, google_voice, voiceId)
• model / google_model
• stability, similarityBoost, style, speed, useSpeakerBoost
• vol / volume (volume MiniMax, (0, 10])
• pitch (intonazione MiniMax intera, da −12 a 12; i valori frazionari vengono troncati)
• emotion (tag emotivo Volcengine)
• applyTextNormalization (auto|on|off)
• languageCode (ISO 639-1)
• seed

Disabilitare completamente gli override del modello:

{ messages: { tts: { modelOverrides: { enabled: false } } } }

Consentire il cambio di provider mantenendo configurabili gli altri parametri:

{ messages: { tts: { modelOverrides: { enabled: true, allowProvider: true, allowSeed: false } } } }

Comandi slash

Comando singolo /tts. Su Discord, OpenClaw registra anche /voice perché /tts è un comando integrato di Discord; il testo /tts ... continua a funzionare.

/tts off | on | status/tts chat on | off | default/tts latest/tts provider <id>/tts persona <id> | off/tts limit <chars>/tts summary off/tts audio <text>

Note sul comportamento:

• /tts on scrive la preferenza TTS locale in always; /tts off la scrive in off.
• /tts chat on|off|default scrive un override TTS automatico limitato alla sessione per la chat corrente.
• /tts persona <id> scrive la preferenza locale della persona; /tts persona off la cancella.
• /tts latest legge l'ultima risposta dell'assistente dalla trascrizione della sessione corrente e la invia una volta come audio. Memorizza solo un hash di tale risposta nella voce della sessione per impedire invii vocali duplicati.
• /tts audio genera una risposta audio una tantum (non attiva o disattiva TTS).
• /tts limit <chars> accetta 100–4096 (4096 è il massimo per didascalie/messaggi di Telegram); i valori al di fuori di questo intervallo vengono rifiutati.
• limit e summary vengono memorizzati nelle preferenze locali, non nella configurazione principale.
• /tts status include la diagnostica di fallback per l'ultimo tentativo: Fallback: <primary> -> <used>, Attempts: ... e i dettagli di ciascun tentativo (provider:outcome(reasonCode) latency).
• /status mostra la modalità TTS attiva insieme al provider, al modello, alla voce e ai metadati sanitizzati dell'endpoint personalizzato configurati quando TTS è abilitato.

Preferenze per utente

I comandi slash scrivono gli override locali in prefsPath. Il valore predefinito è ~/.openclaw/settings/tts.json; è possibile sostituirlo con la variabile d'ambiente OPENCLAW_TTS_PREFS o messages.tts.prefsPath.

Questi valori sostituiscono la configurazione effettiva derivata da messages.tts più il blocco agents.list[].tts attivo per quell'host.

Formati di output

La distribuzione vocale TTS dipende dalle funzionalità del canale. I Plugin dei canali indicano se il TTS in stile vocale deve richiedere ai provider una destinazione voice-note nativa o mantenere la normale sintesi audio-file, e se il canale transcodifica l'output non nativo prima dell'invio.

Note specifiche per provider:

• Transcodifica per Feishu / WhatsApp: quando una risposta con messaggio vocale arriva come MP3/WebM/WAV/M4A o come un altro probabile file audio, il Plugin del canale la transcodifica in Ogg/Opus a 48 kHz con ffmpeg (libopus, 64 kbps) prima di inviare il messaggio vocale nativo. WhatsApp invia il risultato tramite il payload Baileys audio con ptt: true e audio/ogg; codecs=opus. In caso di errore di transcodifica: Feishu intercetta l'errore e ripiega sull'invio del file originale come semplice allegato; WhatsApp non dispone di un ripiego, quindi l'invio stesso non riesce anziché pubblicare un payload PTT incompatibile.
• MiniMax: MP3 (modello speech-2.8-hd, frequenza di campionamento di 32 kHz) per i normali allegati audio; transcodificato in Opus a 48 kHz con ffmpeg per le destinazioni di messaggi vocali indicate dal canale.
• Xiaomi MiMo: MP3 per impostazione predefinita oppure WAV quando configurato; transcodificato in Opus a 48 kHz con ffmpeg per le destinazioni di messaggi vocali indicate dal canale.
• CLI locale: usa il valore outputFormat configurato. Le destinazioni di messaggi vocali vengono convertite in Ogg/Opus e l'output telefonico viene convertito in PCM mono raw a 16 kHz con ffmpeg.
• Google Gemini: restituisce PCM raw a 24 kHz. OpenClaw lo incapsula come WAV per gli allegati audio, lo transcodifica in Opus a 48 kHz per le destinazioni di messaggi vocali e restituisce direttamente PCM per Conversazione/telefonia.
• Gradium: WAV per gli allegati audio, Opus per le destinazioni di messaggi vocali e ulaw_8000 a 8 kHz per la telefonia.
• Inworld: MP3 per i normali allegati audio, OGG_OPUS nativo per le destinazioni di messaggi vocali e PCM raw a 22050 Hz per Conversazione/telefonia.
• xAI: MP3 per impostazione predefinita; la sintesi di file audio può usare mp3, wav, pcm, mulaw o alaw sia per l'output con buffering sia per quello in streaming. Le destinazioni di messaggi vocali usano MP3 per lo streaming e come ripiego con buffering, perché gli output pcm, mulaw e alaw di xAI sono audio raw senza intestazione. La sintesi con buffering usa l'endpoint REST batch /v1/tts di xAI; textToSpeechStream usa wss://api.x.ai/v1/tts nativo. Questo non è il contratto vocale in tempo reale. Il formato vocale Opus nativo non è supportato.
• Microsoft: usa microsoft.outputFormat (valore predefinito: audio-24khz-48kbitrate-mono-mp3).
  • Il trasporto incluso accetta un valore outputFormat, ma il servizio non rende disponibili tutti i formati.
  • I valori del formato di output seguono i formati di output di Microsoft Speech (incluso Ogg/WebM Opus).
  • Il valore sendVoice di Telegram accetta OGG/MP3/M4A; usare OpenAI/ElevenLabs se sono necessari messaggi vocali Opus garantiti.
  • Se il formato di output Microsoft configurato non riesce, OpenClaw riprova con MP3.
  • Quando non è impostato alcun override esplicito della voce e viene usata la voce inglese predefinita, OpenClaw passa automaticamente a una voce neurale cinese (zh-CN-XiaoxiaoNeural, impostazioni locali zh-CN) se il testo della risposta è prevalentemente CJK.

I formati di output di OpenAI ed ElevenLabs sono fissi per ciascun canale, come indicato sopra.

Comportamento del TTS automatico

Quando messages.tts.auto è abilitato, OpenClaw:

• Ignora la sintesi vocale se la risposta contiene già contenuti multimediali strutturati.
• Ignora le risposte molto brevi (meno di 10 caratteri).
• Riassume le risposte lunghe quando i riepiloghi sono abilitati, utilizzando summaryModel (o agents.defaults.model.primary).
• Allega l'audio generato alla risposta.
• In mode: "final", invia comunque solo l'audio della sintesi vocale per le risposte finali trasmesse in streaming al termine del flusso di testo; i contenuti multimediali generati vengono sottoposti alla stessa normalizzazione dei contenuti multimediali del canale applicata ai normali allegati delle risposte.

Se la risposta supera maxLength, OpenClaw non omette mai completamente l'audio:

• Riepilogo attivo (impostazione predefinita) e disponibilità di un modello di riepilogo: riassume il testo fino a circa maxLength caratteri, quindi sintetizza il riepilogo.
• Riepilogo disattivato, errore del riepilogo o nessuna chiave API disponibile per il modello di riepilogo: tronca il testo a maxLength caratteri e sintetizza il testo troncato.

Risposta -> sintesi vocale abilitata?  no  -> invia testo  sì  -> contiene contenuti multimediali / è breve?          sì -> invia testo          no  -> lunghezza > limite?                   no  -> sintesi vocale -> allega audio                   sì  -> riepilogo abilitato e disponibile?                            no  -> tronca -> sintesi vocale -> allega audio                            sì  -> riassumi -> sintesi vocale -> allega audio

Riferimento dei campi

Strumento dell'agente

Lo strumento tts converte il testo in voce e restituisce un allegato audio per la consegna della risposta. Su Feishu, Matrix, Telegram e WhatsApp, l'audio viene consegnato come messaggio vocale anziché come allegato file. Feishu e WhatsApp possono transcodificare l'output TTS non Opus in questo percorso quando ffmpeg è disponibile.

WhatsApp invia l'audio tramite Baileys come nota vocale PTT (audio con ptt: true) e invia il testo visibile separatamente dall'audio PTT, poiché i client non visualizzano in modo uniforme le didascalie delle note vocali.

Lo strumento accetta i campi facoltativi channel e timeoutMs; timeoutMs è un timeout della richiesta al provider per singola chiamata, espresso in millisecondi. I valori per singola chiamata sostituiscono messages.tts.timeoutMs; i timeout TTS configurati sostituiscono qualsiasi valore predefinito del provider definito dal Plugin.

RPC del Gateway

Link ai servizi

• Guida alla sintesi vocale di OpenAI
• Riferimento dell'API Audio di OpenAI
• Sintesi vocale tramite REST di Azure Speech
• Provider Azure Speech
• Sintesi vocale di ElevenLabs
• Autenticazione di ElevenLabs
• Gradium
• API TTS di Inworld
• API MiniMax T2A v2
• API HTTP TTS di Volcengine
• Sintesi vocale Xiaomi MiMo
• node-edge-tts
• Formati di output di Microsoft Speech
• Sintesi vocale di xAI

Argomenti correlati

• Panoramica dei contenuti multimediali
• Generazione musicale
• Generazione video
• Comandi slash
• Plugin per chiamate vocali