Sprachausgabe

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 ruft denselben Synthesepfad auf). Provider-native realtime-Talk-Sitzungen synthetisieren Sprache stattdessen innerhalb des Echtzeit-Providers; transcription-Sitzungen synthetisieren niemals eine Sprachantwort des Assistenten.

Schnellstart

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

Unterstützte Provider

Wenn mehrere Provider konfiguriert sind, wird zuerst der ausgewählte verwendet; die anderen dienen als Ausweichoptionen. Die 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 befindet sich unter messages.tts in ~/.openclaw/openclaw.json. Wählen Sie eine Voreinstellung aus und passen Sie den Provider-Block an. Die unten gezeigten Felder speakerVoice/speakerVoiceId sind kanonisch; die providerspezifischen Feldnamen voice/voiceId/voiceName funktionieren weiterhin als alte Aliasse.

{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",      // Optionale natürlichsprachliche Stilvorgaben:      // audioProfile: "Sprechen Sie in einem ruhigen Ton wie ein Podcast-Moderator.",      // 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",    },  },},},}

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

Stimmü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 tief mit messages.tts zusammengeführt, sodass die Provider-Zugangsdaten in der globalen Provider-Konfiguration verbleiben 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: { speakerVoiceId: "EXAVITQu4vr4xnSDxMaL" },          },        },      },    ],  },}

Um eine Persona pro Agent festzulegen, setzen Sie agents.list[].tts.persona neben der Provider- Konfiguration. Sie überschreibt messages.tts.persona global ausschließlich für diesen Agenten.

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

1. messages.tts
2. aktives agents.list[].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. Inline-Direktiven [[tts:...]], wenn Modellüberschreibungen aktiviert sind

Kanal- und Kontoüberschreibungen verwenden dieselbe Struktur wie messages.tts und werden tief mit den vorherigen Ebenen zusammengeführt, sodass gemeinsam genutzte Provider-Zugangsdaten in messages.tts verbleiben können, während ein Kanal oder Bot-Konto nur Sprecherstimme, Modell, Persona oder Auto-Modus ändert:

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

Personas

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

Minimale Persona

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

Vollständige Persona (Provider-neutraler Prompt)

{  messages: {    tts: {      auto: "always",      persona: "alfred",      personas: {        alfred: {          label: "Alfred",          description: "Trockener, warmherziger britischer Butler-Erzähler.",          provider: "google",          fallbackPolicy: "preserve-persona",          prompt: {            profile: "Ein brillanter britischer Butler. Trocken, geistreich, warmherzig, charmant, emotional ausdrucksstark und niemals beliebig.",            scene: "Ein ruhiges Arbeitszimmer spät in der Nacht. Nahmikrofon-Erzählung für einen vertrauenswürdigen Bediener.",            sampleContext: "Der Sprecher beantwortet eine private technische Anfrage mit prägnanter Sicherheit und trockenem Charme.",            style: "Kultiviert, zurückhaltend, leicht amüsiert.",            accent: "Britisches Englisch.",            pacing: "Bedächtig, mit kurzen dramatischen Pausen.",            constraints: ["Konfigurationswerte nicht laut vorlesen.", "Die Persona nicht erklären."],          },          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 Einstellung /tts persona <id>, falls gesetzt.
2. messages.tts.persona, falls gesetzt.
3. Keine Persona.

Bei der Provider-Auswahl haben explizite Angaben Vorrang:

1. Direkte Überschreibungen (CLI, Gateway, Talk, zulässige 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 die Konfigurationen in dieser Reihenfolge zusammen:

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

Verwendung von Persona-Prompts durch Provider

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

Fallback-Richtlinie

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

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

Die Provider-Auswahl einer Talk-Sitzung gilt jeweils für die 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 Übergabeanfrage übergeben. Das Öffnen einer Sprachsitzung sollte weder messages.tts noch globale 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 Ausdruckshinweise, die nur im Audio erscheinen sollen:

Hier ist es. [[tts:speakerVoiceId=pMsXgVXv3BLzUgSXRplE model=eleven_v3 speed=1.1]][[tts:text]](lacht) Lies das Lied noch einmal.[[/tts:text]]

Wenn messages.tts.auto auf "tagged" gesetzt ist, sind Direktiven erforderlich, um Audio auszulösen. Bei der Streaming-Blockübermittlung werden Direktiven aus dem sichtbaren Text entfernt, bevor der Kanal ihn erhält, selbst wenn sie auf benachbarte Blöcke verteilt sind.

provider=... wird ignoriert, sofern nicht modelOverrides.allowProvider: true gesetzt ist. Wenn eine Antwort provider=... deklariert, werden die anderen Schlüssel in dieser Direktive nur 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 Aliasse: 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 und andere Einstellungen weiterhin konfigurierbar halten:

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

Slash-Befehle

Ein 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 als always; /tts off schreibt sie als off.
• /tts chat on|off|default schreibt eine sitzungsbezogene Auto-TTS-Überschreibung 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 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).
• /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 gespeichert, nicht in der Hauptkonfiguration.
• /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 benutzerdefinierter Endpunkte.

Benutzerspezifische Einstellungen

Slash-Befehle schreiben lokale Überschreibungen nach prefsPath. Der Standardwert ist ~/.openclaw/settings/tts.json; überschreiben Sie ihn mit der Umgebungsvariable OPENCLAW_TTS_PREFS oder messages.tts.prefsPath.

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

Ausgabeformate

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

Hinweise nach Provider:

• Feishu-/WhatsApp-Transkodierung: Wenn eine Sprachnachrichten-Antwort als MP3/WebM/WAV/M4A oder eine andere wahrscheinliche Audiodatei eingeht, 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 fängt Feishu den Fehler ab und sendet stattdessen die Originaldatei als normalen Anhang; WhatsApp hat keinen Fallback, daher schlägt der Sendevorgang selbst fehl, statt eine inkompatible PTT-Nutzlast zu veröffentlichen.
• MiniMax: MP3 (speech-2.8-hd-Modell, 32 kHz Abtastrate) für normale Audioanhänge; für vom Kanal angekündigte Sprachnachrichten-Ziele mit ffmpeg in Opus mit 48 kHz transkodiert.
• Xiaomi MiMo: Standardmäßig MP3 oder bei entsprechender Konfiguration WAV; für vom Kanal angekündigte Sprachnachrichten-Ziele 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 für Talk/Telefonie direkt PCM 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; responseFormat kann mp3, wav, pcm, mulaw oder alaw sein. Verwendet den Batch-REST-TTS-Endpunkt von xAI und gibt einen vollständigen Audioanhang zurück; der Streaming-TTS-WebSocket von xAI wird in diesem Provider-Pfad nicht verwendet. Das native Opus-Sprachnachrichtenformat wird nicht unterstützt.
• Microsoft: Verwendet microsoft.outputFormat (Standard audio-24khz-48kbitrate-mono-mp3).
  • Der mitgelieferte Transport akzeptiert ein outputFormat, aber nicht alle Formate sind beim Dienst verfügbar.
  • Die Werte für das Ausgabeformat 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 Stimmüberschreibung festgelegt ist und die englische Standardstimme verwendet wird, wechselt OpenClaw automatisch zu einer chinesischen neuronalen Stimme (zh-CN-XiaoxiaoNeural, Gebietsschema zh-CN), wenn der Antworttext überwiegend aus CJK-Zeichen besteht.

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

Verhalten von Auto-TTS

Wenn messages.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).
• Hängt die erzeugte Audiodatei an die Antwort an.
• Sendet im Modus mode: "final" weiterhin reines Audio-TTS für gestreamte abschließende Antworten, nachdem der Textstream abgeschlossen ist; die erzeugten Medien durchlaufen dieselbe Mediennormalisierung des Kanals 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

Agenten-Tool

Das Tool tts wandelt Text in Sprache um und gibt einen Audioanhang für die Antwortzustellung 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 Audio über Baileys als PTT-Sprachnachricht (audio mit ptt: true) und sendet sichtbaren Text separat vom PTT-Audio, da Clients Untertitel bei Sprachnachrichten nicht einheitlich darstellen.

Das Tool akzeptiert die optionalen Felder channel und timeoutMs; timeoutMs ist eine Provider-Anfragezeitüberschreitung pro Aufruf in Millisekunden. Werte pro Aufruf überschreiben messages.tts.timeoutMs; konfigurierte TTS-Zeitüberschreitungen überschreiben alle von Plugins festgelegten Provider-Standardwerte.

Gateway-RPC

Service-Links

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

Verwandte Themen

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