Text-zu-Sprache

​

Schnellstart

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

​

Unterstützte Provider

​

Konfiguration

{
  messages: {
    tts: {
      auto: "always",
      provider: "azure-speech",
      providers: {
        "azure-speech": {
          apiKey: "${AZURE_SPEECH_KEY}",
          region: "eastus",
          speakerVoice: "en-US-JennyNeural",
          lang: "en-US",
          outputFormat: "audio-24khz-48kbitrate-mono-mp3",
          voiceNoteOutputFormat: "ogg-24khz-16bit-mono-opus",
        },
      },
    },
  },
}

{
  messages: {
    tts: {
      auto: "always",
      provider: "elevenlabs",
      providers: {
        elevenlabs: {
          apiKey: "${ELEVENLABS_API_KEY}",
          model: "eleven_multilingual_v2",
          speakerVoiceId: "EXAVITQu4vr4xnSDxMaL",
        },
      },
    },
  },
}

{
  messages: {
    tts: {
      auto: "always",
      provider: "google",
      providers: {
        google: {
          apiKey: "${GEMINI_API_KEY}",
          model: "gemini-3.1-flash-tts-preview",
          speakerVoice: "Kore",
          // Optional natural-language style prompts:
          // audioProfile: "Speak in a calm, podcast-host tone.",
          // speakerName: "Alex",
        },
      },
    },
  },
}

{
  messages: {
    tts: {
      auto: "always",
      provider: "gradium",
      providers: {
        gradium: {
          apiKey: "${GRADIUM_API_KEY}",
          speakerVoiceId: "YTpq7expH9539ERJ",
        },
      },
    },
  },
}

{
  messages: {
    tts: {
      auto: "always",
      provider: "inworld",
      providers: {
        inworld: {
          apiKey: "${INWORLD_API_KEY}",
          modelId: "inworld-tts-1.5-max",
          speakerVoiceId: "Sarah",
          temperature: 0.7,
        },
      },
    },
  },
}

{
  messages: {
    tts: {
      auto: "always",
      provider: "tts-local-cli",
      providers: {
        "tts-local-cli": {
          command: "say",
          args: ["-o", "{{OutputPath}}", "{{Text}}"],
          outputFormat: "wav",
          timeoutMs: 120000,
        },
      },
    },
  },
}

{
  messages: {
    tts: {
      auto: "always",
      provider: "microsoft",
      providers: {
        microsoft: {
          enabled: true,
          speakerVoice: "en-US-MichelleNeural",
          lang: "en-US",
          outputFormat: "audio-24khz-48kbitrate-mono-mp3",
          rate: "+0%",
          pitch: "+0%",
        },
      },
    },
  },
}

{
  messages: {
    tts: {
      auto: "always",
      provider: "minimax",
      providers: {
        minimax: {
          apiKey: "${MINIMAX_API_KEY}",
          model: "speech-2.8-hd",
          speakerVoiceId: "English_expressive_narrator",
          speed: 1.0,
          vol: 1.0,
          pitch: 0,
        },
      },
    },
  },
}

{
  messages: {
    tts: {
      auto: "always",
      provider: "openai",
      summaryModel: "openai/gpt-4.1-mini",
      modelOverrides: { enabled: true },
      providers: {
        openai: {
          apiKey: "${OPENAI_API_KEY}",
          model: "gpt-4o-mini-tts",
          speakerVoice: "alloy",
        },
        elevenlabs: {
          apiKey: "${ELEVENLABS_API_KEY}",
          model: "eleven_multilingual_v2",
          speakerVoiceId: "EXAVITQu4vr4xnSDxMaL",
          voiceSettings: { stability: 0.5, similarityBoost: 0.75, style: 0.0, useSpeakerBoost: true, speed: 1.0 },
          applyTextNormalization: "auto",
          languageCode: "en",
        },
      },
    },
  },
}

{
  messages: {
    tts: {
      auto: "always",
      provider: "openrouter",
      providers: {
        openrouter: {
          apiKey: "${OPENROUTER_API_KEY}",
          model: "hexgrad/kokoro-82m",
          speakerVoice: "af_alloy",
          responseFormat: "mp3",
        },
      },
    },
  },
}

{
  messages: {
    tts: {
      auto: "always",
      provider: "volcengine",
      providers: {
        volcengine: {
          apiKey: "${VOLCENGINE_TTS_API_KEY}",
          resourceId: "seed-tts-1.0",
          speakerVoice: "en_female_anna_mars_bigtts",
        },
      },
    },
  },
}

{
  messages: {
    tts: {
      auto: "always",
      provider: "xai",
      providers: {
        xai: {
          apiKey: "${XAI_API_KEY}",
          speakerVoiceId: "eve",
          language: "en",
          responseFormat: "mp3",
        },
      },
    },
  },
}

{
  messages: {
    tts: {
      auto: "always",
      provider: "xiaomi",
      providers: {
        xiaomi: {
          apiKey: "${XIAOMI_API_KEY}",
          model: "mimo-v2.5-tts",
          speakerVoice: "mimo_default",
          format: "mp3",
        },
      },
    },
  },
}

​

Sprachüberschreibungen pro Agent

{
  messages: {
    tts: {
      auto: "always",
      provider: "elevenlabs",
      providers: {
        elevenlabs: { apiKey: "${ELEVENLABS_API_KEY}", model: "eleven_multilingual_v2" },
      },
    },
  },
  agents: {
    list: [
      {
        id: "reader",
        tts: {
          providers: {
            elevenlabs: { speakerVoiceId: "EXAVITQu4vr4xnSDxMaL" },
          },
        },
      },
    ],
  },
}

1. messages.tts
2. aktives agents.list[].tts
3. Kanal-Override, wenn der Kanal channels.<channel>.tts unterstützt
4. Konto-Override, wenn der Kanal channels.<channel>.accounts.<id>.tts übergibt
5. lokale /tts-Einstellungen für diesen Host
6. Inline-Direktiven [[tts:...]], wenn modellgesteuerte Overrides aktiviert sind

{
  messages: {
    tts: {
      provider: "openai",
      providers: {
        openai: { apiKey: "${OPENAI_API_KEY}", model: "gpt-4o-mini-tts" },
      },
    },
  },
  channels: {
    feishu: {
      accounts: {
        english: {
          tts: {
            providers: {
              openai: { speakerVoice: "shimmer" },
            },
          },
        },
      },
    },
  },
}

​

Personas

​

Minimale Persona

{
  messages: {
    tts: {
      auto: "always",
      persona: "narrator",
      personas: {
        narrator: {
          label: "Narrator",
          provider: "elevenlabs",
          providers: {
            elevenlabs: {
              speakerVoiceId: "EXAVITQu4vr4xnSDxMaL",
              modelId: "eleven_multilingual_v2",
            },
          },
        },
      },
    },
  },
}

​

Vollständige Persona (Provider-neutraler Prompt)

{
  messages: {
    tts: {
      auto: "always",
      persona: "alfred",
      personas: {
        alfred: {
          label: "Alfred",
          description: "Dry, warm British butler narrator.",
          provider: "google",
          fallbackPolicy: "preserve-persona",
          prompt: {
            profile: "A brilliant British butler. Dry, witty, warm, charming, emotionally expressive, never generic.",
            scene: "A quiet late-night study. Close-mic narration for a trusted operator.",
            sampleContext: "The speaker is answering a private technical request with concise confidence and dry warmth.",
            style: "Refined, understated, lightly amused.",
            accent: "British English.",
            pacing: "Measured, with short dramatic pauses.",
            constraints: ["Do not read configuration values aloud.", "Do not explain the persona."],
          },
          providers: {
            google: {
              model: "gemini-3.1-flash-tts-preview",
              speakerVoice: "Algieba",
              promptTemplate: "audio-profile-v1",
            },
            openai: { model: "gpt-4o-mini-tts", speakerVoice: "cedar" },
            elevenlabs: {
              speakerVoiceId: "voice_id",
              modelId: "eleven_multilingual_v2",
              seed: 42,
              voiceSettings: {
                stability: 0.65,
                similarityBoost: 0.8,
                style: 0.25,
                useSpeakerBoost: true,
                speed: 0.95,
              },
            },
          },
        },
      },
    },
  },
}

​

Persona-Auflösung

1. Lokale Einstellung /tts persona <id>, falls gesetzt.
2. messages.tts.persona, falls gesetzt.
3. Keine Persona.

1. Direkte Overrides (CLI, Gateway, Talk, zulässige TTS-Direktiven).
2. Lokale Einstellung /tts provider <id>.
3. provider der aktiven Persona.
4. messages.tts.provider.
5. Automatische Auswahl aus der Registry.

1. messages.tts.providers.<id>
2. messages.tts.personas.<persona>.providers.<id>
3. Vertrauenswürdige Request-Overrides
4. Zulässige vom Modell ausgegebene TTS-Direktiven-Overrides

​

Wie Provider Persona-Prompts verwenden

​

Fallback-Richtlinie

​

Modellgesteuerte Direktiven

Here you go.

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

• provider (registrierte Provider-ID; erfordert allowProvider: true)
• speakerVoice / speakerVoiceId (Legacy-Aliasse: voice, voiceName, voice_name, google_voice, voiceId)
• model / google_model
• stability, similarityBoost, style, speed, useSpeakerBoost
• vol / volume (MiniMax-Lautstärke, 0–10)
• pitch (MiniMax-Ganzzahltonhöhe, −12 bis 12; Dezimalwerte werden abgeschnitten)
• emotion (Volcengine-Emotionstag)
• applyTextNormalization (auto|on|off)
• languageCode (ISO 639-1)
• seed

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

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

​

Slash-Befehle

/tts off | on | status
/tts chat on | off | default
/tts latest
/tts provider <id>
/tts persona <id> | off
/tts limit <chars>
/tts summary off
/tts audio <text>

• /tts on schreibt die lokale TTS-Einstellung auf always; /tts off schreibt sie auf off.
• /tts chat on|off|default schreibt einen sitzungsbezogenen Auto-TTS-Override für den aktuellen Chat.
• /tts persona <id> schreibt die lokale Persona-Einstellung; /tts persona off löscht sie.
• /tts latest liest die neueste Assistentenantwort aus dem aktuellen Sitzungstranskript und sendet sie einmal als Audio. Es speichert nur einen Hash dieser Antwort im Sitzungseintrag, um doppelte Sprachausgaben zu unterdrücken.
• /tts audio erzeugt eine einmalige Audio-Antwort (schaltet TTS nicht ein).
• limit und summary werden in lokalen Einstellungen gespeichert, nicht in der Hauptkonfiguration.
• /tts status enthält Fallback-Diagnosen für den neuesten Versuch — Fallback: <primary> -> <used>, Attempts: ... und Details pro Versuch (provider:outcome(reasonCode) latency).
• /status zeigt den aktiven TTS-Modus sowie konfigurierten Provider, Modell, Stimme und bereinigte benutzerdefinierte Endpunkt-Metadaten, wenn TTS aktiviert ist.

​

Benutzerspezifische Einstellungen

​

Ausgabeformate (fest)

• Sprachnotiz-fähige Kanäle: Sprachnotiz-Antworten bevorzugen Opus (opus_48000_64 von ElevenLabs, opus von OpenAI).
  • 48 kHz / 64 kbps ist ein guter Kompromiss für Sprachnachrichten.
• Feishu / WhatsApp: Wenn eine Sprachnotiz-Antwort als MP3/WebM/WAV/M4A oder eine andere wahrscheinliche Audiodatei erzeugt wird, transkodiert das Kanal-Plugin sie vor dem Senden der nativen Sprachnachricht mit ffmpeg zu 48 kHz Ogg/Opus. WhatsApp sendet das Ergebnis über die Baileys-audio-Payload mit ptt: true und audio/ogg; codecs=opus. Wenn die Konvertierung fehlschlägt, erhält Feishu die ursprüngliche Datei als Anhang; der WhatsApp-Versand schlägt fehl, statt eine inkompatible PTT-Payload zu posten.
• Andere Kanäle: MP3 (mp3_44100_128 von ElevenLabs, mp3 von OpenAI).
  • 44,1 kHz / 128 kbps ist die Standardbalance für Sprachklarheit.
• MiniMax: MP3 (speech-2.8-hd-Modell, 32-kHz-Abtastrate) für normale Audioanhänge. Für vom Kanal angekündigte Sprachnotiz-Ziele transkodiert OpenClaw das MiniMax-MP3 vor der Auslieferung mit ffmpeg zu 48 kHz Opus, wenn der Kanal Transkodierung ankündigt.
• Xiaomi MiMo: Standardmäßig MP3 oder WAV, wenn konfiguriert. Für vom Kanal angekündigte Sprachnotiz-Ziele transkodiert OpenClaw Xiaomi-Ausgaben vor der Auslieferung mit ffmpeg zu 48 kHz Opus, wenn der Kanal Transkodierung ankündigt.
• Lokale CLI: Verwendet das konfigurierte outputFormat. Sprachnotiz-Ziele werden zu Ogg/Opus konvertiert, und Telefonieausgabe wird mit ffmpeg zu rohem 16-kHz-Mono-PCM konvertiert.
• Google Gemini: Gemini API TTS gibt rohes 24-kHz-PCM zurück. OpenClaw verpackt es für Audioanhänge als WAV, transkodiert es für Sprachnotiz-Ziele zu 48 kHz Opus und gibt PCM für Talk/Telefonie direkt zurück.
• Gradium: WAV für Audioanhänge, Opus für Sprachnotiz-Ziele und ulaw_8000 bei 8 kHz für Telefonie.
• Inworld: MP3 für normale Audioanhänge, natives OGG_OPUS für Sprachnotiz-Ziele und rohes PCM bei 22050 Hz für Talk/Telefonie.
• xAI: Standardmäßig MP3; responseFormat kann mp3, wav, pcm, mulaw oder alaw sein. OpenClaw verwendet den Batch-REST-TTS-Endpunkt von xAI und gibt einen vollständigen Audioanhang zurück; der Streaming-TTS-WebSocket von xAI wird in diesem Provider-Pfad nicht verwendet. Das native Opus-Sprachnotizformat wird von diesem Pfad nicht unterstützt.
• Microsoft: Verwendet microsoft.outputFormat (Standard audio-24khz-48kbitrate-mono-mp3).
  • Der gebündelte Transport akzeptiert ein outputFormat, aber nicht alle Formate sind vom Dienst verfügbar.
  • Ausgabeformatwerte folgen den Microsoft Speech-Ausgabeformaten (einschließlich Ogg/WebM Opus).
  • Telegram sendVoice akzeptiert OGG/MP3/M4A; verwenden Sie OpenAI/ElevenLabs, wenn Sie garantierte Opus-Sprachnachrichten benötigen.
  • Wenn das konfigurierte Microsoft-Ausgabeformat fehlschlägt, versucht OpenClaw es erneut mit MP3.

​

Auto-TTS-Verhalten

• Überspringt TTS, wenn die Antwort bereits strukturierte Medien enthält.
• Überspringt sehr kurze Antworten (unter 10 Zeichen).
• Fasst lange Antworten zusammen, wenn Zusammenfassungen aktiviert sind, unter Verwendung von summaryModel (oder agents.defaults.model.primary).
• Hängt das generierte Audio an die Antwort an.
• Sendet in mode: "final" weiterhin reines Audio-TTS für gestreamte finale Antworten, nachdem der Textstream abgeschlossen ist; die generierten Medien durchlaufen dieselbe Kanal-Mediennormalisierung wie normale Antwortanhänge.

Reply -> TTS enabled?
  no  -> send text
  yes -> has media / short?
          yes -> send text
          no  -> length > limit?
                   no  -> TTS -> attach audio
                   yes -> summary enabled?
                            no  -> send text
                            yes -> summarize -> TTS -> attach audio

​

Ausgabeformate nach Kanal

• Feishu / WhatsApp-Transkodierung: Wenn eine Sprachnotiz-Antwort als MP3/WebM/WAV/M4A ankommt, transkodiert das Kanal-Plugin mit ffmpeg zu 48 kHz Ogg/Opus. WhatsApp sendet über Baileys mit ptt: true und audio/ogg; codecs=opus. Wenn die Konvertierung fehlschlägt: Feishu fällt auf das Anhängen der ursprünglichen Datei zurück; der WhatsApp-Versand schlägt fehl, statt eine inkompatible PTT-Payload zu posten.
• MiniMax / Xiaomi MiMo: Standardmäßig MP3 (32 kHz für MiniMax speech-2.8-hd); für Sprachnotiz-Ziele über ffmpeg zu 48 kHz Opus transkodiert.
• Lokale CLI: Verwendet das konfigurierte outputFormat. Sprachnotiz-Ziele werden zu Ogg/Opus und Telefonieausgabe zu rohem 16-kHz-Mono-PCM konvertiert.
• Google Gemini: Gibt rohes 24-kHz-PCM zurück. OpenClaw verpackt es für Anhänge als WAV, transkodiert es für Sprachnotiz-Ziele zu 48 kHz Opus und gibt PCM für Talk/Telefonie direkt zurück.
• Inworld: MP3-Anhänge, native OGG_OPUS-Sprachnotiz, rohes PCM mit 22050 Hz für Talk/Telefonie.
• xAI: Standardmäßig MP3; responseFormat kann mp3|wav|pcm|mulaw|alaw sein. Verwendet den Batch-REST-Endpunkt von xAI — Streaming-WebSocket-TTS wird nicht verwendet. Das native Opus-Sprachnotizformat wird nicht unterstützt.
• Microsoft: Verwendet microsoft.outputFormat (Standard audio-24khz-48kbitrate-mono-mp3). Telegram sendVoice akzeptiert OGG/MP3/M4A; verwenden Sie OpenAI/ElevenLabs, wenn Sie garantierte Opus-Sprachnachrichten benötigen. Wenn das konfigurierte Microsoft-Format fehlschlägt, versucht OpenClaw es erneut mit MP3.

​

Feldreferenz

​

Agent-Tool

​

Gateway-RPC

​

Service-Links

• OpenAI-Leitfaden für Text-to-Speech
• OpenAI Audio API-Referenz
• Azure Speech REST Text-to-Speech
• Azure Speech-Provider
• ElevenLabs Text to Speech
• ElevenLabs-Authentifizierung
• Gradium
• Inworld TTS API
• MiniMax T2A v2 API
• Volcengine TTS HTTP API
• Xiaomi MiMo-Sprachsynthese
• node-edge-tts
• Microsoft Speech-Ausgabeformate
• xAI Text-to-Speech

​

Verwandte Themen

• Medienübersicht
• Musikgenerierung
• Videogenerierung
• Slash-Befehle
• Sprachanruf-Plugin