Sintesi vocale

OpenClaw può convertire le risposte in uscita in audio tramite 14 provider vocali e consegnare 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 provider sintetizzano il parlato 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 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: { voiceId: "EXAVITQu4vr4xnSDxMaL" },
          },
        },
      },
    ],
  },
}

Per fissare una persona per agente, imposta agents.list[].tts.persona insieme alla configurazione del provider: sovrascrive la 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 e si uniscono in profondità ai livelli precedenti, quindi le credenziali condivise del provider possono restare in messages.tts mentre un canale o un account bot modifica 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" },
            },
          },
        },
      },
    },
  },
}

# Persona

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 portare binding specifici del provider per voci, modelli, template di prompt, seed e impostazioni vocali.

# Persona minimale

{
  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 usa prima i valori 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 da direttive TTS emesse dal modello e consentite

# Come i provider usano i prompt della persona

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 alcun binding 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 gli ID provider, gli ID modello, gli ID voce e le impostazioni locali da talk.catalog e passarli attraverso la sessione Talk o la richiesta di handoff. L'apertura di una sessione vocale non dovrebbe mutare 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 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

Disabilitare completamente gli override del modello:

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

Consentire 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 Discord integrato — 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 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 volta come audio. 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 vengono archiviati 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 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 env 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 pubblicizzano se il TTS in stile messaggio vocale deve chiedere ai provider un target nativo voice-note o mantenere la normale sintesi audio-file e marcare solo l'output compatibile per la consegna vocale.

• Canali compatibili con le note vocali: le risposte come 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 come nota vocale viene prodotta come MP3/WebM/WAV/M4A o un altro file probabilmente audio, il plugin del canale la transcodifica a Ogg/Opus a 48 kHz 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.
• BlueBubbles: mantiene la sintesi del provider sul normale percorso dei file audio; gli output MP3 e CAF sono contrassegnati per la consegna come memo vocale iMessage.
• 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 per note vocali dichiarate dal canale, OpenClaw transcodifica l'MP3 MiniMax a Opus 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 per note vocali dichiarate dal canale, OpenClaw transcodifica l'output Xiaomi a Opus 48 kHz con ffmpeg prima della consegna quando il canale dichiara la transcodifica.
• CLI locale: usa l'outputFormat configurato. Le destinazioni per note vocali sono convertite in Ogg/Opus e l'output di telefonia viene convertito in PCM mono raw a 16 kHz con ffmpeg.
• Google Gemini: Gemini API TTS restituisce PCM raw a 24 kHz. OpenClaw lo incapsula come WAV per gli allegati audio, lo transcodifica a Opus 48 kHz per le destinazioni per note vocali e restituisce direttamente PCM per Talk/telefonia.
• Gradium: WAV per gli allegati audio, Opus per le destinazioni per note vocali e ulaw_8000 a 8 kHz per la telefonia.
• Inworld: MP3 per i normali allegati audio, OGG_OPUS nativo per le destinazioni per note vocali e PCM raw 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 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 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 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 riassunti 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 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 / 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 come nota vocale arriva come MP3/WebM/WAV/M4A, il plugin del canale la transcodifica a Ogg/Opus 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 di WhatsApp non riesce invece di pubblicare un payload PTT incompatibile.
• MiniMax / Xiaomi MiMo: MP3 predefinito (32 kHz per MiniMax speech-2.8-hd); transcodificato a Opus 48 kHz per le destinazioni per note vocali tramite ffmpeg.
• CLI locale: Usa l'outputFormat configurato. Le destinazioni per note vocali sono convertite in Ogg/Opus e l'output di telefonia in PCM mono raw a 16 kHz.
• Google Gemini: Restituisce PCM raw a 24 kHz. OpenClaw lo incapsula come WAV per gli allegati, lo transcodifica a Opus 48 kHz per le destinazioni per note vocali, restituisce direttamente PCM per Talk/telefonia.
• Inworld: Allegati MP3, nota vocale OGG_OPUS nativa, PCM raw 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 WebSocket TTS 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 non riesce, OpenClaw riprova con MP3.

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

# Riferimento dei campi

# Strumento dell'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 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 visualizzano in modo coerente le didascalie sulle note vocali.

Lo strumento accetta i campi facoltativi channel e timeoutMs; timeoutMs è un timeout di richiesta del provider per chiamata in millisecondi.

# RPC Gateway

# Link dei servizi

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

# Correlati

• Panoramica dei media
• Generazione di musica
• Generazione di video
• Comandi slash
• Plugin per chiamate vocali