Text-to-Speech

OpenClaw wandelt ausgehende Antworten über 14 Sprach-Provider in Audio um: native Sprachnachrichten auf Feishu, Matrix, Telegram und WhatsApp; Audioanhänge überall sonst; sowie PCM-/Ulaw-Streams für Telefonie und Talk.

TTS ist die Sprachausgabehälfte des stt-tts-Modus von Talk (talk.speak verwendet denselben Synthesepfad). Provider-native realtime-Talk-Sitzungen synthetisieren Sprache stattdessen innerhalb des Echtzeit-Providers; transcription-Sitzungen synthetisieren niemals eine gesprochene Assistentenantwort.

Schnellstart

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

Unterstützte Provider

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

Konfiguration

Die TTS-Konfiguration befindet sich unter tts in ~/.openclaw/openclaw.json. Wählen Sie eine Voreinstellung aus und passen Sie den Provider-Block an. Die unten dargestellten Felder speakerVoice/speakerVoiceId sind kanonisch; die providerspezifischen Feldnamen voice/voiceId/voiceName funktionieren weiterhin als veraltete Aliasse.

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

{tts: {auto: "always",provider: "elevenlabs",providers: {  elevenlabs: {    apiKey: "${ELEVENLABS_API_KEY}",    model: "eleven_multilingual_v2",    speakerVoiceId: "EXAVITQu4vr4xnSDxMaL",  },},},}

{tts: {auto: "always",provider: "google",providers: {  google: {    apiKey: "${GEMINI_API_KEY}",    model: "gemini-3.1-flash-tts-preview",    speakerVoice: "Kore",    // Optionale Stilvorgaben in natürlicher Sprache:    // audioProfile: "Sprechen Sie in einem ruhigen Tonfall wie ein Podcast-Moderator.",    // speakerName: "Alex",  },},},}

{tts: {auto: "always",provider: "gradium",providers: {  gradium: {    apiKey: "${GRADIUM_API_KEY}",    speakerVoiceId: "YTpq7expH9539ERJ",  },},},}

{tts: {auto: "always",provider: "inworld",providers: {  inworld: {    apiKey: "${INWORLD_API_KEY}",    modelId: "inworld-tts-1.5-max",    speakerVoiceId: "Sarah",    temperature: 0.7,  },},},}

{tts: {auto: "always",provider: "tts-local-cli",providers: {  "tts-local-cli": {    command: "say",    args: ["-o", "{{OutputPath}}", "{{Text}}"],    outputFormat: "wav",    timeoutMs: 120000,  },},},}

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

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

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

{tts: {auto: "always",provider: "openrouter",providers: {  openrouter: {    apiKey: "${OPENROUTER_API_KEY}",    model: "hexgrad/kokoro-82m",    speakerVoice: "af_alloy",    responseFormat: "mp3",  },},},}

{tts: {auto: "always",provider: "volcengine",providers: {  volcengine: {    apiKey: "${VOLCENGINE_TTS_API_KEY}",    resourceId: "seed-tts-1.0",    speakerVoice: "en_female_anna_mars_bigtts",  },},},}

{tts: {auto: "always",provider: "xai",providers: {  xai: {    apiKey: "${XAI_API_KEY}",    speakerVoiceId: "eve",    language: "en",    responseFormat: "mp3",  },},},}

{tts: {auto: "always",provider: "xiaomi",providers: {  xiaomi: {    apiKey: "${XIAOMI_API_KEY}",    model: "mimo-v2.5-tts",    speakerVoice: "mimo_default",    format: "mp3",  },},},}

Lassen Sie für Xiaomi mimo-v2.5-tts-voicedesign den Wert speakerVoice weg und legen Sie style auf die Vorgabe für den Stimmentwurf fest. OpenClaw sendet diese Vorgabe als TTS-Nachricht user und sendet für das Voicedesign-Modell kein audio.voice.

Agent-spezifische Stimmenüberschreibungen

Verwenden Sie agents.entries.*.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 rekursiv mit tts zusammengeführt, sodass die Provider-Anmeldedaten in der globalen Provider-Konfiguration verbleiben können:

{  tts: {    auto: "always",    provider: "elevenlabs",    providers: {      elevenlabs: { apiKey: "${ELEVENLABS_API_KEY}", model: "eleven_multilingual_v2" },    },  },  agents: {    list: [      {        id: "reader",        tts: {          providers: {            elevenlabs: { speakerVoiceId: "EXAVITQu4vr4xnSDxMaL" },          },        },      },    ],  },}

Um eine Persona für einen einzelnen Agenten festzulegen, setzen Sie agents.entries.*.tts.persona zusammen mit der Provider- Konfiguration — dies überschreibt das globale tts.persona ausschließlich für diesen Agenten.

Prioritätsreihenfolge für automatische Antworten, /tts audio, /tts status und das Agentenwerkzeug tts:

1. tts
2. aktives agents.entries.*.tts
3. Kanalüberschreibung, wenn der Kanal channels.<channel>.tts unterstützt
4. Kontoüberschreibung, wenn der Kanal channels.<channel>.accounts.<id>.tts übergibt
5. lokale /tts-Einstellungen für diesen Host
6. eingebettete [[tts:...]]-Direktiven, wenn modellgesteuerte Überschreibungen aktiviert sind

Kanal- und Kontoüberschreibungen verwenden dieselbe Struktur wie tts und werden rekursiv über die vorherigen Ebenen zusammengeführt. Dadurch können gemeinsam genutzte Provider-Anmeldedaten in tts verbleiben, während ein Kanal oder Bot-Konto nur Sprecherstimme, Modell, Persona oder Automatikmodus ändert:

{  tts: {    provider: "openai",    providers: {      openai: { apiKey: "${OPENAI_API_KEY}", model: "gpt-4o-mini-tts" },    },  },  channels: {    feishu: {      accounts: {        english: {          tts: {            providers: {              openai: { speakerVoice: "shimmer" },            },          },        },      },    },  },}

Personas

Eine Persona ist eine stabile gesprochene Identität, die deterministisch Provider-übergreifend angewendet werden kann. Sie kann einen Provider bevorzugen, Provider-neutrale Prompt-Absichten definieren und Provider-spezifische Zuordnungen für Stimmen, Modelle, Prompt- Vorlagen, Seeds und Stimmeinstellungen enthalten.

Minimale Persona

{  tts: {    auto: "always",    persona: "narrator",    personas: {      narrator: {        label: "Erzähler",        provider: "elevenlabs",        providers: {          elevenlabs: {            speakerVoiceId: "EXAVITQu4vr4xnSDxMaL",            modelId: "eleven_multilingual_v2",          },        },      },    },  },}

Vollständige Persona (Provider-spezifische Ausgestaltung)

{  tts: {    auto: "always",    persona: "alfred",    personas: {      alfred: {        label: "Alfred",        description: "Trockener, warmherziger britischer Butler-Erzähler.",        provider: "google",        fallbackPolicy: "preserve-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,            },          },        },      },    },  },}

Persona-Auflösung

Die aktive Persona wird deterministisch ausgewählt:

1. lokale /tts persona <id>-Einstellung, sofern festgelegt.
2. tts.persona, sofern festgelegt.
3. Keine Persona.

Die Provider-Auswahl erfolgt mit Vorrang für explizite Angaben:

1. Direkte Überschreibungen (CLI, Gateway, Talk, zulässige TTS-Direktiven).
2. Lokale /tts provider <id>-Einstellung.
3. provider der aktiven Persona.
4. tts.provider.
5. Automatische Auswahl aus der Registry.

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

1. tts.providers.<id>
2. tts.personas.<persona>.providers.<id>
3. Vertrauenswürdige Anforderungsüberschreibungen
4. Zulässige, vom Modell ausgegebene Überschreibungen durch TTS-Direktiven

Benutzerdefinierte Persona-Ausgestaltung

Die Provider-neutrale personas.<id>.prompt.*-Konfiguration wird nicht mehr verwendet. Doctor entfernt diese Felder und verweist auf die Schnittstelle des Sprach-Providers. Legen Sie integrierte Provider- Einstellungen unter personas.<id>.providers.<provider> ab (beispielsweise Google- personaPrompt oder OpenAI-instructions). Implementieren Sie für eine benutzerdefinierte Ausgestaltung ein Sprach-Provider-Plugin mit prepareSynthesis(ctx) und geben Sie angepassten Text, eine Provider-Konfiguration oder Überschreibungen zurück, bevor synthesize() ausgeführt wird. Dadurch verbleibt die ausdrucksstarke Prompt-Erstellung im Provider-Code, in dem die Semantik der Anforderungen bekannt ist.

Fallback-Richtlinie

fallbackPolicy steuert das Verhalten, wenn eine Persona keine Zuordnung für den versuchten Provider besitzt:

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

Die Provider-Auswahl einer Talk-Sitzung gilt nur für diese Sitzung. Ein Talk-Client sollte Provider-IDs, Modell-IDs, Stimmen-IDs und Gebietsschemas aus talk.catalog auswählen und sie über die Talk-Sitzungs- oder Übergabeanforderung übergeben. Das Öffnen einer Sprachsitzung sollte weder tts noch die globalen Standardwerte des Talk-Providers verändern.

Modellgesteuerte Direktiven

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

Bitte sehr. [[tts:speakerVoiceId=pMsXgVXv3BLzUgSXRplE model=eleven_v3 speed=1.1]][[tts:text]](lacht) Lesen Sie das Lied noch einmal vor.[[/tts:text]]

Wenn tts.auto den Wert "tagged" hat, sind Direktiven erforderlich, um Audio auszulösen. Bei der blockweisen Streaming-Auslieferung werden Direktiven aus dem sichtbaren Text entfernt, bevor der Kanal ihn empfängt, selbst wenn sie auf benachbarte Blöcke verteilt sind.

provider=... wird ignoriert, sofern nicht modelOverrides.allowProvider: true. Wenn eine Antwort provider=... deklariert, werden die anderen Schlüssel in dieser Direktive ausschließlich von diesem Provider ausgewertet; nicht unterstützte Schlüssel werden entfernt und als Warnungen zu TTS- Direktiven gemeldet.

Verfügbare Direktiven-Schlüssel:

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

Modellüberschreibungen vollständig deaktivieren:

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

Provider-Wechsel zulassen, während andere Einstellungen konfigurierbar bleiben:

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

Slash-Befehle

Einzelner Befehl /tts. Auf Discord registriert OpenClaw außerdem /voice, da /tts ein integrierter Discord-Befehl ist — der Textbefehl /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>

Hinweise zum Verhalten:

• /tts on schreibt die lokale TTS-Einstellung nach always; /tts off schreibt sie nach off.
• /tts chat on|off|default schreibt für den aktuellen Chat eine sitzungsbezogene Auto-TTS-Überschreibung.
• /tts persona <id> schreibt die lokale Persona-Einstellung; /tts persona off löscht sie.
• /tts latest liest die neueste Assistentenantwort aus dem Transkript der aktuellen Sitzung und sendet sie einmalig als Audio. Im Sitzungseintrag wird nur ein Hash dieser Antwort gespeichert, um doppelte Sprachausgaben zu unterdrücken.
• /tts audio erzeugt eine einmalige Audioantwort (aktiviert TTS nicht dauerhaft).
• /tts limit <chars> akzeptiert 100–4096 (4096 ist das Telegram-Maximum für Bildunterschriften/Nachrichten); Werte außerhalb dieses Bereichs werden abgelehnt.
• limit und summary werden in lokalen Einstellungen und nicht in der Hauptkonfiguration gespeichert.
• /tts status enthält Fallback-Diagnosen für den letzten Versuch — Fallback: <primary> -> <used>, Attempts: ... und Details pro Versuch (provider:outcome(reasonCode) latency).
• /status zeigt bei aktiviertem TTS den aktiven TTS-Modus sowie den konfigurierten Provider, das Modell, die Stimme und bereinigte Metadaten des benutzerdefinierten Endpunkts an.

Benutzerspezifische Einstellungen

Slash-Befehle schreiben lokale Überschreibungen in den Pfad für TTS-Einstellungen. Der Standardwert lautet ~/.openclaw/settings/tts.json; überschreiben Sie ihn mit OPENCLAW_TTS_PREFS. Doctor verschiebt den nicht mehr verwendeten globalen Wert tts.prefsPath in den gemeinsamen Maschinenstatus. Fortgeschrittene Multi-Agent-Konfigurationen können weiterhin agents.entries.<id>.tts.prefsPath festlegen, wenn Agenten absichtlich getrennte Einstellungsspeicher verwenden.

Diese überschreiben die wirksame Konfiguration aus tts sowie den aktiven agents.entries.*.tts-Block für diesen Host.

Ausgabeformate

Die TTS-Sprachausgabe richtet sich nach den Fähigkeiten des Kanals. Kanal-Plugins geben an, ob TTS im Sprachstil von Providern ein natives voice-note-Zielformat anfordern oder die normale audio-file-Synthese beibehalten soll und ob der Kanal nicht native Ausgaben vor dem Senden transkodiert.

Hinweise pro Provider:

• Feishu-/WhatsApp-Transkodierung: Wenn eine Sprachnachrichten-Antwort als MP3/WebM/WAV/M4A oder andere wahrscheinliche Audiodatei vorliegt, transkodiert das Kanal-Plugin sie vor dem Senden der nativen Sprachnachricht mit ffmpeg (libopus, 64 kbps) in Ogg/Opus mit 48 kHz. WhatsApp sendet das Ergebnis über die Baileys-audio-Nutzlast mit ptt: true und audio/ogg; codecs=opus. Bei einem Transkodierungsfehler: Feishu fängt den Fehler ab und sendet ersatzweise die Originaldatei als normalen Anhang; WhatsApp bietet keinen Fallback, sodass der Sendevorgang selbst fehlschlägt, statt eine inkompatible PTT-Nutzlast zu veröffentlichen.
• MiniMax: MP3 (speech-2.8-hd-Modell, Abtastrate 32 kHz) für normale Audioanhänge; für vom Kanal als Sprachnachrichten-Ziele ausgewiesene Ziele wird mit ffmpeg in Opus mit 48 kHz transkodiert.
• Xiaomi MiMo: Standardmäßig MP3 oder bei entsprechender Konfiguration WAV; für vom Kanal als Sprachnachrichten-Ziele ausgewiesene Ziele wird mit ffmpeg in Opus mit 48 kHz transkodiert.
• Lokale CLI: Verwendet das konfigurierte outputFormat. Sprachnachrichten-Ziele werden in Ogg/Opus und Telefonieausgaben mit ffmpeg in rohes Mono-PCM mit 16 kHz konvertiert.
• Google Gemini: Gibt rohes PCM mit 24 kHz zurück. OpenClaw verpackt es für Audioanhänge als WAV, transkodiert es für Sprachnachrichten-Ziele in Opus mit 48 kHz und gibt PCM für Talk/Telefonie direkt zurück.
• Gradium: WAV für Audioanhänge, Opus für Sprachnachrichten-Ziele und ulaw_8000 mit 8 kHz für Telefonie.
• Inworld: MP3 für normale Audioanhänge, natives OGG_OPUS für Sprachnachrichten-Ziele und rohes PCM mit 22050 Hz für Talk/Telefonie.
• xAI: Standardmäßig MP3; die Audiodateisynthese kann mp3, wav, pcm, mulaw oder alaw sowohl für gepufferte als auch für Streaming-Ausgaben verwenden. Sprachnachrichten-Ziele verwenden MP3 für Streaming und den gepufferten Fallback, da die Ausgaben pcm, mulaw und alaw von xAI headerlose Rohaudiodaten sind. Die gepufferte Synthese verwendet den Batch-REST-Endpunkt /v1/tts von xAI; textToSpeechStream verwendet natives wss://api.x.ai/v1/tts. Dies ist nicht der Echtzeit-Sprachvertrag. Das native Opus-Sprachnachrichtenformat wird nicht unterstützt.
• Microsoft: Verwendet microsoft.outputFormat (Standardwert audio-24khz-48kbitrate-mono-mp3).
  • Der gebündelte Transport akzeptiert ein outputFormat, aber nicht alle Formate sind über den Dienst verfügbar.
  • Ausgabeformatwerte entsprechen 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.
  • Wenn keine explizite Stimmenüberschreibung festgelegt ist und die englische Standardstimme verwendet wird, wechselt OpenClaw automatisch zu einer chinesischen neuronalen Stimme (zh-CN-XiaoxiaoNeural, Gebietsschema zh-CN), falls der Antworttext überwiegend aus CJK-Zeichen besteht.

Die Ausgabeformate von OpenAI und ElevenLabs sind wie oben aufgeführt je Kanal festgelegt.

Verhalten von Auto-TTS

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

• Überspringt TTS, wenn die Antwort bereits strukturierte Medien enthält.
• Überspringt sehr kurze Antworten (unter 10 Zeichen).
• Fasst lange Antworten zusammen, wenn Zusammenfassungen aktiviert sind, und verwendet dabei summaryModel (oder agents.defaults.model.primary).
• Fügt das erzeugte Audio der Antwort hinzu.
• Sendet in mode: "final" nach Abschluss des Textstreams weiterhin reine TTS-Audioausgaben für gestreamte endgültige Antworten; die erzeugten Medien durchlaufen dieselbe Kanalmedien-Normalisierung wie normale Antwortanhänge.

Wenn die Antwort maxLength überschreitet, überspringt OpenClaw die Audioausgabe niemals vollständig:

• Zusammenfassung aktiviert (Standard) und ein Zusammenfassungsmodell ist verfügbar: Fasst den Text auf ungefähr maxLength Zeichen zusammen und synthetisiert anschließend die Zusammenfassung.
• Zusammenfassung deaktiviert, die Zusammenfassung schlägt fehl oder für das Zusammenfassungsmodell ist kein API-Schlüssel verfügbar: Kürzt den Text auf maxLength Zeichen und synthetisiert den gekürzten Text.

Antwort -> TTS aktiviert?  nein -> Text senden  ja   -> enthält Medien / kurz?          ja   -> Text senden          nein -> Länge > Grenzwert?                   nein -> TTS -> Audio anhängen                   ja   -> Zusammenfassung aktiviert und verfügbar?                            nein -> kürzen -> TTS -> Audio anhängen                            ja   -> zusammenfassen -> TTS -> Audio anhängen

Feldreferenz

Agentenwerkzeug

Das Werkzeug tts wandelt Text in Sprache um und gibt einen Audioanhang für die Zustellung der Antwort zurück. Bei Feishu, Matrix, Telegram und WhatsApp wird das Audio als Sprachnachricht statt als Dateianhang zugestellt. Feishu und WhatsApp können auf diesem Pfad TTS-Ausgaben, die nicht im Opus-Format vorliegen, transkodieren, wenn ffmpeg verfügbar ist.

WhatsApp sendet Audiodaten über Baileys als PTT-Sprachnachricht (audio mit ptt: true) und sendet sichtbaren Text getrennt vom PTT-Audio, da Clients Untertitel bei Sprachnachrichten nicht einheitlich darstellen.

Das Werkzeug akzeptiert die optionalen Felder channel und timeoutMs; timeoutMs ist eine Provider-Anfragezeitüberschreitung pro Aufruf in Millisekunden. Werte pro Aufruf überschreiben tts.timeoutMs; konfigurierte TTS-Zeitüberschreitungen überschreiben alle vom Plugin definierten Provider-Standardwerte.

Gateway-RPC

Service-Links

• OpenAI-Leitfaden zur Text-zu-Sprache-Umwandlung
• OpenAI-Audio-API-Referenz
• Azure Speech REST-Text-zu-Sprache
• Azure-Speech-Provider
• ElevenLabs Text-zu-Sprache
• 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-zu-Sprache

Verwandte Themen

• Medienübersicht
• Musikgenerierung
• Videogenerierung
• Slash-Befehle
• Plugin für Sprachanrufe