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.

TTS est la moitié sortie vocale du mode stt-tts de Talk. Les sessions Talk realtime natives du fournisseur synthétisent la parole dans le fournisseur en 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 sélectionné est utilisé en premier et les autres servent d’options de secours. Le résumé automatique utilise summaryModel (ou agents.defaults.model.primary), ce fournisseur doit donc aussi être authentifié si vous gardez 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",      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",    },  },},},}

Pour Xiaomi mimo-v2.5-tts-voicedesign, omettez speakerVoice et définissez style sur l’invite de conception vocale. OpenClaw envoie cette invite comme message TTS user et n’envoie pas audio.voice pour le modèle voicedesign.

Remplacements de voix par agent

Utilisez agents.list[].tts lorsqu’un agent doit parler avec un fournisseur, une voix, un modèle, une persona ou un mode auto-TTS différent. Le bloc de l’agent est fusionné en profondeur au-dessus de messages.tts, ce qui permet aux identifiants du fournisseur de rester 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: { speakerVoiceId: "EXAVITQu4vr4xnSDxMaL" },          },        },      },    ],  },}

Pour épingler une persona par agent, définissez agents.list[].tts.persona avec la configuration du fournisseur — elle remplace la messages.tts.persona globale 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 du canal, lorsque le canal prend en charge channels.<channel>.tts
4. remplacement du compte, lorsque le canal transmet channels.<channel>.accounts.<id>.tts
5. préférences /tts locales pour cet hôte
6. directives inline [[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 se fusionnent en profondeur au-dessus des couches précédentes, ce qui permet aux identifiants de fournisseur partagés de rester dans messages.tts tandis qu’un canal ou un compte de bot modifie uniquement la voix du locuteur, le modèle, la persona ou le mode auto:

{  messages: {    tts: {      provider: "openai",      providers: {        openai: { apiKey: "${OPENAI_API_KEY}", model: "gpt-4o-mini-tts" },      },    },  },  channels: {    feishu: {      accounts: {        english: {          tts: {            providers: {              openai: { speakerVoice: "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 de prompt neutre vis-à-vis des fournisseurs et transporter des liaisons propres aux fournisseurs pour les voix, modèles, modèles de prompt, seeds et réglages de voix.

Persona minimale

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

Persona complète (prompt neutre vis-à-vis 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",              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,              },            },          },        },      },    },  },}

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 suit d’abord les éléments 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 autorisés issus de directives TTS émises par le modèle

Comment les fournisseurs utilisent les prompts de persona

Les champs de prompt de persona (profile, scene, sampleContext, style, accent, pacing, constraints) sont neutres vis-à-vis du fournisseur. Chaque fournisseur décide comment les utiliser:

Politique de fallback

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

L’ensemble de la requête TTS n’échoue que lorsque tous les fournisseurs tentés sont ignorés ou échouent.

La sélection du fournisseur de session Talk est limitée à la session. Un client Talk doit choisir les ID de fournisseur, ID de modèle, ID de voix et paramètres régionaux 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 du fournisseur 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 ne doivent apparaître que dans l’audio:

Here you go. [[tts:speakerVoiceId=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 livraison de blocs en streaming supprime les directives du texte visible avant que le canal ne les voie, même lorsqu’elles sont réparties entre 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 supprimées et signalées comme avertissements de directive TTS.

Clés de directive disponibles:

• provider (ID de fournisseur enregistré; nécessite allowProvider: true)
• speakerVoice / speakerVoiceId (alias hérités: 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 du 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 parce que /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 la conversation actuelle.
• /tts persona <id> écrit la préférence de persona locale; /tts persona off l’efface.
• /tts latest lit la dernière réponse de l’assistant dans la transcription de la session actuelle et l’envoie une fois sous forme d’audio. Elle ne stocke qu’un hash de cette réponse sur 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 fallback pour la dernière tentative — Fallback: <primary> -> <used>, Attempts: ..., et le détail par tentative (provider:outcome(reasonCode) latency).
• /status affiche le mode TTS actif ainsi que le fournisseur, le modèle, la voix configurés et les métadonnées de point de terminaison personnalisé assainies 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.

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

Formats de sortie (fixes)

La livraison 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 une synthèse audio-file normale et seulement marquer la sortie compatible pour la livraison 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 kbit/s offre 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 format 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 d’origine en pièce jointe ; l’envoi WhatsApp échoue plutôt que de publier une charge utile PTT incompatible.
• Autres canaux: MP3 (mp3_44100_128 depuis ElevenLabs, mp3 depuis OpenAI).
  • 44,1 kHz / 128 kbit/s 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 la prise en charge du transcodage.
• Xiaomi MiMo: MP3 par défaut, ou WAV lorsque 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 la prise en charge du transcodage.
• CLI locale: utilise le outputFormat configuré. Les cibles de notes vocales sont converties en Ogg/Opus, et la sortie de téléphonie est convertie en PCM mono brut 16 kHz avec ffmpeg.
• Google Gemini: la TTS de l’API Gemini renvoie du PCM brut 24 kHz. OpenClaw l’encapsule en WAV pour les pièces jointes audio, la transcode en Opus 48 kHz pour les cibles de notes vocales, et renvoie directement le PCM pour Talk/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/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 inclus 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 la TTS si la réponse contient déjà des médias structurés.
• 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, en utilisant summaryModel (ou agents.defaults.model.primary).
• Joint l’audio généré à la réponse.
• En mode: "final", envoie toujours une TTS audio seule pour les réponses finales diffusées en streaming après la fin du flux de texte ; le média généré passe par la même normalisation des médias de 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’il n’y a pas de clé API pour le modèle de résumé), l’audio est ignoré et la réponse textuelle normale est envoyée.

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

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 la 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 à la pièce jointe du fichier d’origine ; l’envoi WhatsApp échoue au lieu 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 note vocale via ffmpeg.
• CLI locale : utilise le outputFormat configuré. Les cibles de note vocale sont converties en Ogg/Opus et la sortie téléphonique 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 note vocale, et renvoie directement le PCM pour Discussion/téléphonie.
• Inworld : pièces jointes MP3, note vocale native OGG_OPUS, PCM brut 22050 Hz pour Discussion/téléphonie.
• xAI : MP3 par défaut ; responseFormat peut être 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 note vocale 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 du texte en parole et renvoie 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 systématiquement 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. Les valeurs par appel remplacent messages.tts.timeoutMs ; les délais d’expiration TTS configurés remplacent toute valeur par défaut de fournisseur définie par un plugin.

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 Inworld TTS
• 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 de musique
• Génération de vidéo
• Commandes slash
• Plugin d’appel vocal