​

Text-to-Speech (TTS)

​

Unterstützte Dienste

• ElevenLabs (primärer oder Fallback-Anbieter)
• Microsoft (primärer oder Fallback-Anbieter; die aktuelle gebündelte Implementierung verwendet node-edge-tts)
• MiniMax (primärer oder Fallback-Anbieter; verwendet die T2A-v2-API)
• OpenAI (primärer oder Fallback-Anbieter; 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 guide
• OpenAI Audio API reference
• ElevenLabs Text to Speech
• ElevenLabs Authentication
• MiniMax T2A v2 API
• node-edge-tts
• Microsoft Speech output formats

​

Ist es standardmäßig aktiviert?

​

Konfiguration

​

Minimale Konfiguration (Aktivieren + Anbieter)

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

​

Auto-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: alter Schalter (doctor migriert dies zu auto).
• mode: "final" (Standard) oder "all" (einschließlich Tool-/Block-Antworten).
• provider: Speech-Anbieter-ID wie "elevenlabs", "microsoft", "minimax" oder "openai" (Fallback erfolgt automatisch).
• Wenn provider nicht gesetzt ist, verwendet OpenClaw den ersten konfigurierten Speech-Anbieter in der Auto-Select-Reihenfolge der Registry.
• Das alte provider: "edge" funktioniert weiterhin und wird zu microsoft normalisiert.
• summaryModel: optionales günstiges Modell für Auto-Zusammenfassungen; Standard ist agents.defaults.model.primary.
  • Akzeptiert provider/model oder einen konfigurierten Modellalias.
• modelOverrides: erlaubt dem Modell, TTS-Direktiven auszugeben (standardmäßig aktiviert).
  • allowProvider ist standardmäßig false (Anbieterwechsel ist Opt-in).
• providers.<id>: anbieterbezogene Einstellungen, nach Speech-Anbieter-ID gruppiert.
• Alte direkte Anbieterblö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 JSON-Pfad für Einstellungen (Anbieter/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 Voice-Namen 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, env: MINIMAX_API_HOST).
• providers.minimax.model: TTS-Modell (Standard speech-2.8-hd, env: MINIMAX_TTS_MODEL).
• providers.minimax.voiceId: Voice-Kennung (Standard English_expressive_narrator, env: 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-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 finden Sie unter Microsoft Speech output formats; nicht alle Formate werden vom gebündelten Edge-basierten Transport unterstützt.
• providers.microsoft.rate / providers.microsoft.pitch / providers.microsoft.volume: Prozentzeichenfolgen (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.*: alter Alias für dieselben Microsoft-Einstellungen.

​

Modellgesteuerte Überschreibungen (standardmäßig aktiviert)

Here you go.

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

• provider (registrierte Speech-Anbieter-ID, zum Beispiel openai, elevenlabs, minimax oder microsoft; erfordert allowProvider: true)
• voice (OpenAI-Voice) 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 (Zusammenfassungsschwelle; Standard 1500 Zeichen)
• summarize (Standard true)

​

Ausgabeformate (fest)

• Feishu / Matrix / Telegram / WhatsApp: Opus-Voice-Message (opus_48000_64 von ElevenLabs, opus von OpenAI).
  • 48 kHz / 64 kbps ist ein guter Kompromiss für Voice-Messages.
• Andere Kanäle: MP3 (mp3_44100_128 von ElevenLabs, mp3 von OpenAI).
  • 44,1 kHz / 128 kbps ist die Standardbalance für klare Sprachwiedergabe.
• MiniMax: MP3 (Modell speech-2.8-hd, 32-kHz-Samplerate). Voice-Note-Format wird nativ nicht unterstützt; verwenden Sie OpenAI oder ElevenLabs für garantierte Opus-Voice-Messages.
• Microsoft: verwendet microsoft.outputFormat (Standard audio-24khz-48kbitrate-mono-mp3).
  • Der gebündelte Transport akzeptiert ein outputFormat, aber nicht alle Formate sind über den Dienst verfügbar.
  • Werte für das Ausgabeformat entsprechen Microsoft Speech output formats (einschließlich Ogg/WebM Opus).
  • Telegram sendVoice akzeptiert OGG/MP3/M4A; verwenden Sie OpenAI/ElevenLabs, wenn Sie garantierte Opus-Voice-Messages 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:-Direktive enthält.
• sehr kurze Antworten (< 10 Zeichen) werden übersprungen.
• lange Antworten werden, wenn aktiviert, mit agents.defaults.model.primary (oder summaryModel) zusammengefasst.
• das generierte Audio wird an die Antwort angehängt.

​

Ablaufdiagramm

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

​

Verwendung von Slash-Befehlen

/tts off
/tts on
/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.
• Die Konfiguration messages.tts.auto akzeptiert off|always|inbound|tagged.
• /tts on schreibt die lokale TTS-Einstellung auf always; /tts off schreibt sie auf off.
• Verwenden Sie die Konfiguration, wenn Sie inbound- oder tagged-Standards möchten.
• limit und summary werden in lokalen Einstellungen gespeichert, nicht in der Hauptkonfiguration.
• /tts audio erzeugt eine einmalige Audioantwort (aktiviert TTS nicht dauerhaft).
• /tts status enthält Sichtbarkeit von Fallbacks für den neuesten Versuch:
  • erfolgreicher Fallback: Fallback: <primary> -> <used> plus Attempts: ...
  • Fehler: Error: ... plus Attempts: ...
  • detaillierte Diagnose: Attempt details: provider:outcome(reasonCode) latency
• OpenAI- und ElevenLabs-API-Fehler enthalten jetzt geparste Fehlerdetails des Anbieters und die Request-ID (wenn vom Anbieter zurückgegeben), die in TTS-Fehlern/Logs sichtbar gemacht werden.

​

Agent-Tool

​

Gateway-RPC

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