Tekst-naar-spraak

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

TTS is de helft voor spraakuitvoer van Talks 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 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 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",
      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 wordt deep-merged 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 zetten, stel je agents.list[].tts.persona in naast de provider- configuratie — dit overschrijft de globale messages.tts.persona alleen voor die agent.

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

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

Kanaal- en accountoverrides 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 kan worden toegepast. Die kan de voorkeur geven aan één provider, providerneutrale promptintentie definiëren en providerspecifieke bindingen bevatten voor stemmen, modellen, promptsjablonen, 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: "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",
              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,
              },
            },
          },
        },
      },
    },
  },
}

# Personaresolutie

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 met expliciet eerst:

1. Directe overrides (CLI, Gateway, Talk, toegestane TTS-richtlijnen).
2. Lokale voorkeur /tts provider <id>.
3. De 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 requestoverrides
4. Toegestane door het model uitgezonden TTS-richtlijnoverrides

# Hoe providers personaprompts gebruiken

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

# Fallbackbeleid

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

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

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

# Modelgestuurde richtlijnen

Standaard kan de assistant [[tts:...]]-richtlijnen uitzenden 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 richtlijnen vereist om audio te activeren. Streamingbloklevering verwijdert richtlijnen uit zichtbare tekst voordat het kanaal ze ziet, zelfs wanneer ze over aangrenzende blokken zijn gesplitst.

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

Beschikbare richtlijnsleutels:

• 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 (MiniMax-gehele 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 instellingen 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 die naar off.
• /tts chat on|off|default schrijft een sessiegebonden auto-TTS-override voor de huidige chat.
• /tts persona <id> schrijft de lokale personavoorkeur; /tts persona off wist die.
• /tts latest leest het nieuwste assistant-antwoord uit het transcript van de huidige sessie en verzendt het eenmaal als audio. Het slaat alleen een hash van dat antwoord op in het sessie-item 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 gesaneerde metadata van aangepaste endpoints wanneer TTS is ingeschakeld.

# Voorkeuren per gebruiker

Slash-commando's schrijven lokale overrides 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 gestuurd door kanaalmogelijkheden. Kanaal-Plugins adverteren of TTS in stemstijl providers om een native voice-note-doel moet vragen of normale audio-file-synthese moet behouden en compatibele uitvoer alleen moet markeren voor stemlevering.

• Kanalen met ondersteuning voor spraaknotities: spraaknotitie-antwoorden 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 spraaknotitie-antwoord wordt geproduceerd als MP3/WebM/WAV/M4A of een ander waarschijnlijk audiobestand, transcodeert de kanaal-Plugin het 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; verzending via WhatsApp mislukt in plaats van een incompatibele PTT-payload te plaatsen.
• BlueBubbles: houdt providersynthese op het normale pad voor audiobestanden; MP3- en CAF-uitvoer wordt gemarkeerd voor levering als iMessage-spraakmemo.
• Andere kanalen: MP3 (mp3_44100_128 van ElevenLabs, mp3 van OpenAI).
  • 44,1 kHz / 128 kbps is de standaardbalans voor heldere spraak.
• 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 vóór levering naar 48 kHz Opus met ffmpeg wanneer het kanaal transcoding adverteert.
• Xiaomi MiMo: standaard MP3, of WAV wanneer geconfigureerd. Voor door kanalen geadverteerde doelen voor spraaknotities transcodeert OpenClaw Xiaomi-uitvoer vóór levering naar 48 kHz Opus met ffmpeg wanneer het kanaal transcoding adverteert.
• Lokale CLI: gebruikt de geconfigureerde outputFormat. Doelen voor spraaknotities 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 doelen voor spraaknotities en retourneert PCM rechtstreeks 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 het batch-REST-TTS-eindpunt van xAI en retourneert een volledige audiobijlage; de streaming TTS-WebSocket van xAI wordt niet gebruikt door dit providerpad. Native Opus-formaat voor spraaknotities 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 vanuit de service.
  • Waarden voor uitvoerformaten 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:-instructie 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 definitieve antwoorden nadat de tekststream is voltooid; de gegenereerde media doorloopt dezelfde kanaalmedianormalisatie als normale antwoordbijlagen.

Als het antwoord langer is dan maxLength en samenvatten 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-transcodering: Wanneer een voice-note-antwoord binnenkomt als MP3/WebM/WAV/M4A, transcodeert de kanaal-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 posten.
• MiniMax / Xiaomi MiMo: Standaard MP3 (32 kHz voor MiniMax speech-2.8-hd); getranscodeerd naar 48 kHz Opus voor voice-note-doelen via ffmpeg.
• Lokale CLI: Gebruikt geconfigureerde outputFormat. Voice-note-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 voice-note-doelen, retourneert PCM direct voor Talk/telefonie.
• Inworld: MP3-bijlagen, native OGG_OPUS voice-note, 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-voice-note-formaat 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 vastgezet zoals hierboven vermeld.

# Veldreferentie

# Agenttool

De tool tts zet tekst om naar spraak en retourneert een audiobijlage voor antwoordlevering. Op Feishu, Matrix, Telegram en WhatsApp wordt de audio geleverd 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 providerspecifieke aanvraagtime-out per aanroep in milliseconden.

# Gateway RPC

# Servicelinks

• OpenAI-handleiding voor tekst-naar-spraak
• OpenAI Audio API-referentie
• Azure Speech REST 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-uitvoerformaten
• xAI tekst-naar-spraak

# Gerelateerd

• Media-overzicht
• Muziek genereren
• Video genereren
• Slash-opdrachten
• Spraakoproep-Plugin