Sintesi vocale

OpenClaw può convertire le risposte in uscita in audio tramite 14 provider vocali e inviare messaggi vocali nativi su Feishu, Matrix, Telegram e WhatsApp, allegati audio ovunque altrove, e stream PCM/Ulaw per telefonia e Talk.

TTS è la metà di output vocale della modalità stt-tts di Talk. Le sessioni Talk realtime native del provider sintetizzano la voce all'interno del provider realtime invece di chiamare questo percorso TTS, mentre le sessioni transcription non sintetizzano una risposta vocale dell'assistente.

Avvio rapido

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

Provider supportati

Se sono configurati più provider, quello selezionato viene usato per primo e gli altri sono opzioni di fallback. Il riepilogo automatico usa summaryModel (o agents.defaults.model.primary), quindi anche quel provider deve essere autenticato se mantieni abilitati i riepiloghi.

Configurazione

La configurazione TTS si trova sotto messages.tts in ~/.openclaw/openclaw.json. Scegli un preset e adatta il blocco del provider:

{messages: {tts: {  auto: "always",  provider: "azure-speech",  providers: {    "azure-speech": {      apiKey: "${AZURE_SPEECH_KEY}",      region: "eastus",      voice: "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",      voiceId: "EXAVITQu4vr4xnSDxMaL",    },  },},},}

{messages: {tts: {  auto: "always",  provider: "google",  providers: {    google: {      apiKey: "${GEMINI_API_KEY}",      model: "gemini-3.1-flash-tts-preview",      voiceName: "Kore",      // Optional natural-language style prompts:      // audioProfile: "Speak in a calm, podcast-host tone.",      // speakerName: "Alex",    },  },},},}

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

{messages: {tts: {  auto: "always",  provider: "inworld",  providers: {    inworld: {      apiKey: "${INWORLD_API_KEY}",      modelId: "inworld-tts-1.5-max",      voiceId: "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,      voice: "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",      voiceId: "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",      voice: "alloy",    },    elevenlabs: {      apiKey: "${ELEVENLABS_API_KEY}",      model: "eleven_multilingual_v2",      voiceId: "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",      voice: "af_alloy",      responseFormat: "mp3",    },  },},},}

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

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

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

Override vocali per agente

Usa agents.list[].tts quando un agente deve parlare con un provider, una voce, un modello, una persona o una modalità Auto-TTS diversi. Il blocco dell'agente viene unito ricorsivamente sopra messages.tts, quindi le credenziali del provider possono restare 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: { voiceId: "EXAVITQu4vr4xnSDxMaL" },          },        },      },    ],  },}

Per fissare una persona per agente, imposta agents.list[].tts.persona accanto alla configurazione del provider — sovrascrive messages.tts.persona globale 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 locali /tts per questo host
6. direttive inline [[tts:...]] quando gli override guidati dal modello sono abilitati

Gli override di canale e account usano la stessa forma di messages.tts ed eseguono un deep merge sopra i livelli precedenti, così le credenziali condivise del provider possono restare in messages.tts mentre un canale o account bot cambia solo voce, modello, persona o modalità automatica:

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

Persone

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

Persona minima

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

Persona completa (prompt indipendente dal provider)

{  messages: {    tts: {      auto: "always",      persona: "alfred",      personas: {        alfred: {          label: "Alfred",          description: "Dry, warm British butler narrator.",          provider: "google",          fallbackPolicy: "preserve-persona",          prompt: {            profile: "A brilliant British butler. Dry, witty, warm, charming, emotionally expressive, never generic.",            scene: "A quiet late-night study. Close-mic narration for a trusted operator.",            sampleContext: "The speaker is answering a private technical request with concise confidence and dry warmth.",            style: "Refined, understated, lightly amused.",            accent: "British English.",            pacing: "Measured, with short dramatic pauses.",            constraints: ["Do not read configuration values aloud.", "Do not explain the persona."],          },          providers: {            google: {              model: "gemini-3.1-flash-tts-preview",              voiceName: "Algieba",              promptTemplate: "audio-profile-v1",            },            openai: { model: "gpt-4o-mini-tts", voice: "cedar" },            elevenlabs: {              voiceId: "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 procede dando 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 in quest'ordine:

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

Come i provider usano i prompt delle persone

I campi 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 ha alcuna associazione per il provider tentato:

L'intera richiesta TTS fallisce solo quando ogni provider tentato viene saltato o fallisce.

La selezione del provider della sessione Talk è limitata alla sessione. Un client Talk dovrebbe scegliere id provider, id modello, id voce e locale da talk.catalog e passarli attraverso la sessione Talk o la richiesta di handoff. L'apertura di una sessione vocale non dovrebbe modificare messages.tts o i valori predefiniti globali del provider Talk.

Direttive guidate dal modello

Per impostazione predefinita, l'assistente può emettere direttive [[tts:...]] per sovrascrivere voce, modello o velocità per una singola risposta, più un blocco facoltativo [[tts:text]]...[[/tts:text]] per indicazioni espressive che dovrebbero apparire solo nell'audio:

Here you go. [[tts:voiceId=pMsXgVXv3BLzUgSXRplE model=eleven_v3 speed=1.1]][[tts:text]](laughs) Read the song once more.[[/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 veda, anche quando sono divise tra blocchi adiacenti.

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

Chiavi di direttiva disponibili:

• provider (id provider registrato; richiede allowProvider: true)
• voice / voiceName / voice_name / google_voice / voiceId
• model / google_model
• stability, similarityBoost, style, speed, useSpeakerBoost
• vol / volume (volume MiniMax, 0–10)
• pitch (pitch intero MiniMax, da −12 a 12; i valori frazionari vengono troncati)
• emotion (tag emozione Volcengine)
• applyTextNormalization (auto|on|off)
• languageCode (ISO 639-1)
• seed

Disabilita completamente gli override del modello:

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

Consenti il cambio di provider mantenendo configurabili le altre manopole:

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

Comandi slash

Singolo comando /tts. Su Discord, OpenClaw registra anche /voice perché /tts è un comando integrato di Discord — il testo /tts ... funziona comunque.

/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 su always; /tts off la scrive su off.
• /tts chat on|off|default scrive un override auto-TTS 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 come audio una volta. Memorizza solo un hash di quella risposta nella voce della sessione per sopprimere invii vocali duplicati.
• /tts audio genera una risposta audio una tantum (non attiva TTS).
• limit e summary sono memorizzati nelle preferenze locali, non nella configurazione principale.
• /tts status include diagnostica di fallback per l'ultimo tentativo — Fallback: <primary> -> <used>, Attempts: ... e dettagli per tentativo (provider:outcome(reasonCode) latency).
• /status mostra la modalità TTS attiva più provider, modello, voce e metadati dell'endpoint personalizzato sanificati quando TTS è abilitato.

Preferenze per utente

I comandi slash scrivono override locali in prefsPath. Il valore predefinito è ~/.openclaw/settings/tts.json; sovrascrivilo con la variabile di ambiente OPENCLAW_TTS_PREFS o messages.tts.prefsPath.

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

Formati di output (fissi)

La consegna vocale TTS è guidata dalle capacità del canale. I Plugin di canale dichiarano se il TTS in stile vocale dovrebbe chiedere ai provider un target nativo voice-note oppure mantenere la normale sintesi audio-file e contrassegnare solo l'output compatibile per la consegna vocale.

• Canali compatibili con note vocali: le risposte con note vocali preferiscono Opus (opus_48000_64 da ElevenLabs, opus da OpenAI).
  • 48kHz / 64kbps è un buon compromesso per i messaggi vocali.
• Feishu / WhatsApp: quando una risposta con nota vocale viene prodotta come MP3/WebM/WAV/M4A o un altro file probabilmente audio, il plugin del canale la transcodifica in Ogg/Opus a 48kHz con ffmpeg prima di inviare il messaggio vocale nativo. WhatsApp invia il risultato tramite il payload Baileys audio con ptt: true e audio/ogg; codecs=opus. Se la conversione non riesce, Feishu riceve il file originale come allegato; l'invio WhatsApp non riesce invece di pubblicare un payload PTT incompatibile.
• Altri canali: MP3 (mp3_44100_128 da ElevenLabs, mp3 da OpenAI).
  • 44,1kHz / 128kbps è il bilanciamento predefinito per la chiarezza del parlato.
• MiniMax: MP3 (modello speech-2.8-hd, frequenza di campionamento 32kHz) per gli allegati audio normali. Per le destinazioni di note vocali dichiarate dal canale, OpenClaw transcodifica l'MP3 MiniMax in Opus a 48kHz con ffmpeg prima della consegna quando il canale dichiara la transcodifica.
• Xiaomi MiMo: MP3 per impostazione predefinita, oppure WAV quando configurato. Per le destinazioni di note vocali dichiarate dal canale, OpenClaw transcodifica l'output Xiaomi in Opus a 48kHz con ffmpeg prima della consegna quando il canale dichiara la transcodifica.
• CLI locale: usa il outputFormat configurato. Le destinazioni di note vocali vengono convertite in Ogg/Opus e l'output per telefonia viene convertito in PCM mono grezzo a 16 kHz con ffmpeg.
• Google Gemini: Gemini API TTS restituisce PCM grezzo a 24kHz. OpenClaw lo incapsula come WAV per gli allegati audio, lo transcodifica in Opus a 48kHz per le destinazioni di note vocali e restituisce direttamente PCM per Talk/telefonia.
• Gradium: WAV per gli allegati audio, Opus per le destinazioni di note vocali e ulaw_8000 a 8 kHz per la telefonia.
• Inworld: MP3 per gli allegati audio normali, OGG_OPUS nativo per le destinazioni di note vocali e PCM grezzo a 22050 Hz per Talk/telefonia.
• xAI: MP3 per impostazione predefinita; responseFormat può essere mp3, wav, pcm, mulaw o alaw. OpenClaw usa l'endpoint TTS REST batch di xAI e restituisce un allegato audio completo; il WebSocket TTS in streaming di xAI non viene usato da questo percorso provider. Il formato nativo Opus per note vocali non è supportato da questo percorso.
• Microsoft: usa microsoft.outputFormat (predefinito audio-24khz-48kbitrate-mono-mp3).
  • Il trasporto incluso accetta un outputFormat, ma non tutti i formati sono disponibili dal servizio.
  • I valori del formato di output seguono i formati di output Microsoft Speech (inclusi Ogg/WebM Opus).
  • Telegram sendVoice accetta OGG/MP3/M4A; usa OpenAI/ElevenLabs se ti servono messaggi vocali Opus garantiti.
  • Se il formato di output Microsoft configurato non riesce, OpenClaw riprova con MP3.

I formati di output OpenAI/ElevenLabs sono fissi per canale (vedi sopra).

Comportamento Auto-TTS

Quando messages.tts.auto è abilitato, OpenClaw:

• Salta il TTS se la risposta contiene già media o una direttiva MEDIA:.
• Salta le risposte molto brevi (meno di 10 caratteri).
• Riassume le risposte lunghe quando i riepiloghi sono abilitati, usando summaryModel (o agents.defaults.model.primary).
• Allega l'audio generato alla risposta.
• In mode: "final", invia comunque TTS solo audio per le risposte finali in streaming dopo il completamento dello stream di testo; il media generato passa attraverso la stessa normalizzazione dei media del canale degli allegati di risposta normali.

Se la risposta supera maxLength e il riepilogo è disattivato (o non c'è una chiave API per il modello di riepilogo), l'audio viene saltato e viene inviata la normale risposta di testo.

Reply -> TTS enabled?  no  -> send text  yes -> has media / MEDIA: / short?          yes -> send text          no  -> length > limit?                   no  -> TTS -> attach audio                   yes -> summary enabled?                            no  -> send text                            yes -> summarize -> TTS -> attach audio

Formati di output per canale

Note per provider:

• Transcodifica Feishu / WhatsApp: quando una risposta con nota vocale arriva come MP3/WebM/WAV/M4A, il plugin del canale transcodifica in Ogg/Opus a 48 kHz con ffmpeg. WhatsApp invia tramite Baileys con ptt: true e audio/ogg; codecs=opus. Se la conversione non riesce: Feishu ripiega sull'allegare il file originale; l'invio WhatsApp fallisce invece di pubblicare un payload PTT incompatibile.
• MiniMax / Xiaomi MiMo: MP3 predefinito (32 kHz per MiniMax speech-2.8-hd); transcodificato in Opus a 48 kHz per le destinazioni con nota vocale tramite ffmpeg.
• CLI locale: usa outputFormat configurato. Le destinazioni con nota vocale vengono convertite in Ogg/Opus e l'output di telefonia in PCM mono grezzo a 16 kHz.
• Google Gemini: restituisce PCM grezzo a 24 kHz. OpenClaw lo incapsula come WAV per gli allegati, lo transcodifica in Opus a 48 kHz per le destinazioni con nota vocale, restituisce direttamente PCM per Talk/telefonia.
• Inworld: allegati MP3, nota vocale nativa OGG_OPUS, PCM grezzo a 22050 Hz per Talk/telefonia.
• xAI: MP3 per impostazione predefinita; responseFormat può essere mp3|wav|pcm|mulaw|alaw. Usa l'endpoint REST batch di xAI: il TTS WebSocket in streaming non viene usato. Il formato nativo Opus per note vocali non è supportato.
• Microsoft: usa microsoft.outputFormat (predefinito audio-24khz-48kbitrate-mono-mp3). Telegram sendVoice accetta OGG/MP3/M4A; usa OpenAI/ElevenLabs se ti servono messaggi vocali Opus garantiti. Se il formato Microsoft configurato fallisce, OpenClaw riprova con MP3.

I formati di output di OpenAI e ElevenLabs sono fissi per canale come elencato sopra.

Riferimento dei campi

Strumento agente

Lo strumento tts converte il testo in parlato e restituisce un allegato audio per la consegna della risposta. Su Feishu, Matrix, Telegram e WhatsApp, l'audio viene consegnato come messaggio vocale invece che 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 perché i client non renderizzano in modo coerente le didascalie sulle note vocali.

Lo strumento accetta i campi facoltativi channel e timeoutMs; timeoutMs è un timeout della richiesta al provider per singola chiamata, in millisecondi.

RPC Gateway

Link ai servizi

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

Correlati

• Panoramica media
• Generazione musicale
• Generazione video
• Comandi slash
• Plugin chiamate vocali