OpenClaw Text-to-Speech einrichten: ElevenLabs & OpenAI

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 oder Fallback-Provider)
Microsoft (primärer oder Fallback-Provider; die aktuelle Implementierung nutzt node-edge-tts)
OpenAI (primärer oder Fallback-Provider; wird auch für Zusammenfassungen verwendet)

Microsoft Sprach-Hinweise

Der integrierte Microsoft-Provider nutzt aktuell den Online-Neural-TTS-Dienst von Microsoft Edge über die node-edge-tts Library. Es handelt sich um einen gehosteten Dienst (nicht lokal), der Microsoft-Endpunkte verwendet und keinen API Key benötigt. node-edge-tts bietet Sprachkonfigurationsoptionen und Ausgabeformate, allerdings werden nicht alle Optionen vom Dienst unterstützt. Alte Konfigurationen und Directives mit edge funktionieren weiterhin und werden automatisch zu microsoft umgewandelt.

Da dieser Pfad ein öffentlicher Webdienst ohne veröffentlichtes SLA oder Quoten ist, solltest du ihn als Best-Effort-Lösung betrachten. Wenn du garantierte Limits und Support benötigst, empfehle ich dir OpenAI oder ElevenLabs.

Optionale Keys

Wenn du OpenAI oder ElevenLabs nutzen möchtest:

ELEVENLABS_API_KEY (oder XI_API_KEY)
OPENAI_API_KEY

Microsoft benötigt keinen API Key.

Falls du mehrere Provider konfigurierst, wird der ausgewählte Provider zuerst genutzt und die anderen dienen als Fallback-Optionen. Auto-Summary verwendet 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 Konfiguration mit messages.tts.auto oder pro Session mit /tts always (Alias: /tts on) einschalten.

Wenn messages.tts.provider nicht festgelegt ist, wählt OpenClaw den ersten konfigurierten Provider basierend auf der automatischen Auswahlreihenfolge im Registry aus.

Konfiguration

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

Minimale Konfiguration (Aktivierung + Provider)

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

OpenAI als Hauptanbieter 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 als Hauptanbieter (ohne 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 Speech 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",
    },
  },
}

Audio-Antwort nur nach eingehender Sprachnachricht

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

Auto-Zusammenfassung für lange Antworten deaktivieren

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

Führe danach diesen Befehl aus:

/tts summary off

Hinweise zu den Feldern

auto: Modus für automatisches TTS (off, always, inbound, tagged).
- inbound sendet Audio nur nach einer eingehenden Sprachnachricht.
- tagged sendet Audio nur, wenn die Antwort [[tts]] Tags enthält.
enabled: Veralteter Schalter (der Doctor migriert dies automatisch zu auto).
mode: "final" (Standard) oder "all" (beinhaltet Antworten von Tools/Blöcken).
provider: ID des Sprach-Providers wie "elevenlabs", "microsoft" oder "openai" (Fallback erfolgt automatisch).
Wenn provider nicht gesetzt ist, nutzt OpenClaw den ersten konfigurierten Provider gemäß der Registry-Reihenfolge.
Der veraltete Wert provider: "edge" funktioniert weiterhin und wird intern zu microsoft umgewandelt.
summaryModel: Optionales, günstiges Modell für die automatische Zusammenfassung; Standard ist agents.defaults.model.primary.
- Akzeptiert provider/model oder einen konfigurierten Modell-Alias.
modelOverrides: Erlaubt dem Modell, TTS-Anweisungen zu geben (standardmäßig aktiviert).
- allowProvider ist standardmäßig false (Provider-Wechsel muss explizit erlaubt werden).
providers.<id>: Provider-spezifische Einstellungen, sortiert nach der ID des Sprach-Providers.
Veraltete direkte Provider-Blöcke (messages.tts.openai, messages.tts.elevenlabs, messages.tts.microsoft, messages.tts.edge) werden beim Laden automatisch nach messages.tts.providers.<id> migriert.
maxTextLength: Maximale Zeichenanzahl für den TTS-Input. /tts audio schlägt bei Überschreitung fehl.
timeoutMs: Zeitüberschreitung für Anfragen (ms).
prefsPath: Überschreibt den lokalen Pfad für die Präferenzen-JSON (Provider/Limit/Zusammenfassung).
apiKey Werte nutzen als Fallback Umgebungsvariablen (ELEVENLABS_API_KEY/XI_API_KEY, OPENAI_API_KEY).
providers.elevenlabs.baseUrl: Überschreibt die Basis-URL der ElevenLabs API.
providers.openai.baseUrl: Überschreibt den OpenAI TTS Endpunkt.
- Reihenfolge der Auflösung: messages.tts.providers.openai.baseUrl -> OPENAI_TTS_BASE_URL -> https://api.openai.com/v1
- Andere Werte als der Standard werden als OpenAI-kompatible TTS-Endpunkte behandelt, sodass eigene Modell- und Stimmnamen akzeptiert werden.
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: Ganzzahl 0..4294967295 (für bestmögliche Deterministik)
providers.microsoft.enabled: Erlaubt die Nutzung von Microsoft Speech (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 in den Microsoft Speech Dokumentationen; 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 Speech Anfragen.
providers.microsoft.timeoutMs: Eigene Zeitüberschreitung für Anfragen (ms).
edge.*: Veralteter Alias für dieselben Microsoft-Einstellungen.

Modellgesteuerte Overrides (standardmäßig aktiviert)

Standardmäßig kann das Modell TTS-Anweisungen für eine einzelne Antwort ausgeben. Wenn messages.tts.auto auf tagged eingestellt ist, sind diese Anweisungen zwingend erforderlich, um Audio zu erzeugen.

Wenn aktiviert, kann das Modell [[tts:...]] Anweisungen nutzen, um die Stimme für eine Antwort zu ändern. Zusätzlich gibt es einen optionalen [[tts:text]]...[[/tts:text]] Block für expressive Tags (wie Lachen oder Gesangshinweise), die nur in der Audioausgabe erscheinen sollen.

provider=... Anweisungen 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 Schlüssel für Anweisungen (wenn aktiviert):

provider (ID eines registrierten Providers, z. B. openai, elevenlabs oder microsoft; benötigt allowProvider: true)
voice (OpenAI Stimme) 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,
      },
    },
  },
}

Benutzerspezifische Einstellungen

Mit Slash commands schreibst du lokale Overrides direkt in den prefsPath. Standardmäßig ist das ~/.openclaw/settings/tts.json, aber du kannst den Pfad mit OPENCLAW_TTS_PREFS oder messages.tts.prefsPath überschreiben.

Diese Felder werden gespeichert:

enabled
provider
maxLength (Schwellenwert für die Zusammenfassung; Standard sind 1500 Zeichen)
summarize (Standardmäßig auf true gesetzt)

Diese Werte überschreiben die Einstellungen unter messages.tts.* für den jeweiligen Host.

Ausgabeformate (festgelegt)

Feishu / Matrix / Telegram / WhatsApp: Hier werden Opus Sprachnachrichten verwendet (opus_48000_64 bei ElevenLabs, opus bei OpenAI). 48kHz bei 64kbps ist ein guter Kompromiss für Sprachnachrichten.
Andere Kanäle: Hier kommt MP3 zum Einsatz (mp3_44100_128 bei ElevenLabs, mp3 bei OpenAI). 44.1kHz bei 128kbps ist die Standard-Balance für eine klare Sprachausgabe.
Microsoft: Nutzt microsoft.outputFormat (Standard ist audio-24khz-48kbitrate-mono-mp3).
- Der integrierte Transport akzeptiert ein outputFormat, allerdings stellt der Service nicht alle Formate zur Verfügung.
- Die Werte für das Ausgabeformat richten sich nach den Microsoft Speech Formaten (einschließlich Ogg/WebM Opus).
- Telegram sendVoice akzeptiert OGG, MP3 und M4A. Wenn du garantiert Opus Sprachnachrichten willst, solltest du OpenAI oder ElevenLabs wählen.
- Falls das konfigurierte Microsoft-Format fehlschlägt, macht OpenClaw einen automatischen Retry mit MP3.

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

AI Setup Assistant

Auto-TTS-Verhalten

Wenn du die Funktion aktivierst, folgt OpenClaw einer klaren Logik, um die TTS-Ausgabe sinnvoll zu steuern und unnötige API-Aufrufe zu vermeiden:

TTS wird übersprungen, wenn die Antwort bereits Medien oder eine MEDIA:-Anweisung enthält.
Sehr kurze Antworten (< 10 Zeichen) werden ignoriert.
Lange Antworten werden zusammengefasst, sofern du dies über agents.defaults.model.primary (oder summaryModel) aktiviert hast.
Das generierte Audio wird automatisch an die Antwort angehängt.

Falls die Antwort das Limit von maxLength überschreitet und die Zusammenfassung deaktiviert ist (oder kein API-Key für das Summary-Model vorliegt), wird das Audio übersprungen. In diesem Fall erhältst du nur die normale Textantwort. Ich empfehle dir, das Summary-Model immer zu konfigurieren, damit der Flow auch bei längeren Texten nicht unterbrochen wird.

Flow-Diagramm

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

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

Hinweis zu Discord: /tts ist ein integrierter Discord-Befehl, daher registriert OpenClaw dort /voice als nativen Befehl. Der Text /tts ... funktioniert trotzdem.

/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 (Allowlist- und Owner-Regeln gelten weiterhin).
commands.text oder die native Befehlsregistrierung muss aktiviert sein.
off|always|inbound|tagged sind Toggles pro Session (/tts on ist ein Alias für /tts always).
limit und summary werden in den lokalen Prefs gespeichert, nicht in der Hauptkonfiguration.
/tts audio generiert eine einmalige Audio-Antwort (aktiviert TTS nicht dauerhaft).
/tts status enthält die Fallback-Sichtbarkeit für den letzten Versuch:
- Erfolg: Fallback: <primary> -> <used> plus Attempts: ...
- Fehler: Error: ... plus Attempts: ...
- Detaillierte Diagnose: Attempt details: provider:outcome(reasonCode) latency
Fehler bei der OpenAI und ElevenLabs API enthalten jetzt detaillierte Fehlermeldungen des Providers und die Request-ID (sofern vom Provider zurückgegeben), die in den TTS-Fehlern oder Logs angezeigt werden.

Agent Tool

Das tts Tool wandelt Text in Sprache um und gibt einen Audio-Anhang für die Antwort aus. Wenn der Channel Feishu, Matrix, Telegram oder WhatsApp ist, wird das Audio als Sprachnachricht statt als Dateianhang gesendet.

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.