OpenClaw Text-to-Speech: Sprachausgabe in Minuten einrichten

Text-to-Speech (TTS)

OpenClaw kann ausgehende Antworten mit ElevenLabs, Microsoft oder OpenAI in Audio umwandeln. Das funktioniert überall dort, wo OpenClaw Audio senden kann.

Unterstützte Dienste

ElevenLabs (Primärer Provider oder Fallback)
Microsoft (Primärer Provider oder Fallback; die aktuelle Implementierung nutzt node-edge-tts)
OpenAI (Primärer Provider oder Fallback; wird auch für Zusammenfassungen genutzt)

Hinweise zu Microsoft Speech

Der integrierte Microsoft-Sprachprovider nutzt aktuell den Online-Dienst für neuronale TTS von Microsoft Edge über die node-edge-tts Library. Es handelt sich um einen gehosteten Service (nicht lokal), der Microsoft-Endpoints nutzt und keinen API-Key erfordert. node-edge-tts bietet verschiedene Konfigurationsoptionen und Ausgabeformate, allerdings unterstützt der Service nicht alle Optionen. Alte Konfigurationen oder Directives mit edge funktionieren weiterhin und werden automatisch zu microsoft umgewandelt.

Da dieser Pfad ein öffentlicher Webdienst ohne garantiertes SLA oder Quoten ist, solltest du ihn als Best-Effort-Lösung betrachten. Wenn du garantierte Limits und Support brauchst, nutze OpenAI oder ElevenLabs.

Optionale Keys

Wenn du OpenAI oder ElevenLabs nutzen möchtest:

ELEVENLABS_API_KEY (oder XI_API_KEY)
OPENAI_API_KEY

Microsoft Speech benötigt keinen API-Key.

Falls du mehrere Provider konfiguriert hast, wird der gewählte Provider zuerst genutzt und die anderen dienen als Fallback. Die automatische Zusammenfassung nutzt das konfigurierte summaryModel (oder agents.defaults.model.primary). Dieser Provider muss also ebenfalls authentifiziert sein, wenn du Summaries aktivierst.

Service-Links

Ist es standardmäßig aktiviert?

Nein. Auto-TTS ist standardmäßig deaktiviert. Du kannst es in der Config über messages.tts.auto einschalten oder pro Session mit /tts always (Alias: /tts on).

Wenn messages.tts.provider nicht gesetzt ist, wählt OpenClaw automatisch den ersten konfigurierten Sprachprovider aus der Registry.

Konfiguration

Die TTS-Konfiguration findest du unter messages.tts in der openclaw.json. Das vollständige Schema findest du in der Gateway configuration.

Minimale Konfiguration (Aktivierung + Provider)

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

OpenAI primär mit ElevenLabs Fallback

{
  messages: {
    tts: {
      auto: "always",
      provider: "openai",
      summaryModel: "openai/gpt-4.1-mini",
      modelOverrides: {
        enabled: true,
      },
      providers: {
        openai: {
          apiKey: "openai_api_key",
          baseUrl: "https://api.openai.com/v1",
          model: "gpt-4o-mini-tts",
          voice: "alloy",
        },
        elevenlabs: {
          apiKey: "elevenlabs_api_key",
          baseUrl: "https://api.elevenlabs.io",
          voiceId: "voice_id",
          modelId: "eleven_multilingual_v2",
          seed: 42,
          applyTextNormalization: "auto",
          languageCode: "en",
          voiceSettings: {
            stability: 0.5,
            similarityBoost: 0.75,
            style: 0.0,
            useSpeakerBoost: true,
            speed: 1.0,
          },
        },
      },
    },
  },
}

Microsoft primär (kein API-Key)

{
  messages: {
    tts: {
      auto: "always",
      provider: "microsoft",
      providers: {
        microsoft: {
          enabled: true,
          voice: "en-US-MichelleNeural",
          lang: "en-US",
          outputFormat: "audio-24khz-48kbitrate-mono-mp3",
          rate: "+10%",
          pitch: "-5%",
        },
      },
    },
  },
}

Microsoft Sprachausgabe deaktivieren

{
  messages: {
    tts: {
      providers: {
        microsoft: {
          enabled: false,
        },
      },
    },
  },
}

Eigene Limits + Pfad für Präferenzen

{
  messages: {
    tts: {
      auto: "always",
      maxTextLength: 4000,
      timeoutMs: 30000,
      prefsPath: "~/.openclaw/settings/tts.json",
    },
  },
}

Nur mit Audio antworten nach einer eingehenden Sprachnachricht

{
  messages: {
    tts: {
      auto: "inbound",
    },
  },
}

Auto-Summary für lange Antworten deaktivieren

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

Führe danach diesen Befehl aus:

/tts summary off

Hinweise zu den Feldern

auto: Auto-TTS-Modus (off, always, inbound, tagged).
- inbound sendet Audio nur nach einer eingehenden Sprachnachricht.
- tagged sendet Audio nur, wenn die Antwort [[tts]]-Tags enthält.
enabled: Legacy-Schalter (der Doctor migriert dies zu auto).
mode: "final" (Standard) oder "all" (beinhaltet Tool/Block-Antworten).
provider: ID des Sprach-Providers wie "elevenlabs", "microsoft" oder "openai" (Fallback erfolgt automatisch).
Wenn provider nicht gesetzt ist, nutzt OpenClaw den ersten konfigurierten Sprach-Provider in der Registry-Reihenfolge.
Legacy provider: "edge" funktioniert weiterhin und wird zu microsoft normalisiert.
summaryModel: Optionales, günstiges Modell für Auto-Summary; Standard ist agents.defaults.model.primary.
- Akzeptiert provider/model oder einen konfigurierten Modell-Alias.
modelOverrides: Erlaubt dem Modell, TTS-Directives auszugeben (standardmäßig an).
- allowProvider ist standardmäßig false (Provider-Wechsel muss explizit erlaubt werden).
providers.<id>: Provider-spezifische Einstellungen, zugeordnet über die Sprach-Provider-ID.
Legacy-Blöcke für direkte Provider (messages.tts.openai, messages.tts.elevenlabs, messages.tts.microsoft, messages.tts.edge) werden beim Laden automatisch zu messages.tts.providers.<id> migriert.
maxTextLength: Harte Obergrenze für den TTS-Input (Zeichen). /tts audio schlägt fehl, wenn dieser Wert überschritten wird.
timeoutMs: Timeout für Anfragen (ms).
prefsPath: Überschreibt den lokalen Pfad für die Präferenzen-JSON (Provider/Limit/Summary).
apiKey-Werte greifen auf Umgebungsvariablen zurück (ELEVENLABS_API_KEY/XI_API_KEY, OPENAI_API_KEY).
providers.elevenlabs.baseUrl: Überschreibt die ElevenLabs API Base-URL.
providers.openai.baseUrl: Überschreibt den OpenAI TTS Endpoint.
- Auflösungsreihenfolge: messages.tts.providers.openai.baseUrl -> OPENAI_TTS_BASE_URL -> https://api.openai.com/v1
- Nicht-Standardwerte werden als OpenAI-kompatible TTS-Endpoints behandelt, daher werden eigene Modell- und Stimmennamen akzeptiert.
providers.elevenlabs.voiceSettings:
- stability, similarityBoost, style: 0..1
- useSpeakerBoost: true|false
- speed: 0.5..2.0 (1.0 = normal)
providers.elevenlabs.applyTextNormalization: auto|on|off
providers.elevenlabs.languageCode: 2-stelliger ISO 639-1 Code (z. B. en, de)
providers.elevenlabs.seed: Integer 0..4294967295 (bestmögliche Deterministik)
providers.microsoft.enabled: Erlaubt die Nutzung der Microsoft-Sprachausgabe (Standard true; kein API-Key nötig).
providers.microsoft.voice: Name der Microsoft Neural Voice (z. B. en-US-MichelleNeural).
providers.microsoft.lang: Sprachcode (z. B. en-US).
providers.microsoft.outputFormat: Microsoft Ausgabeformat (z. B. audio-24khz-48kbitrate-mono-mp3).
- Gültige Werte findest du bei den Microsoft Speech Ausgabeformaten; nicht alle Formate werden vom integrierten Edge-Transport unterstützt.
providers.microsoft.rate / providers.microsoft.pitch / providers.microsoft.volume: Prozentangaben als String (z. B. +10%, -5%).
providers.microsoft.saveSubtitles: Schreibt JSON-Untertitel parallel zur Audiodatei.
providers.microsoft.proxy: Proxy-URL für Microsoft Sprach-Anfragen.
providers.microsoft.timeoutMs: Override für den Request-Timeout (ms).
edge.*: Legacy-Alias für dieselben Microsoft-Einstellungen.

Modellgesteuerte Overrides (standardmäßig aktiviert)

Standardmäßig kann das Modell TTS-Directives für eine einzelne Antwort ausgeben. Wenn messages.tts.auto auf tagged eingestellt ist, sind diese Directives erforderlich, um die Sprachausgabe zu triggern.

Wenn aktiviert, kann das Modell [[tts:...]]-Directives ausgeben, um die Stimme für eine einzelne Antwort zu überschreiben. Zusätzlich ist ein optionaler [[tts:text]]...[[/tts:text]]-Block möglich, um expressive Tags (Lachen, Gesangshinweise etc.) einzufügen, die nur in der Audiodatei erscheinen sollen.

provider=...-Directives werden ignoriert, außer modelOverrides.allowProvider: true ist gesetzt.

Beispiel für eine Antwort:

Here you go.

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

Verfügbare Directive-Keys (wenn aktiviert):

provider (registrierte Sprach-Provider-ID, zum Beispiel openai, elevenlabs oder microsoft; erfordert allowProvider: true)
voice (OpenAI Voice) oder voiceId (ElevenLabs)
model (OpenAI TTS Modell oder ElevenLabs Modell-ID)
stability, similarityBoost, style, speed, useSpeakerBoost
applyTextNormalization (auto|on|off)
languageCode (ISO 639-1)
seed

Alle Modell-Overrides deaktivieren:

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

Optionale Allowlist (Provider-Wechsel erlauben, während andere Einstellungen konfigurierbar bleiben):

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

Benutzerdefinierte Einstellungen

Slash-Commands schreiben lokale Overrides direkt in den prefsPath. Standardmäßig ist das ~/.openclaw/settings/tts.json, aber du kannst diesen Pfad über OPENCLAW_TTS_PREFS oder messages.tts.prefsPath anpassen.

Diese Felder werden gespeichert:

enabled
provider
maxLength (Schwellenwert für Zusammenfassungen; Standard: 1500 Zeichen)
summarize (Standard: true)

Diese Einstellungen überschreiben messages.tts.* für den jeweiligen Host. Ich empfehle dir, diese Overrides zu nutzen, um das Verhalten für einzelne User präzise zu steuern.

Ausgabeformate (festgelegt)

Feishu / Matrix / Telegram / WhatsApp: Opus Sprachnachricht (opus_48000_64 von ElevenLabs, opus von OpenAI). 48kHz / 64kbps ist hier ein sehr guter Kompromiss für Sprachnachrichten.
Andere Kanäle: MP3 (mp3_44100_128 von ElevenLabs, mp3 von OpenAI). 44.1kHz / 128kbps ist die Standard-Balance für klare Sprache.
Microsoft: Nutzt microsoft.outputFormat (Standard: audio-24khz-48kbitrate-mono-mp3). Der integrierte Transport akzeptiert zwar ein outputFormat, aber der Service bietet nicht jedes Format an. Die Werte folgen den Microsoft Speech Ausgabeformaten (inklusive Ogg/WebM Opus). Telegram sendVoice akzeptiert OGG, MP3, M4A sowie weitere Formate. Nutze OpenAI oder ElevenLabs, wenn du garantierte Opus-Sprachnachrichten brauchst. Falls das konfigurierte Microsoft-Format fehlschlägt, versucht OpenClaw automatisch einen Retry mit MP3.

Die Ausgabeformate für OpenAI und ElevenLabs sind pro Kanal fest vorgegeben (siehe oben).

Auto-TTS-Verhalten

Wenn du die Funktion aktivierst, arbeitet OpenClaw nach einer klaren Logik. Ich empfehle dir, die Zusammenfassung immer zu aktivieren, damit deine User nicht von ewig langen Audio-Files erschlagen werden.

OpenClaw überspringt TTS, wenn die Antwort bereits Medien oder eine MEDIA:-Anweisung enthält.
Sehr kurze Antworten (< 10 Zeichen) werden ignoriert, um unnötige API-Calls zu sparen.
Lange Antworten werden automatisch zusammengefasst, wenn du das konfiguriert hast. Dafür wird agents.defaults.model.primary (oder summaryModel) verwendet.
Das fertige Audio wird direkt an die Antwort angehängt.

Sollte die Antwort die maxLength überschreiten und die Zusammenfassung ist aus (oder es fehlt der API-Key für das Summary-Model), wird das Audio einfach weggelassen und nur die normale Textantwort gesendet.

Flussdiagramm

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 (summaryModel or agents.defaults.model.primary)
                                      -> TTS -> attach audio

Nutzung von Slash-Commands

Es gibt einen einzigen Befehl: /tts. Schau dir die Slash commands an, um Details zur Aktivierung zu erfahren.

Discord-Hinweis: Da /tts ein nativer Discord-Befehl ist, registriert OpenClaw dort /voice als eigenen Befehl. Text-Eingaben wie /tts ... funktionieren aber weiterhin.

/tts off
/tts always
/tts inbound
/tts tagged
/tts status
/tts provider openai
/tts limit 2000
/tts summary off
/tts audio Hello from OpenClaw

Hinweise:

Befehle erfordern einen autorisierten Absender (die Regeln für Allowlist/Owner gelten weiterhin).
commands.text oder die native Befehlsregistrierung muss aktiviert sein.
off|always|inbound|tagged sind Schalter pro Session (/tts on ist ein Alias für /tts always).
limit und summary werden in den lokalen Prefs gespeichert, nicht in der Haupt-Config.
/tts audio erzeugt eine einmalige Audio-Antwort (schaltet TTS nicht dauerhaft ein).
/tts status zeigt Details zum Fallback für den letzten Versuch:
- Erfolg bei Fallback: Fallback: <primary> -> <used> plus Attempts: ...
- Fehler: Error: ... plus Attempts: ...
- Diagnose-Details: Attempt details: provider:outcome(reasonCode) latency
Fehler bei der OpenAI und ElevenLabs API enthalten jetzt Details vom Provider und die Request-ID (falls vorhanden). Diese Infos siehst du direkt in den TTS-Fehlern oder Logs.

Agent-Tool

Das tts Tool wandelt Text in Sprache um und gibt einen Audio-Anhang für die Antwort zurück. Wenn du Feishu, Matrix, Telegram oder WhatsApp nutzt, wird das Audio direkt als Sprachnachricht gesendet, anstatt als einfacher Dateianhang.

Gateway RPC

Gateway-Methoden:

tts.status
tts.enable
tts.disable
tts.convert
tts.setProvider
tts.providers

OpenClaw Expert

Noch festgefahren?

Wenn diese Seite nicht hilft, frage OpenClaw Expert nach Schritt-fuer-Schritt-Loesungen.