Synthèse vocale

OpenClaw convertit les réponses sortantes en audio via 14 fournisseurs de synthèse vocale : messages vocaux natifs sur Feishu, Matrix, Telegram et WhatsApp ; pièces jointes audio partout ailleurs ; et flux PCM/Ulaw pour la téléphonie et Talk.

La synthèse vocale constitue la partie de sortie vocale du mode stt-tts de Talk (talk.speak appelle ce même chemin de synthèse). Les sessions Talk realtime natives du fournisseur synthétisent la parole au sein du fournisseur temps réel ; les sessions transcription ne synthétisent jamais 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 de solutions de repli. Le résumé automatique utilise summaryModel (ou agents.defaults.model.primary) ; ce fournisseur doit donc également être authentifié si vous laissez les résumés activés.

Configuration

La configuration de la synthèse vocale se trouve sous messages.tts dans ~/.openclaw/openclaw.json. Choisissez un préréglage et adaptez le bloc du fournisseur. Les champs speakerVoice/speakerVoiceId présentés ci-dessous sont canoniques ; les noms de champs propres à chaque fournisseur, voice/voiceId/ voiceName, continuent de fonctionner comme anciens alias.

{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",      // Invites de style facultatives en langage naturel :      // audioProfile: "Parlez d’un ton calme, comme un animateur de podcast.",      // 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 TTS automatique différent. Le bloc de l’agent est fusionné en profondeur avec messages.tts, afin que les identifiants du fournisseur puissent 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 définir une persona par agent, configurez agents.list[].tts.persona avec la configuration du fournisseur : elle remplace la valeur globale de messages.tts.persona pour cet agent uniquement.

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 celui-ci 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 [[tts:...]] intégrées lorsque les remplacements par le modèle sont activés

Les remplacements de canal et de compte utilisent la même structure que messages.tts et sont fusionnés en profondeur avec 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 du locuteur, 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: { speakerVoice: "shimmer" },            },          },        },      },    },  },}

Personas

Une persona est une identité vocale stable qui peut être appliquée de manière déterministe à tous les fournisseurs. Elle peut privilégier un fournisseur, définir une intention d’invite indépendante du fournisseur et contenir des liaisons propres à chaque fournisseur 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: "Narrateur",          provider: "elevenlabs",          providers: {            elevenlabs: {              speakerVoiceId: "EXAVITQu4vr4xnSDxMaL",              modelId: "eleven_multilingual_v2",            },          },        },      },    },  },}

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

{  messages: {    tts: {      auto: "always",      persona: "alfred",      personas: {        alfred: {          label: "Alfred",          description: "Narrateur majordome britannique, pince-sans-rire et chaleureux.",          provider: "google",          fallbackPolicy: "preserve-persona",          prompt: {            profile: "Un brillant majordome britannique. Pince-sans-rire, spirituel, chaleureux, charmant, expressif sur le plan émotionnel, jamais générique.",            scene: "Un bureau calme tard dans la nuit. Narration en prise de son rapprochée pour un opérateur de confiance.",            sampleContext: "Le locuteur répond à une demande technique privée avec une assurance concise et une chaleur teintée d’humour pince-sans-rire.",            style: "Raffiné, sobre, légèrement amusé.",            accent: "Anglais britannique.",            pacing: "Mesuré, avec de courtes pauses dramatiques.",            constraints: ["Ne pas lire les valeurs de configuration à voix haute.", "Ne pas expliquer la 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 manière 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 privilégie les valeurs 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 dans le 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 par des directives TTS émises par le modèle

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 ne possède aucune liaison pour le fournisseur tenté :

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

La sélection du fournisseur d’une session Talk est limitée à la session. Un client Talk doit choisir les identifiants de fournisseur, de modèle, de voix et les paramètres régionaux dans talk.catalog, puis les transmettre par l’intermédiaire de la session Talk ou de la requête de transfert. L’ouverture d’une session vocale ne doit pas modifier messages.tts ni les valeurs globales par défaut 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 doivent apparaître uniquement dans l’audio :

Voici. [[tts:speakerVoiceId=pMsXgVXv3BLzUgSXRplE model=eleven_v3 speed=1.1]][[tts:text]](rit) Lisez encore une fois la chanson.[[/tts:text]]

Lorsque messages.tts.auto vaut "tagged", les directives sont obligatoires pour déclencher l’audio. La diffusion des blocs en streaming retire les directives du texte visible avant que le canal ne le reçoive, 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 (identifiant 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 MiniMax entière, de −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 par le modèle :

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

Autoriser le changement de fournisseur tout en gardant les autres paramètres configurables :

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

Commandes slash

Commande unique /tts. Sur Discord, OpenClaw enregistre également /voice, car /tts est une commande intégrée de Discord — la commande textuelle /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>

Remarques sur le comportement :

• /tts on écrit la préférence TTS locale avec la valeur always ; /tts off lui attribue la valeur off.
• /tts chat on|off|default écrit un remplacement TTS automatique limité à la session pour la discussion actuelle.
• /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 actuelle et l’envoie une fois sous forme audio. Seul un hachage de cette réponse est stocké dans l’entrée de session afin d’empêcher les envois vocaux en double.
• /tts audio génère une réponse audio ponctuelle (sans activer le TTS).
• /tts limit <chars> accepte 100–4096 (4096 est la limite maximale de légende/message de Telegram) ; les valeurs hors de cette plage sont rejetées.
• limit et summary sont stockés dans les préférences locales, et non dans la configuration principale.
• /tts status inclut les diagnostics de repli de la dernière tentative — Fallback: <primary> -> <used>, Attempts: ... et les détails de chaque tentative (provider:outcome(reasonCode) latency).
• /status affiche le mode TTS actif ainsi que le fournisseur, le modèle et la voix configurés, et les métadonnées assainies du point de terminaison personnalisé lorsque le 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 provenant de messages.tts et du bloc agents.list[].tts actif pour cet hôte.

Formats de sortie

La diffusion vocale TTS dépend des capacités du canal. Les plugins de canal indiquent si la TTS de type message vocal doit demander aux fournisseurs une cible native voice-note ou conserver la synthèse audio-file normale, et si le canal transcode la sortie non native avant l’envoi.

Remarques par fournisseur :

• Transcodage Feishu / WhatsApp : lorsqu’une réponse sous forme de message vocal arrive au format MP3/WebM/WAV/M4A ou sous la forme d’un autre fichier probablement audio, le plugin de canal la transcode en Ogg/Opus 48 kHz avec ffmpeg (libopus, 64 kbps) avant d’envoyer le message vocal natif. WhatsApp envoie le résultat au moyen de la charge utile audio de Baileys avec ptt: true et audio/ogg; codecs=opus. En cas d’échec du transcodage : Feishu intercepte l’erreur et envoie à la place le fichier d’origine en tant que simple pièce jointe ; WhatsApp ne dispose d’aucun mécanisme de repli, l’envoi lui-même échoue donc au lieu de publier une charge utile PTT incompatible.
• MiniMax : MP3 (modèle speech-2.8-hd, fréquence d’échantillonnage de 32 kHz) pour les pièces jointes audio normales ; transcodé en Opus 48 kHz avec ffmpeg pour les cibles de message vocal annoncées par le canal.
• Xiaomi MiMo : MP3 par défaut, ou WAV lorsque configuré ; transcodé en Opus 48 kHz avec ffmpeg pour les cibles de message vocal annoncées par le canal.
• CLI locale : utilise le outputFormat configuré. Les cibles de message vocal sont converties en Ogg/Opus et la sortie téléphonique est convertie en PCM mono brut 16 kHz avec ffmpeg.
• Google Gemini : renvoie du PCM brut 24 kHz. OpenClaw l’encapsule au format WAV pour les pièces jointes audio, le transcode en Opus 48 kHz pour les cibles de message vocal et renvoie directement le PCM pour Talk/la téléphonie.
• Gradium : WAV pour les pièces jointes audio, Opus pour les cibles de message vocal 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 message vocal 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. Utilise le point de terminaison REST TTS 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 vocal Opus natif n’est pas pris en charge.
• Microsoft : utilise microsoft.outputFormat (valeur par défaut : audio-24khz-48kbitrate-mono-mp3).
  • Le transport intégré accepte un outputFormat, mais tous les formats ne sont pas disponibles auprès du service.
  • Les valeurs du format de sortie suivent les formats de sortie Microsoft Speech (notamment Ogg/WebM Opus).
  • La méthode sendVoice de Telegram 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.
  • Lorsqu’aucun remplacement explicite de la voix n’est défini et que la voix anglaise par défaut est utilisée, OpenClaw bascule automatiquement vers une voix neuronale chinoise (zh-CN-XiaoxiaoNeural, paramètres régionaux zh-CN) si le texte de la réponse est majoritairement en caractères CJK.

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

Comportement TTS automatique

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

• Ignore la TTS si la réponse contient déjà un média structuré.
• 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 de agents.defaults.model.primary).
• Joint l’audio généré à la réponse.
• En mode: "final", envoie toujours une TTS uniquement audio 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 du canal que les pièces jointes de réponse normales.

Si la réponse dépasse maxLength, OpenClaw n’ignore jamais complètement l’audio :

• Résumé activé (par défaut) et un modèle de résumé est disponible : résume le texte à environ maxLength caractères, puis synthétise le résumé.
• Résumé désactivé, échec du résumé ou aucune clé API disponible pour le modèle de résumé : tronque le texte à maxLength caractères et synthétise le texte tronqué.

Réponse -> TTS activée ?  non -> envoyer le texte  oui -> contient un média / est courte ?          oui -> envoyer le texte          non -> longueur > limite ?                   non -> TTS -> joindre l’audio                   oui -> résumé activé et disponible ?                            non -> tronquer -> TTS -> joindre l’audio                            oui -> résumer -> TTS -> joindre l’audio

Référence des champs

Outil de l’agent

L’outil tts convertit le 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 envoyé sous forme de message vocal plutôt que de pièce jointe. Feishu et WhatsApp peuvent transcoder une sortie TTS autre qu’Opus sur ce parcours lorsque ffmpeg est disponible.

WhatsApp envoie l’audio via Baileys sous forme de 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 des notes vocales.

L’outil accepte les champs facultatifs channel et timeoutMs ; timeoutMs est un délai d’expiration par appel pour la requête au fournisseur, en millisecondes. Les valeurs par appel remplacent messages.tts.timeoutMs ; les délais d’expiration TTS configurés remplacent toute valeur par défaut du fournisseur définie par un Plugin.

RPC du Gateway

Liens vers les services

• 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

Pages connexes

• Vue d’ensemble des médias
• Génération de musique
• Génération de vidéos
• Commandes slash
• Plugin d’appel vocal