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

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

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

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

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

Підтримувані постачальники

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

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

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

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

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

Використовуйте agents.list[].tts, коли один агент має говорити з іншим постачальником, голосом, моделлю, персоною або режимом Auto-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: { voiceId: "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: { voice: "shimmer" },            },          },        },      },    },  },}

Персони

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

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

{  messages: {    tts: {      auto: "always",      persona: "narrator",      personas: {        narrator: {          label: "Narrator",          provider: "elevenlabs",          providers: {            elevenlabs: { voiceId: "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",              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,              },            },          },        },      },    },  },}

Розв’язання персони

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

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 або запит handoff. Відкриття голосової сесії не повинно змінювати messages.tts або глобальні стандартні налаштування провайдера Talk.

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

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

Here you go. [[tts:voiceId=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)
• 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 записує перевизначення auto-TTS, обмежене сесією, для поточного чату.
• /tts persona <id> записує локальне налаштування персони; /tts persona off очищує його.
• /tts latest читає останню відповідь асистента з поточного транскрипта сесії та один раз надсилає її як аудіо. Він зберігає лише хеш цієї відповіді в записі сесії, щоб пригнічувати дублікати голосових надсилань.
• /tts audio генерує одноразову аудіовідповідь (це не вмикає TTS).
• limit і summary зберігаються в локальних налаштуваннях, а не в основній конфігурації.
• /tts status містить діагностику fallback для останньої спроби — Fallback: <primary> -> <used>, Attempts: ... і деталі для кожної спроби (provider:outcome(reasonCode) latency).
• /status показує активний режим TTS, а також налаштовані провайдер, модель, голос і очищені метадані користувацького endpoint, коли TTS увімкнено.

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

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

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

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

Доставлення голосу TTS керується можливостями каналу. Plugins каналів оголошують, чи має voice-style 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 завершується помилкою замість публікації несумісного payload PTT.
• Інші канали: 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, а телефонний вивід конвертується в сирий 16 кГц mono PCM за допомогою ffmpeg.
• Google Gemini: Gemini API TTS повертає сирий 24 кГц PCM. 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, якщо відповідь уже містить медіа або директиву MEDIA:.
• Пропускає дуже короткі відповіді (менше 10 символів).
• Підсумовує довгі відповіді, коли підсумки ввімкнені, використовуючи summaryModel (або agents.defaults.model.primary).
• Додає згенероване аудіо до відповіді.
• У mode: "final" все одно надсилає audio-only TTS для потокових фінальних відповідей після завершення текстового потоку; згенероване медіа проходить ту саму нормалізацію медіа каналу, що й звичайні вкладення відповіді.

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

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

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

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

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

Gateway RPC

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

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

Пов’язане

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