Sintesi vocale

OpenClaw può convertire le risposte in uscita in audio tramite 14 fornitori di sintesi vocale e recapitare messaggi vocali nativi su Feishu, Matrix, Telegram e WhatsApp, allegati audio ovunque altrove, e flussi PCM/Ulaw per telefonia e Talk.

TTS è la metà di output vocale della modalità stt-tts di Talk. Le sessioni Talk realtime native del fornitore sintetizzano la voce all'interno del fornitore in tempo reale 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",    },  },}

Fornitori supportati

Se sono configurati più fornitori, 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 fornitore 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 fornitore:

{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",      // 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}",      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, ometti speakerVoice e imposta style sul prompt di progettazione vocale. OpenClaw invia quel prompt come messaggio user TTS e non invia audio.voice per il modello voicedesign.

Sostituzioni vocali per agente

Usa agents.list[].tts quando un agente deve parlare con un provider, voce, modello, persona o modalità TTS automatica diversi. Il blocco dell'agente esegue un deep merge 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: { speakerVoiceId: "EXAVITQu4vr4xnSDxMaL" },          },        },      },    ],  },}

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

Ordine di precedenza per 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 del 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, quindi le credenziali condivise del provider possono restare in messages.tts mentre un canale o account bot cambia solo voce del parlante, 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: { speakerVoice: "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: {              speakerVoiceId: "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",              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 procede dando priorità agli elementi espliciti:

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 del registro.

Per ogni tentativo di provider, OpenClaw unisce le configurazioni in questo 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 della persona

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 ha nessuna 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 ha ambito di sessione. Un client Talk dovrebbe scegliere ID provider, ID modello, ID voce e impostazioni locali 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 segnali espressivi che devono comparire solo nell'audio:

Here you go. [[tts:speakerVoiceId=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)
• speakerVoice / speakerVoiceId (alias legacy: voice, voiceName, voice_name, google_voice, voiceId)
• model / google_model
• stability, similarityBoost, style, speed, useSpeakerBoost
• vol / volume (volume MiniMax, 0–10)
• pitch (intonazione intera 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 impostazioni:

{ 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 su always; /tts off la scrive su off.
• /tts chat on|off|default scrive un override TTS automatico con ambito di 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 sola volta come audio. Memorizza solo un hash di quella risposta nella voce di sessione per evitare 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 sanificati dell'endpoint personalizzato configurati 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 d'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 deve chiedere ai provider un target nativo voice-note o mantenere la normale sintesi audio-file e contrassegnare solo l'output compatibile per la consegna vocale.

• Canali compatibili con le note vocali: le risposte con note vocali preferiscono Opus (opus_48000_64 da ElevenLabs, opus da OpenAI).
  • 48 kHz / 64 kbps è un buon compromesso per i messaggi vocali.
• Feishu / WhatsApp: quando una risposta con nota vocale viene prodotta come MP3/WebM/WAV/M4A o come un altro probabile file audio, il Plugin del canale la transcodifica a 48 kHz Ogg/Opus con ffmpeg prima di inviare il messaggio vocale nativo. WhatsApp invia il risultato tramite il payload audio di Baileys con ptt: true e audio/ogg; codecs=opus. Se la conversione non riesce, Feishu riceve il file originale come allegato; l'invio di WhatsApp non riesce invece di pubblicare un payload PTT incompatibile.
• Altri canali: MP3 (mp3_44100_128 da ElevenLabs, mp3 da OpenAI).
  • 44,1 kHz / 128 kbps è il bilanciamento predefinito per la chiarezza del parlato.
• MiniMax: MP3 (modello speech-2.8-hd, frequenza di campionamento 32 kHz) per i normali allegati audio. Per le destinazioni di note vocali dichiarate dal canale, OpenClaw transcodifica l'MP3 di MiniMax in Opus a 48 kHz 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 48 kHz 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 di telefonia viene convertito in PCM mono grezzo a 16 kHz con ffmpeg.
• Google Gemini: il TTS dell'API Gemini restituisce PCM grezzo a 24 kHz. OpenClaw lo racchiude come WAV per gli allegati audio, lo transcodifica in Opus a 48 kHz 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 i normali allegati audio, 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 del 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 di Microsoft Speech (inclusi Ogg/WebM Opus).
  • Telegram sendVoice accetta OGG/MP3/M4A; usa OpenAI/ElevenLabs se hai bisogno di messaggi vocali Opus garantiti.
  • Se il formato di output Microsoft configurato non riesce, OpenClaw ritenta 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à contenuti multimediali strutturati.
• Salta le risposte molto brevi (meno di 10 caratteri).
• Riassume le risposte lunghe quando i riassunti sono abilitati, usando summaryModel (o agents.defaults.model.primary).
• Allega l'audio generato alla risposta.
• In mode: "final", invia comunque il TTS solo audio per le risposte finali in streaming dopo il completamento dello stream di testo; il contenuto multimediale generato passa attraverso la stessa normalizzazione multimediale del canale degli allegati di risposta normali.

Se la risposta supera maxLength e il riassunto è disattivato (o manca una chiave API per il modello di riassunto), l'audio viene saltato e viene inviata la normale risposta testuale.

Reply -> TTS enabled?  no  -> send text  yes -> has 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 la 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 sono 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: lo streaming WebSocket TTS 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 hai bisogno di messaggi vocali Opus garantiti. Se il formato Microsoft configurato fallisce, OpenClaw riprova con MP3.

I formati di output OpenAI ed ElevenLabs sono fissati per canale come elencato sopra.

Riferimento dei campi

Strumento agente

Lo strumento tts converte il testo in sintesi vocale 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 perché i client non renderizzano in modo coerente le didascalie sulle note vocali.

Lo strumento accetta i campi opzionali channel e timeoutMs; timeoutMs è un timeout di richiesta del provider per chiamata in millisecondi. I valori per chiamata eseguono l'override di messages.tts.timeoutMs; i timeout TTS configurati eseguono l'override di qualsiasi valore predefinito del provider definito dal Plugin.

RPC Gateway

Collegamenti ai servizi

• Guida OpenAI text-to-speech
• Riferimento API OpenAI Audio
• Azure Speech REST text-to-speech
• Provider Azure Speech
• ElevenLabs Text to Speech
• Autenticazione ElevenLabs
• Gradium
• API Inworld TTS
• API MiniMax T2A v2
• API HTTP Volcengine TTS
• 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 per chiamate vocali