Text-to-Speech (TTS)

OpenClaw kann ausgehende Antworten mit ElevenLabs, OpenAI oder Edge TTS in Audio umwandeln. Das funktioniert überall, wo OpenClaw Audio senden kann – bei Telegram erscheint eine runde Sprachnachricht-Blase.

Unterstützte Dienste

  • ElevenLabs (primärer oder Fallback-Provider)
  • OpenAI (primärer oder Fallback-Provider; wird auch für Zusammenfassungen verwendet)
  • Edge TTS (primärer oder Fallback-Provider; nutzt node-edge-tts, Standard wenn keine API-Keys vorhanden)

Edge TTS Hinweise

Edge TTS nutzt Microsofts Online-Neural-TTS-Service über die node-edge-tts-Bibliothek. Es ist ein gehosteter Service (nicht lokal), verwendet Microsoft-Endpoints und benötigt keinen API-Key. node-edge-tts bietet Zugriff auf Sprachkonfigurationsoptionen und Ausgabeformate, aber nicht alle Optionen werden vom Edge-Service unterstützt. citeturn2search0

Da Edge TTS ein öffentlicher Web-Service ohne veröffentlichtes SLA oder Quota ist, solltest du ihn als Best-Effort-Service betrachten. Wenn du garantierte Limits und Support brauchst, verwende OpenAI oder ElevenLabs. Microsofts Speech REST API dokumentiert ein 10-Minuten-Audio-Limit pro Request; Edge TTS veröffentlicht keine Limits, also geh von ähnlichen oder niedrigeren Limits aus. citeturn0search3

Optionale API-Keys

Wenn du OpenAI oder ElevenLabs nutzen möchtest:

  • ELEVENLABS_API_KEY (oder XI_API_KEY)
  • OPENAI_API_KEY

Edge TTS benötigt keinen API-Key. Wenn keine API-Keys gefunden werden, verwendet OpenClaw standardmäßig Edge TTS (außer du deaktivierst es mit messages.tts.edge.enabled=false).

Wenn mehrere Provider konfiguriert sind, wird der ausgewählte Provider zuerst verwendet und die anderen dienen als Fallback. Auto-Summary nutzt das konfigurierte summaryModel (oder agents.defaults.model.primary), daher muss dieser Provider auch authentifiziert sein, wenn du Zusammenfassungen aktivierst.

Ist TTS standardmäßig aktiviert?

Nein. Auto-TTS ist standardmäßig aus. Aktiviere es in der Config mit messages.tts.auto oder pro Session mit /tts always (Alias: /tts on).

Edge TTS ist standardmäßig aktiviert, sobald TTS eingeschaltet ist, und wird automatisch verwendet, wenn keine OpenAI- oder ElevenLabs-API-Keys verfügbar sind.

Konfiguration

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

Minimale Config (aktivieren + 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,
      },
      openai: {
        apiKey: "openai_api_key",
        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,
        },
      },
    },
  },
}

Edge TTS primär (ohne API-Key)

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

Edge TTS deaktivieren

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

Custom Limits + Prefs-Pfad

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

Nur Audio-Antwort nach eingehender Sprachnachricht

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

Auto-Summary für lange Antworten deaktivieren

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

Dann führe aus:

/tts summary off

Hinweise zu den Feldern

  • auto: Auto-TTS-Modus (off, always, inbound, tagged).
    • inbound sendet nur Audio nach einer eingehenden Sprachnachricht.
    • tagged sendet nur Audio, wenn die Antwort [[tts]]-Tags enthält.
  • enabled: Legacy-Toggle (Doctor migriert dies zu auto).
  • mode: "final" (Standard) oder "all" (inkl. Tool/Block-Antworten).
  • provider: "elevenlabs", "openai" oder "edge" (Fallback ist automatisch).
  • Wenn provider nicht gesetzt ist, bevorzugt OpenClaw openai (falls Key vorhanden), dann elevenlabs (falls Key vorhanden), sonst edge.
  • summaryModel: optionales günstiges Modell für Auto-Summary; Standard ist agents.defaults.model.primary.
    • Akzeptiert provider/model oder einen konfigurierten Model-Alias.
  • modelOverrides: erlaubt dem Modell, TTS-Direktiven auszugeben (standardmäßig an).
  • maxTextLength: Hartes Limit für TTS-Input (Zeichen). /tts audio schlägt fehl, wenn überschritten.
  • timeoutMs: Request-Timeout (ms).
  • prefsPath: überschreibt den lokalen Prefs-JSON-Pfad (Provider/Limit/Summary).
  • apiKey-Werte fallen zurück auf Umgebungsvariablen (ELEVENLABS_API_KEY/XI_API_KEY, OPENAI_API_KEY).
  • elevenlabs.baseUrl: überschreibt die ElevenLabs-API-Base-URL.
  • elevenlabs.voiceSettings:
    • stability, similarityBoost, style: 0..1
    • useSpeakerBoost: true|false
    • speed: 0.5..2.0 (1.0 = normal)
  • elevenlabs.applyTextNormalization: auto|on|off
  • elevenlabs.languageCode: 2-stelliger ISO 639-1-Code (z. B. en, de)
  • elevenlabs.seed: Integer 0..4294967295 (Best-Effort-Determinismus)
  • edge.enabled: erlaubt Edge-TTS-Nutzung (Standard true; kein API-Key nötig).
  • edge.voice: Edge-Neural-Voice-Name (z. B. en-US-MichelleNeural).
  • edge.lang: Sprachcode (z. B. en-US).
  • edge.outputFormat: Edge-Ausgabeformat (z. B. audio-24khz-48kbitrate-mono-mp3).
    • Siehe Microsoft Speech Output Formats für gültige Werte; nicht alle Formate werden von Edge unterstützt.
  • edge.rate / edge.pitch / edge.volume: Prozent-Strings (z. B. +10%, -5%).
  • edge.saveSubtitles: schreibt JSON-Untertitel neben die Audio-Datei.
  • edge.proxy: Proxy-URL für Edge-TTS-Requests.
  • edge.timeoutMs: Request-Timeout-Override (ms).

Modellgesteuerte Overrides (standardmäßig an)

Standardmäßig kann das Modell TTS-Direktiven für eine einzelne Antwort ausgeben. Wenn messages.tts.auto auf tagged steht, sind diese Direktiven erforderlich, um Audio auszulösen.

Wenn aktiviert, kann das Modell [[tts:...]]-Direktiven ausgeben, um die Stimme für eine einzelne Antwort zu überschreiben, plus einen optionalen [[tts:text]]...[[/tts:text]]-Block, um expressive Tags (Lachen, Gesangs-Cues, etc.) bereitzustellen, die nur im Audio erscheinen sollen.

Beispiel-Antwort-Payload:

Hier bitte.

[[tts:provider=elevenlabs voiceId=pMsXgVXv3BLzUgSXRplE model=eleven_v3 speed=1.1]]
[[tts:text]](lacht) Lies das Lied noch einmal.[[/tts:text]]

Verfügbare Direktiven-Keys (wenn aktiviert):

  • provider (openai | elevenlabs | edge)
  • 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 (bestimmte Overrides deaktivieren, während Tags aktiviert bleiben):

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

Benutzerspezifische Einstellungen

Slash-Befehle schreiben lokale Overrides in prefsPath (Standard: ~/.openclaw/settings/tts.json, überschreibbar mit OPENCLAW_TTS_PREFS oder messages.tts.prefsPath).

Gespeicherte Felder:

  • enabled
  • provider
  • maxLength (Summary-Schwellenwert; Standard 1500 Zeichen)
  • summarize (Standard true)

Diese überschreiben messages.tts.* für diesen Host.

Ausgabeformate (fest)

  • Telegram: Opus-Sprachnachricht (opus_48000_64 von ElevenLabs, opus von OpenAI).
    • 48kHz / 64kbps ist ein guter Kompromiss für Sprachnachrichten und erforderlich für die runde Blase.
  • Andere Channels: MP3 (mp3_44100_128 von ElevenLabs, mp3 von OpenAI).
    • 44,1kHz / 128kbps ist die Standard-Balance für Sprachklarheit.
  • Edge TTS: verwendet edge.outputFormat (Standard audio-24khz-48kbitrate-mono-mp3).
    • node-edge-tts akzeptiert ein outputFormat, aber nicht alle Formate sind vom Edge-Dienst verfügbar. citeturn2search0
    • Ausgabeformat-Werte folgen Microsoft Speech Output Formats (inkl. Ogg/WebM Opus). citeturn1search0
    • Telegram sendVoice akzeptiert OGG/MP3/M4A; nutze OpenAI/ElevenLabs, wenn du garantierte Opus-Sprachnachrichten brauchst. citeturn1search1
    • Wenn das konfigurierte Edge-Ausgabeformat fehlschlägt, versucht OpenClaw es erneut mit MP3.

OpenAI/ElevenLabs-Formate sind fest; Telegram erwartet Opus für Sprachnachrichten-UX.

Auto-TTS-Verhalten

Wenn aktiviert, macht OpenClaw Folgendes:

  • überspringt TTS, wenn die Antwort bereits Medien oder eine MEDIA:-Direktive enthält.
  • überspringt sehr kurze Antworten (< 10 Zeichen).
  • fasst lange Antworten zusammen, wenn aktiviert, mit agents.defaults.model.primary (oder summaryModel).
  • hängt das generierte Audio an die Antwort an.

Wenn die Antwort maxLength überschreitet und Summary aus ist (oder kein API-Key für das Summary-Modell vorhanden), wird Audio übersprungen und die normale Textantwort gesendet.

Flussdiagramm

Antwort -> TTS aktiviert?
  nein -> Text senden
  ja   -> hat Medien / MEDIA: / kurz?
          ja   -> Text senden
          nein -> Länge > Limit?
                   nein -> TTS -> Audio anhängen
                   ja   -> Summary aktiviert?
                            nein -> Text senden
                            ja   -> zusammenfassen (summaryModel oder agents.defaults.model.primary)
                                      -> TTS -> Audio anhängen

Slash-Befehl-Nutzung

Es gibt einen einzigen Befehl: /tts. Siehe Slash-Befehle für Details zur Aktivierung.

Discord-Hinweis: /tts ist ein eingebauter Discord-Befehl, daher registriert OpenClaw dort /voice als nativen Befehl. 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 Hallo von OpenClaw

Hinweise:

  • Befehle erfordern einen autorisierten Absender (Allowlist/Owner-Regeln gelten weiterhin).
  • commands.text oder native Befehlsregistrierung muss aktiviert sein.
  • off|always|inbound|tagged sind Session-Toggles (/tts on ist ein Alias für /tts always).
  • limit und summary werden in lokalen Prefs gespeichert, nicht in der Haupt-Config.
  • /tts audio generiert eine einmalige Audio-Antwort (schaltet TTS nicht ein).

Agent-Tool

Das tts-Tool wandelt Text in Sprache um und gibt einen MEDIA:-Pfad zurück. Wenn das Ergebnis Telegram-kompatibel ist, enthält das Tool [[audio_as_voice]], damit Telegram eine Sprachblase sendet.

Gateway-RPC

Gateway-Methoden:

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