​

Text-to-Speech (TTS)

​

Unterstützte Dienste

• ElevenLabs (primärer oder Fallback-Provider)
• Microsoft (primärer oder Fallback-Provider; die aktuelle gebündelte Implementierung verwendet node-edge-tts)
• MiniMax (primärer oder Fallback-Provider; verwendet die T2A-v2-API)
• OpenAI (primärer oder Fallback-Provider; wird auch für Zusammenfassungen verwendet)

​

Hinweise zu Microsoft Speech

​

Optionale Schlüssel

• ELEVENLABS_API_KEY (oder XI_API_KEY)
• MINIMAX_API_KEY
• OPENAI_API_KEY

​

Dienst-Links

• OpenAI Text-to-Speech-Leitfaden
• OpenAI Audio API-Referenz
• ElevenLabs Text to Speech
• ElevenLabs Authentication
• MiniMax T2A v2 API
• node-edge-tts
• Microsoft-Speech-Ausgabeformate

​

Ist es standardmäßig aktiviert?

​

Konfiguration

​

Minimale Konfiguration (aktivieren + Provider)

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

​

OpenAI primär mit ElevenLabs als 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-Schlüssel)

{
  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%",
        },
      },
    },
  },
}

​

MiniMax primär

{
  messages: {
    tts: {
      auto: "always",
      provider: "minimax",
      providers: {
        minimax: {
          apiKey: "minimax_api_key",
          baseUrl: "https://api.minimax.io",
          model: "speech-2.8-hd",
          voiceId: "English_expressive_narrator",
          speed: 1.0,
          vol: 1.0,
          pitch: 0,
        },
      },
    },
  },
}

​

Microsoft Speech deaktivieren

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

​

Benutzerdefinierte Limits + prefs-Pfad

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

​

Nur nach einer eingehenden Sprachnachricht mit Audio antworten

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

​

Automatische Zusammenfassung für lange Antworten deaktivieren

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

/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: veralteter Schalter (doctor migriert dies zu auto).
• mode: "final" (Standard) oder "all" (einschließlich Tool-/Block-Antworten).
• provider: Speech-Provider-ID wie "elevenlabs", "microsoft", "minimax" oder "openai" (Fallback erfolgt automatisch).
• Wenn provider nicht gesetzt ist, verwendet OpenClaw den ersten konfigurierten Speech-Provider in der Auto-Select-Reihenfolge der Registry.
• Das veraltete provider: "edge" funktioniert weiterhin und wird zu microsoft normalisiert.
• summaryModel: optionales günstiges Modell für automatische Zusammenfassungen; Standard ist agents.defaults.model.primary.
  • Akzeptiert provider/model oder einen konfigurierten Modellalias.
• modelOverrides: erlaubt dem Modell, TTS-Directives auszugeben (standardmäßig aktiviert).
  • allowProvider ist standardmäßig false (Provider-Wechsel ist Opt-in).
• providers.<id>: provider-eigene Einstellungen, verschlüsselt nach Speech-Provider-ID.
• Veraltete direkte Provider-Blöcke (messages.tts.openai, messages.tts.elevenlabs, messages.tts.microsoft, messages.tts.edge) werden beim Laden automatisch zu messages.tts.providers.<id> migriert.
• maxTextLength: hartes Limit für TTS-Eingaben (Zeichen). /tts audio schlägt fehl, wenn es überschritten wird.
• timeoutMs: Request-Timeout (ms).
• prefsPath: überschreibt den lokalen prefs-JSON-Pfad (Provider/Limit/Zusammenfassung).
• apiKey-Werte greifen auf Umgebungsvariablen zurück (ELEVENLABS_API_KEY/XI_API_KEY, MINIMAX_API_KEY, OPENAI_API_KEY).
• providers.elevenlabs.baseUrl: überschreibt die ElevenLabs-API-Basis-URL.
• providers.openai.baseUrl: überschreibt den OpenAI-TTS-Endpunkt.
  • Auflösungsreihenfolge: messages.tts.providers.openai.baseUrl -> OPENAI_TTS_BASE_URL -> https://api.openai.com/v1
  • Nicht standardmäßige Werte werden als OpenAI-kompatible TTS-Endpunkte behandelt, daher werden benutzerdefinierte Modell- und Stimmmnamen 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: Ganzzahl 0..4294967295 (Best-Effort-Determinismus)
• providers.minimax.baseUrl: überschreibt die MiniMax-API-Basis-URL (Standard https://api.minimax.io, Umgebungsvariable: MINIMAX_API_HOST).
• providers.minimax.model: TTS-Modell (Standard speech-2.8-hd, Umgebungsvariable: MINIMAX_TTS_MODEL).
• providers.minimax.voiceId: Sprachkennung (Standard English_expressive_narrator, Umgebungsvariable: MINIMAX_TTS_VOICE_ID).
• providers.minimax.speed: Wiedergabegeschwindigkeit 0.5..2.0 (Standard 1.0).
• providers.minimax.vol: Lautstärke (0, 10] (Standard 1.0; muss größer als 0 sein).
• providers.minimax.pitch: Tonhöhenverschiebung -12..12 (Standard 0).
• providers.microsoft.enabled: erlaubt die Nutzung von Microsoft Speech (Standard true; kein API-Schlüssel).
• providers.microsoft.voice: Name der Microsoft-Neural-Stimme (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 finden Sie unter Microsoft-Speech-Ausgabeformate; nicht alle Formate werden vom gebündelten Edge-basierten Transport unterstützt.
• providers.microsoft.rate / providers.microsoft.pitch / providers.microsoft.volume: Prozent-Strings (z. B. +10%, -5%).
• providers.microsoft.saveSubtitles: schreibt JSON-Untertitel neben die Audiodatei.
• providers.microsoft.proxy: Proxy-URL für Microsoft-Speech-Requests.
• providers.microsoft.timeoutMs: Überschreibung des Request-Timeouts (ms).
• edge.*: veralteter Alias für dieselben Microsoft-Einstellungen.

​

Modellgesteuerte Überschreibungen (standardmäßig aktiviert)

Hier ist sie.

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

• provider (registrierte Speech-Provider-ID, z. B. openai, elevenlabs, minimax oder microsoft; erfordert allowProvider: true)
• voice (OpenAI-Stimme) oder voiceId (ElevenLabs / MiniMax)
• model (OpenAI-TTS-Modell, ElevenLabs-Modell-ID oder MiniMax-Modell)
• stability, similarityBoost, style, speed, useSpeakerBoost
• vol / volume (MiniMax-Lautstärke, 0-10)
• pitch (MiniMax-Tonhöhe, -12 bis 12)
• applyTextNormalization (auto|on|off)
• languageCode (ISO 639-1)
• seed

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

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

​

Benutzerspezifische Einstellungen

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

​

Ausgabeformate (fest)

• Feishu / Matrix / Telegram / WhatsApp: Opus-Sprachnachricht (opus_48000_64 von ElevenLabs, opus von OpenAI).
  • 48 kHz / 64 kbps ist ein guter Kompromiss für Sprachnachrichten.
• Andere Kanäle: MP3 (mp3_44100_128 von ElevenLabs, mp3 von OpenAI).
  • 44,1 kHz / 128 kbps ist der Standardkompromiss für klare Sprachwiedergabe.
• MiniMax: MP3 (speech-2.8-hd-Modell, 32-kHz-Abtastrate). Das Format für Sprachnotizen wird nativ nicht unterstützt; verwenden Sie OpenAI oder ElevenLabs für garantiertes Opus bei Sprachnachrichten.
• Microsoft: verwendet microsoft.outputFormat (Standard audio-24khz-48kbitrate-mono-mp3).
  • Der gebündelte Transport akzeptiert ein outputFormat, aber nicht alle Formate sind im Dienst verfügbar.
  • Die Werte für Ausgabeformate folgen den Microsoft-Speech-Ausgabeformaten (einschließlich Ogg/WebM Opus).
  • Telegram sendVoice akzeptiert OGG/MP3/M4A; verwenden Sie OpenAI/ElevenLabs, wenn Sie garantiertes Opus für Sprachnachrichten benötigen.
  • Wenn das konfigurierte Microsoft-Ausgabeformat fehlschlägt, versucht OpenClaw es erneut mit MP3.

​

Verhalten von Auto-TTS

• TTS wird übersprungen, wenn die Antwort bereits Medien oder eine MEDIA:-Directive enthält.
• Sehr kurze Antworten (< 10 Zeichen) werden übersprungen.
• Lange Antworten werden bei aktivierter Funktion mit agents.defaults.model.primary (oder summaryModel) zusammengefasst.
• Das erzeugte Audio wird an die Antwort angehängt.

​

Ablaufdiagramm

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

​

Verwendung per Slash-Befehl

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

• Befehle erfordern einen autorisierten Absender (Allowlist-/Owner-Regeln gelten weiterhin).
• commands.text oder die Registrierung nativer Befehle muss aktiviert sein.
• off|always|inbound|tagged sind Umschalter pro Sitzung (/tts on ist ein Alias für /tts always).
• limit und summary werden in lokalen Einstellungen gespeichert, nicht in der Hauptkonfiguration.
• /tts audio erzeugt eine einmalige Audio-Antwort (aktiviert TTS nicht dauerhaft).
• /tts status enthält Fallback-Sichtbarkeit für den letzten Versuch:
  • erfolgreicher Fallback: Fallback: <primary> -> <used> plus Attempts: ...
  • Fehler: Error: ... plus Attempts: ...
  • detaillierte Diagnostik: Attempt details: provider:outcome(reasonCode) latency
• Fehler von OpenAI- und ElevenLabs-APIs enthalten jetzt geparste Provider-Fehlerdetails und Request-IDs (wenn vom Provider zurückgegeben), was in TTS-Fehlern/Logs sichtbar gemacht wird.

​

Agent-Tool

​

Gateway RPC

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