Synthèse vocale

OpenClaw peut convertir les réponses sortantes en audio avec 14 fournisseurs de synthèse vocale et livrer des messages vocaux natifs sur Feishu, Matrix, Telegram et WhatsApp, des pièces jointes audio partout ailleurs, ainsi que des flux PCM/Ulaw pour la téléphonie et Talk.

Le TTS est la moitié de sortie vocale du mode stt-tts de Talk. Les sessions Talk realtime natives du fournisseur synthétisent la parole dans le fournisseur temps réel au lieu d’appeler ce chemin TTS, tandis que les sessions transcription ne synthétisent pas de réponse vocale de l’assistant.

Démarrage rapide

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

Fournisseurs pris en charge

Si plusieurs fournisseurs sont configurés, celui qui est sélectionné est utilisé en premier et les autres servent d’options de repli. Le résumé automatique utilise summaryModel (ou agents.defaults.model.primary) ; ce fournisseur doit donc également être authentifié si vous conservez les résumés activés.

Configuration

La configuration TTS se trouve sous messages.tts dans ~/.openclaw/openclaw.json. Choisissez un préréglage et adaptez le bloc du fournisseur :

{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",    },  },},},}

Remplacements de voix par agent

Utilisez agents.list[].tts lorsqu’un agent doit parler avec un autre fournisseur, une autre voix, un autre modèle, une autre persona ou un autre mode Auto-TTS. Le bloc de l’agent fusionne en profondeur avec messages.tts, ce qui permet de conserver les identifiants du fournisseur dans la configuration globale du fournisseur :

{  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" },          },        },      },    ],  },}

Pour épingler une persona par agent, définissez agents.list[].tts.persona avec la configuration du fournisseur — cela remplace le messages.tts.persona global uniquement pour cet agent.

Ordre de priorité pour les réponses automatiques, /tts audio, /tts status et l’outil d’agent tts :

1. messages.tts
2. agents.list[].tts actif
3. remplacement de canal, lorsque le canal prend en charge channels.<channel>.tts
4. remplacement de compte, lorsque le canal transmet channels.<channel>.accounts.<id>.tts
5. préférences locales /tts pour cet hôte
6. directives intégrées [[tts:...]] lorsque les remplacements pilotés par le modèle sont activés

Les remplacements de canal et de compte utilisent la même forme que messages.tts et fusionnent en profondeur par-dessus les couches précédentes, afin que les identifiants partagés du fournisseur puissent rester dans messages.tts tandis qu’un canal ou un compte de bot modifie uniquement la voix, le modèle, la persona ou le mode automatique :

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

Personas

Une persona est une identité vocale stable qui peut être appliquée de façon déterministe entre fournisseurs. Elle peut privilégier un fournisseur, définir une intention d’invite indépendante du fournisseur, et transporter des liaisons propres aux fournisseurs pour les voix, les modèles, les modèles d’invite, les graines et les paramètres vocaux.

Persona minimale

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

Persona complète (invite indépendante du fournisseur)

{  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,              },            },          },        },      },    },  },}

Résolution de la persona

La persona active est sélectionnée de façon déterministe :

1. Préférence locale /tts persona <id>, si elle est définie.
2. messages.tts.persona, si elle est définie.
3. Aucune persona.

La sélection du fournisseur applique d’abord les réglages explicites :

1. Remplacements directs (CLI, Gateway, Talk, directives TTS autorisées).
2. Préférence locale /tts provider <id>.
3. provider de la persona active.
4. messages.tts.provider.
5. Sélection automatique du registre.

Pour chaque tentative de fournisseur, OpenClaw fusionne les configurations dans cet ordre :

1. messages.tts.providers.<id>
2. messages.tts.personas.<persona>.providers.<id>
3. Remplacements de requête approuvés
4. Remplacements de directives TTS émises par le modèle et autorisées

Utilisation des invites de persona par les fournisseurs

Les champs d’invite de persona (profile, scene, sampleContext, style, accent, pacing, constraints) sont indépendants du fournisseur. Chaque fournisseur décide comment les utiliser :

Politique de repli

fallbackPolicy contrôle le comportement lorsqu’une persona n’a aucune liaison pour le fournisseur tenté :

L’ensemble de la requête TTS échoue uniquement lorsque chaque fournisseur tenté est ignoré ou échoue.

La sélection de fournisseur pour une session Talk est limitée à la session. Un client Talk doit choisir les identifiants de fournisseur, de modèle, de voix et les locales depuis talk.catalog et les transmettre via la session Talk ou la requête de transfert. L’ouverture d’une session vocale ne doit pas modifier messages.tts ni les valeurs par défaut globales des fournisseurs Talk.

Directives pilotées par le modèle

Par défaut, l’assistant peut émettre des directives [[tts:...]] pour remplacer la voix, le modèle ou la vitesse pour une seule réponse, ainsi qu’un bloc facultatif [[tts:text]]...[[/tts:text]] pour les indications expressives qui doivent apparaître uniquement dans l’audio :

Here you go. [[tts:voiceId=pMsXgVXv3BLzUgSXRplE model=eleven_v3 speed=1.1]][[tts:text]](laughs) Read the song once more.[[/tts:text]]

Lorsque messages.tts.auto vaut "tagged", les directives sont requises pour déclencher l’audio. La diffusion de blocs en streaming retire les directives du texte visible avant que le canal ne les voie, même lorsqu’elles sont réparties sur des blocs adjacents.

provider=... est ignoré sauf si modelOverrides.allowProvider: true. Lorsqu’une réponse déclare provider=..., les autres clés de cette directive sont analysées uniquement par ce fournisseur ; les clés non prises en charge sont retirées et signalées comme avertissements de directive TTS.

Clés de directive disponibles :

• provider (identifiant de fournisseur enregistré ; nécessite allowProvider: true)
• voice / voiceName / voice_name / google_voice / voiceId
• model / google_model
• stability, similarityBoost, style, speed, useSpeakerBoost
• vol / volume (volume MiniMax, 0–10)
• pitch (hauteur entière MiniMax, −12 à 12 ; les valeurs fractionnaires sont tronquées)
• emotion (balise d’émotion Volcengine)
• applyTextNormalization (auto|on|off)
• languageCode (ISO 639-1)
• seed

Désactiver entièrement les remplacements de modèle :

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

Autoriser le changement de fournisseur tout en gardant les autres réglages configurables :

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

Commandes slash

Commande unique /tts. Sur Discord, OpenClaw enregistre aussi /voice, car /tts est une commande Discord intégrée — le texte /tts ... fonctionne toujours.

/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>

Notes de comportement :

• /tts on écrit la préférence TTS locale sur always ; /tts off l’écrit sur off.
• /tts chat on|off|default écrit un remplacement auto-TTS limité à la session pour le chat courant.
• /tts persona <id> écrit la préférence locale de persona ; /tts persona off l’efface.
• /tts latest lit la dernière réponse de l’assistant dans la transcription de la session courante et l’envoie une fois en audio. Elle stocke uniquement un hachage de cette réponse dans l’entrée de session afin de supprimer les envois vocaux en double.
• /tts audio génère une réponse audio ponctuelle (n’active pas TTS).
• limit et summary sont stockés dans les préférences locales, pas dans la configuration principale.
• /tts status inclut les diagnostics de repli pour la dernière tentative — Fallback: <primary> -> <used>, Attempts: ..., et les détails par tentative (provider:outcome(reasonCode) latency).
• /status affiche le mode TTS actif ainsi que le fournisseur, le modèle, la voix et les métadonnées de point de terminaison personnalisé nettoyées configurés lorsque TTS est activé.

Préférences par utilisateur

Les commandes slash écrivent les remplacements locaux dans prefsPath. La valeur par défaut est ~/.openclaw/settings/tts.json ; remplacez-la avec la variable d’environnement OPENCLAW_TTS_PREFS ou messages.tts.prefsPath.

Ceux-ci remplacent la configuration effective issue de messages.tts plus le bloc agents.list[].tts actif pour cet hôte.

Formats de sortie (fixes)

La diffusion vocale TTS est pilotée par les capacités du canal. Les plugins de canal annoncent si le TTS de style vocal doit demander aux fournisseurs une cible native voice-note ou conserver la synthèse audio-file normale et uniquement marquer la sortie compatible pour la diffusion vocale.

• Canaux compatibles avec les notes vocales : les réponses sous forme de note vocale privilégient Opus (opus_48000_64 depuis ElevenLabs, opus depuis OpenAI).
  • 48 kHz / 64 kbps constitue un bon compromis pour les messages vocaux.
• Feishu / WhatsApp : lorsqu’une réponse sous forme de note vocale est produite en MP3/WebM/WAV/M4A ou dans un autre fichier probablement audio, le plugin de canal la transcode en Ogg/Opus 48 kHz avec ffmpeg avant d’envoyer le message vocal natif. WhatsApp envoie le résultat via la charge utile Baileys audio avec ptt: true et audio/ogg; codecs=opus. Si la conversion échoue, Feishu reçoit le fichier original en pièce jointe ; l’envoi WhatsApp échoue au lieu de publier une charge utile PTT incompatible.
• Autres canaux : MP3 (mp3_44100_128 depuis ElevenLabs, mp3 depuis OpenAI).
  • 44,1 kHz / 128 kbps est l’équilibre par défaut pour la clarté de la parole.
• MiniMax : MP3 (modèle speech-2.8-hd, fréquence d’échantillonnage de 32 kHz) pour les pièces jointes audio normales. Pour les cibles de notes vocales annoncées par le canal, OpenClaw transcode le MP3 MiniMax en Opus 48 kHz avec ffmpeg avant la livraison lorsque le canal annonce le transcodage.
• Xiaomi MiMo : MP3 par défaut, ou WAV lorsqu’il est configuré. Pour les cibles de notes vocales annoncées par le canal, OpenClaw transcode la sortie Xiaomi en Opus 48 kHz avec ffmpeg avant la livraison lorsque le canal annonce le transcodage.
• CLI locale : utilise le outputFormat configuré. Les cibles de notes vocales sont converties en Ogg/Opus et la sortie téléphonique est convertie en PCM mono brut 16 kHz avec ffmpeg.
• Google Gemini : le TTS de l’API Gemini renvoie du PCM brut 24 kHz. OpenClaw l’encapsule en WAV pour les pièces jointes audio, le transcode en Opus 48 kHz pour les cibles de notes vocales, et renvoie directement le PCM pour Talk/la téléphonie.
• Gradium : WAV pour les pièces jointes audio, Opus pour les cibles de notes vocales, et ulaw_8000 à 8 kHz pour la téléphonie.
• Inworld : MP3 pour les pièces jointes audio normales, OGG_OPUS natif pour les cibles de notes vocales, et PCM brut à 22050 Hz pour Talk/la téléphonie.
• xAI : MP3 par défaut ; responseFormat peut être mp3, wav, pcm, mulaw ou alaw. OpenClaw utilise le point de terminaison TTS REST par lots de xAI et renvoie une pièce jointe audio complète ; le WebSocket TTS en streaming de xAI n’est pas utilisé par ce chemin de fournisseur. Le format natif Opus pour les notes vocales n’est pas pris en charge par ce chemin.
• Microsoft : utilise microsoft.outputFormat (par défaut audio-24khz-48kbitrate-mono-mp3).
  • Le transport groupé accepte un outputFormat, mais tous les formats ne sont pas disponibles depuis le service.
  • Les valeurs de format de sortie suivent les formats de sortie Microsoft Speech (y compris Ogg/WebM Opus).
  • Telegram sendVoice accepte OGG/MP3/M4A ; utilisez OpenAI/ElevenLabs si vous avez besoin de messages vocaux Opus garantis.
  • Si le format de sortie Microsoft configuré échoue, OpenClaw réessaie avec MP3.

Les formats de sortie OpenAI/ElevenLabs sont fixes par canal (voir ci-dessus).

Comportement Auto-TTS

Lorsque messages.tts.auto est activé, OpenClaw :

• Ignore le TTS si la réponse contient déjà un média ou une directive MEDIA:.
• Ignore les réponses très courtes (moins de 10 caractères).
• Résume les réponses longues lorsque les résumés sont activés, à l’aide de summaryModel (ou agents.defaults.model.primary).
• Joint l’audio généré à la réponse.
• En mode: "final", envoie toujours le TTS audio seul pour les réponses finales diffusées une fois le flux de texte terminé ; le média généré passe par la même normalisation des médias du canal que les pièces jointes de réponse normales.

Si la réponse dépasse maxLength et que le résumé est désactivé (ou qu’aucune clé API n’est disponible pour le modèle de résumé), l’audio est ignoré et la réponse textuelle normale est envoyée.

Réponse -> TTS activé ?  non -> envoyer le texte  oui -> contient un média / MEDIA: / court ?          oui -> envoyer le texte          non -> longueur > limite ?                   non -> TTS -> joindre l’audio                   oui -> résumé activé ?                            non -> envoyer le texte                            oui -> résumer -> TTS -> joindre l’audio

Formats de sortie par canal

Notes par fournisseur :

• Transcodage Feishu / WhatsApp : lorsqu’une réponse par note vocale arrive en MP3/WebM/WAV/M4A, le Plugin de canal transcode en Ogg/Opus 48 kHz avec ffmpeg. WhatsApp envoie via Baileys avec ptt: true et audio/ogg; codecs=opus. Si la conversion échoue : Feishu revient à l’ajout du fichier original en pièce jointe ; l’envoi WhatsApp échoue plutôt que de publier une charge utile PTT incompatible.
• MiniMax / Xiaomi MiMo : MP3 par défaut (32 kHz pour MiniMax speech-2.8-hd) ; transcodé en Opus 48 kHz pour les cibles de notes vocales via ffmpeg.
• CLI locale : utilise le outputFormat configuré. Les cibles de notes vocales sont converties en Ogg/Opus et la sortie téléphonie en PCM mono 16 kHz brut.
• Google Gemini : renvoie du PCM 24 kHz brut. OpenClaw l’encapsule en WAV pour les pièces jointes, le transcode en Opus 48 kHz pour les cibles de notes vocales, renvoie directement le PCM pour Talk/la téléphonie.
• Inworld : pièces jointes MP3, note vocale native OGG_OPUS, PCM brut 22050 Hz pour Talk/la téléphonie.
• xAI : MP3 par défaut ; responseFormat peut valoir mp3|wav|pcm|mulaw|alaw. Utilise le point de terminaison REST par lot de xAI — le TTS WebSocket en streaming n’est pas utilisé. Le format natif Opus pour notes vocales n’est pas pris en charge.
• Microsoft : utilise microsoft.outputFormat (par défaut audio-24khz-48kbitrate-mono-mp3). Telegram sendVoice accepte OGG/MP3/M4A ; utilisez OpenAI/ElevenLabs si vous avez besoin de messages vocaux Opus garantis. Si le format Microsoft configuré échoue, OpenClaw réessaie avec MP3.

Les formats de sortie OpenAI et ElevenLabs sont fixes par canal, comme indiqué ci-dessus.

Référence des champs

Outil d’agent

L’outil tts convertit le texte en parole et retourne une pièce jointe audio pour la livraison de la réponse. Sur Feishu, Matrix, Telegram et WhatsApp, l’audio est livré comme message vocal plutôt que comme pièce jointe de fichier. Feishu et WhatsApp peuvent transcoder la sortie TTS non Opus sur ce chemin lorsque ffmpeg est disponible.

WhatsApp envoie l’audio via Baileys comme note vocale PTT (audio avec ptt: true) et envoie le texte visible séparément de l’audio PTT, car les clients n’affichent pas toujours les légendes sur les notes vocales.

L’outil accepte les champs facultatifs channel et timeoutMs ; timeoutMs est un délai d’expiration de requête fournisseur par appel, en millisecondes.

RPC Gateway

Liens de service

• Guide de synthèse vocale OpenAI
• Référence de l’API audio OpenAI
• Synthèse vocale REST Azure Speech
• Fournisseur Azure Speech
• Synthèse vocale ElevenLabs
• Authentification ElevenLabs
• Gradium
• API TTS Inworld
• API MiniMax T2A v2
• API HTTP TTS Volcengine
• Synthèse vocale Xiaomi MiMo
• node-edge-tts
• Formats de sortie Microsoft Speech
• Synthèse vocale xAI

Connexe

• Vue d’ensemble des médias
• Génération musicale
• Génération vidéo
• Commandes slash
• Plugin d’appel vocal