Text-to-speech (TTS)

OpenClaw can convert outbound replies into audio using ElevenLabs, OpenAI, or Edge TTS. It works anywhere OpenClaw 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; uses node-edge-tts, default when no API keys)

Edge TTS notes

Edge TTS uses Microsoft Edge’s online neural TTS service via the node-edge-tts library. It’s a hosted service (not local), uses Microsoft’s endpoints, and does not require an API key. node-edge-tts exposes speech configuration options and output formats, but not all options are supported by the Edge service. citeturn2search0 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. citeturn0search3

Optional keys

If you want OpenAI or ElevenLabs:

ELEVENLABS_API_KEY (or XI_API_KEY)
OPENAI_API_KEY

Edge TTS does not require an API key. If no API keys are found, OpenClaw defaults to Edge TTS (unless disabled via 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

Is it enabled by default?

No. Auto‑TTS is off by default. Enable it in config with messages.tts.auto or per session with /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 under messages.tts in openclaw.json. Full schema is in Gateway configuration.

Minimal config (enable + provider)

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

OpenAI primary with ElevenLabs fallback

{
  messages: {
    tts: {
      auto: "always",
      provider: "openai",
      summaryModel: "openai/gpt-4.1-mini",
      modelOverrides: {
        enabled: true,
      },
      openai: {
        apiKey: "openai_api_key",
        model: "gpt-4o-mini-tts",
        voice: "alloy",
      },
      elevenlabs: {
        apiKey: "elevenlabs_api_key",
        baseUrl: "https://api.elevenlabs.io",
        voiceId: "voice_id",
        modelId: "eleven_multilingual_v2",
        seed: 42,
        applyTextNormalization: "auto",
        languageCode: "en",
        voiceSettings: {
          stability: 0.5,
          similarityBoost: 0.75,
          style: 0.0,
          useSpeakerBoost: true,
          speed: 1.0,
        },
      },
    },
  },
}

Edge TTS primary (no API key)

{
  messages: {
    tts: {
      auto: "always",
      provider: "edge",
      edge: {
        enabled: true,
        voice: "en-US-MichelleNeural",
        lang: "en-US",
        outputFormat: "audio-24khz-48kbitrate-mono-mp3",
        rate: "+10%",
        pitch: "-5%",
      },
    },
  },
}

Disable Edge TTS

{
  messages: {
    tts: {
      edge: {
        enabled: false,
      },
    },
  },
}

Custom limits + prefs path

{
  messages: {
    tts: {
      auto: "always",
      maxTextLength: 4000,
      timeoutMs: 30000,
      prefsPath: "~/.openclaw/settings/tts.json",
    },
  },
}

Only reply with audio after an inbound voice note

{
  messages: {
    tts: {
      auto: "inbound",
    },
  },
}

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 per auto mode.
"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).

Supported channels: Telegram, WhatsApp.

{
  messages: {
    tts: {
      auto: "inbound",
      voiceNoteLoop: "enabled",
    },
  },
}

Disable auto-summary for long replies

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

Then run:

/tts summary off

Notes on fields

auto: auto‑TTS mode (off, always, inbound, tagged).
- inbound only sends audio after an inbound voice note.
- tagged only sends audio when the reply includes [[tts]] tags.
enabled: legacy toggle (doctor migrates this to auto).
mode: "final" (default) or "all" (includes tool/block replies).
provider: "elevenlabs", "openai", or "edge" (fallback is automatic).
If provider is unset, OpenClaw prefers openai (if key), then elevenlabs (if key), otherwise edge.
summaryModel: optional cheap model for auto-summary; defaults to agents.defaults.model.primary.
- Accepts provider/model or a configured model alias.
modelOverrides: allow the model to emit TTS directives (on by default).
- allowProvider defaults to false (provider switching is opt-in).
maxTextLength: hard cap for TTS input (chars). /tts audio fails if exceeded.
timeoutMs: request timeout (ms).
prefsPath: override the local prefs JSON path (provider/limit/summary).
apiKey values fall back to env vars (ELEVENLABS_API_KEY/XI_API_KEY, OPENAI_API_KEY).
elevenlabs.baseUrl: override ElevenLabs API base URL.
elevenlabs.voiceSettings:
- stability, similarityBoost, style: 0..1
- useSpeakerBoost: true|false
- speed: 0.5..2.0 (1.0 = normal)
elevenlabs.applyTextNormalization: auto|on|off
elevenlabs.languageCode: 2-letter ISO 639-1 (e.g. en, de)
elevenlabs.seed: integer 0..4294967295 (best-effort determinism)
edge.enabled: allow Edge TTS usage (default true; 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".

Model-driven overrides (default on)

By default, the model can emit TTS directives for a single reply. When messages.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:

Here you go.

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

Available directive keys (when enabled):

provider (openai | elevenlabs | edge, requires allowProvider: true)
voice (OpenAI voice) or voiceId (ElevenLabs)
model (OpenAI TTS model or ElevenLabs model id)
stability, similarityBoost, style, speed, useSpeakerBoost
applyTextNormalization (auto|on|off)
languageCode (ISO 639-1)
seed

Disable all model overrides:

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

Optional allowlist (enable provider switching while keeping other knobs configurable):

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

Per-user preferences

Slash commands write local overrides to prefsPath (default: ~/.openclaw/settings/tts.json, override with OPENCLAW_TTS_PREFS or messages.tts.prefsPath). Stored fields:

enabled
provider
maxLength (summary threshold; default 1500 chars)
summarize (default true)

These override messages.tts.* for that host.

Output formats (fixed)

Telegram: Opus voice note (opus_48000_64 from ElevenLabs, opus from OpenAI).
- 48kHz / 64kbps is a good voice-note tradeoff and required for the round bubble.
Other channels: MP3 (mp3_44100_128 from ElevenLabs, mp3 from OpenAI).
- 44.1kHz / 128kbps is the default balance for speech clarity.
Edge TTS: uses edge.outputFormat (default audio-24khz-48kbitrate-mono-mp3).
- node-edge-tts accepts an outputFormat, but not all formats are available from the Edge service. citeturn2search0
- Output format values follow Microsoft Speech output formats (including Ogg/WebM Opus). citeturn1search0
- Telegram sendVoice accepts OGG/MP3/M4A; use OpenAI/ElevenLabs if you need guaranteed Opus voice notes. citeturn1search1
- If the configured Edge output format fails, OpenClaw retries with MP3.

OpenAI/ElevenLabs formats are fixed; Telegram expects Opus for voice-note UX.

Auto-TTS behavior

When enabled, OpenClaw:

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 (or summaryModel).
attaches the generated audio to the reply.

If the reply exceeds 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

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 (summaryModel or agents.defaults.model.primary)
                                      -> TTS -> attach audio

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 OpenClaw registers /voice as the native command there. Text /tts ... still works.

/tts on
/tts off
/tts status
/tts provider openai
/tts limit 2000
/tts summary off
/tts audio Hello from OpenClaw
/tts help

Notes:

Commands require an authorized sender (allowlist/owner rules still apply).
commands.text or native command registration must be enabled.
Bare /tts shows the current status.
on / off are the per‑session toggle. The finer modes — always, inbound, tagged — are config values for messages.tts.auto, not chat commands.
limit (default 1500, max 4096) and summary are stored in local prefs, not the main config.
/tts audio generates a one-off audio reply (does not toggle TTS on).

Agent tool

The tts 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.status
tts.enable
tts.disable
tts.convert
tts.setProvider
tts.providers

Troubleshooting

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. OpenClaw 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; OpenClaw 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.

Getting started

Talking to your AI

Built-in tools

Help

Users

Automation

CLI command reference

Help and FAQ

Media nodes

Setup and onboarding

Voice and realtime

More agent tools

Shohin

Text-to-Speech

Text-to-speech (TTS)

Supported services

Edge TTS notes

Optional keys

Service links

Is it enabled by default?

Config

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

Disable auto-summary for long replies

Notes on fields

Model-driven overrides (default on)

Per-user preferences

Output formats (fixed)

Auto-TTS behavior

Flow diagram

Slash command usage

Agent tool

Gateway RPC

Troubleshooting

​Text-to-speech (TTS)

​Supported services

​Edge TTS notes

​Optional keys

​Service links

​Is it enabled by default?

​Config

​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

​Disable auto-summary for long replies

​Notes on fields

​Model-driven overrides (default on)

​Per-user preferences

​Output formats (fixed)

​Auto-TTS behavior

​Flow diagram

​Slash command usage

​Agent tool

​Gateway RPC

​Troubleshooting

​Related

Text-to-speech (TTS)

Supported services

Edge TTS notes

Optional keys

Service links

Is it enabled by default?

Config

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

Disable auto-summary for long replies

Notes on fields

Model-driven overrides (default on)

Per-user preferences

Output formats (fixed)

Auto-TTS behavior

Flow diagram

Slash command usage

Agent tool

Gateway RPC

Troubleshooting

Related