Text-zu-Sprache

OpenClaw kann ausgehende Antworten bei 14 Speech-Providern in Audio umwandeln und native Sprachnachrichten auf Feishu, Matrix, Telegram und WhatsApp, Audio-Anhänge überall sonst sowie PCM/Ulaw-Streams für Telefonie und Talk ausliefern.

TTS ist die Sprachausgabe-Hälfte von Talks stt-tts-Modus. Provider-native realtime-Talk-Sitzungen synthetisieren Sprache innerhalb des Echtzeit-Providers, statt diesen TTS-Pfad aufzurufen, während transcription-Sitzungen keine Assistenten-Sprachantwort synthetisieren.

Schnellstart

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

Unterstützte Provider

Wenn mehrere Provider konfiguriert sind, wird der ausgewählte zuerst verwendet und die anderen sind Fallback-Optionen. Automatische Zusammenfassung verwendet summaryModel (oder agents.defaults.model.primary), daher muss dieser Provider ebenfalls authentifiziert sein, wenn Sie Zusammenfassungen aktiviert lassen.

Konfiguration

Die TTS-Konfiguration liegt unter messages.tts in ~/.openclaw/openclaw.json. Wählen Sie ein Preset und passen Sie den Provider-Block an:

{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",    },  },},},}

Sprachüberschreibungen pro Agent

Verwenden Sie agents.list[].tts, wenn ein Agent mit einem anderen Provider, einer anderen Stimme, einem anderen Modell, einer anderen Persona oder einem anderen Auto-TTS-Modus sprechen soll. Der Agent-Block wird per Deep Merge über messages.tts gelegt, sodass Provider-Anmeldedaten in der globalen Provider-Konfiguration bleiben können:

{  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" },          },        },      },    ],  },}

Um eine agentenspezifische Persona festzulegen, setzen Sie agents.list[].tts.persona zusammen mit der Provider-Konfiguration. Sie überschreibt die globale messages.tts.persona nur für diesen Agenten.

Rangfolge für automatische Antworten, /tts audio, /tts status und das Agent-Tool tts:

1. messages.tts
2. aktives agents.list[].tts
3. Kanal-Override, wenn der Kanal channels.<channel>.tts unterstützt
4. Konto-Override, wenn der Kanal channels.<channel>.accounts.<id>.tts übergibt
5. lokale /tts-Einstellungen für diesen Host
6. Inline-Direktiven [[tts:...]], wenn Modell-Overrides aktiviert sind

Kanal- und Konto-Overrides verwenden dieselbe Struktur wie messages.tts und werden per Deep Merge über die früheren Ebenen gelegt. So können gemeinsame Provider-Anmeldedaten in messages.tts bleiben, während ein Kanal oder Bot-Konto nur Stimme, Modell, Persona oder Automatikmodus ändert:

{  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

Eine Persona ist eine stabile gesprochene Identität, die deterministisch providerübergreifend angewendet werden kann. Sie kann einen Provider bevorzugen, eine providerneutrale Prompt-Absicht definieren und providerspezifische Bindings für Stimmen, Modelle, Prompt-Vorlagen, Seeds und Spracheinstellungen enthalten.

Minimale Persona

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

Vollständige Persona (providerneutraler Prompt)

{  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,              },            },          },        },      },    },  },}

Auflösung der Persona

Die aktive Persona wird deterministisch ausgewählt:

1. lokale Einstellung /tts persona <id>, falls gesetzt.
2. messages.tts.persona, falls gesetzt.
3. Keine Persona.

Die Provider-Auswahl läuft mit expliziten Vorgaben zuerst:

1. Direkte Overrides (CLI, Gateway, Talk, erlaubte TTS-Direktiven).
2. lokale Einstellung /tts provider <id>.
3. provider der aktiven Persona.
4. messages.tts.provider.
5. Automatische Auswahl aus der Registry.

Für jeden Provider-Versuch führt OpenClaw Konfigurationen in dieser Reihenfolge zusammen:

1. messages.tts.providers.<id>
2. messages.tts.personas.<persona>.providers.<id>
3. Vertrauenswürdige Request-Overrides
4. Erlaubte, vom Modell ausgegebene TTS-Direktiv-Overrides

Wie Provider Persona-Prompts verwenden

Persona-Prompt-Felder (profile, scene, sampleContext, style, accent, pacing, constraints) sind providerneutral. Jeder Provider entscheidet selbst, wie er sie verwendet:

Fallback-Richtlinie

fallbackPolicy steuert das Verhalten, wenn eine Persona kein Binding für den versuchten Provider hat:

Der gesamte TTS-Request schlägt nur fehl, wenn jeder versuchte Provider übersprungen wird oder fehlschlägt.

Die Provider-Auswahl für Talk-Sitzungen ist sitzungsbezogen. Ein Talk-Client sollte Provider-IDs, Modell-IDs, Voice-IDs und Locales aus talk.catalog auswählen und sie über die Talk-Sitzung oder den Handoff-Request übergeben. Das Öffnen einer Sprachsitzung sollte messages.tts oder globale Talk-Provider-Standards nicht verändern.

Modellgesteuerte Direktiven

Standardmäßig kann der Assistent [[tts:...]]-Direktiven ausgeben, um Stimme, Modell oder Geschwindigkeit für eine einzelne Antwort zu überschreiben, plus einen optionalen [[tts:text]]...[[/tts:text]]-Block für ausdrucksstarke Hinweise, die nur im Audio erscheinen sollen:

Here you go. [[tts:voiceId=pMsXgVXv3BLzUgSXRplE model=eleven_v3 speed=1.1]][[tts:text]](laughs) Read the song once more.[[/tts:text]]

Wenn messages.tts.auto "tagged" ist, sind Direktiven erforderlich, um Audio auszulösen. Die Streaming-Blockauslieferung entfernt Direktiven aus sichtbarem Text, bevor der Kanal sie sieht, auch wenn sie über benachbarte Blöcke verteilt sind.

provider=... wird ignoriert, sofern modelOverrides.allowProvider: true nicht gesetzt ist. Wenn eine Antwort provider=... deklariert, werden die anderen Schlüssel in dieser Direktive nur von diesem Provider geparst; nicht unterstützte Schlüssel werden entfernt und als TTS-Direktivwarnungen gemeldet.

Verfügbare Direktivschlüssel:

• provider (registrierte Provider-ID; erfordert allowProvider: true)
• voice / voiceName / voice_name / google_voice / voiceId
• model / google_model
• stability, similarityBoost, style, speed, useSpeakerBoost
• vol / volume (MiniMax-Lautstärke, 0–10)
• pitch (MiniMax-Ganzzahltonhöhe, −12 bis 12; Dezimalwerte werden abgeschnitten)
• emotion (Volcengine-Emotions-Tag)
• applyTextNormalization (auto|on|off)
• languageCode (ISO 639-1)
• seed

Modell-Overrides vollständig deaktivieren:

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

Provider-Wechsel erlauben, während andere Regler konfigurierbar bleiben:

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

Slash-Befehle

Einzelner Befehl /tts. Auf Discord registriert OpenClaw zusätzlich /voice, weil /tts ein integrierter Discord-Befehl ist. Textuelles /tts ... funktioniert weiterhin.

/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>

Verhaltenshinweise:

• /tts on schreibt die lokale TTS-Einstellung auf always; /tts off schreibt sie auf off.
• /tts chat on|off|default schreibt einen sitzungsbezogenen Auto-TTS-Override für den aktuellen Chat.
• /tts persona <id> schreibt die lokale Persona-Einstellung; /tts persona off löscht sie.
• /tts latest liest die neueste Assistentenantwort aus dem aktuellen Sitzungstranskript und sendet sie einmalig als Audio. Es speichert nur einen Hash dieser Antwort im Sitzungseintrag, um doppelte Sprachausgaben zu unterdrücken.
• /tts audio erzeugt eine einmalige Audioantwort (schaltet TTS nicht ein).
• limit und summary werden in lokalen Einstellungen gespeichert, nicht in der Hauptkonfiguration.
• /tts status enthält Fallback-Diagnosen für den neuesten Versuch: Fallback: <primary> -> <used>, Attempts: ... sowie Details pro Versuch (provider:outcome(reasonCode) latency).
• /status zeigt den aktiven TTS-Modus sowie den konfigurierten Provider, das Modell, die Stimme und bereinigte Metadaten für benutzerdefinierte Endpunkte, wenn TTS aktiviert ist.

Benutzerspezifische Einstellungen

Slash-Befehle schreiben lokale Overrides nach prefsPath. Der Standard ist ~/.openclaw/settings/tts.json; überschreiben Sie ihn mit der Umgebungsvariablen OPENCLAW_TTS_PREFS oder messages.tts.prefsPath.

Diese überschreiben die effektive Konfiguration aus messages.tts plus den aktiven Block agents.list[].tts für diesen Host.

Ausgabeformate (fest)

Die TTS-Sprachauslieferung wird durch Kanalfähigkeiten gesteuert. Kanal-Plugins geben an, ob TTS im Sprachstil Provider nach einem nativen Ziel voice-note fragen soll oder ob normale audio-file-Synthese beibehalten und kompatible Ausgabe nur für die Sprachauslieferung markiert werden soll.

• Kanäle mit Sprachnotiz-Unterstützung: Sprachnotiz-Antworten bevorzugen Opus (opus_48000_64 von ElevenLabs, opus von OpenAI).
  • 48 kHz / 64 kbit/s ist ein guter Kompromiss für Sprachnachrichten.
• Feishu / WhatsApp: Wenn eine Sprachnotiz-Antwort als MP3/WebM/WAV/M4A oder eine andere wahrscheinliche Audiodatei erzeugt wird, transkodiert das Kanal-Plugin sie vor dem Senden der nativen Sprachnachricht mit ffmpeg nach 48 kHz Ogg/Opus. WhatsApp sendet das Ergebnis über die Baileys-audio-Payload mit ptt: true und audio/ogg; codecs=opus. Wenn die Konvertierung fehlschlägt, erhält Feishu die Originaldatei als Anhang; der WhatsApp-Versand schlägt fehl, statt eine inkompatible PTT-Payload zu posten.
• Andere Kanäle: MP3 (mp3_44100_128 von ElevenLabs, mp3 von OpenAI).
  • 44,1 kHz / 128 kbit/s ist die Standardbalance für Sprachverständlichkeit.
• MiniMax: MP3 (speech-2.8-hd-Modell, 32-kHz-Abtastrate) für normale Audioanhänge. Für vom Kanal angegebene Sprachnotiz-Ziele transkodiert OpenClaw das MiniMax-MP3 vor der Auslieferung mit ffmpeg nach 48 kHz Opus, wenn der Kanal Transkodierung angibt.
• Xiaomi MiMo: Standardmäßig MP3 oder WAV, wenn konfiguriert. Für vom Kanal angegebene Sprachnotiz-Ziele transkodiert OpenClaw die Xiaomi-Ausgabe vor der Auslieferung mit ffmpeg nach 48 kHz Opus, wenn der Kanal Transkodierung angibt.
• Lokale CLI: verwendet das konfigurierte outputFormat. Sprachnotiz-Ziele werden nach Ogg/Opus konvertiert, und Telefonieausgabe wird mit ffmpeg in rohes 16-kHz-Mono-PCM konvertiert.
• Google Gemini: Gemini API TTS gibt rohes 24-kHz-PCM zurück. OpenClaw verpackt es für Audioanhänge als WAV, transkodiert es für Sprachnotiz-Ziele nach 48 kHz Opus und gibt PCM für Talk/Telefonie direkt zurück.
• Gradium: WAV für Audioanhänge, Opus für Sprachnotiz-Ziele und ulaw_8000 bei 8 kHz für Telefonie.
• Inworld: MP3 für normale Audioanhänge, natives OGG_OPUS für Sprachnotiz-Ziele und rohes PCM bei 22050 Hz für Talk/Telefonie.
• xAI: standardmäßig MP3; responseFormat kann mp3, wav, pcm, mulaw oder alaw sein. OpenClaw verwendet den Batch-REST-TTS-Endpunkt von xAI und gibt einen vollständigen Audioanhang zurück; der Streaming-TTS-WebSocket von xAI wird von diesem Provider-Pfad nicht verwendet. Das native Opus-Sprachnotizformat wird von diesem Pfad nicht unterstützt.
• Microsoft: verwendet microsoft.outputFormat (Standard audio-24khz-48kbitrate-mono-mp3).
  • Der gebündelte Transport akzeptiert ein outputFormat, aber nicht alle Formate sind beim Dienst verfügbar.
  • Ausgabeformatwerte folgen den Microsoft Speech-Ausgabeformaten (einschließlich Ogg/WebM Opus).
  • Telegram sendVoice akzeptiert OGG/MP3/M4A; verwenden Sie OpenAI/ElevenLabs, wenn Sie garantierte Opus-Sprachnachrichten benötigen.
  • Wenn das konfigurierte Microsoft-Ausgabeformat fehlschlägt, versucht OpenClaw es erneut mit MP3.

OpenAI/ElevenLabs-Ausgabeformate sind je nach Kanal festgelegt (siehe oben).

Auto-TTS-Verhalten

Wenn messages.tts.auto aktiviert ist, führt OpenClaw Folgendes aus:

• Überspringt TTS, wenn die Antwort bereits Medien oder eine MEDIA:-Direktive enthält.
• Überspringt sehr kurze Antworten (unter 10 Zeichen).
• Fasst lange Antworten zusammen, wenn Zusammenfassungen aktiviert sind, unter Verwendung von summaryModel (oder agents.defaults.model.primary).
• Hängt das erzeugte Audio an die Antwort an.
• In mode: "final" wird weiterhin nur Audio-TTS für gestreamte finale Antworten gesendet, nachdem der Textstream abgeschlossen ist; die erzeugten Medien durchlaufen dieselbe Kanal-Mediennormalisierung wie normale Antwortanhänge.

Wenn die Antwort maxLength überschreitet und die Zusammenfassung deaktiviert ist (oder kein API-Schlüssel für das Zusammenfassungsmodell vorhanden ist), wird Audio übersprungen und die normale Textantwort gesendet.

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

Ausgabeformate nach Kanal

Hinweise pro Provider:

• Feishu / WhatsApp-Transcodierung: Wenn eine Sprachnotiz-Antwort als MP3/WebM/WAV/M4A ankommt, transcodiert das Kanal-Plugin sie mit ffmpeg zu 48 kHz Ogg/Opus. WhatsApp sendet über Baileys mit ptt: true und audio/ogg; codecs=opus. Wenn die Konvertierung fehlschlägt: Feishu fällt darauf zurück, die Originaldatei anzuhängen; der WhatsApp-Versand schlägt fehl, statt eine inkompatible PTT-Nutzlast zu posten.
• MiniMax / Xiaomi MiMo: Standardmäßig MP3 (32 kHz für MiniMax speech-2.8-hd); wird für Sprachnotiz-Ziele über ffmpeg zu 48 kHz Opus transcodiert.
• Lokale CLI: Verwendet das konfigurierte outputFormat. Sprachnotiz-Ziele werden zu Ogg/Opus konvertiert und Telefonie-Ausgabe zu rohem 16-kHz-Mono-PCM.
• Google Gemini: Gibt rohes 24-kHz-PCM zurück. OpenClaw verpackt es für Anhänge als WAV, transcodiert es für Sprachnotiz-Ziele zu 48 kHz Opus und gibt PCM direkt für Talk/Telefonie zurück.
• Inworld: MP3-Anhänge, natives OGG_OPUS für Sprachnotizen, rohes PCM mit 22050 Hz für Talk/Telefonie.
• xAI: Standardmäßig MP3; responseFormat kann mp3|wav|pcm|mulaw|alaw sein. Verwendet den Batch-REST-Endpunkt von xAI — Streaming-WebSocket-TTS wird nicht verwendet. Natives Opus-Format für Sprachnotizen wird nicht unterstützt.
• Microsoft: Verwendet microsoft.outputFormat (Standard audio-24khz-48kbitrate-mono-mp3). Telegram sendVoice akzeptiert OGG/MP3/M4A; verwenden Sie OpenAI/ElevenLabs, wenn Sie garantiert Opus-Sprachnachrichten benötigen. Wenn das konfigurierte Microsoft-Format fehlschlägt, versucht OpenClaw es erneut mit MP3.

OpenAI- und ElevenLabs-Ausgabeformate sind wie oben aufgeführt pro Kanal festgelegt.

Feldreferenz

Agenten-Tool

Das Tool tts wandelt Text in Sprache um und gibt einen Audio-Anhang für die Antwortzustellung zurück. In Feishu, Matrix, Telegram und WhatsApp wird das Audio als Sprachnachricht statt als Datei-Anhang zugestellt. Feishu und WhatsApp können auf diesem Pfad Nicht-Opus-TTS-Ausgaben transkodieren, wenn ffmpeg verfügbar ist.

WhatsApp sendet Audio über Baileys als PTT-Sprachnotiz (audio mit ptt: true) und sendet sichtbaren Text separat von PTT-Audio, da Clients Beschriftungen auf Sprachnotizen nicht zuverlässig anzeigen.

Das Tool akzeptiert optionale Felder channel und timeoutMs; timeoutMs ist ein anrufbezogener Provider-Anfrage-Timeout in Millisekunden.

Gateway-RPC

Service-Links

• OpenAI-Leitfaden für Text-to-Speech
• OpenAI Audio API-Referenz
• Azure Speech REST Text-to-Speech
• Azure Speech Provider
• ElevenLabs Text to Speech
• ElevenLabs-Authentifizierung
• Gradium
• Inworld TTS API
• MiniMax T2A v2 API
• Volcengine TTS HTTP API
• Xiaomi MiMo-Sprachsynthese
• node-edge-tts
• Microsoft Speech-Ausgabeformate
• xAI Text-to-Speech

Verwandt

• Medienüberblick
• Musikgenerierung
• Videogenerierung
• Slash-Befehle
• Sprachanruf-Plugin