Tekst-naar-spraak

OpenClaw zet uitgaande antwoorden om in audio via 14 spraakproviders: native spraakberichten op Feishu, Matrix, Telegram en WhatsApp; audio- bijlagen op alle andere platforms; en PCM/Ulaw-streams voor telefonie en Talk.

TTS is de spraakuitvoerhelft van de stt-tts-modus van Talk (talk.speak-gesprekken gebruiken ditzelfde synthesepad). Providernatieve realtime-Talk-sessies synthetiseren spraak binnen de realtimeprovider; transcription-sessies synthetiseren nooit een gesproken antwoord van de assistent.

Snel aan de slag

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

Ondersteunde providers

Als meerdere providers zijn geconfigureerd, wordt de geselecteerde provider eerst gebruikt en dienen de andere als terugvalopties. Automatische samenvattingen gebruiken summaryModel (of agents.defaults.model.primary), dus die provider moet ook geauthenticeerd zijn als je samenvattingen ingeschakeld laat.

Configuratie

De TTS-configuratie staat onder tts in ~/.openclaw/openclaw.json. Kies een voorinstelling en pas het providerblok aan. De hieronder getoonde velden speakerVoice/speakerVoiceId zijn canoniek; de eigen veldnamen voice/voiceId/ voiceName van elke provider werken nog als verouderde aliassen.

{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",    // Optionele stijlprompts in natuurlijke taal:    // audioProfile: "Spreek met een kalme toon, zoals een podcastpresentator.",    // 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",  },},},}

Laat voor Xiaomi mimo-v2.5-tts-voicedesign speakerVoice weg en stel style in op de prompt voor het stemontwerp. OpenClaw verzendt die prompt als het TTS-bericht user en verzendt audio.voice niet voor het voicedesign-model.

Stemoverschrijvingen per agent

Gebruik agents.entries.*.tts wanneer één agent met een andere provider, stem, model, persona of automatische TTS-modus moet spreken. Het agentblok wordt diep samengevoegd boven op tts, zodat providerreferenties in de globale providerconfiguratie kunnen blijven staan:

{  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.entries.*.tts.persona in naast de providerconfiguratie — deze overschrijft de algemene tts.persona uitsluitend voor die agent.

Volgorde van prioriteit voor automatische antwoorden, /tts audio, /tts status en de agenttool tts:

1. tts
2. actieve agents.entries.*.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:...]]-instructies wanneer modelgestuurde overschrijvingen zijn ingeschakeld

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

{  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 bij verschillende providers. De persona kan de voorkeur geven aan één provider, providerneutrale promptintentie definiëren en providerspecifieke koppelingen bevatten voor stemmen, modellen, promptsjablonen, seeds en steminstellingen.

Minimale persona

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

Volledige persona (providerspecifieke vormgeving)

{  tts: {    auto: "always",    persona: "alfred",    personas: {      alfred: {        label: "Alfred",        description: "Droge, warme Britse butlerverteller.",        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,            },          },        },      },    },  },}

Personaresolutie

De actieve persona wordt deterministisch geselecteerd:

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

Providerselectie verwerkt expliciete keuzes eerst:

1. Directe overschrijvingen (CLI, Gateway, Talk, toegestane TTS-instructies).
2. /tts provider <id> lokale voorkeur.
3. provider van de actieve persona.
4. tts.provider.
5. Automatische selectie uit het register.

Voor elke providerpoging voegt OpenClaw configuraties in deze volgorde samen:

1. tts.providers.<id>
2. tts.personas.<persona>.providers.<id>
3. Vertrouwde aanvraagoverschrijvingen
4. Toegestane overschrijvingen uit door het model uitgegeven TTS-instructies

Aangepaste personavormgeving

Providerneutrale personas.<id>.prompt.*-configuratie is buiten gebruik gesteld. Doctor verwijdert die velden en verwijst naar de interface van de spraakprovider. Plaats ingebouwde providerinstellingen onder personas.<id>.providers.<provider> (bijvoorbeeld Google personaPrompt of OpenAI instructions). Voor aangepaste vormgeving implementeer je een spraakproviderplugin met prepareSynthesis(ctx) en retourneer je aangepaste tekst, providerconfiguratie of overschrijvingen voordat synthesize() wordt uitgevoerd. Hierdoor blijft de constructie van expressieve prompts in de providercode, waar de semantiek van de aanvraag bekend is.

Terugvalbeleid

fallbackPolicy bepaalt het gedrag wanneer een persona geen koppeling heeft voor de provider die wordt geprobeerd:

De volledige TTS-aanvraag mislukt alleen wanneer elke providerpoging wordt overgeslagen of mislukt.

De providerselectie voor een Talk-sessie geldt uitsluitend binnen de sessie. Een Talk-client hoort provider-ID's, model-ID's, stem-ID's en landinstellingen te kiezen uit talk.catalog en deze door te geven via de Talk-sessie of overdrachtsaanvraag. Het openen van een spraaksessie hoort tts of de algemene standaardproviders van Talk niet te wijzigen.

Modelgestuurde instructies

Standaard kan de assistent [[tts:...]]-instructies uitvoeren om de stem, het model of de snelheid voor één antwoord te overschrijven, plus een optioneel [[tts:text]]...[[/tts:text]]-blok voor expressieve aanwijzingen die alleen in de audio mogen voorkomen:

Alsjeblieft. [[tts:speakerVoiceId=pMsXgVXv3BLzUgSXRplE model=eleven_v3 speed=1.1]][[tts:text]](lacht) Lees het lied nogmaals.[[/tts:text]]

Wanneer tts.auto gelijk is aan "tagged", zijn instructies vereist om audio te activeren. Bij gestreamde bloklevering worden instructies uit zichtbare tekst verwijderd voordat het kanaal ze ontvangt, 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 instructie uitsluitend door die provider geparseerd; niet-ondersteunde sleutels worden verwijderd en gemeld als waarschuwingen voor TTS-instructies.

Beschikbare instructiesleutels:

• provider (geregistreerde provider-ID; vereist allowProvider: true)
• speakerVoice / speakerVoiceId (verouderde aliassen: voice, voiceName, voice_name, google_voice, voiceId)
• model / google_model
• stability, similarityBoost, style, speed, useSpeakerBoost
• vol / volume (MiniMax-volume, (0, 10])
• pitch (gehele 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 } } } }

Wisselen van provider toestaan terwijl andere instellingen configureerbaar blijven:

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

Slash-opdrachten

Eén opdracht: /tts. Op Discord registreert OpenClaw ook /voice, omdat /tts een ingebouwde Discord-opdracht is — de 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 automatische 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 transcript van de huidige sessie en verzendt het eenmaal als audio. Alleen een hash van dat antwoord wordt in het sessie-item opgeslagen om dubbele spraakverzendingen te voorkomen.
• /tts audio genereert een eenmalig audioantwoord (schakelt TTS niet in).
• /tts limit <chars> accepteert 100–4096 (4096 is het maximum voor Telegram-bijschriften/-berichten); waarden buiten dat bereik worden geweigerd.
• limit en summary worden opgeslagen in lokale voorkeuren, niet in de hoofdconfiguratie.
• /tts status bevat terugvaldiagnostiek voor de nieuwste poging — Fallback: <primary> -> <used>, Attempts: ... en details per poging (provider:outcome(reasonCode) latency).
• /status toont de actieve TTS-modus plus de geconfigureerde provider, het model, de stem en opgeschoonde metagegevens van aangepaste eindpunten wanneer TTS is ingeschakeld.

Voorkeuren per gebruiker

Slash-opdrachten schrijven lokale overschrijvingen naar het pad voor TTS-voorkeuren. De standaardwaarde is ~/.openclaw/settings/tts.json; overschrijf deze met OPENCLAW_TTS_PREFS. Doctor verplaatst de buiten gebruik gestelde algemene waarde tts.prefsPath naar gedeelde machinestatus. Geavanceerde configuraties met meerdere agents kunnen nog steeds agents.entries.<id>.tts.prefsPath instellen wanneer agents bewust afzonderlijke voorkeursopslag gebruiken.

Deze overschrijven de effectieve configuratie van tts plus het actieve agents.entries.*.tts-blok voor die host.

Uitvoerformaten

De levering van TTS-spraak wordt bepaald door de kanaalmogelijkheden. Kanaalplugins geven aan of TTS in spraakstijl providers om een systeemeigen voice-note-doel moet vragen of normale audio-file-synthese moet behouden, en of het kanaal niet-systeemeigen uitvoer vóór verzending transcodeert.

Opmerkingen per provider:

• Transcodering voor Feishu / WhatsApp: wanneer een antwoord als spraakbericht binnenkomt als MP3/WebM/WAV/M4A of een ander waarschijnlijk audiobestand, transcodeert de kanaalplugin het vóór verzending als systeemeigen spraakbericht naar 48 kHz Ogg/Opus met ffmpeg (libopus, 64 kbps). WhatsApp verzendt het resultaat via de Baileys-audio-payload met ptt: true en audio/ogg; codecs=opus. Bij een transcoderingsfout: Feishu vangt de fout op en valt terug op verzending van het oorspronkelijke bestand als gewone bijlage; WhatsApp heeft geen terugvaloptie, waardoor de verzending zelf mislukt in plaats van een incompatibele PTT-payload te plaatsen.
• MiniMax: MP3 (speech-2.8-hd-model, samplefrequentie van 32 kHz) voor normale audiobijlagen; getranscodeerd naar 48 kHz Opus met ffmpeg voor doelen die door het kanaal als spraakbericht worden aangeduid.
• Xiaomi MiMo: standaard MP3, of WAV wanneer dit is geconfigureerd; getranscodeerd naar 48 kHz Opus met ffmpeg voor doelen die door het kanaal als spraakbericht worden aangeduid.
• Lokale CLI: gebruikt de geconfigureerde outputFormat. Doelen voor spraakberichten worden geconverteerd naar Ogg/Opus en telefonie-uitvoer wordt met ffmpeg geconverteerd naar onbewerkte 16 kHz mono-PCM.
• Google Gemini: retourneert onbewerkte 24 kHz PCM. OpenClaw verpakt deze als WAV voor audiobijlagen, transcodeert deze naar 48 kHz Opus voor doelen voor spraakberichten en retourneert PCM rechtstreeks voor Talk/telefonie.
• Gradium: WAV voor audiobijlagen, Opus voor doelen voor spraakberichten en ulaw_8000 op 8 kHz voor telefonie.
• Inworld: MP3 voor normale audiobijlagen, systeemeigen OGG_OPUS voor doelen voor spraakberichten en onbewerkte PCM op 22050 Hz voor Talk/telefonie.
• xAI: standaard MP3; synthese van audiobestanden kan mp3, wav, pcm, mulaw of alaw gebruiken voor zowel gebufferde als gestreamde uitvoer. Doelen voor spraakberichten gebruiken MP3 voor streaming en als gebufferde terugvaloptie, omdat de uitvoer van xAI voor pcm, mulaw en alaw onbewerkte audio zonder headers is. Gebufferde synthese gebruikt het batch-REST-/v1/tts-eindpunt van xAI; textToSpeechStream gebruikt systeemeigen wss://api.x.ai/v1/tts. Dit is niet het realtime-spraakcontract. Een systeemeigen Opus-indeling voor spraakberichten wordt niet ondersteund.
• Microsoft: gebruikt microsoft.outputFormat (standaard audio-24khz-48kbitrate-mono-mp3).
  • Het meegeleverde transport accepteert een outputFormat, maar niet alle indelingen zijn beschikbaar via de service.
  • Waarden voor de uitvoerindeling volgen de uitvoerindelingen van Microsoft Speech (waaronder Ogg/WebM Opus).
  • Telegram sendVoice accepteert OGG/MP3/M4A; gebruik OpenAI/ElevenLabs als je gegarandeerde Opus-spraakberichten nodig hebt.
  • Als de geconfigureerde Microsoft-uitvoerindeling mislukt, probeert OpenClaw het opnieuw met MP3.
  • Wanneer geen expliciete stemoverschrijving is ingesteld en de standaard Engelse stem wordt gebruikt, schakelt OpenClaw automatisch over naar een Chinese neurale stem (zh-CN-XiaoxiaoNeural, landinstelling zh-CN) als de antwoordtekst voornamelijk uit CJK-tekens bestaat.

De uitvoerindelingen van OpenAI en ElevenLabs liggen per kanaal vast zoals hierboven vermeld.

Gedrag van automatische TTS

Wanneer 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 toe aan het antwoord.
• Verzendt in mode: "final" nog steeds uitsluitend audio-TTS voor gestreamde definitieve antwoorden nadat de tekststream is voltooid; de gegenereerde media ondergaan dezelfde normalisatie van kanaalmedia als normale antwoordbijlagen.

Als het antwoord langer is dan maxLength, slaat OpenClaw audio nooit volledig over:

• Samenvatting aan (standaard) en er is een samenvattingsmodel beschikbaar: vat de tekst samen tot ongeveer maxLength tekens en synthetiseert vervolgens de samenvatting.
• Samenvatting uit, samenvatten mislukt of er is geen API-sleutel beschikbaar voor het samenvattingsmodel: kort de tekst in tot maxLength tekens en synthetiseert de ingekorte tekst.

Antwoord -> TTS ingeschakeld?  nee -> tekst verzenden  ja  -> bevat media / kort?          ja  -> tekst verzenden          nee -> lengte > limiet?                   nee -> TTS -> audio toevoegen                   ja  -> samenvatting ingeschakeld en beschikbaar?                            nee -> inkorten -> TTS -> audio toevoegen                            ja  -> samenvatten -> TTS -> audio toevoegen

Veldreferentie

Agenttool

De tool tts zet tekst om in spraak en retourneert een audiobijlage voor het afleveren van antwoorden. Op Feishu, Matrix, Telegram en WhatsApp wordt de audio afgeleverd 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-spraakbericht (audio met ptt: true) en verzendt zichtbare tekst afzonderlijk van PTT-audio, omdat clients bijschriften bij spraakberichten niet consistent weergeven.

De tool accepteert optionele velden channel en timeoutMs; timeoutMs is een time-out per aanroep voor providerverzoeken in milliseconden. Waarden per aanroep overschrijven tts.timeoutMs; geconfigureerde TTS-time-outs overschrijven elke door een Plugin ingestelde standaardwaarde van de provider.

Gateway-RPC

Servicekoppelingen

• OpenAI-handleiding voor tekst-naar-spraak
• OpenAI Audio API-referentie
• Azure Speech REST voor tekst-naar-spraak
• Azure Speech-provider
• ElevenLabs tekst-naar-spraak
• 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
• Muziek genereren
• Video genereren
• Slash-opdrachten
• Plugin voor spraakoproepen