Перетворення тексту на мовлення

OpenClaw може перетворювати вихідні відповіді на аудіо через 14 провайдерів мовлення і доставляти нативні голосові повідомлення у Feishu, Matrix, Telegram і WhatsApp, аудіовкладення всюди інде, а також PCM/Ulaw-потоки для телефонії та Talk.

TTS — це половина виводу мовлення для режиму stt-tts у Talk. Провайдер-нативні сеанси Talk realtime синтезують мовлення всередині realtime-провайдера замість виклику цього TTS-шляху, тоді як сеанси transcription не синтезують голосову відповідь асистента.

Швидкий старт

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

Підтримувані провайдери

Якщо налаштовано кількох провайдерів, спершу використовується вибраний, а інші є резервними варіантами. Автозведення використовує summaryModel (або agents.defaults.model.primary), тому цей провайдер також має бути автентифікований, якщо ви залишаєте зведення ввімкненими.

Конфігурація

Конфігурація TTS міститься в messages.tts у ~/.openclaw/openclaw.json. Виберіть пресет і адаптуйте блок провайдера:

{messages: {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",    },  },},},}

{messages: {tts: {  auto: "always",  provider: "elevenlabs",  providers: {    elevenlabs: {      apiKey: "${ELEVENLABS_API_KEY}",      model: "eleven_multilingual_v2",      speakerVoiceId: "EXAVITQu4vr4xnSDxMaL",    },  },},},}

{messages: {tts: {  auto: "always",  provider: "google",  providers: {    google: {      apiKey: "${GEMINI_API_KEY}",      model: "gemini-3.1-flash-tts-preview",      speakerVoice: "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}",      speakerVoiceId: "YTpq7expH9539ERJ",    },  },},},}

{messages: {tts: {  auto: "always",  provider: "inworld",  providers: {    inworld: {      apiKey: "${INWORLD_API_KEY}",      modelId: "inworld-tts-1.5-max",      speakerVoiceId: "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,      speakerVoice: "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",      speakerVoiceId: "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",      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",    },  },},},}

{messages: {tts: {  auto: "always",  provider: "openrouter",  providers: {    openrouter: {      apiKey: "${OPENROUTER_API_KEY}",      model: "hexgrad/kokoro-82m",      speakerVoice: "af_alloy",      responseFormat: "mp3",    },  },},},}

{messages: {tts: {  auto: "always",  provider: "volcengine",  providers: {    volcengine: {      apiKey: "${VOLCENGINE_TTS_API_KEY}",      resourceId: "seed-tts-1.0",      speakerVoice: "en_female_anna_mars_bigtts",    },  },},},}

{messages: {tts: {  auto: "always",  provider: "xai",  providers: {    xai: {      apiKey: "${XAI_API_KEY}",      speakerVoiceId: "eve",      language: "en",      responseFormat: "mp3",    },  },},},}

{messages: {tts: {  auto: "always",  provider: "xiaomi",  providers: {    xiaomi: {      apiKey: "${XIAOMI_API_KEY}",      model: "mimo-v2.5-tts",      speakerVoice: "mimo_default",      format: "mp3",    },  },},},}

Для Xiaomi mimo-v2.5-tts-voicedesign опустіть speakerVoice і встановіть style у prompt для дизайну голосу. OpenClaw надсилає цей prompt як TTS-повідомлення user і не надсилає audio.voice для моделі voicedesign.

Перевизначення голосу для окремого агента

Використовуйте agents.list[].tts, коли один агент має говорити з іншим провайдером, голосом, моделлю, персоною або режимом автоматичного TTS. Блок агента виконує глибоке злиття поверх messages.tts, тому облікові дані провайдера можуть залишатися в глобальній конфігурації провайдера:

{  messages: {    tts: {      auto: "always",      provider: "elevenlabs",      providers: {        elevenlabs: { apiKey: "${ELEVENLABS_API_KEY}", model: "eleven_multilingual_v2" },      },    },  },  agents: {    list: [      {        id: "reader",        tts: {          providers: {            elevenlabs: { speakerVoiceId: "EXAVITQu4vr4xnSDxMaL" },          },        },      },    ],  },}

Щоб закріпити персону для окремого агента, задайте agents.list[].tts.persona поруч із конфігурацією провайдера — це перевизначає глобальне messages.tts.persona лише для цього агента.

Порядок пріоритету для автоматичних відповідей, /tts audio, /tts status і інструмента агента tts:

1. messages.tts
2. активне agents.list[].tts
3. перевизначення каналу, коли канал підтримує channels.<channel>.tts
4. перевизначення облікового запису, коли канал передає channels.<channel>.accounts.<id>.tts
5. локальні налаштування /tts для цього хоста
6. вбудовані директиви [[tts:...]], коли ввімкнено перевизначення моделлю

Перевизначення каналу й облікового запису використовують ту саму форму, що й messages.tts, і виконують глибоке злиття поверх попередніх шарів, тому спільні облікові дані провайдера можуть залишатися в messages.tts, тоді як канал або обліковий запис бота змінює лише голос мовця, модель, персону або автоматичний режим:

{  messages: {    tts: {      provider: "openai",      providers: {        openai: { apiKey: "${OPENAI_API_KEY}", model: "gpt-4o-mini-tts" },      },    },  },  channels: {    feishu: {      accounts: {        english: {          tts: {            providers: {              openai: { speakerVoice: "shimmer" },            },          },        },      },    },  },}

Персони

Персона — це стабільна мовна ідентичність, яку можна детерміновано застосовувати між провайдерами. Вона може надавати перевагу одному провайдеру, визначати нейтральний до провайдера намір промпта та містити прив’язки для конкретних провайдерів для голосів, моделей, шаблонів промптів, seed і налаштувань голосу.

Мінімальна персона

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

Повна персона (нейтральний до провайдера промпт)

{  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",              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,              },            },          },        },      },    },  },}

Визначення персони

Активна персона вибирається детерміновано:

1. Локальне налаштування /tts persona <id>, якщо задано.
2. messages.tts.persona, якщо задано.
3. Без персони.

Вибір провайдера виконується з пріоритетом явних значень:

1. Прямі перевизначення (CLI, Gateway, Talk, дозволені директиви TTS).
2. Локальне налаштування /tts provider <id>.
3. provider активної персони.
4. messages.tts.provider.
5. Автовибір із реєстру.

Для кожної спроби провайдера OpenClaw зливає конфігурації в такому порядку:

1. messages.tts.providers.<id>
2. messages.tts.personas.<persona>.providers.<id>
3. Довірені перевизначення запиту
4. Дозволені перевизначення директив TTS, згенерованих моделлю

Як провайдери використовують промпти персони

Поля промпта персони (profile, scene, sampleContext, style, accent, pacing, constraints) є нейтральними до провайдера. Кожен провайдер вирішує, як їх використовувати:

Політика резервного переходу

fallbackPolicy керує поведінкою, коли персона не має прив’язки для провайдера, що пробується:

Увесь запит TTS завершується помилкою лише тоді, коли кожен провайдер, що пробувався, пропущено або він зазнав помилки.

Вибір провайдера сеансу Talk має область дії сеансу. Клієнт Talk має вибирати ідентифікатори провайдерів, ідентифікатори моделей, ідентифікатори голосів і локалі з talk.catalog та передавати їх через сеанс Talk або запит передавання. Відкриття голосового сеансу не повинно змінювати messages.tts або глобальні типові значення провайдера Talk.

Директиви, керовані моделлю

Типово асистент може видавати директиви [[tts:...]], щоб перевизначити голос, модель або швидкість для однієї відповіді, а також необов’язковий блок [[tts:text]]...[[/tts:text]] для виразних підказок, які мають з’являтися лише в аудіо:

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

Коли messages.tts.auto має значення "tagged", директиви обов’язкові для запуску аудіо. Потокова доставка блоків вилучає директиви з видимого тексту до того, як канал їх побачить, навіть якщо вони розділені між сусідніми блоками.

provider=... ігнорується, якщо modelOverrides.allowProvider: true не задано. Коли відповідь оголошує provider=..., інші ключі в цій директиві аналізуються лише цим провайдером; непідтримувані ключі вилучаються та повідомляються як попередження директив TTS.

Доступні ключі директив:

• provider (ідентифікатор зареєстрованого провайдера; потребує allowProvider: true)
• speakerVoice / speakerVoiceId (застарілі псевдоніми: voice, voiceName, voice_name, google_voice, voiceId)
• model / google_model
• stability, similarityBoost, style, speed, useSpeakerBoost
• vol / volume (гучність MiniMax, 0–10)
• pitch (цілочисельна висота тону MiniMax, −12 до 12; дробові значення обрізаються)
• emotion (тег емоції Volcengine)
• applyTextNormalization (auto|on|off)
• languageCode (ISO 639-1)
• seed

Повністю вимкнути перевизначення моделлю:

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

Дозволити перемикання провайдера, залишивши інші регулятори налаштовуваними:

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

Slash-команди

Одна команда /tts. У Discord OpenClaw також реєструє /voice, тому що /tts є вбудованою командою Discord — текстова /tts ... усе ще працює.

/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>

Примітки щодо поведінки:

• /tts on записує локальне налаштування TTS у always; /tts off записує його в off.
• /tts chat on|off|default записує перевизначення автоматичного TTS з областю дії сеансу для поточного чату.
• /tts persona <id> записує локальне налаштування персони; /tts persona off очищає його.
• /tts latest читає останню відповідь асистента з транскрипта поточного сеансу та надсилає її як аудіо один раз. Вона зберігає лише хеш цієї відповіді в записі сеансу, щоб пригнічувати дубльовані голосові надсилання.
• /tts audio генерує одноразову аудіовідповідь (не вмикає TTS).
• limit і summary зберігаються в локальних налаштуваннях, а не в основній конфігурації.
• /tts status містить діагностику резервного переходу для останньої спроби — Fallback: <primary> -> <used>, Attempts: ... і деталі для кожної спроби (provider:outcome(reasonCode) latency).
• /status показує активний режим TTS, а також налаштовані провайдер, модель, голос і очищені метадані користувацької кінцевої точки, коли TTS увімкнено.

Налаштування для кожного користувача

Slash-команди записують локальні перевизначення в prefsPath. Типове значення — ~/.openclaw/settings/tts.json; перевизначте його змінною середовища OPENCLAW_TTS_PREFS або messages.tts.prefsPath.

Вони перевизначають ефективну конфігурацію з messages.tts плюс активний блок agents.list[].tts для цього хоста.

Формати виводу (фіксовані)

Доставка голосу TTS керується можливостями каналу. Plugins каналів оголошують, чи має TTS у стилі голосового повідомлення запитувати в провайдерів нативну ціль voice-note, чи зберігати звичайний синтез audio-file і лише позначати сумісний вивід для голосової доставки.

• Канали з підтримкою голосових нотаток: відповіді голосовими нотатками надають перевагу Opus (opus_48000_64 від ElevenLabs, opus від OpenAI).
  • 48 кГц / 64 кбіт/с — вдалий компроміс для голосових повідомлень.
• Feishu / WhatsApp: коли відповідь голосовою нотаткою створюється як MP3/WebM/WAV/M4A або інший імовірний аудіофайл, Plugin каналу транскодує її у 48 кГц Ogg/Opus за допомогою ffmpeg перед надсиланням нативного голосового повідомлення. WhatsApp надсилає результат через payload audio Baileys із ptt: true та audio/ogg; codecs=opus. Якщо конвертація завершується невдало, Feishu отримує оригінальний файл як вкладення; надсилання WhatsApp завершується помилкою, замість публікації несумісного PTT payload.
• Інші канали: MP3 (mp3_44100_128 від ElevenLabs, mp3 від OpenAI).
  • 44,1 кГц / 128 кбіт/с — стандартний баланс для чіткості мовлення.
• MiniMax: MP3 (модель speech-2.8-hd, частота дискретизації 32 кГц) для звичайних аудіовкладень. Для цілей голосових нотаток, оголошених каналом, OpenClaw транскодує MiniMax MP3 у 48 кГц Opus за допомогою ffmpeg перед доставкою, коли канал оголошує транскодування.
• Xiaomi MiMo: MP3 за замовчуванням або WAV, якщо налаштовано. Для цілей голосових нотаток, оголошених каналом, OpenClaw транскодує вивід Xiaomi у 48 кГц Opus за допомогою ffmpeg перед доставкою, коли канал оголошує транскодування.
• Локальний CLI: використовує налаштований outputFormat. Цілі голосових нотаток конвертуються в Ogg/Opus, а телефонний вивід конвертується в сирий моно PCM 16 кГц за допомогою ffmpeg.
• Google Gemini: Gemini API TTS повертає сирий PCM 24 кГц. OpenClaw обгортає його як WAV для аудіовкладень, транскодує його у 48 кГц Opus для цілей голосових нотаток і повертає PCM напряму для Talk/телефонії.
• Gradium: WAV для аудіовкладень, Opus для цілей голосових нотаток і ulaw_8000 на 8 кГц для телефонії.
• Inworld: MP3 для звичайних аудіовкладень, нативний OGG_OPUS для цілей голосових нотаток і сирий PCM на 22050 Гц для Talk/телефонії.
• xAI: MP3 за замовчуванням; responseFormat може бути mp3, wav, pcm, mulaw або alaw. OpenClaw використовує batch REST TTS endpoint xAI і повертає повне аудіовкладення; streaming TTS WebSocket xAI не використовується цим шляхом провайдера. Нативний формат голосових нотаток Opus не підтримується цим шляхом.
• Microsoft: використовує microsoft.outputFormat (за замовчуванням audio-24khz-48kbitrate-mono-mp3).
  • Вбудований транспорт приймає outputFormat, але сервіс надає не всі формати.
  • Значення формату виводу відповідають форматам виводу Microsoft Speech (зокрема Ogg/WebM Opus).
  • Telegram sendVoice приймає OGG/MP3/M4A; використовуйте OpenAI/ElevenLabs, якщо вам потрібні гарантовані голосові повідомлення Opus.
  • Якщо налаштований формат виводу Microsoft завершується помилкою, OpenClaw повторює спробу з MP3.

Формати виводу OpenAI/ElevenLabs фіксовані для кожного каналу (див. вище).

Поведінка Auto-TTS

Коли messages.tts.auto увімкнено, OpenClaw:

• Пропускає TTS, якщо відповідь уже містить структуровані медіа.
• Пропускає дуже короткі відповіді (менше 10 символів).
• Узагальнює довгі відповіді, коли узагальнення ввімкнено, використовуючи summaryModel (або agents.defaults.model.primary).
• Додає згенероване аудіо до відповіді.
• У mode: "final" все одно надсилає аудіо-only TTS для потокових фінальних відповідей після завершення текстового потоку; згенеровані медіа проходять ту саму нормалізацію медіа каналу, що й звичайні вкладення відповіді.

Якщо відповідь перевищує maxLength, а узагальнення вимкнено (або немає API-ключа для моделі узагальнення), аудіо пропускається, і надсилається звичайна текстова відповідь.

Reply -> TTS enabled?  no  -> send text  yes -> has media / short?          yes -> send text          no  -> length > limit?                   no  -> TTS -> attach audio                   yes -> summary enabled?                            no  -> send text                            yes -> summarize -> TTS -> attach audio

Формати виводу за каналами

Нотатки за провайдерами:

• Транскодування Feishu / WhatsApp: Коли відповідь голосовою нотаткою надходить як MP3/WebM/WAV/M4A, Plugin каналу транскодує її в 48 кГц Ogg/Opus за допомогою ffmpeg. WhatsApp надсилає через Baileys з ptt: true і audio/ogg; codecs=opus. Якщо конвертація не вдається: Feishu повертається до прикріплення оригінального файлу; надсилання WhatsApp завершується помилкою замість публікації несумісного PTT-вмісту.
• MiniMax / Xiaomi MiMo: MP3 за замовчуванням (32 кГц для MiniMax speech-2.8-hd); транскодується в 48 кГц Opus для цілей голосових нотаток через ffmpeg.
• Локальний CLI: Використовує налаштований outputFormat. Цілі голосових нотаток конвертуються в Ogg/Opus, а телефонний вихід — у сирий моно PCM 16 кГц.
• Google Gemini: Повертає сирий PCM 24 кГц. OpenClaw обгортає його як WAV для вкладень, транскодує в 48 кГц Opus для цілей голосових нотаток, повертає PCM напряму для Talk/телефонії.
• Inworld: MP3-вкладення, нативний OGG_OPUS для голосових нотаток, сирий PCM 22050 Гц для Talk/телефонії.
• xAI: MP3 за замовчуванням; responseFormat може бути mp3|wav|pcm|mulaw|alaw. Використовує пакетний REST-ендпоінт xAI — потоковий WebSocket TTS не використовується. Нативний формат голосових нотаток Opus не підтримується.
• Microsoft: Використовує microsoft.outputFormat (за замовчуванням audio-24khz-48kbitrate-mono-mp3). Telegram sendVoice приймає OGG/MP3/M4A; використовуйте OpenAI/ElevenLabs, якщо вам потрібні гарантовані голосові повідомлення Opus. Якщо налаштований формат Microsoft дає збій, OpenClaw повторює спробу з MP3.

Формати виводу OpenAI і ElevenLabs фіксовані для кожного каналу, як зазначено вище.

Довідник полів

Інструмент агента

Інструмент tts перетворює текст на мовлення та повертає аудіовкладення для доставки відповіді. У Feishu, Matrix, Telegram і WhatsApp аудіо доставляється як голосове повідомлення, а не як файлове вкладення. Feishu і WhatsApp можуть транскодувати вивід TTS не у форматі Opus на цьому шляху, коли доступний ffmpeg.

WhatsApp надсилає аудіо через Baileys як голосову нотатку PTT (audio з ptt: true) і надсилає видимий текст окремо від аудіо PTT, оскільки клієнти не завжди стабільно відображають підписи до голосових нотаток.

Інструмент приймає необов’язкові поля channel і timeoutMs; timeoutMs — це час очікування запиту до провайдера для окремого виклику в мілісекундах. Значення для окремого виклику перевизначають messages.tts.timeoutMs; налаштовані часи очікування TTS перевизначають будь-яке стандартне значення провайдера, задане Plugin.

Gateway RPC

Посилання на сервіси

• Посібник OpenAI з перетворення тексту на мовлення
• Довідник OpenAI Audio API
• Azure Speech REST для перетворення тексту на мовлення
• Провайдер Azure Speech
• ElevenLabs Text to Speech
• Автентифікація ElevenLabs
• Gradium
• Inworld TTS API
• MiniMax T2A v2 API
• Volcengine TTS HTTP API
• Синтез мовлення Xiaomi MiMo
• node-edge-tts
• Формати виводу Microsoft Speech
• xAI перетворення тексту на мовлення

Пов’язане

• Огляд медіа
• Генерація музики
• Генерація відео
• Слеш-команди
• Plugin голосових викликів