Synthèse vocale

OpenClaw peut convertir les réponses sortantes en audio auprès de 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 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 repli. 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 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 fournisseur, une voix, un modèle, une persona ou un mode Auto-TTS différents. Le bloc de l'agent fusionne en profondeur par-dessus messages.tts, les identifiants du fournisseur peuvent donc rester dans la configuration fournisseur globale :

{
  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 fournisseur : elle remplace messages.tts.persona global 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. substitution de canal, lorsque le canal prend en charge channels.<channel>.tts
4. substitution de compte, lorsque le canal transmet channels.<channel>.accounts.<id>.tts
5. préférences /tts locales pour cet hôte
6. directives [[tts:...]] inline lorsque les substitutions du modèle sont activées

Les substitutions 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 pendant qu’un canal ou un compte de bot ne change que la voix, le modèle, le 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: { voice: "shimmer" },
            },
          },
        },
      },
    },
  },
}

# Personas

Un persona est une identité parlée stable qui peut être appliquée de façon déterministe entre fournisseurs. Il peut privilégier un fournisseur, définir une intention de prompt neutre vis-à-vis des fournisseurs, et porter des liaisons propres aux fournisseurs pour les voix, les modèles, les modèles de prompt, les graines et les paramètres de voix.

# Persona minimal

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

# Persona complet (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",
              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 du persona

Le persona actif est sélectionné de façon déterministe :

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

La sélection du fournisseur procède en donnant priorité à l’explicite :

1. Substitutions directes (CLI, Gateway, Talk, directives TTS autorisées).
2. Préférence locale /tts provider <id>.
3. provider du persona actif.
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. Substitutions de requête approuvées
4. Substitutions de directive TTS émises par le modèle et autorisées

# 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 des fournisseurs. Chaque fournisseur décide comment les utiliser :

# Politique de repli

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

Toute la requête TTS échoue uniquement lorsque chaque fournisseur tenté est ignoré ou échoue.

La sélection du fournisseur de 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 depuis talk.catalog, puis 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 substituer la voix, le modèle ou la vitesse pour une seule réponse, ainsi qu’un bloc optionnel [[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 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 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 substitutions 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, car /tts est une commande intégrée de Discord — 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 une substitution auto-TTS limitée à la session pour le chat actuel.
• /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 depuis la transcription de la session actuelle et l’envoie une seule fois en audio. Il 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 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 d’endpoint personnalisé nettoyées lorsque TTS est activé.

# Préférences par utilisateur

Les commandes slash écrivent les substitutions locales dans prefsPath. La valeur par défaut est ~/.openclaw/settings/tts.json ; substituez-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 type 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 une livraison vocale.

• Canaux compatibles avec les notes vocales: les réponses en note vocale privilégient Opus (opus_48000_64 depuis ElevenLabs, opus depuis OpenAI).
  • 48 kHz / 64 kbps offre un bon compromis pour les messages vocaux.
• Feishu / WhatsApp: lorsqu’une réponse en 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 d’origine en pièce jointe ; l’envoi WhatsApp échoue au lieu de publier une charge utile PTT incompatible.
• BlueBubbles: conserve la synthèse du fournisseur sur le chemin normal des fichiers audio ; les sorties MP3 et CAF sont marquées pour l’envoi de mémos vocaux iMessage.
• 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 la prise en charge du 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 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 téléphonique est convertie en PCM mono brut 16 kHz avec ffmpeg.
• Google Gemini: la synthèse vocale 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/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 inclus accepte un outputFormat, mais tous les formats ne sont pas disponibles auprès du 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 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, en utilisant summaryModel (ou agents.defaults.model.primary).
• Joint l’audio généré à la réponse.
• En mode: "final", envoie toujours le TTS audio uniquement 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 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.

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

# 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 à joindre le fichier original ; 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 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éphonie en PCM mono brut 16 kHz.
• Google Gemini : renvoie du PCM brut 24 kHz. OpenClaw l’encapsule en WAV pour les pièces jointes, le transcode en Opus 48 kHz pour les cibles de note vocale, 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 être mp3|wav|pcm|mulaw|alaw. Utilise le point de terminaison REST par lots de xAI — le TTS WebSocket en streaming n’est pas utilisé. Le format natif Opus de 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 en 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 renvoie une pièce jointe audio pour la remise de la réponse. Sur Feishu, Matrix, Telegram et WhatsApp, l’audio est remis 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