Text-to-speech (TTS)
WednesdayAI can convert outbound replies into audio using ElevenLabs, OpenAI, or Edge TTS. It works anywhere WednesdayAI can send audio; Telegram gets a round voice-note bubble.Supported services
- ElevenLabs (primary or fallback provider)
- OpenAI (primary or fallback provider; also used for summaries)
- Edge TTS (primary or fallback provider; built-in client, default when no API keys)
- Plugin providers (primary or fallback provider; registered by plugins such as the bundled Kokoro plugin — see Custom and local providers)
Edge TTS notes
Edge TTS uses Microsoft Edge’s online neural TTS service through a built-in client vendored from thenode-edge-tts library. It’s a hosted service (not local), uses Microsoft’s endpoints, and
does not require an API key. The client exposes speech configuration options and output formats,
but not all options are supported by the Edge service. citeturn2search0
Because Edge TTS is a public web service without a published SLA or quota, treat it
as best-effort. If you need guaranteed limits and support, use OpenAI or ElevenLabs.
Microsoft’s Speech REST API documents a 10‑minute audio limit per request; Edge TTS
does not publish limits, so assume similar or lower limits. citeturn0search3
Optional keys
If you want OpenAI or ElevenLabs:ELEVENLABS_API_KEY(orXI_API_KEY)OPENAI_API_KEY
messages.tts.edge.enabled=false).
If multiple providers are configured, the selected provider is used first and the others are fallback options.
Auto-summary uses the configured summaryModel (or agents.defaults.model.primary),
so that provider must also be authenticated if you enable summaries.
Service links
- OpenAI Text-to-Speech guide
- OpenAI Audio API reference
- ElevenLabs Text to Speech
- ElevenLabs Authentication
- node-edge-tts
- Microsoft Speech output formats
Is it enabled by default?
No. Auto‑TTS is off by default. Enable it in config withmessages.tts.auto or per session with /tts always (alias: /tts on).
Edge TTS is enabled by default once TTS is on, and is used automatically
when no OpenAI or ElevenLabs API keys are available.
Config
TTS config lives undermessages.tts in openclaw.json.
Full schema is in Gateway configuration.
Minimal config (enable + provider)
OpenAI primary with ElevenLabs fallback
Edge TTS primary (no API key)
Disable Edge TTS
Custom limits + prefs path
Only reply with audio after an inbound voice note
Voice note conversation loop
voiceNoteLoop keeps the conversation in voice-note mode after the agent replies. When the user sends a voice note and TTS generates audio, the mode controls what gets delivered back.
"disabled"(default): reply is text only; TTS still applies perautomode."enabled": when inbound message is a voice note and TTS generates audio, the text is suppressed — only the voice note is delivered back."both": reply delivers both the voice note and text. On WhatsApp, text is sent as a separate follow-up message (WhatsApp audio messages do not support captions).
Disable auto-summary for long replies
Notes on fields
auto: auto‑TTS mode (off,always,inbound,tagged).inboundonly sends audio after an inbound voice note.taggedonly sends audio when the reply includes[[tts]]tags.
enabled: legacy toggle (doctor migrates this toauto).mode:"final"(default) or"all"(includes tool/block replies).provider:"elevenlabs","openai","edge", or a plugin-registered provider id such askokoro(fallback is automatic).- If
provideris unset, WednesdayAI prefersopenai(if key), thenelevenlabs(if key), otherwiseedge. Plugin providers are never auto-selected; setproviderto use one. summaryModel: optional cheap model for auto-summary; defaults toagents.defaults.model.primary.- Accepts
provider/modelor a configured model alias.
- Accepts
modelOverrides: allow the model to emit TTS directives (on by default).allowProviderdefaults tofalse(provider switching is opt-in).
maxTextLength: hard cap for TTS input (chars), measured on the text before speech cleanup./tts audiofails if exceeded. Cleanup can make the spoken text slightly longer (x >= 5becomes “x greater than or equal to 5”); that text is still synthesized.timeoutMs: request timeout (ms).prefsPath: override the local prefs JSON path (provider/limit/summary).apiKeyvalues fall back to env vars (ELEVENLABS_API_KEY/XI_API_KEY,OPENAI_API_KEY).elevenlabs.baseUrl: override ElevenLabs API base URL.elevenlabs.modelId: ElevenLabs model id (defaulteleven_multilingual_v2). For interactive Read aloud,eleven_flash_v2_5sounds nearly the same and responds noticeably faster, which matters when the client plays chunks back to back; the batch default stayseleven_multilingual_v2for the best quality on one-shot voice notes.openai.baseUrl: OpenAI-compatible endpoint for OpenAI TTS (defaulthttps://api.openai.com/v1). Overridable per agent withagents.list[].tts.openai.baseUrl. Replaces the deprecatedOPENAI_TTS_BASE_URLenv var, which is now only used when no config value is set (the gateway logs a one-time deprecation warning when it is the source). A non-default endpoint also relaxes the OpenAI model and voice validators, so a local server can accept model and voice names api.openai.com does not know.providers: per-provider settings for plugin-registered speech providers, keyed by provider id (voice,model, plus provider-specific keys). Built-in ids are rejected here; per-agent override underagents.list[].tts.providers. See Custom and local providers.elevenlabs.voiceSettings:stability,similarityBoost,style:0..1useSpeakerBoost:true|falsespeed:0.5..2.0(1.0 = normal)
elevenlabs.applyTextNormalization:auto|on|offelevenlabs.languageCode: 2-letter ISO 639-1 (e.g.en,de)elevenlabs.seed: integer0..4294967295(best-effort determinism)edge.enabled: allow Edge TTS usage (defaulttrue; no API key).edge.voice: Edge neural voice name (e.g.en-US-MichelleNeural).edge.lang: language code (e.g.en-US).edge.outputFormat: Edge output format (e.g.audio-24khz-48kbitrate-mono-mp3).- See Microsoft Speech output formats for valid values; not all formats are supported by Edge.
edge.rate/edge.pitch/edge.volume: percent strings (e.g.+10%,-5%).edge.saveSubtitles: write JSON subtitles alongside the audio file.edge.proxy: proxy URL for Edge TTS requests.edge.timeoutMs: request timeout override (ms).voiceNoteLoop: voice note conversation loop mode ("disabled"|"enabled"|"both"). Telegram and WhatsApp only. Default"disabled".readAloud.enabled: allow chat clients to read replies aloud on demand through thetts.speakgateway RPC (web client’s Read aloud action). Defaulttrue. Turn off to stop on-demand synthesis spend; auto-TTS and/ttsare unaffected.naturalize.enabled: rewrite reply text into natural spoken English before any TTS provider synthesizes it (defaulttrue): arrows, comparison operators, slashes, file paths, hashes and identifiers become words or are dropped, and code blocks are announced as omitted. Markdown, code, emoji and URL paths are always removed regardless. Turn off for non-English assistants; override per agent withagents.list[].tts.naturalize.enabled. See How replies are spoken.naturalize.mode:"rules"(default) uses only the built-in speech rules."llm"also asks a model to rewrite automatic voice replies, read aloud and/ttsaudio for natural phrasing, which adds a model call (cost and latency) per clip and sends the reply text to that model. Live voice (Voice mode, Discord voice, phone calls) always uses rules. Falls back to the rules text if the model fails.naturalize.model: model for the naturalizellmrewrite, as provider/model or an alias. Defaults tomessages.tts.summaryModel, then the default agent model. A local model keeps reply text on your machine.
Per-agent TTS (agents.list[].tts)
Any agent entry can carry a tts block with the same fields as messages.tts
(voice, provider, model, readAloud, …). It is deep-merged over the
global config, so a per-agent block only needs the fields that differ:
/tts commands, and
the tts tool for that agent. A provider pinned with /tts provider (stored in
the prefs file) still wins over any configured provider.
For Discord voice playback there is one more layer: the resolution order is
messages.tts → the route agent’s agents.list[].tts → channels.discord.voice.tts,
so voice.tts still wins for voice channels.
How replies are spoken
Before any provider synthesizes audio, WednesdayAI prepares the reply text for speech with a deterministic cleanup stage. The text on screen is unchanged; only the audio input is cleaned. The cleanup has two stages: Structural, always on (language-neutral). Markdown and layout are removed and the result is joined into a single line with sentence pauses:- Headings and emphasis become plain sentences:
## Weatherfollowed byIt will rain.is spoken as “Weather. It will rain.” - Lists become spoken sentences; ordered lists speak their item numbers (“1. Open settings”) and task-list checkboxes are dropped.
- Tables are read row by row: a
| Name | Role |table becomes “Name: Ada, Role: Admin. Name: Bob, Role: User.” - Links are spoken by their label text; a bare URL is spoken as its host without
www.(https://www.example.com/docsbecomes “example.com”). - Images, strikethrough text, HTML elements and emoji are dropped. Placeholder tags such as
<your-api-key>stay as literal text. - The output is one line, so providers that truncate input at a newline never lose text.
naturalize.enabled, default true). Symbols and machine text become words:
The rules also turn underscores into spaces, read parentheticals as comma-delimited asides
(
Restart (after saving) now becomes “Restart, after saving, now”), and capitalise the first
letter after a sentence end.
Numbers, filenames and acronyms (always on)
After the URL cleanup, a deterministic normaliser runs on every speech unit, in bothnaturalize.enabled: true and false. It turns numbers, identifiers and machine text into
already-spoken words before any provider sees them, because different providers’ text-to-grapheme
stages disagree: some read four-digit numbers as years, a hyphen-prefixed number as “minus”, an
all-caps word as one shouted word, or skip codes the dictionary does not know. Its output forms:
File names that contain a digit or an underscore keep their extension with a spoken “dot”. A
digit-free name such as
report.pdf is left as written, and so are decimals, versions, times and
dates (3.14159, v1.2.3, 10:30, 2026-11-16). Short letter-prefixed codes like Q1 and
H2 speak the letter and then the number. Acronyms of two to four letters are spelled with
dotted letters (A.M.D.), except a small list of well-known spoken acronyms (NASA, NATO, GIF,
JSON and similar) which stay as written, and common all-caps English words (NONE, NOTE, TOTAL,
URGENT and similar) which are spoken as lowercase words. Standalone numbers of five or more
digits are read digit by digit unless the next word names a quantity (users, rows, records,
dollars and similar), in which case they are read as a full quantity. Money and percentages are
read as words. A reply unit that is exactly one of the silent sentinels NONE, NO_REPLY or
HEARTBEAT_OK speaks nothing at all, in both naturalize settings. Email addresses are never
rewritten.
Turning it off or changing it
messages.tts.naturalize controls the pass globally and agents.list[].tts.naturalize overrides
it per agent. enabled: false skips only the English rules above: markdown, code, emoji and URL
paths are still removed, and code blocks are then dropped silently. The switch exists so
non-English assistants avoid inserted English words like “to” or “or”; a raw ### or table pipe is
never worth speaking either way.
llm mode (opt-in)
naturalize.mode: "llm" adds a model rewrite on top of the rules for batch paths only:
automatic voice replies, the web client’s Read aloud, and /tts audio. Live speech (Voice mode,
Discord voice, phone calls), the tts tool and tts.convert always use the rules only, because a
model call adds cost and latency per clip and sends reply text to that model.
- The model sees the rules-cleaned text, never raw markdown, and the rules run again on its output. If the rewrite fails, is truncated, or is suspiciously shorter than the rules text, WednesdayAI falls back to the rules text and logs a warning (never the text itself).
- The model is
naturalize.model, defaulting tomessages.tts.summaryModel, then the default agent model. A local model keeps reply text on your machine.
Read modes
Every synthesis request carries a read mode that selects how much rewriting happens before the provider speaks. Three modes, plus two optional per-request parameters ontts.speak (Read
aloud) and talk.session.create (Voice conversation):
literal: only the structural cleanup runs. No English word substitutions, no code-block announcement, no model rewrite. Code blocks are dropped silently.human(default): the English speech lexicon rules and the normaliser above run. This is what the rules pass did before read modes.hybrid:humanplus the LLM spoken rewrite (naturalize.mode: "llm"). The model rewrite is added only on the batch paths, Read aloud,/tts audioand automatic voice replies. Voice mode treatshybridashuman: a model call per streamed clause adds too much latency.
messages.tts.naturalize setting, so there is no
new config key: enabled: false reads literal, mode: "llm" reads hybrid, anything else reads
human. A readMode parameter on the request overrides the derived default for that request.
The second optional parameter is speed, a synthesis speed multiplier from 0.75 to 2, where 1 is
unchanged. Speed is provider-native, so pitch stays natural. The Kokoro plugin forwards it to
Kokoro-FastAPI’s /audio/speech (Kokoro honours it); other providers ignore it for now and speak
at their normal rate. A speed change takes effect from the next chunk the provider synthesizes.
Voice mode
Voice mode cleans the assistant stream with the same rules, clause by clause. Fenced code is tracked across the streamed clauses and is not spoken: the block is announced as “Code example omitted” (or dropped with the rules off), and prose after a closing fence is spoken.Custom and local providers
Plugins can register additional batch TTS providers, so you are not limited to the built-inelevenlabs, openai and edge. WednesdayAI ships one bundled plugin provider: Kokoro, a
local text-to-speech server from Kokoro-FastAPI. It
speaks OpenAI-compatible TTS against your own hardware, with no API key.
Run a Kokoro server
ghcr.io/remsky/kokoro-fastapi-gpu. Confirm the server is up:
curl localhost:8880/v1/models should list the kokoro model.
Enable the plugin and select the provider
plugins.entries.kokoro.enabled: the plugin is bundled but disabled by default.plugins.entries.kokoro.config.baseUrl: Kokoro-FastAPI endpoint (defaulthttp://127.0.0.1:8880/v1).plugins.entries.kokoro.config.model: model id (defaultkokoro).plugins.entries.kokoro.config.voice: default voice (defaultaf_heart).messages.tts.provider/agents.list[].tts.provider: set tokokoroto make it the primary provider for that scope. Plugin providers never win automatic selection; you must setprovider.talk.provider: makes Kokoro the spoken reply provider for Voice conversation (see below).
messages.tts.providers.<id> (and the per-agent override agents.list[].tts.providers.<id>),
with voice and model as the common keys. Built-in ids are rejected under providers — the
built-ins keep their own blocks (messages.tts.openai, messages.tts.elevenlabs,
messages.tts.edge).
Fallback order
When the primary provider fails, the fallback order is: the configured primary, then the built-ins (openai, elevenlabs, edge), then the remaining plugin-registered providers. A plugin provider
can therefore serve as a fallback for OpenAI or ElevenLabs without extra configuration.
Per-agent voices
Theagents.list[].tts block gives each agent its own voice, and it applies everywhere the agent
speaks: Read aloud, voice notes, auto-TTS, the /tts commands and the tts tool. In the example
above, the ops agent speaks with am_adam while every other agent uses the plugin default
af_heart.
Voices can be mixed, passing several through at once — for example af_bella+af_sky:
Voice conversation voice precedence
When Voice conversation (talk.provider: "kokoro" in stt-tts mode) speaks, the voice resolves in
this order:
- The active agent’s
agents.list[].ttsvoice for the talk provider (agents.list[].tts.providers.kokoro.voice). talk.providers.kokoro.voiceId(the global Talk setting, unchanged).messages.tts.providers.kokoro.voice(plugin providers only).- The provider’s default voice (the plugin’s
config.voice,af_heart).
Kokoro is speech output only. Voice conversation still needs a streaming speech-to-text provider
(for example ElevenLabs) — see
Voice conversation sessions and
ElevenLabs streaming voice.
Read aloud for chat clients
The web client’s Read aloud button reads an assistant reply aloud on demand. The client sends the reply text to thetts.speak gateway RPC, which synthesizes it with the merged TTS config
above and returns inline audio; tts.readAloud.status tells the client whether the button is
available and what the text limit is. Both RPCs are admitted to the web client’s narrow
operator.sessions.read/operator.sessions.write scopes (see ADR 0102).
What decides whether the button is available:
- The gate:
messages.tts.readAloud.enabled(defaulttrue), with the per-agent overrideagents.list[].tts.readAloud.enabled. Turning the gate off stops on-demand synthesis spend; auto-TTS,/ttsand thettstool are unaffected. - A configured provider. Edge TTS counts when enabled, so the default config works with no API key.
- Read aloud and Voice mode never overlap: while a Voice conversation is active (listening,
thinking or speaking), the button is unavailable (
unavailable during Voice mode), and starting Voice mode stops any playback in progress. - The client skips code blocks, tables and raw HTML when it decides what to speak, packs the rest
into short chunks — at most 200 characters for the first chunk so playback starts after one
short synthesis, 600 for later chunks, each still under
maxTextLength(default 4096) — and plays them in sequence, synthesizing the next chunk while the current one plays, so a long reply still plays in full. - Text longer than
maxTextLengthis refused withtext_too_long; a synthesized clip larger than 16 MiB is refused withaudio_too_large. - There is no rate limit; the gate and
maxTextLengthare the controls. - Playback survives a dropped connection: the client retries a transient synthesis failure
(socket close,
UNAVAILABLE, retryable rate limit) up to 2 more times before it shows an error, so nothing gateway-side is needed for a read to continue across a reconnect. A permanent refusal (readAlouddisabled for the agent) is never retried. - TTS config is read when the gateway starts. Restart the gateway after changing any
messages.ttsoragents.list[].ttsvalue.
Model-driven overrides (default on)
By default, the model can emit TTS directives for a single reply. Whenmessages.tts.auto is tagged, these directives are required to trigger audio.
When enabled, the model can emit [[tts:...]] directives to override the voice
for a single reply, plus an optional [[tts:text]]...[[/tts:text]] block to
provide expressive tags (laughter, singing cues, etc) that should only appear in
the audio.
provider=... directives are ignored unless modelOverrides.allowProvider: true.
Example reply payload:
provider(openai|elevenlabs|edge, or a registered plugin provider id; requiresallowProvider: true; ids are matched case-insensitively)voice(OpenAI voice) orvoiceId(ElevenLabs)model— routing depends on the key and value:openai_model=goes to OpenAI andelevenlabs_model=to ElevenLabs. A baremodel=routes by value: a known OpenAI model id goes to OpenAI, aneleven_*model id goes to ElevenLabs; with a customopenai.baseUrl, any other id goes to OpenAI (the endpoint decides what it accepts), otherwise to ElevenLabs.stability,similarityBoost,style,speed,useSpeakerBoostapplyTextNormalization(auto|on|off)languageCode(ISO 639-1)seed
voice= and voiceId= only affect the
OpenAI and ElevenLabs built-ins, and a plugin provider takes its voice and model from
messages.tts.providers.<id> (or the per-agent agents.list[].tts.providers.<id>) config. A
provider= directive may still name a plugin provider when allowProvider is on.
Disable all model overrides:
Per-user preferences
Slash commands write local overrides toprefsPath (default:
~/.openclaw/settings/tts.json, override with OPENCLAW_TTS_PREFS or
messages.tts.prefsPath).
Stored fields:
enabledprovidermaxLength(summary threshold; default 1500 chars)summarize(defaulttrue)
messages.tts.* for that host.
Output formats (fixed)
- Telegram: Opus voice note (
opus_48000_64from ElevenLabs,opusfrom OpenAI).- 48kHz / 64kbps is a good voice-note tradeoff and required for the round bubble.
- Other channels: MP3 (
mp3_44100_128from ElevenLabs,mp3from OpenAI).- 44.1kHz / 128kbps is the default balance for speech clarity.
- Edge TTS: uses
edge.outputFormat(defaultaudio-24khz-48kbitrate-mono-mp3).- The Edge client accepts an
outputFormat, but not all formats are available from the Edge service. citeturn2search0 - Output format values follow Microsoft Speech output formats (including Ogg/WebM Opus). citeturn1search0
- Telegram
sendVoiceaccepts OGG/MP3/M4A; use OpenAI/ElevenLabs if you need guaranteed Opus voice notes. citeturn1search1 - If the configured Edge output format fails, WednesdayAI retries with MP3.
- The Edge client accepts an
Auto-TTS behavior
When enabled, WednesdayAI:- skips TTS if the reply already contains media or a
MEDIA:directive. - skips very short replies (< 10 chars).
- summarizes long replies when enabled using
agents.defaults.model.primary(orsummaryModel). - attaches the generated audio to the reply.
maxLength and summary is off (or no API key for the
summary model), audio
is skipped and the normal text reply is sent.
Flow diagram
Slash command usage
There is a single command:/tts.
See Slash commands for enablement details.
Discord note: /tts is a built-in Discord command, so WednesdayAI registers
/voice as the native command there. Text /tts ... still works.
- Commands require an authorized sender (allowlist/owner rules still apply).
commands.textor native command registration must be enabled.off|always|inbound|taggedare per‑session toggles (/tts onis an alias for/tts always).limitandsummaryare stored in local prefs, not the main config./tts provideraccepts a built-in id or a plugin-registered provider id (for example/tts provider kokoro);/tts providerwith no argument lists every provider with its configured state./tts audiogenerates a one-off audio reply (does not toggle TTS on).
Agent tool
Thetts tool converts text to speech and returns a MEDIA: path. When the
result is Telegram-compatible, the tool includes [[audio_as_voice]] so
Telegram sends a voice bubble.
Gateway RPC
Gateway methods:tts.statustts.enabletts.disabletts.converttts.setProvidertts.providerstts.speak(on-demand read aloud, inline audio)tts.readAloud.status(whether read aloud is available)
Troubleshooting
The web client’s Read aloud button is unavailable or fails Check, in order:messages.tts.readAloud.enabled is true (or that agent’s
agents.list[].tts.readAloud.enabled does not override it to false); a provider is configured
(Edge TTS with messages.tts.edge.enabled at its true default counts). Turning read aloud off
does not affect auto-TTS, /tts or the tts tool. A request whose text exceeds
messages.tts.maxTextLength fails with text_too_long, and a clip larger than 16 MiB fails with
audio_too_large. Config changes need a gateway restart.
Read aloud sounds different from the configured provider, or is slow
When a configured provider fails, the gateway falls back to the next one and logs a warning naming
which provider served the request: tts.speak: served by <provider> after N failed provider(s) in <latency>ms: <provider>: <error>…. The error text is redacted of credentials, so it is safe to
paste into support requests; the failing provider’s error says what to fix.
The voice reads symbols like “dash greater than”, “slash” or “hash hash”
The naturalize pass is off where it should be on. Check messages.tts.naturalize.enabled is
true (the default) and that the agent speaking does not override it to false with
agents.list[].tts.naturalize.enabled. Config changes need a gateway restart. Code blocks are
still removed with the pass off, so a voice that reads code back is a separate symptom: check
whether the clip came from a streaming Voice mode engine, which speaks its own model output and
does not run this pass.
The assistant is non-English and the voice inserts English words
Turn the English rules off for that agent with agents.list[].tts.naturalize.enabled: false (or
globally with messages.tts.naturalize.enabled: false). The structural cleanup keeps running —
markdown, code, emoji and URL paths are still removed — only the English word substitutions stop,
so code blocks are dropped silently instead of being announced as omitted.
naturalize.mode: "llm" produces no rewritten phrasing
Check messages.tts.naturalize.mode is "llm", that the mode only affects automatic voice
replies, Read aloud and /tts audio (live speech and the tts tool never use it), and that
naturalize.model (defaulting to messages.tts.summaryModel, then the default agent model)
resolves to a model the gateway can authenticate. When the model call fails or its rewrite looks
wrong, WednesdayAI silently falls back to the rules text and logs a warning in the gateway logs — the
warning never contains the reply text.
TTS is enabled but no audio is sent — only text arrives
Check that messages.tts.auto is set to "always", "inbound", or "tagged" (not "off"). The /tts status command shows the active mode for the current session. Also confirm at least one provider is available: ElevenLabs or OpenAI API key in config or env vars, or Edge TTS enabled (messages.tts.edge.enabled defaults to true). Replies shorter than 10 characters and replies that already contain media are always sent as text.
Audio is generated but Telegram doesn’t show it as a round voice bubble
Telegram requires Opus-encoded OGG for voice notes. WednesdayAI uses opus output from OpenAI and opus_48000_64 from ElevenLabs automatically. Edge TTS uses the edge.outputFormat you configure; set it to an Ogg/WebM Opus format if you need guaranteed voice bubbles, or switch to OpenAI or ElevenLabs for Telegram.
Edge TTS fails with a connection error
Edge TTS connects to Microsoft’s online endpoints and has no published SLA. Transient failures are expected; WednesdayAI retries with MP3 on format errors. For reliable production use, configure OpenAI or ElevenLabs as the primary provider and let Edge TTS serve as a fallback only.
voiceNoteLoop: "enabled" shows text replies instead of audio-only
voiceNoteLoop only suppresses text when (1) the inbound message was a voice note and (2) TTS successfully generated audio. If TTS fails (API error, text too long, no provider), the text reply is sent as a fallback. Check the gateway logs for TTS errors. Also verify messages.tts.auto is "inbound" or "always" — "tagged" mode requires a [[tts]] tag in the reply to trigger audio.
Related
This page covers
messages.tts: one-shot, whole-utterance audio attached to an outbound chat
reply. It is a separate system from the live voice conversation behind the
/v2/client web client’s Dictate and Voice mode controls, which uses talk.conversation/
talk.providers.<id> instead — see
Voice conversation sessions and
ElevenLabs streaming voice. The two keep separate ElevenLabs config even
when both point at the same vendor: cascaded Voice mode reads talk.providers.<id>, not
messages.tts.elevenlabs, and an unset cascaded Voice model falls back to eleven_flash_v2_5
rather than this page’s eleven_multilingual_v2. The realtime Voice engine likewise reads its
own Talk provider credentials — for example talk.providers["openai-realtime"].apiKey (falling
back to plugin defaults and OPENAI_API_KEY) — but it does not read messages.tts either.