Gateway configuration<\/a>.<\/p>\nMinimal config (enable + provider)<\/h3>\n
“`json5 theme={“theme”:{“light”:”min-light”,”dark”:”min-dark”}}
\n{
\n messages: {
\n tts: {
\n auto: “always”,
\n provider: “elevenlabs”,
\n },
\n },
\n}<\/p>\n
\n### OpenAI primary with ElevenLabs fallback\n\n```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}\n{\n messages: {\n tts: {\n auto: "always",\n provider: "openai",\n summaryModel: "openai\/gpt-4.1-mini",\n modelOverrides: {\n enabled: true,\n },\n openai: {\n apiKey: "openai_api_key",\n baseUrl: "https:\/\/api.openai.com\/v1",\n model: "gpt-4o-mini-tts",\n voice: "alloy",\n },\n elevenlabs: {\n apiKey: "elevenlabs_api_key",\n baseUrl: "https:\/\/api.elevenlabs.io",\n voiceId: "voice_id",\n modelId: "eleven_multilingual_v2",\n seed: 42,\n applyTextNormalization: "auto",\n languageCode: "en",\n voiceSettings: {\n stability: 0.5,\n similarityBoost: 0.75,\n style: 0.0,\n useSpeakerBoost: true,\n speed: 1.0,\n },\n },\n },\n },\n}\n<\/code><\/pre>\nMicrosoft primary (no API key)<\/h3>\n
“`json5 theme={“theme”:{“light”:”min-light”,”dark”:”min-dark”}}
\n{
\n messages: {
\n tts: {
\n auto: “always”,
\n provider: “microsoft”,
\n microsoft: {
\n enabled: true,
\n voice: “en-US-MichelleNeural”,
\n lang: “en-US”,
\n outputFormat: “audio-24khz-48kbitrate-mono-mp3”,
\n rate: “+10%”,
\n pitch: “-5%”,
\n },
\n },
\n },
\n}<\/p>\n
\n### Disable Microsoft speech\n\n```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}\n{\n messages: {\n tts: {\n microsoft: {\n enabled: false,\n },\n },\n },\n}\n<\/code><\/pre>\nCustom limits + prefs path<\/h3>\n
“`json5 theme={“theme”:{“light”:”min-light”,”dark”:”min-dark”}}
\n{
\n messages: {
\n tts: {
\n auto: “always”,
\n maxTextLength: 4000,
\n timeoutMs: 30000,
\n prefsPath: “~\/.openclaw\/settings\/tts.json”,
\n },
\n },
\n}<\/p>\n
\n### Only reply with audio after an inbound voice note\n\n```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}\n{\n messages: {\n tts: {\n auto: "inbound",\n },\n },\n}\n<\/code><\/pre>\nDisable auto-summary for long replies<\/h3>\n
“`json5 theme={“theme”:{“light”:”min-light”,”dark”:”min-dark”}}
\n{
\n messages: {
\n tts: {
\n auto: “always”,
\n },
\n },
\n}<\/p>\n
\nThen run:\n\n<\/code><\/pre>\n\/tts summary off<\/p>\n
\n### Notes on fields\n\n* `auto`: auto\u2011TTS mode (`off`, `always`, `inbound`, `tagged`).\n * `inbound` only sends audio after an inbound voice note.\n * `tagged` only sends audio when the reply includes `[[tts]]` tags.\n* `enabled`: legacy toggle (doctor migrates this to `auto`).\n* `mode`: `"final"` (default) or `"all"` (includes tool\/block replies).\n* `provider`: speech provider id such as `"elevenlabs"`, `"microsoft"`, or `"openai"` (fallback is automatic).\n* If `provider` is **unset**, OpenClaw prefers `openai` (if key), then `elevenlabs` (if key),\n otherwise `microsoft`.\n* Legacy `provider: "edge"` still works and is normalized to `microsoft`.\n* `summaryModel`: optional cheap model for auto-summary; defaults to `agents.defaults.model.primary`.\n * Accepts `provider\/model` or a configured model alias.\n* `modelOverrides`: allow the model to emit TTS directives (on by default).\n * `allowProvider` defaults to `false` (provider switching is opt-in).\n* `maxTextLength`: hard cap for TTS input (chars). `\/tts audio` fails if exceeded.\n* `timeoutMs`: request timeout (ms).\n* `prefsPath`: override the local prefs JSON path (provider\/limit\/summary).\n* `apiKey` values fall back to env vars (`ELEVENLABS_API_KEY`\/`XI_API_KEY`, `OPENAI_API_KEY`).\n* `elevenlabs.baseUrl`: override ElevenLabs API base URL.\n* `openai.baseUrl`: override the OpenAI TTS endpoint.\n * Resolution order: `messages.tts.openai.baseUrl` -> `OPENAI_TTS_BASE_URL` -> `https:\/\/api.openai.com\/v1`\n * Non-default values are treated as OpenAI-compatible TTS endpoints, so custom model and voice names are accepted.\n* `elevenlabs.voiceSettings`:\n * `stability`, `similarityBoost`, `style`: `0..1`\n * `useSpeakerBoost`: `true|false`\n * `speed`: `0.5..2.0` (1.0 = normal)\n* `elevenlabs.applyTextNormalization`: `auto|on|off`\n* `elevenlabs.languageCode`: 2-letter ISO 639-1 (e.g. `en`, `de`)\n* `elevenlabs.seed`: integer `0..4294967295` (best-effort determinism)\n* `microsoft.enabled`: allow Microsoft speech usage (default `true`; no API key).\n* `microsoft.voice`: Microsoft neural voice name (e.g. `en-US-MichelleNeural`).\n* `microsoft.lang`: language code (e.g. `en-US`).\n* `microsoft.outputFormat`: Microsoft output format (e.g. `audio-24khz-48kbitrate-mono-mp3`).\n * See Microsoft Speech output formats for valid values; not all formats are supported by the bundled Edge-backed transport.\n* `microsoft.rate` \/ `microsoft.pitch` \/ `microsoft.volume`: percent strings (e.g. `+10%`, `-5%`).\n* `microsoft.saveSubtitles`: write JSON subtitles alongside the audio file.\n* `microsoft.proxy`: proxy URL for Microsoft speech requests.\n* `microsoft.timeoutMs`: request timeout override (ms).\n* `edge.*`: legacy alias for the same Microsoft settings.\n\n## Model-driven overrides (default on)\n\nBy default, the model **can** emit TTS directives for a single reply.\nWhen `messages.tts.auto` is `tagged`, these directives are required to trigger audio.\n\nWhen enabled, the model can emit `[[tts:...]]` directives to override the voice\nfor a single reply, plus an optional `[[tts:text]]...[[\/tts:text]]` block to\nprovide expressive tags (laughter, singing cues, etc) that should only appear in\nthe audio.\n\n`provider=...` directives are ignored unless `modelOverrides.allowProvider: true`.\n\nExample reply payload:\n\n<\/code><\/pre>\nHere you go.<\/p>\n
[[tts:voiceId=pMsXgVXv3BLzUgSXRplE model=eleven_v3 speed=1.1]]
\n[tts:text]<\/a> Read the song once more.[[\/tts:text]]<\/p>\n\nAvailable directive keys (when enabled):\n\n* `provider` (registered speech provider id, for example `openai`, `elevenlabs`, or `microsoft`; requires `allowProvider: true`)\n* `voice` (OpenAI voice) or `voiceId` (ElevenLabs)\n* `model` (OpenAI TTS model or ElevenLabs model id)\n* `stability`, `similarityBoost`, `style`, `speed`, `useSpeakerBoost`\n* `applyTextNormalization` (`auto|on|off`)\n* `languageCode` (ISO 639-1)\n* `seed`\n\nDisable all model overrides:\n\n```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}\n{\n messages: {\n tts: {\n modelOverrides: {\n enabled: false,\n },\n },\n },\n}\n<\/code><\/pre>\nOptional allowlist (enable provider switching while keeping other knobs configurable):<\/p>\n
“`json5 theme={“theme”:{“light”:”min-light”,”dark”:”min-dark”}}
\n{
\n messages: {
\n tts: {
\n modelOverrides: {
\n enabled: true,
\n allowProvider: true,
\n allowSeed: false,
\n },
\n },
\n },
\n}<\/p>\n
\n## Per-user preferences\n\nSlash commands write local overrides to `prefsPath` (default:\n`~\/.openclaw\/settings\/tts.json`, override with `OPENCLAW_TTS_PREFS` or\n`messages.tts.prefsPath`).\n\nStored fields:\n\n* `enabled`\n* `provider`\n* `maxLength` (summary threshold; default 1500 chars)\n* `summarize` (default `true`)\n\nThese override `messages.tts.*` for that host.\n\n## Output formats (fixed)\n\n* **Telegram**: Opus voice note (`opus_48000_64` from ElevenLabs, `opus` from OpenAI).\n * 48kHz \/ 64kbps is a good voice-note tradeoff and required for the round bubble.\n* **Other channels**: MP3 (`mp3_44100_128` from ElevenLabs, `mp3` from OpenAI).\n * 44.1kHz \/ 128kbps is the default balance for speech clarity.\n* **Microsoft**: uses `microsoft.outputFormat` (default `audio-24khz-48kbitrate-mono-mp3`).\n * The bundled transport accepts an `outputFormat`, but not all formats are available from the service.\n * Output format values follow Microsoft Speech output formats (including Ogg\/WebM Opus).\n * Telegram `sendVoice` accepts OGG\/MP3\/M4A; use OpenAI\/ElevenLabs if you need\n guaranteed Opus voice notes. \ue200cite\ue202turn1search1\ue201\n * If the configured Microsoft output format fails, OpenClaw retries with MP3.\n\nOpenAI\/ElevenLabs formats are fixed; Telegram expects Opus for voice-note UX.\n\n## Auto-TTS behavior\n\nWhen enabled, OpenClaw:\n\n* skips TTS if the reply already contains media or a `MEDIA:` directive.\n* skips very short replies (< 10 chars).\n* summarizes long replies when enabled using `agents.defaults.model.primary` (or `summaryModel`).\n* attaches the generated audio to the reply.\n\nIf the reply exceeds `maxLength` and summary is off (or no API key for the\nsummary model), audio\nis skipped and the normal text reply is sent.\n\n## Flow diagram\n\n<\/code><\/pre>\nReply -> TTS enabled?
\n no -> send text
\n yes -> has media \/ MEDIA: \/ short?
\n yes -> send text
\n no -> length > limit?
\n no -> TTS -> attach audio
\n yes -> summary enabled?
\n no -> send text
\n yes -> summarize (summaryModel or agents.defaults.model.primary)
\n -> TTS -> attach audio<\/p>\n
\n## Slash command usage\n\nThere is a single command: `\/tts`.\nSee [Slash commands](\/tools\/slash-commands) for enablement details.\n\nDiscord note: `\/tts` is a built-in Discord command, so OpenClaw registers\n`\/voice` as the native command there. Text `\/tts ...` still works.\n\n<\/code><\/pre>\n\/tts off
\n\/tts always
\n\/tts inbound
\n\/tts tagged
\n\/tts status
\n\/tts provider openai
\n\/tts limit 2000
\n\/tts summary off
\n\/tts audio Hello from OpenClaw
\n“`<\/p>\n
Notes:<\/p>\n
\n- Commands require an authorized sender (allowlist\/owner rules still apply).<\/li>\n
commands.text<\/code> or native command registration must be enabled.<\/li>\noff|always|inbound|tagged<\/code> are per\u2011session toggles (\/tts on<\/code> is an alias for \/tts always<\/code>).<\/li>\nlimit<\/code> and summary<\/code> are stored in local prefs, not the main config.<\/li>\n\/tts audio<\/code> generates a one-off audio reply (does not toggle TTS on).<\/li>\n<\/ul>\nAgent tool<\/h2>\n
The tts<\/code> tool converts text to speech and returns a MEDIA:<\/code> path. When the
\nresult is Telegram-compatible, the tool includes [[audio_as_voice]]<\/code> so
\nTelegram sends a voice bubble.<\/p>\nGateway RPC<\/h2>\n
Gateway methods:<\/p>\n
\ntts.status<\/code><\/li>\ntts.enable<\/code><\/li>\ntts.disable<\/code><\/li>\ntts.convert<\/code><\/li>\ntts.setProvider<\/code><\/li>\ntts.providers<\/code><\/li>\n<\/ul>\n","protected":false},"excerpt":{"rendered":"Text-to-Speech Text-to-speech (TTS) OpenClaw can conver […]<\/p>\n","protected":false},"author":0,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[2],"tags":[],"class_list":["post-647","post","type-post","status-publish","format-standard","hentry","category-docs"],"_links":{"self":[{"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/posts\/647","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/types\/post"}],"replies":[{"embeddable":true,"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/comments?post=647"}],"version-history":[{"count":2,"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/posts\/647\/revisions"}],"predecessor-version":[{"id":718,"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/posts\/647\/revisions\/718"}],"wp:attachment":[{"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/media?parent=647"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/categories?post=647"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/tags?post=647"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}