Text-to-Speech (TTS)

OpenClaw kann ausgehende Antworten per ElevenLabs, OpenAI oder Edge TTS in Audio umwandeln. Es funktioniert überall dort, 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-Dienst über die node-edge-tts-Bibliothek. Es ist ein gehosteter Dienst (nicht lokal), verwendet Microsoft-Endpunkte und benötigt keinen API-Key. node-edge-tts bietet Sprachkonfigurations-Optionen und Ausgabeformate, aber nicht alle Optionen werden vom Edge-Dienst unterstützt. citeturn2search0

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

Optionale Keys

Wenn du OpenAI oder ElevenLabs verwenden 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 (es sei denn, es wird über messages.tts.edge.enabled=false deaktiviert).

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), also muss dieser Provider ebenfalls authentifiziert sein, wenn du Zusammenfassungen aktivierst.

Ist es standardmäßig aktiviert?

Nein. Auto-TTS ist standardmäßig deaktiviert. Aktiviere es in der Konfiguration 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 vorhanden sind.

Konfiguration

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

Minimale Konfiguration (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",
        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,
        },
      },
    },
  },
}

Edge TTS primär (kein 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,
      },
    },
  },
}

Benutzerdefinierte Limits + Prefs-Pfad

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

Nur nach eingehender Sprachnachricht mit Audio antworten

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

Auto-Summary für lange Antworten deaktivieren

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

Dann ausführen:

/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-Toggle (Doctor migriert dies zu auto).
  • mode: "final" (Standard) oder "all" (enthält Tool-/Block-Replies).
  • provider: "elevenlabs", "openai" oder "edge" (Fallback erfolgt 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 Modell-Alias.
  • modelOverrides: erlaubt dem Modell, TTS-Direktiven auszugeben (standardmäßig an).
    • allowProvider ist standardmäßig false (Provider-Wechsel ist opt-in).
  • 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 auf Umgebungsvariablen zurück (ELEVENLABS_API_KEY/XI_API_KEY, OPENAI_API_KEY).
  • elevenlabs.baseUrl: überschreibt die ElevenLabs-API-Basis-URL.
  • openai.baseUrl: überschreibt den OpenAI-TTS-Endpunkt.
    • Auflösungsreihenfolge: messages.tts.openai.baseUrl -> OPENAI_TTS_BASE_URL -> https://api.openai.com/v1
    • Nicht-Standardwerte werden als OpenAI-kompatible TTS-Endpunkte behandelt, sodass benutzerdefinierte Modell- und Stimmnamen akzeptiert werden.
  • 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: Edge-TTS-Nutzung erlauben (Standard true; kein API-Key).
  • 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).
    • Gültige Werte findest du bei den Microsoft-Speech-Ausgabeformaten; nicht alle Formate werden von Edge unterstützt.
  • edge.rate / edge.pitch / edge.volume: Prozent-Strings (z. B. +10%, -5%).
  • edge.saveSubtitles: JSON-Untertitel neben der Audiodatei speichern.
  • edge.proxy: Proxy-URL für Edge-TTS-Anfragen.
  • 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 für expressive Tags (Lachen, Gesangs-Cues usw.), die nur im Audio erscheinen sollen.

provider=...-Direktiven werden ignoriert, es sei denn modelOverrides.allowProvider: true.

Beispiel-Reply-Payload:

Here you go.

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

Verfügbare Direktiven-Keys (wenn aktiviert):

  • provider (openai | elevenlabs | edge, erfordert 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, andere Einstellungen konfigurierbar lassen):

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

Benutzerspezifische Einstellungen

Slash-Commands 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-Schwellwert; Standard 1500 Zeichen)
  • summarize (Standard true)

Diese überschreiben messages.tts.* für den jeweiligen Host.

Ausgabeformate (fest)

  • Telegram: Opus-Sprachnachricht (opus_48000_64 von ElevenLabs, opus von OpenAI).
    • 48kHz / 64kbps ist ein guter Kompromiss für Sprachnachrichten und nötig 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 über den Edge-Dienst verfügbar. citeturn2search0
    • Ausgabeformat-Werte folgen den Microsoft-Speech-Ausgabeformaten (einschließlich Ogg/WebM Opus). citeturn1search0
    • Telegrams sendVoice akzeptiert OGG/MP3/M4A; verwende 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 die Sprachnachrichten-UX.

Auto-TTS-Verhalten

Wenn aktiviert, verhält sich OpenClaw wie folgt:

  • Ü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 die Zusammenfassung deaktiviert ist (oder kein API-Key für das Summary-Modell vorhanden), wird das Audio übersprungen und die normale Textantwort gesendet.

Ablaufdiagramm

Antwort -> TTS aktiviert?
  nein -> Text senden
  ja   -> Hat Medien / MEDIA: / zu 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-Command-Nutzung

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

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

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

Agent-Tool

Das tts-Tool wandelt Text in Sprache um und gibt einen MEDIA:-Pfad zurück. Wenn das Ergebnis Telegram-kompatibel ist, fügt das Tool [[audio_as_voice]] hinzu, damit Telegram eine Sprachnachrichten-Blase sendet.

Gateway-RPC

Gateway-Methoden:

  • tts.status
  • tts.enable
  • tts.disable
  • tts.convert
  • tts.setProvider
  • tts.providers
arrow_back
Zurück
Location Command
Weiter
Providers
arrow_forward