Synthèse vocale

OpenClaw peut convertir les réponses sortantes en audio via 14 fournisseurs de synthèse vocale et envoyer 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.

La TTS est la partie sortie vocale du mode stt-tts de Talk. Les sessions Talk natives du realtime synthétisent la voix à l’intérieur du 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.

Quick start

Choisir un fournisseur
OpenAI et ElevenLabs sont les options hébergées les plus fiables. Microsoft et le Local CLI fonctionnent sans clé d’API. Consultez la matrice des fournisseurs pour la liste complète.
Définir la clé API
Exportez la variable d’environnement pour votre fournisseur (par exemple OPENAI_API_KEY, ELEVENLABS_API_KEY). Microsoft et le CLI local n’ont pas besoin de clé.

Activer dans la configuration

Définissez messages.tts.auto: "always" et messages.tts.provider :

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

Essayer dans le chat
/tts status affiche l’état actuel. /tts audio Hello from OpenClaw envoie une réponse audio unique.

Fournisseurs pris en charge

Fournisseur	Auth	Notes
Azure Speech	`AZURE_SPEECH_KEY` + `AZURE_SPEECH_REGION` (aussi `AZURE_SPEECH_API_KEY`, `SPEECH_KEY`, `SPEECH_REGION`)	Sortie de notes vocales Ogg/Opus natives et téléphonie.
DeepInfra	`DEEPINFRA_API_KEY`	TTS compatible OpenAI. La valeur par défaut est `hexgrad/Kokoro-82M`.
ElevenLabs	`ELEVENLABS_API_KEY` ou `XI_API_KEY`	Clonage vocal, multilingue, déterministe via `seed`; diffusé pour la lecture vocale sur Discord.
Google Gemini	`GEMINI_API_KEY` ou `GOOGLE_API_KEY`	TTS par lots de l’API Gemini; conscient du personnage via `promptTemplate: "audio-profile-v1"`.
Gradium	`GRADIUM_API_KEY`	Sortie de notes vocales et téléphonie.
Inworld	`INWORLD_API_KEY`	API TTS en continu. Note vocale Opus native et téléphonie PCM.
CLI local	aucun	Exécute une commande TTS locale configurée.
Microsoft	aucun	TTS neuronal Edge public via `node-edge-tts`. Best-effort, sans SLA.
MiniMax	`MINIMAX_API_KEY` (ou Plan de jeton : `MINIMAX_OAUTH_TOKEN`, `MINIMAX_CODE_PLAN_KEY`, `MINIMAX_CODING_API_KEY`)	T2A v2 API. La valeur par défaut est `speech-2.8-hd`.
OpenAI	`OPENAI_API_KEY`	Également utilisé pour le résumé automatique; prend en charge le personnage `instructions`.
OpenRouter	`OPENROUTER_API_KEY` (peut réutiliser `models.providers.openrouter.apiKey`)	Modèle par défaut `hexgrad/kokoro-82m`.
Volcengine	`VOLCENGINE_TTS_API_KEY` ou `BYTEPLUS_SEED_SPEECH_API_KEY` (AppID/jeton hérité : `VOLCENGINE_TTS_APPID`/`_TOKEN`)	BytePlus Seed Speech HTTP API.
Vydra	`VYDRA_API_KEY`	Fournisseur partagé d’images, de vidéos et de synthèse vocale.
xAI	`XAI_API_KEY`	Synthèse vocale par lots xAI. La note vocale native Opus n’est pas prise en charge.
Xiaomi MiMo	`XIAOMI_API_KEY`	Synthèse vocale MiMo via les compléments de chat Xiaomi.

Si plusieurs providers 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), donc ce provider doit é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 de provider :

{
  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 le Xiaomi mimo-v2.5-tts-voicedesign, omettez speakerVoice et définissez style sur le prompt de conception vocale. OpenClaw envoie ce prompt 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 personnalité ou un mode TTS automatique différent. Le bloc d’agent effectue une fusion profonde (deep-merge) sur 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 figer une personnalité par agent, définissez agents.list[].tts.persona avec la configuration du fournisseur — elle remplace le messages.tts.persona global pour cet agent uniquement.

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

messages.tts
agents.list[].tts actif
remplacement de canal (channel), lorsque le canal prend en charge channels.<channel>.tts
remplacement de compte, lorsque le canal transmet channels.<channel>.accounts.<id>.tts
préférences locales /tts pour cet hôte
directives [[tts:...]] en ligne lorsque les remplacements de modèle sont activés

Les remplacements de canal et de compte utilisent la même structure que messages.tts et fusionnent profondément (deep-merge) sur les couches précédentes, de sorte que les identifiants partagés du fournisseur peuvent rester dans messages.tts tandis qu’un canal ou un compte de bot ne change que la voix du locuteur, le modèle, la personnalité 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" },
            },
          },
        },
      },
    },
  },
}

Personnalités

Une persona est une identité vocale stable qui peut être appliquée de manière déterministe sur plusieurs providers. Elle peut préférer un provider, définir une intention de prompt neutre vis-à-vis du provider et transporter des liaisons spécifiques au provider pour les voix, les modèles, les modèles de prompt, les seeds et les réglages vocaux.

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 provider)

{
  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 manière déterministe :

/tts persona <id> préférence locale, si définie.
messages.tts.persona, si défini.
Aucune persona.

La sélection du provider fonctionne par ordre de priorité explicite :

Remplacements directs (CLI, passerelle, Talk, directives TTS autorisées).
/tts provider <id> préférence locale.
provider de la persona active.
messages.tts.provider.
Sélection automatique dans le registre.

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

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

Comment les providers utilisent les prompts de persona

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

Google Gemini

Enveloppe les champs de prompt de persona dans une structure de prompt TTS Gemini uniquement lorsque la configuration effective du provider Google définit promptTemplate: "audio-profile-v1" ou personaPrompt. Les anciens champs audioProfile et speakerName sont toujours ajoutés en préambule en tant que texte de prompt spécifique à Google. Les balises audio en ligne telles que [whispers] ou [laughs] à l’intérieur d’un bloc [[tts:text]]OpenClaw sont préservées dans la transcription Gemini ; OpenClaw ne génère pas ces balises.

OpenAIOpenAI

Mappe les champs de prompt de persona au champ de demande instructionsOpenAI uniquement lorsque aucun instructions OpenAI explicite n’est configuré. Le instructions explicite l’emporte toujours.

Autres providers

Utilise uniquement les liaisons de persona spécifiques au provider sous `personas.

.providers.

`. Les champs de prompt de persona sont ignorés sauf si le provider implémente sa propre cartographie de persona-prompt.

Politique de repli

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

Politique	Comportement
`preserve-persona`	Par défaut. Les champs de prompt neutres vis-à-vis du provider restent disponibles ; le provider peut les utiliser ou les ignorer.
`provider-defaults`	Le persona est omis de la préparation du prompt pour cette tentative ; le provider utilise ses paramètres neutres par défaut tandis que le repli vers d’autres providers continue.
`fail`	Ignore cette tentative de provider avec `reasonCode: "not_configured"` et `personaBinding: "missing"`. Les providers de repli sont toujours essayés.

L’ensemble de la demande TTS échoue uniquement lorsque tous les providers tentés sont ignorés ou échouent.

La sélection de provider de session Talk est limitée à la session. Un client Talk doit choisir les ids de provider, les ids de modèle, les ids de voix et les paramètres régionaux à partir de talk.catalog et les transmettre via la session Talk ou la demande de transfert. L’ouverture d’une session vocale ne doit pas modifier messages.tts ni les paramètres par défaut globaux des providers Talk.

Directives basées sur 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, plus un bloc [[tts:text]]...[[/tts:text]] optionnel pour les indices expressifs qui doivent apparaître dans l’audio uniquement :

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 est "tagged", les directives sont requises pour déclencher l’audio. La livraison de blocs en continu supprime les directives du texte visible avant que le channel 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 provider ; les clés non prises en charge sont supprimées et signalées en tant qu’avertissements de directive TTS.

Clés de directive disponibles :

provider (id de provider 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 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 par le modèle :

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

Autoriser le changement de provider 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 à 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 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 une substitution auto-TTS limitée à la session pour la discussion actuelle.
/tts persona <id> écrit la préférence de personnalité locale ; /tts persona off l’efface.
/tts latest lit la dernière réponse de l’assistant à partir de la transcription de la session actuelle et l’envoie sous forme audio une seule fois. Il stocke uniquement un hachage de cette réponse dans l’entrée de session pour éviter les envois vocaux en double.
/tts audio génère une réponse audio ponctuelle (n’active pas le TTS).
limit et summary sont stockés dans les préférences locales, et non dans la configuration principale.
/tts status inclut des diagnostics de repli pour 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 provider, le modèle, la voix et les métadonnées du point de terminaison personnalisé nettoyés lorsque le TTS est activé.

Préférences par utilisateur

Les commandes slash écrivent des substitutions locales 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.

Champ stocké	Effet
`auto`	Substitution locale auto-TTS (`always`, `off`, …)
`provider`	Substitution locale du provider principal
`persona`	Substitution locale de personnalité
`maxLength`	Seuil de résumé (par défaut `1500` caractères)
`summarize`	Commutateur de résumé (par défaut `true`)

Ces éléments remplacent la configuration effective de messages.tts ainsi que 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 indiquent si le TTS de type vocal doit demander aux providers une cible native voice-note ou conserver une synthèse audio-file normale et marquer uniquement la sortie compatible pour la diffusion vocale.

Canaux compatibles avec les notes vocales : les réponses par note vocale préfèrent Opus (opus_48000_64 d’ElevenLabs, opusOpenAI d’OpenAI).
- 48 kHz / 64 kbps est un bon compromis pour les messages vocaux.
Feishu / WhatsApp : lorsqu’une réponse par note vocale est produite en MP3/WebM/WAV/M4A ou dans un autre format de fichier audio probable, le plugin de canal le transcode en Ogg/Opus 48 kHz avec WhatsAppffmpegWhatsAppBaileys avant d’envoyer le message vocal natif. WhatsApp envoie le résultat via la charge utile audio de Baileys avec ptt: true et audio/ogg; codecs=opusWhatsApp. Si la conversion échoue, Feishu reçoit le fichier d’origine en pièce jointe ; l’envoi WhatsApp échoue plutôt que de poster une charge utile PTT incompatible.
Autres canaux : MP3 (mp3_44100_128 d’ElevenLabs, mp3OpenAI d’OpenAI).
- 44,1 kHz / 128 kbps est l’équilibre par défaut pour la clarté de la parole.
MiniMax : MP3 (modèle MiniMaxspeech-2.8-hdOpenClawMiniMax, taux d’échantillonnage 32 kHz) pour les pièces jointes audio normales. Pour les cibles de notes vocales annoncées par le canal, OpenClaw transcode le MP3 de 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 si configuré. Pour les cibles de notes vocales annoncées par le canal, OpenClaw transcode la sortie Xiaomi en Opus 48 kHz avec XiaomiOpenClawXiaomiffmpeg avant la livraison lorsque le canal annonce la prise en charge du transcodage.
CLI locale : utilise le CLIoutputFormat 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 : l’API TTS Gemini renvoie du PCM brut 24 kHz. OpenClaw l’enveloppe en WAV pour les pièces jointes audio, le transcode en Opus 48 kHz pour les cibles de notes vocales, et renvoie le PCM directement 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 alawOpenClaw. OpenClaw utilise le point de terminaison REST TTS par lot d’xAI et renvoie une pièce jointe audio complète ; le WebSocket TTS en flux d’xAI n’est pas utilisé par ce chemin de fournisseur. Le format de note vocale Opus natif 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 auprès du service.
- Les valeurs de format de sortie suivent les formats de sortie de Microsoft Speech (y compris Ogg/WebM Opus).
- Telegram TelegramsendVoiceOpenAI 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 TTS automatique

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

Ignore le 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 longues réponses 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 mode: "final", envoie toujours du TTS audio uniquement pour les réponses finales en flux après la fin du flux de texte ; les médias générés passent par la même normalisation des médias de canal que les pièces jointes de réponses normales.

Si la réponse dépasse maxLengthAPI 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 texte 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

Cible	Format
Feishu / Matrix / Telegram / WhatsApp	Les réponses en note vocale préfèrent Opus (`opus_48000_64` d’ElevenLabs, `opus` de OpenAI). 48 kHz / 64 kbps offre un équilibre entre clarté et taille.
Autres canaux	MP3 (`mp3_44100_128` d’ElevenLabs, `mp3` de OpenAI). 44,1 kHz / 128 kbps par défaut pour la voix.
Talk / téléphonie	PCM natif du fournisseur (Inworld 22050 Hz, Google 24 kHz), ou `ulaw_8000` de Gradium pour la téléphonie.

Notes par fournisseur :

Transcodage Feishu / WhatsApp : Lorsqu’une réponse en note vocale est au format 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 à l’attachement du fichier original ; l’envoi WhatsApp échoue plutôt que de poster une charge PTT incompatible.
MiniMaxXiaomi / 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 local : Utilise le outputFormat configuré. Les cibles de notes vocales sont converties en Ogg/Opus et la sortie téléphonique en PCM mono brut 16 kHz.
Google Gemini : Renvoie du PCM brut 24 kHz. OpenClaw l’enveloppe en WAV pour les pièces jointes, le transcode en Opus 48 kHz pour les cibles de notes vocales, et renvoie le PCM directement pour Talk/téléphonie.
Inworld : Pièces jointes MP3, note vocale native OGG_OPUS, PCM brut 22050 Hz pour Talk/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 — la TTS WebSocket en continu n’est pas utilisée. Le format de note vocale Opus natif 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 de OpenAI et ElevenLabs sont fixes par channel, comme indiqué ci-dessus.

Référence des champs

Top-level messages.tts.*

Mode TTS automatique. inbound envoie l’audio uniquement après un message vocal entrant ; tagged n’envoie l’audio que si la réponse inclut des directives [[tts:...]] ou un bloc [[tts:text]].

Commutateur hérité. openclaw doctor --fix migre ceci vers auto.

"all" inclut les réponses d’outils/blocs en plus des réponses finales.

Identifiant du fournisseur de synthèse vocale. Si non défini, OpenClaw utilise le premier fournisseur configuré dans l’ordre de sélection automatique du registre. L’ancien provider: "edge" est réécrit en "microsoft" par openclaw doctor --fix.

Identifiant de persona actif depuis personas. Normalisé en minuscules.

Identité vocale stable. Champs : label, description, provider, fallbackPolicy, prompt, `providers.

`. Voir Personas.

Modèle économique pour le résumé automatique ; par défaut agents.defaults.model.primary. Accepte provider/model ou un alias de modèle configuré.

Autoriser le modèle à émettre des directives TTS. enabled par défaut est true ; allowProvider par défaut est false.

Paramètres appartenant au fournisseur, indexés par l’identifiant du fournisseur de synthèse vocale. Les blocs directs hérités (messages.tts.openai, .elevenlabs, .microsoft, .edge) sont réécrits par openclaw doctor --fix ; ne commitez que `messages.tts.providers.

Limite stricte pour les caractères d’entrée TTS. /tts audio échoue si dépassé.

Délai d’expiration de la requête en millisecondes.

Remplacer le chemin JSON des préférences locales (provider/limit/summary). Par défaut ~/.openclaw/settings/tts.json.

Azure Speech

Env : AZURE_SPEECH_KEY, AZURE_SPEECH_API_KEY ou SPEECH_KEY.

Région Azure Speech (p. ex. eastus). Env : AZURE_SPEECH_REGION ou SPEECH_REGION.

Remplacement facultatif du point de terminaison Azure Speech (alias baseUrl).

ShortName de la voix Azure. Par défaut en-US-JennyNeural. Alias de l’ancienne version : voice.

Code de langue SSML. Par défaut en-US.

Azure X-Microsoft-OutputFormat pour l’audio standard. Par défaut audio-24khz-48kbitrate-mono-mp3.

Azure X-Microsoft-OutputFormat pour la sortie en note vocale. Par défaut ogg-24khz-16bit-mono-opus.

ElevenLabs

Revient à ELEVENLABS_API_KEY ou XI_API_KEY.

ID du modèle (ex. eleven_multilingual_v2, eleven_v3).

ID de la voix ElevenLabs. Alias hérité : voiceId.

stability, similarityBoost, style (chacun 0..1), useSpeakerBoost (true|false), speed (0.5..2.0, 1.0 = normal).

Mode de normalisation du texte.

ISO 639-1 sur 2 lettres (ex. en, de).

Entier 0..4294967295 pour un déterminisme au mieux.

Remplacer l’URL de base de l’API ElevenLabs.

Google Gemini

Revient à GEMINI_API_KEY / GOOGLE_API_KEY. Si omis, le TTS peut réutiliser models.providers.google.apiKey avant le repli vers l’environnement.

Modèle TTS Gemini. Par défaut gemini-3.1-flash-tts-preview.

Nom de la voix prédéfinie Gemini. Par défaut Kore. Alias historiques : voiceName, voice.

Invite de style en langage naturel ajoutée avant le texte parlé.

Étiquette de locuteur optionnelle ajoutée avant le texte parlé lorsque votre invite utilise un locuteur nommé.

Définir sur audio-profile-v1 pour encapsuler les champs d’invite de persona actifs dans une structure d’invite TTS Gemini déterministe.

Texte d’invite de persona supplémentaire spécifique à Google, ajouté aux Notes du réalisateur du modèle.

Seul https://generativelanguage.googleapis.com est accepté.

Gradium

Env : GRADIUM_API_KEY.

Par défaut https://api.gradium.ai.

Emma par défaut (YTpq7expH9539ERJ). Alias historique : voiceId.

Inworld

Inworld principal

Env : INWORLD_API_KEY.

Par défaut https://api.inworld.ai.

Par défaut inworld-tts-1.5-max. Aussi : inworld-tts-1.5-mini, inworld-tts-1-max, inworld-tts-1.

Par défaut Sarah. Alias hérité : voiceId.

Température d’échantillonnage 0..2.

CLI local (tts-local-cli)

Exécutable local ou chaîne de commande pour le TTS CLI.

Arguments de commande. Prend en charge les espaces réservés {{ Text }}, {{ OutputPath }}, {{ OutputDir }}, {{ OutputBase }}.

Format de sortie CLI attendu. Par défaut mp3 pour les pièces jointes audio.

Délai d’attente de la commande en millisecondes. Par défaut 120000.

Répertoire de travail optionnel pour la commande.

Remplacements d’environnement optionnels pour la commande.

APIMicrosoft (sans clé API)

Autoriser l’utilisation de la synthèse vocale Microsoft.

Nom de la voix neurale Microsoft (ex. en-US-MichelleNeural). Alias hérité : voice.

Code de langue (ex. en-US).

Format de sortie Microsoft. Par défaut audio-24khz-48kbitrate-mono-mp3. Tous les formats ne sont pas pris en charge par le transport Edge inclus.

Chaînes de pourcentage (ex. +10%, -5%).

Écrire des sous-titres JSON avec le fichier audio.

URL du proxy pour les requêtes de synthèse vocale Microsoft.

Remplacement du délai d’expiration de la requête (ms).

Alias hérité. Exécutez openclaw doctor --fix pour réécrire la configuration persistante vers providers.microsoft.

MiniMaxMiniMax

Retourne à MINIMAX_API_KEY. Auth Token Plan via MINIMAX_OAUTH_TOKEN, MINIMAX_CODE_PLAN_KEY, ou MINIMAX_CODING_API_KEY.

Par défaut https://api.minimax.io. Env : MINIMAX_API_HOST.

Par défaut speech-2.8-hd. Env : MINIMAX_TTS_MODEL.

Par défaut English_expressive_narrator. Env : MINIMAX_TTS_VOICE_ID. Alias historique : voiceId.

0.5..2.0. Par défaut 1.0.

(0, 10]. Par défaut 1.0.

Entier -12..12. Par défaut 0. Les valeurs fractionnaires sont tronquées avant la requête.

OpenAIOpenAI

Revient à OPENAI_API_KEY.

ID du model TTS OpenAI (par ex. gpt-4o-mini-tts).

Nom de la voix (par ex. alloy, cedar). Alias hérité : voice.

Champ instructions OpenAI explicite. Lorsqu’il est défini, les champs de prompt de persona ne sont pas mappés automatiquement.

Champs JSON supplémentaires fusionnés dans les corps de requête /audio/speechOpenAIOpenAI après les champs TTS OpenAI générés. À utiliser pour les points de terminaison compatibles OpenAI tels que Kokoro qui nécessitent des clés spécifiques au provider comme lang ; les clés de prototype non sécurisées sont ignorées.

Remplacer le point de terminaison TTS OpenAI. Ordre de résolution : config → OPENAI_TTS_BASE_URL → https://api.openai.com/v1OpenAI. Les valeurs par défaut sont traitées comme des points de terminaison TTS compatibles OpenAI, donc les noms de model et de voix personnalisés sont acceptés.

OpenRouterOpenRouter

Env : OPENROUTER_API_KEY. Peut réutiliser models.providers.openrouter.apiKey.

Par défaut https://openrouter.ai/api/v1. L’ancien https://openrouter.ai/v1 est normalisé.

Par défaut hexgrad/kokoro-82m. Alias : modelId.

Par défaut af_alloy. Anciens alias : voice, voiceId.

Par défaut mp3.

Surcharge de vitesse propre au fournisseur.

Volcengine (BytePlus Seed Speech)

Env : VOLCENGINE_TTS_API_KEY ou BYTEPLUS_SEED_SPEECH_API_KEY.

Par défaut seed-tts-1.0. Env : VOLCENGINE_TTS_RESOURCE_ID. Utilisez seed-tts-2.0 lorsque votre projet dispose de droits TTS 2.0.

En-tête de clé d’application. Par défaut aGjiRDfUWi. Env : VOLCENGINE_TTS_APP_KEY.

Remplacer le point de terminaison HTTP TTS Seed Speech. Env : VOLCENGINE_TTS_BASE_URL.

Type de voix. Par défaut en_female_anna_mars_bigtts. Env : VOLCENGINE_TTS_VOICE. Alias hérité : voice.

Rapport de vitesse natif du fournisseur.

Balise d’émotion native du fournisseur.

Champs hérités de la console vocale Volcengine. Env : VOLCENGINE_TTS_APPID, VOLCENGINE_TTS_TOKEN, VOLCENGINE_TTS_CLUSTER (par défaut volcano_tts).

xAI

Env : XAI_API_KEY.

Par défaut https://api.x.ai/v1. Env : XAI_BASE_URL.

Par défaut eve. Voix en direct : ara, eve, leo, rex, sal, una. Alias hérité : voiceId.

Code de langue BCP-47 ou auto. Par défaut en.

Par défaut mp3.

Remplacement de la vitesse natif du fournisseur.

Xiaomi MiMo

Env : XIAOMI_API_KEY.

Par défaut https://api.xiaomimimo.com/v1. Env : XIAOMI_BASE_URL.

Par défaut mimo-v2.5-tts. Env : XIAOMI_TTS_MODEL. Prend également en charge mimo-v2-tts et mimo-v2.5-tts-voicedesign.

Par défaut mimo_default pour les modèles de voix prédéfinis. Env : XIAOMI_TTS_VOICE. Alias hérité : voice. Non envoyé pour mimo-v2.5-tts-voicedesign.

Par défaut mp3. Env : XIAOMI_TTS_FORMAT.

Instruction de style en langage naturel facultative envoyée en tant que message utilisateur ; non prononcée. Pour mimo-v2.5-tts-voicedesign, il s’agit du prompt de conception vocale ; OpenClaw fournit une valeur par défaut en cas d’omission.

Agent tool

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 délivré sous forme de message vocal plutôt que de fichier pièce jointe. Feishu et WhatsApp peuvent transcoder la sortie TTS non Opus sur ce chemin 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 ne rendent 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 la demande du provider 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 du provider définie par le plugin.

Gateway RPC

Méthode	Objet
`tts.status`	Lire l’état actuel du TTS et la dernière tentative.
`tts.enable`	Définir la préférence automatique locale sur `always`.
`tts.disable`	Définir la préférence automatique locale sur `off`.
`tts.convert`	Conversion ponctuelle texte → audio.
`tts.setProvider`	Définir la préférence locale du provider.
`tts.setPersona`	Définir la préférence locale de personnalité.
`tts.providers`	Lister les providers configurés et leur statut.