Tekst-naar-spraak

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

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

Snel starten

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

Ondersteunde providers

Als meerdere providers zijn geconfigureerd, wordt de geselecteerde eerst gebruikt en zijn de andere fallbackopties. 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",      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",    },  },},},}

Voor Xiaomi mimo-v2.5-tts-voicedesign laat je speakerVoice weg en stel je style in op de prompt voor stemontwerp. OpenClaw verstuurt die prompt als het TTS-user-bericht en verstuurt geen audio.voice voor het voicedesign-model.

Spraakoverschrijvingen per agent

Gebruik agents.list[].tts wanneer een agent moet spreken met een andere provider, stem, model, persona of auto-TTS-modus. Het agentblok wordt diep samengevoegd bovenop messages.tts, zodat providerreferenties in de globale providerconfiguratie kunnen blijven staan:

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

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

Volgorde van prioriteit 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 bovenop de eerdere lagen, zodat gedeelde providerreferenties in messages.tts kunnen blijven staan terwijl een kanaal of botaccount alleen de sprekerstem, het model, de 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: { speakerVoice: "shimmer" },            },          },        },      },    },  },}

Persona's

Een persona is een stabiele gesproken identiteit die deterministisch kan worden toegepast over providers heen. Deze kan één provider prefereren, 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: {              speakerVoiceId: "EXAVITQu4vr4xnSDxMaL",              modelId: "eleven_multilingual_v2",            },          },        },      },    },  },}

Volledige persona (providerneutrale 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-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 werkt 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 selectie uit het register.

Voor elke providerpoging voegt OpenClaw configuraties samen in deze volgorde:

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 persona-prompts gebruiken

Persona-promptvelden (profile, scene, sampleContext, style, accent, pacing, constraints) zijn providerneutraal. Elke provider bepaalt zelf 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 standaardwaarden voor Talk-providers 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:speakerVoiceId=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. Streamingbloklevering 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 directieve alleen door die provider geparseerd; niet-ondersteunde sleutels worden verwijderd en gerapporteerd als TTS-directiefwaarschuwingen.

Beschikbare directiefsleutels:

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

Schakel modeloverschrijvingen volledig uit:

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

Sta providerwissels toe terwijl andere knoppen configureerbaar blijven:

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

Slashcommando's

Eén commando /tts. Op Discord registreert OpenClaw ook /voice omdat /tts een ingebouwd Discord-commando is — tekst /tts ... blijft werken.

/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 het eenmaal als audio. Het slaat alleen een hash van dat antwoord op in de sessie-entry om dubbele stemverzendingen 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 voor aangepaste endpoints wanneer TTS is ingeschakeld.

Voorkeuren per gebruiker

Slashcommando's schrijven lokale overschrijvingen naar prefsPath. De standaardwaarde is ~/.openclaw/settings/tts.json; overschrijf dit 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 bepaald door kanaalmogelijkheden. Kanaalplugins adverteren of voice-style TTS providers moet vragen om een native voice-note-doel of normale audio-file-synthese moet behouden en compatibele uitvoer alleen moet markeren voor stemlevering.

• Kanalen met ondersteuning voor spraaknotities: 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 kanaalplugin dit met ffmpeg naar 48 kHz Ogg/Opus 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 originele 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 kanalen geadverteerde doelen voor spraaknotities transcodeert OpenClaw de MiniMax-MP3 met ffmpeg naar 48 kHz Opus vóór aflevering wanneer het kanaal transcoding adverteert.
• Xiaomi MiMo: standaard MP3, of WAV wanneer geconfigureerd. Voor door kanalen geadverteerde doelen voor spraaknotities transcodeert OpenClaw Xiaomi-uitvoer met ffmpeg naar 48 kHz Opus vóór aflevering wanneer het kanaal transcoding adverteert.
• Lokale CLI: gebruikt de geconfigureerde outputFormat. Doelen voor spraaknotities worden geconverteerd naar Ogg/Opus en telefonie-uitvoer wordt met ffmpeg geconverteerd naar ruwe 16 kHz mono PCM.
• Google Gemini: Gemini API TTS retourneert ruwe 24 kHz PCM. OpenClaw verpakt dit als WAV voor audiobijlagen, transcodeert het naar 48 kHz Opus voor doelen voor spraaknotities, en retourneert PCM direct voor Talk/telefonie.
• Gradium: WAV voor audiobijlagen, Opus voor doelen voor spraaknotities, en ulaw_8000 op 8 kHz voor telefonie.
• Inworld: MP3 voor normale audiobijlagen, native OGG_OPUS voor doelen voor spraaknotities, 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-indeling voor spraaknotities wordt door dit pad niet ondersteund.
• Microsoft: gebruikt microsoft.outputFormat (standaard audio-24khz-48kbitrate-mono-mp3).
  • Het gebundelde transport accepteert een outputFormat, maar niet alle indelingen zijn beschikbaar vanuit de service.
  • Waarden voor uitvoerindelingen volgen Microsoft Speech-uitvoerindelingen (inclusief Ogg/WebM Opus).
  • Telegram sendVoice accepteert OGG/MP3/M4A; gebruik OpenAI/ElevenLabs als u gegarandeerde Opus-spraakberichten nodig hebt.
  • Als de geconfigureerde Microsoft-uitvoerindeling mislukt, probeert OpenClaw het opnieuw met MP3.

OpenAI/ElevenLabs-uitvoerindelingen liggen per kanaal vast (zie hierboven).

Auto-TTS-gedrag

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

• Slaat TTS over als het antwoord al gestructureerde media 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 als bijlage 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 doorlopen 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 / short?          yes -> send text          no  -> length > limit?                   no  -> TTS -> attach audio                   yes -> summary enabled?                            no  -> send text                            yes -> summarize -> TTS -> attach audio

Uitvoerindelingen per kanaal

Opmerkingen per provider:

• Feishu / WhatsApp-transcodering: Wanneer een antwoord als spraaknotitie binnenkomt als MP3/WebM/WAV/M4A, transcodeert de kanaal-Plugin dit naar 48 kHz Ogg/Opus met ffmpeg. WhatsApp verzendt via Baileys met ptt: true en audio/ogg; codecs=opus. Als de 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 doelen voor spraaknotities via ffmpeg.
• Lokale CLI: Gebruikt de geconfigureerde outputFormat. Doelen voor spraaknotities 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 doelen voor spraaknotities, en 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-indeling voor spraaknotities 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 de geconfigureerde Microsoft-indeling mislukt, probeert OpenClaw het opnieuw met MP3.

OpenAI- en ElevenLabs-uitvoerindelingen zijn per kanaal vastgezet zoals hierboven vermeld.

Veldreferentie

Agenttool

De tool tts converteert tekst naar spraak en retourneert een audiobijlage voor antwoordbezorging. Op Feishu, Matrix, Telegram en WhatsApp wordt de audio bezorgd als 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 apart van PTT-audio, omdat clients bijschriften op spraaknotities niet consistent weergeven.

De tool accepteert optionele velden channel en timeoutMs; timeoutMs is een per-aanroep aanvraagtijdslimiet voor de provider in milliseconden. Per-aanroepwaarden overschrijven messages.tts.timeoutMs; geconfigureerde TTS-time-outs overschrijven elke door Plugin geschreven standaardproviderwaarde.

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-authenticatie
• 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

• Mediaoverzicht
• Muziekgeneratie
• Videogeneratie
• Slash-opdrachten
• Spraakoproep-Plugin