Synthèse vocale

OpenClaw convertit les réponses sortantes en audio avec 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 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 en 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 secours. 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 voice/voiceId/ voiceName propres à chaque fournisseur continuent de fonctionner comme alias hérités.

{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 facultatives de style en langage naturel :      // audioProfile: "Parlez d’un ton calme, comme lors de l’animation d’un 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 user de synthèse vocale 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é récursivement par-dessus messages.tts, de sorte que les identifiants du fournisseur peuvent 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 : cette valeur remplace la valeur globale 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 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 [[tts:...]] intégrées lorsque les remplacements pilotés 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 récursivement par-dessus les couches précédentes. Les identifiants partagés du fournisseur peuvent ainsi rester dans messages.tts, tandis qu’un canal ou un compte de bot ne modifie que 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 entre les fournisseurs. Elle peut privilégier un fournisseur, définir une intention d’invite indépendante du fournisseur et comporter 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 silencieux tard dans la nuit. Narration de proximité au microphone 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 lisez pas les valeurs de configuration à voix haute.", "N’expliquez pas 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 donne la priorité aux 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 par 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 fiables
4. Remplacements autorisés 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 de leur utilisation :

Politique de repli

fallbackPolicy contrôle le comportement lorsqu’une persona ne possède aucune liaison pour le fournisseur tenté :

La requête TTS complète n’échoue que 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 et de voix ainsi que les paramètres régionaux dans talk.catalog, puis les transmettre par l’intermédiaire de la requête de session ou de transfert Talk. 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 :

Voilà. [[tts:speakerVoiceId=pMsXgVXv3BLzUgSXRplE model=eleven_v3 speed=1.1]][[tts:text]](rit) Lisez la chanson une fois de plus.[[/tts:text]]

Lorsque messages.tts.auto vaut "tagged", les directives sont obligatoires pour déclencher l’audio. La diffusion des blocs en continu supprime les directives du texte visible avant que le canal ne les 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 (anciens alias : 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 conservant les autres paramètres configurables :

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

Commandes à barre oblique

Commande unique /tts. Sur Discord, OpenClaw enregistre également /voice, car /tts est une commande Discord intégrée ; 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 dans always ; /tts off l’écrit dans 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’éviter les envois vocaux en double.
• /tts audio génère une réponse audio ponctuelle (n’active pas le TTS).
• /tts limit <chars> accepte 100–4096 (4096 correspond au maximum de légende ou de message 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, la voix et les métadonnées nettoyées du point de terminaison personnalisé configurés lorsque le TTS est activé.

Préférences par utilisateur

Les commandes à barre oblique é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, ainsi que le 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 le TTS de type vocal doit demander aux fournisseurs une cible voice-note native 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 dans 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 Baileys audio 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 comme simple pièce jointe ; WhatsApp ne dispose d’aucune solution 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 selon la configuration ; 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 ; la synthèse de fichiers audio peut utiliser mp3, wav, pcm, mulaw ou alaw pour les sorties mises en mémoire tampon comme pour les sorties en streaming. Les cibles de message vocal utilisent le MP3 pour le streaming et comme solution de repli mise en mémoire tampon, car les sorties pcm, mulaw et alaw de xAI sont des données audio brutes sans en-tête. La synthèse mise en mémoire tampon utilise le point de terminaison REST par lot /v1/tts de xAI ; textToSpeechStream utilise le wss://api.x.ai/v1/tts natif. Il ne s’agit pas du contrat vocal en temps réel. Le format vocal Opus natif n’est pas pris en charge.
• Microsoft : utilise microsoft.outputFormat (audio-24khz-48kbitrate-mono-mp3 par défaut).
  • 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 de Microsoft Speech (notamment Ogg/WebM Opus).
  • Le 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 en MP3.
  • Lorsqu’aucun remplacement vocal explicite 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 d’OpenAI et d’ElevenLabs sont fixes pour chaque canal, comme indiqué ci-dessus.

Comportement du TTS automatique

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

• Ignore la synthèse vocale 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, à l’aide de summaryModel (ou agents.defaults.model.primary).
• Joint l’audio généré à la réponse.
• Dans mode: "final", envoie toujours une synthèse vocale uniquement audio pour les réponses finales diffusées en continu une fois la diffusion du texte terminée ; le média généré passe par la même normalisation des médias du canal que les pièces jointes habituelles des réponses.

Si la réponse dépasse maxLength, OpenClaw n’omet 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 -> Synthèse vocale activée ?  non -> envoyer le texte  oui -> contient un média / est courte ?           oui -> envoyer le texte           non -> longueur > limite ?                    non -> synthèse vocale -> joindre l’audio                    oui -> résumé activé et disponible ?                             non -> tronquer -> synthèse vocale -> joindre l’audio                             oui -> résumer -> synthèse vocale -> joindre l’audio

Référence des champs