Tekst-naar-spraak

OpenClaw kan uitgaande antwoorden omzetten naar audio via 14 spraakproviders en native spraakberichten leveren op Feishu, Matrix, Telegram en WhatsApp, audio-bijlagen overal elders, en PCM/Ulaw-streams voor telefonie en Talk.

TTS is de spraakuitvoerhelft van de stt-tts-modus van Talk. Provider-native realtime Talk-sessies synthetiseren spraak binnen de realtime-provider in plaats van dit TTS-pad aan te roepen, terwijl transcription-sessies geen spraakantwoord van de assistent synthetiseren.

Snel aan de slag

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

Ondersteunde providers

Als meerdere providers zijn geconfigureerd, wordt de geselecteerde provider eerst gebruikt en zijn de andere fallback-opties. Automatische samenvatting gebruikt summaryModel (of agents.defaults.model.primary), dus die provider moet ook geauthenticeerd zijn als je samenvattingen ingeschakeld houdt.

Configuratie

TTS-configuratie staat onder messages.tts in ~/.openclaw/openclaw.json. Kies een preset en pas het providerblok aan:

{messages: {tts: {  auto: "always",  provider: "azure-speech",  providers: {    "azure-speech": {      apiKey: "${AZURE_SPEECH_KEY}",      region: "eastus",      voice: "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",      voiceId: "EXAVITQu4vr4xnSDxMaL",    },  },},},}

{messages: {tts: {  auto: "always",  provider: "google",  providers: {    google: {      apiKey: "${GEMINI_API_KEY}",      model: "gemini-3.1-flash-tts-preview",      voiceName: "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}",      voiceId: "YTpq7expH9539ERJ",    },  },},},}

{messages: {tts: {  auto: "always",  provider: "inworld",  providers: {    inworld: {      apiKey: "${INWORLD_API_KEY}",      modelId: "inworld-tts-1.5-max",      voiceId: "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,      voice: "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",      voiceId: "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",      voice: "alloy",    },    elevenlabs: {      apiKey: "${ELEVENLABS_API_KEY}",      model: "eleven_multilingual_v2",      voiceId: "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",      voice: "af_alloy",      responseFormat: "mp3",    },  },},},}

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

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

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

Stemoverschrijvingen per agent

Gebruik agents.list[].tts wanneer één agent met een andere provider, stem, model, persona of Auto-TTS-modus moet spreken. Het agentblok deep-merget over messages.tts, zodat providerreferenties in de globale providerconfiguratie kunnen blijven:

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

Om een persona per agent vast te pinnen, stel je agents.list[].tts.persona in naast de providerconfiguratie — deze overschrijft de globale messages.tts.persona alleen voor die agent.

Voorrangsvolgorde voor automatische antwoorden, /tts audio, /tts status en de agenttool tts:

1. messages.tts
2. actieve agents.list[].tts
3. kanaaloverschrijving, wanneer het kanaal channels.<channel>.tts ondersteunt
4. accountoverschrijving, wanneer het kanaal channels.<channel>.accounts.<id>.tts doorgeeft
5. lokale /tts-voorkeuren voor deze host
6. inline [[tts:...]]-directieven wanneer modeloverschrijvingen zijn ingeschakeld

Kanaal- en accountoverschrijvingen gebruiken dezelfde vorm als messages.tts en worden diep samengevoegd over de eerdere lagen, zodat gedeelde providerreferenties in messages.tts kunnen blijven terwijl een kanaal of botaccount alleen stem, model, persona of automatische modus wijzigt:

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

Persona's

Een persona is een stabiele gesproken identiteit die deterministisch over providers heen kan worden toegepast. Deze kan één provider verkiezen, providerneutrale promptintentie definiëren en providerspecifieke koppelingen bevatten voor stemmen, modellen, prompttemplates, seeds en steminstellingen.

Minimale persona

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

Volledige persona (providerneutrale prompt)

{  messages: {    tts: {      auto: "always",      persona: "alfred",      personas: {        alfred: {          label: "Alfred",          description: "Droge, warme Britse butlerverteller.",          provider: "google",          fallbackPolicy: "preserve-persona",          prompt: {            profile: "Een briljante Britse butler. Droog, gevat, warm, charmant, emotioneel expressief, nooit generiek.",            scene: "Een stille studeerkamer laat op de avond. Close-mic-vertelling voor een vertrouwde operator.",            sampleContext: "De spreker beantwoordt een privé technisch verzoek met beknopt zelfvertrouwen en droge warmte.",            style: "Verfijnd, ingetogen, licht geamuseerd.",            accent: "Brits Engels.",            pacing: "Afgewogen, met korte dramatische pauzes.",            constraints: ["Lees configuratiewaarden niet hardop voor.", "Leg de persona niet uit."],          },          providers: {            google: {              model: "gemini-3.1-flash-tts-preview",              voiceName: "Algieba",              promptTemplate: "audio-profile-v1",            },            openai: { model: "gpt-4o-mini-tts", voice: "cedar" },            elevenlabs: {              voiceId: "voice_id",              modelId: "eleven_multilingual_v2",              seed: 42,              voiceSettings: {                stability: 0.65,                similarityBoost: 0.8,                style: 0.25,                useSpeakerBoost: true,                speed: 0.95,              },            },          },        },      },    },  },}

Persona-resolutie

De actieve persona wordt deterministisch geselecteerd:

1. Lokale voorkeur /tts persona <id>, indien ingesteld.
2. messages.tts.persona, indien ingesteld.
3. Geen persona.

Providerselectie verloopt expliciet eerst:

1. Directe overschrijvingen (CLI, Gateway, Talk, toegestane TTS-directieven).
2. Lokale voorkeur /tts provider <id>.
3. provider van de actieve persona.
4. messages.tts.provider.
5. Automatische registerselectie.

Voor elke providerpoging voegt OpenClaw configuraties in deze volgorde samen:

1. messages.tts.providers.<id>
2. messages.tts.personas.<persona>.providers.<id>
3. Vertrouwde verzoekoverschrijvingen
4. Toegestane door het model uitgegeven TTS-directiefoverschrijvingen

Hoe providers personaprompts gebruiken

Personapromptvelden (profile, scene, sampleContext, style, accent, pacing, constraints) zijn providerneutraal. Elke provider bepaalt hoe deze worden gebruikt:

Fallbackbeleid

fallbackPolicy bepaalt het gedrag wanneer een persona geen koppeling heeft voor de geprobeerde provider:

Het volledige TTS-verzoek mislukt alleen wanneer elke geprobeerde provider wordt overgeslagen of mislukt.

Providerselectie voor Talk-sessies is sessiegebonden. Een Talk-client moet provider-id's, model-id's, stem-id's en locales kiezen uit talk.catalog en deze doorgeven via de Talk-sessie of het overdrachtsverzoek. Het openen van een stemsessie mag messages.tts of globale Talk-providerstandaarden niet wijzigen.

Modelgestuurde directieven

Standaard kan de assistent [[tts:...]]-directieven uitsturen om stem, model of snelheid voor één antwoord te overschrijven, plus een optioneel [[tts:text]]...[[/tts:text]]-blok voor expressieve aanwijzingen die alleen in audio moeten verschijnen:

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

Wanneer messages.tts.auto "tagged" is, zijn directieven vereist om audio te activeren. Streaming bloklevering verwijdert directieven uit zichtbare tekst voordat het kanaal ze ziet, zelfs wanneer ze over aangrenzende blokken zijn verdeeld.

provider=... wordt genegeerd tenzij modelOverrides.allowProvider: true. Wanneer een antwoord provider=... declareert, worden de andere sleutels in die directief alleen door die provider geparsed; niet-ondersteunde sleutels worden verwijderd en gerapporteerd als TTS-directiefwaarschuwingen.

Beschikbare directiefsleutels:

• provider (geregistreerde provider-id; vereist allowProvider: true)
• voice / voiceName / voice_name / google_voice / voiceId
• model / google_model
• stability, similarityBoost, style, speed, useSpeakerBoost
• vol / volume (MiniMax-volume, 0–10)
• pitch (geheel getal voor MiniMax-toonhoogte, −12 tot 12; fractionele waarden worden afgekapt)
• emotion (Volcengine-emotietag)
• applyTextNormalization (auto|on|off)
• languageCode (ISO 639-1)
• seed

Modeloverschrijvingen volledig uitschakelen:

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

Providerwisseling toestaan terwijl andere knoppen configureerbaar blijven:

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

Slash-commando's

Eén commando /tts. Op Discord registreert OpenClaw ook /voice, omdat /tts een ingebouwd Discord-commando is — tekst /tts ... werkt nog steeds.

/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>

Gedragsnotities:

• /tts on schrijft de lokale TTS-voorkeur naar always; /tts off schrijft deze naar off.
• /tts chat on|off|default schrijft een sessiegebonden auto-TTS-overschrijving voor de huidige chat.
• /tts persona <id> schrijft de lokale personavoorkeur; /tts persona off wist deze.
• /tts latest leest het nieuwste assistentantwoord uit het huidige sessietranscript en verzendt dit eenmaal als audio. Het slaat alleen een hash van dat antwoord op in de sessievermelding om dubbele spraakverzendingen te onderdrukken.
• /tts audio genereert een eenmalig audioantwoord (schakelt TTS niet in).
• limit en summary worden opgeslagen in lokale voorkeuren, niet in de hoofdconfiguratie.
• /tts status bevat fallbackdiagnostiek voor de nieuwste poging — Fallback: <primary> -> <used>, Attempts: ... en details per poging (provider:outcome(reasonCode) latency).
• /status toont de actieve TTS-modus plus geconfigureerde provider, model, stem en opgeschoonde metadata van aangepaste endpoints wanneer TTS is ingeschakeld.

Voorkeuren per gebruiker

Slash-commando's schrijven lokale overschrijvingen naar prefsPath. De standaardwaarde is ~/.openclaw/settings/tts.json; overschrijf deze met de env-var OPENCLAW_TTS_PREFS of messages.tts.prefsPath.

Deze overschrijven de effectieve configuratie uit messages.tts plus het actieve agents.list[].tts-blok voor die host.

Uitvoerformaten (vast)

TTS-stemlevering wordt gestuurd door kanaalcapaciteiten. Kanaalplugins adverteren of spraakachtige TTS providers moet vragen om een native voice-note-doel of normale audio-file-synthese moet behouden en alleen compatibele uitvoer voor spraaklevering moet markeren.

• Kanalen met spraaknotitie-ondersteuning: antwoorden als spraaknotitie geven de voorkeur aan Opus (opus_48000_64 van ElevenLabs, opus van OpenAI).
  • 48 kHz / 64 kbps is een goede afweging voor spraakberichten.
• Feishu / WhatsApp: wanneer een antwoord als spraaknotitie wordt geproduceerd als MP3/WebM/WAV/M4A of een ander waarschijnlijk audiobestand, transcodeert de channel plugin dit naar 48 kHz Ogg/Opus met ffmpeg voordat het native spraakbericht wordt verzonden. WhatsApp verzendt het resultaat via de Baileys-audio-payload met ptt: true en audio/ogg; codecs=opus. Als conversie mislukt, ontvangt Feishu het oorspronkelijke bestand als bijlage; verzenden via WhatsApp mislukt in plaats van een incompatibele PTT-payload te plaatsen.
• Andere kanalen: MP3 (mp3_44100_128 van ElevenLabs, mp3 van OpenAI).
  • 44,1 kHz / 128 kbps is de standaardbalans voor spraakhelderheid.
• MiniMax: MP3 (speech-2.8-hd-model, samplefrequentie van 32 kHz) voor normale audiobijlagen. Voor door het kanaal aangekondigde spraaknotitie-doelen transcodeert OpenClaw de MiniMax-MP3 naar 48 kHz Opus met ffmpeg vóór levering wanneer het kanaal transcoding aankondigt.
• Xiaomi MiMo: standaard MP3, of WAV wanneer geconfigureerd. Voor door het kanaal aangekondigde spraaknotitie-doelen transcodeert OpenClaw Xiaomi-uitvoer naar 48 kHz Opus met ffmpeg vóór levering wanneer het kanaal transcoding aankondigt.
• Lokale CLI: gebruikt de geconfigureerde outputFormat. Spraaknotitie-doelen worden geconverteerd naar Ogg/Opus en telefonie-uitvoer wordt geconverteerd naar ruwe 16 kHz mono PCM met ffmpeg.
• Google Gemini: Gemini API TTS retourneert ruwe 24 kHz PCM. OpenClaw verpakt dit als WAV voor audiobijlagen, transcodeert het naar 48 kHz Opus voor spraaknotitie-doelen en retourneert PCM rechtstreeks voor Talk/telefonie.
• Gradium: WAV voor audiobijlagen, Opus voor spraaknotitie-doelen, en ulaw_8000 op 8 kHz voor telefonie.
• Inworld: MP3 voor normale audiobijlagen, native OGG_OPUS voor spraaknotitie-doelen, en ruwe PCM op 22050 Hz voor Talk/telefonie.
• xAI: standaard MP3; responseFormat kan mp3, wav, pcm, mulaw of alaw zijn. OpenClaw gebruikt xAI's batch REST TTS-eindpunt en retourneert een volledige audiobijlage; xAI's streaming TTS WebSocket wordt niet gebruikt door dit providerpad. Native Opus-spraaknotitieformaat wordt niet ondersteund door dit pad.
• Microsoft: gebruikt microsoft.outputFormat (standaard audio-24khz-48kbitrate-mono-mp3).
  • Het meegeleverde transport accepteert een outputFormat, maar niet alle formaten zijn beschikbaar via de service.
  • Uitvoerformaatwaarden volgen Microsoft Speech-uitvoerformaten (inclusief Ogg/WebM Opus).
  • Telegram sendVoice accepteert OGG/MP3/M4A; gebruik OpenAI/ElevenLabs als je gegarandeerde Opus-spraakberichten nodig hebt.
  • Als het geconfigureerde Microsoft-uitvoerformaat mislukt, probeert OpenClaw het opnieuw met MP3.

OpenAI/ElevenLabs-uitvoerformaten zijn per kanaal vastgelegd (zie hierboven).

Auto-TTS-gedrag

Wanneer messages.tts.auto is ingeschakeld, doet OpenClaw het volgende:

• Slaat TTS over als het antwoord al media of een MEDIA:-directive bevat.
• Slaat zeer korte antwoorden over (minder dan 10 tekens).
• Vat lange antwoorden samen wanneer samenvattingen zijn ingeschakeld, met summaryModel (of agents.defaults.model.primary).
• Voegt de gegenereerde audio toe aan het antwoord.
• In mode: "final" wordt nog steeds audio-only TTS verzonden voor gestreamde eindantwoorden nadat de tekststream is voltooid; de gegenereerde media gaat door dezelfde kanaalmedianormalisatie als normale antwoordbijlagen.

Als het antwoord maxLength overschrijdt en samenvatting is uitgeschakeld (of er geen API-sleutel is voor het samenvattingsmodel), wordt audio overgeslagen en wordt het normale tekstantwoord verzonden.

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 -> TTS -> attach audio

Uitvoerformaten per kanaal

Opmerkingen per provider:

• Feishu / WhatsApp-transcoding: Wanneer een antwoord als spraaknotitie binnenkomt als MP3/WebM/WAV/M4A, transcodeert de channel plugin naar 48 kHz Ogg/Opus met ffmpeg. WhatsApp verzendt via Baileys met ptt: true en audio/ogg; codecs=opus. Als conversie mislukt: Feishu valt terug op het bijvoegen van het oorspronkelijke bestand; verzenden via WhatsApp mislukt in plaats van een incompatibele PTT-payload te plaatsen.
• MiniMax / Xiaomi MiMo: Standaard MP3 (32 kHz voor MiniMax speech-2.8-hd); getranscodeerd naar 48 kHz Opus voor spraaknotitie-doelen via ffmpeg.
• Lokale CLI: Gebruikt geconfigureerde outputFormat. Spraaknotitie-doelen worden geconverteerd naar Ogg/Opus en telefonie-uitvoer naar ruwe 16 kHz mono PCM.
• Google Gemini: Retourneert ruwe 24 kHz PCM. OpenClaw verpakt dit als WAV voor bijlagen, transcodeert naar 48 kHz Opus voor spraaknotitie-doelen, retourneert PCM rechtstreeks voor Talk/telefonie.
• Inworld: MP3-bijlagen, native OGG_OPUS-spraaknotitie, ruwe PCM 22050 Hz voor Talk/telefonie.
• xAI: Standaard MP3; responseFormat kan mp3|wav|pcm|mulaw|alaw zijn. Gebruikt xAI's batch REST-eindpunt — streaming WebSocket TTS wordt niet gebruikt. Native Opus-spraaknotitieformaat wordt niet ondersteund.
• Microsoft: Gebruikt microsoft.outputFormat (standaard audio-24khz-48kbitrate-mono-mp3). Telegram sendVoice accepteert OGG/MP3/M4A; gebruik OpenAI/ElevenLabs als je gegarandeerde Opus-spraakberichten nodig hebt. Als het geconfigureerde Microsoft-formaat mislukt, probeert OpenClaw het opnieuw met MP3.

OpenAI- en ElevenLabs-uitvoerformaten zijn per kanaal vastgelegd zoals hierboven vermeld.

Veldreferentie

Agent-tool

De tool tts zet tekst om naar spraak en retourneert een audiobijlage voor antwoordbezorging. Op Feishu, Matrix, Telegram en WhatsApp wordt de audio geleverd als een spraakbericht in plaats van als bestandsbijlage. Feishu en WhatsApp kunnen niet-Opus TTS-uitvoer op dit pad transcoderen wanneer ffmpeg beschikbaar is.

WhatsApp verzendt audio via Baileys als een PTT-spraaknotitie (audio met ptt: true) en verzendt zichtbare tekst afzonderlijk van PTT-audio omdat clients bijschriften bij spraaknotities niet consequent weergeven.

De tool accepteert optionele velden channel en timeoutMs; timeoutMs is een provider-aanvraagtime-out per aanroep in milliseconden.

Gateway RPC

Servicelinks

• OpenAI-gids voor tekst-naar-spraak
• OpenAI Audio API-referentie
• Azure Speech REST tekst-naar-spraak
• Azure Speech-provider
• ElevenLabs Text to Speech
• ElevenLabs Authentication
• Gradium
• Inworld TTS API
• MiniMax T2A v2 API
• Volcengine TTS HTTP API
• Xiaomi MiMo-spraaksynthese
• node-edge-tts
• Microsoft Speech-uitvoerindelingen
• xAI tekst-naar-spraak

Gerelateerd

• Media-overzicht
• Muziekgeneratie
• Videogeneratie
• Slash-opdrachten
• Plugin voor spraakoproepen