Text-to-Speech

​

Schnellstart

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

​

Unterstützte Provider

​

Konfiguration

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

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

{
  tts: {
    auto: "always",
    provider: "google",
    providers: {
      google: {
        apiKey: "${GEMINI_API_KEY}",
        model: "gemini-3.1-flash-tts-preview",
        speakerVoice: "Kore",
        // Optionale Stilvorgaben in natürlicher Sprache:
        // audioProfile: "Sprechen Sie in einem ruhigen Tonfall wie ein Podcast-Moderator.",
        // speakerName: "Alex",
      },
    },
  },
}

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

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

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

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

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

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

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

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

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

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

​

Agent-spezifische Stimmenüberschreibungen

{
  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. tts
2. aktives agents.entries.*.tts
3. Kanalüberschreibung, wenn der Kanal channels.<channel>.tts unterstützt
4. Kontoüberschreibung, wenn der Kanal channels.<channel>.accounts.<id>.tts übergibt
5. lokale /tts-Einstellungen für diesen Host
6. eingebettete [[tts:...]]-Direktiven, wenn modellgesteuerte Überschreibungen aktiviert sind

{
  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

{
  tts: {
    auto: "always",
    persona: "narrator",
    personas: {
      narrator: {
        label: "Erzähler",
        provider: "elevenlabs",
        providers: {
          elevenlabs: {
            speakerVoiceId: "EXAVITQu4vr4xnSDxMaL",
            modelId: "eleven_multilingual_v2",
          },
        },
      },
    },
  },
}

​

Vollständige Persona (Provider-spezifische Ausgestaltung)

{
  tts: {
    auto: "always",
    persona: "alfred",
    personas: {
      alfred: {
        label: "Alfred",
        description: "Trockener, warmherziger britischer Butler-Erzähler.",
        provider: "google",
        fallbackPolicy: "preserve-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 /tts persona <id>-Einstellung, sofern festgelegt.
2. tts.persona, sofern festgelegt.
3. Keine Persona.

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

1. tts.providers.<id>
2. tts.personas.<persona>.providers.<id>
3. Vertrauenswürdige Anforderungsüberschreibungen
4. Zulässige, vom Modell ausgegebene Überschreibungen durch TTS-Direktiven

​

Benutzerdefinierte Persona-Ausgestaltung

​

Fallback-Richtlinie

​

Modellgesteuerte Direktiven

Bitte sehr.

[[tts:speakerVoiceId=pMsXgVXv3BLzUgSXRplE model=eleven_v3 speed=1.1]]
[[tts:text]](lacht) Lesen Sie das Lied noch einmal vor.[[/tts:text]]

• provider (registrierte Provider-ID; erfordert allowProvider: true)
• speakerVoice / speakerVoiceId (veraltete Aliase: voice, voiceName, voice_name, google_voice, voiceId)
• model / google_model
• stability, similarityBoost, style, speed, useSpeakerBoost
• vol / volume (MiniMax-Lautstärke, (0, 10])
• pitch (ganzzahlige MiniMax-Tonhöhe, −12 bis 12; Nachkommastellen werden abgeschnitten)
• emotion (Volcengine-Emotions-Tag)
• 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 nach always; /tts off schreibt sie nach off.
• /tts chat on|off|default schreibt für den aktuellen Chat eine sitzungsbezogene Auto-TTS-Überschreibung.
• /tts persona <id> schreibt die lokale Persona-Einstellung; /tts persona off löscht sie.
• /tts latest liest die neueste Assistentenantwort aus dem Transkript der aktuellen Sitzung und sendet sie einmalig als Audio. Im Sitzungseintrag wird nur ein Hash dieser Antwort gespeichert, um doppelte Sprachausgaben zu unterdrücken.
• /tts audio erzeugt eine einmalige Audioantwort (aktiviert TTS nicht dauerhaft).
• /tts limit <chars> akzeptiert 100–4096 (4096 ist das Telegram-Maximum für Bildunterschriften/Nachrichten); Werte außerhalb dieses Bereichs werden abgelehnt.
• limit und summary werden in lokalen Einstellungen und nicht in der Hauptkonfiguration gespeichert.
• /tts status enthält Fallback-Diagnosen für den letzten Versuch — Fallback: <primary> -> <used>, Attempts: ... und Details pro Versuch (provider:outcome(reasonCode) latency).
• /status zeigt bei aktiviertem TTS den aktiven TTS-Modus sowie den konfigurierten Provider, das Modell, die Stimme und bereinigte Metadaten des benutzerdefinierten Endpunkts an.

​

Benutzerspezifische Einstellungen

​

Ausgabeformate

• Feishu-/WhatsApp-Transkodierung: Wenn eine Sprachnachrichten-Antwort als MP3/WebM/WAV/M4A oder andere wahrscheinliche Audiodatei vorliegt, transkodiert das Kanal-Plugin sie vor dem Senden der nativen Sprachnachricht mit ffmpeg (libopus, 64 kbps) in Ogg/Opus mit 48 kHz. WhatsApp sendet das Ergebnis über die Baileys-audio-Nutzlast mit ptt: true und audio/ogg; codecs=opus. Bei einem Transkodierungsfehler: Feishu fängt den Fehler ab und sendet ersatzweise die Originaldatei als normalen Anhang; WhatsApp bietet keinen Fallback, sodass der Sendevorgang selbst fehlschlägt, statt eine inkompatible PTT-Nutzlast zu veröffentlichen.
• MiniMax: MP3 (speech-2.8-hd-Modell, Abtastrate 32 kHz) für normale Audioanhänge; für vom Kanal als Sprachnachrichten-Ziele ausgewiesene Ziele wird mit ffmpeg in Opus mit 48 kHz transkodiert.
• Xiaomi MiMo: Standardmäßig MP3 oder bei entsprechender Konfiguration WAV; für vom Kanal als Sprachnachrichten-Ziele ausgewiesene Ziele wird mit ffmpeg in Opus mit 48 kHz transkodiert.
• Lokale CLI: Verwendet das konfigurierte outputFormat. Sprachnachrichten-Ziele werden in Ogg/Opus und Telefonieausgaben mit ffmpeg in rohes Mono-PCM mit 16 kHz konvertiert.
• Google Gemini: Gibt rohes PCM mit 24 kHz zurück. OpenClaw verpackt es für Audioanhänge als WAV, transkodiert es für Sprachnachrichten-Ziele in Opus mit 48 kHz und gibt PCM für Talk/Telefonie direkt zurück.
• Gradium: WAV für Audioanhänge, Opus für Sprachnachrichten-Ziele und ulaw_8000 mit 8 kHz für Telefonie.
• Inworld: MP3 für normale Audioanhänge, natives OGG_OPUS für Sprachnachrichten-Ziele und rohes PCM mit 22050 Hz für Talk/Telefonie.
• xAI: Standardmäßig MP3; die Audiodateisynthese kann mp3, wav, pcm, mulaw oder alaw sowohl für gepufferte als auch für Streaming-Ausgaben verwenden. Sprachnachrichten-Ziele verwenden MP3 für Streaming und den gepufferten Fallback, da die Ausgaben pcm, mulaw und alaw von xAI headerlose Rohaudiodaten sind. Die gepufferte Synthese verwendet den Batch-REST-Endpunkt /v1/tts von xAI; textToSpeechStream verwendet natives wss://api.x.ai/v1/tts. Dies ist nicht der Echtzeit-Sprachvertrag. Das native Opus-Sprachnachrichtenformat wird nicht unterstützt.
• Microsoft: Verwendet microsoft.outputFormat (Standardwert audio-24khz-48kbitrate-mono-mp3).
  • Der gebündelte Transport akzeptiert ein outputFormat, aber nicht alle Formate sind über den Dienst verfügbar.
  • Ausgabeformatwerte entsprechen 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.
  • Wenn keine explizite Stimmenüberschreibung festgelegt ist und die englische Standardstimme verwendet wird, wechselt OpenClaw automatisch zu einer chinesischen neuronalen Stimme (zh-CN-XiaoxiaoNeural, Gebietsschema zh-CN), falls der Antworttext überwiegend aus CJK-Zeichen besteht.

​

Verhalten von Auto-TTS

• Ü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, und verwendet dabei summaryModel (oder agents.defaults.model.primary).
• Fügt das erzeugte Audio der Antwort hinzu.
• Sendet in mode: "final" nach Abschluss des Textstreams weiterhin reine TTS-Audioausgaben für gestreamte endgültige Antworten; die erzeugten Medien durchlaufen dieselbe Kanalmedien-Normalisierung wie normale Antwortanhänge.

• Zusammenfassung aktiviert (Standard) und ein Zusammenfassungsmodell ist verfügbar: Fasst den Text auf ungefähr maxLength Zeichen zusammen und synthetisiert anschließend die Zusammenfassung.
• Zusammenfassung deaktiviert, die Zusammenfassung schlägt fehl oder für das Zusammenfassungsmodell ist kein API-Schlüssel verfügbar: Kürzt den Text auf maxLength Zeichen und synthetisiert den gekürzten Text.

Antwort -> TTS aktiviert?
  nein -> Text senden
  ja   -> enthält Medien / kurz?
          ja   -> Text senden
          nein -> Länge > Grenzwert?
                   nein -> TTS -> Audio anhängen
                   ja   -> Zusammenfassung aktiviert und verfügbar?
                            nein -> kürzen -> TTS -> Audio anhängen
                            ja   -> zusammenfassen -> TTS -> Audio anhängen

​

Feldreferenz

​

Agentenwerkzeug

​

Gateway-RPC

​

Service-Links

• OpenAI-Leitfaden zur Text-zu-Sprache-Umwandlung
• OpenAI-Audio-API-Referenz
• Azure Speech REST-Text-zu-Sprache
• Azure-Speech-Provider
• ElevenLabs Text-zu-Sprache
• 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-zu-Sprache

​

Verwandte Themen

• Medienübersicht
• Musikgenerierung
• Videogenerierung
• Slash-Befehle
• Plugin für Sprachanrufe