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

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

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

Швидкий початок

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

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

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

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

Конфігурація TTS міститься в messages.tts у файлі ~/.openclaw/openclaw.json. Виберіть готовий набір і адаптуйте блок постачальника. Показані нижче поля speakerVoice/speakerVoiceId є канонічними; власні назви полів voice/voiceId/ voiceName кожного постачальника досі працюють як застарілі псевдоніми.

{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",      // Необов'язкові підказки щодо стилю природною мовою:      // audioProfile: "Говоріть спокійним тоном ведучого подкасту.",      // 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 підказку для проєктування голосу. OpenClaw надсилає цю підказку як повідомлення 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" },            },          },        },      },    },  },}

Персони

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

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

{  messages: {    tts: {      auto: "always",      persona: "narrator",      personas: {        narrator: {          label: "Оповідач",          provider: "elevenlabs",          providers: {            elevenlabs: {              speakerVoiceId: "EXAVITQu4vr4xnSDxMaL",              modelId: "eleven_multilingual_v2",            },          },        },      },    },  },}

Повна персона (незалежна від провайдера підказка)

{  messages: {    tts: {      auto: "always",      persona: "alfred",      personas: {        alfred: {          label: "Альфред",          description: "Стриманий, доброзичливий британський дворецький-оповідач.",          provider: "google",          fallbackPolicy: "preserve-persona",          prompt: {            profile: "Блискучий британський дворецький. Стриманий, дотепний, доброзичливий, чарівний, емоційно виразний, ніколи не шаблонний.",            scene: "Тихий нічний кабінет. Оповідь близько до мікрофона для довіреного оператора.",            sampleContext: "Мовець відповідає на приватний технічний запит стисло, впевнено та зі стриманою доброзичливістю.",            style: "Вишуканий, стриманий, з легкою усмішкою.",            accent: "Британська англійська.",            pacing: "Розмірений, із короткими драматичними паузами.",            constraints: ["Не зачитувати значення конфігурації вголос.", "Не пояснювати персону."],          },          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]] для виразних підказок, які мають бути присутні лише в аудіо:

Ось, будь ласка. [[tts:speakerVoiceId=pMsXgVXv3BLzUgSXRplE model=eleven_v3 speed=1.1]][[tts:text]](сміється) Прочитай пісню ще раз.[[/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 } } } }

Команди зі скісною рискою

Єдина команда /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).
• /tts limit <chars> приймає значення 100–4096 (4096 — максимальна довжина підпису/повідомлення Telegram); значення поза цим діапазоном відхиляються.
• limit і summary зберігаються в локальних налаштуваннях, а не в основній конфігурації.
• /tts status містить діагностику резервних переходів для останньої спроби — Fallback: <primary> -> <used>, Attempts: ... і відомості про кожну спробу (provider:outcome(reasonCode) latency).
• /status показує активний режим TTS, а також налаштовані провайдер, модель, голос і очищені метадані власної кінцевої точки, коли TTS увімкнено.

Налаштування окремих користувачів

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

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

Формати виведення

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

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

• Перекодування Feishu / WhatsApp: коли відповідь у вигляді голосового повідомлення надходить як MP3/WebM/WAV/M4A або інший імовірний аудіофайл, плагін каналу перед надсиланням нативного голосового повідомлення перекодовує його в Ogg/Opus із частотою 48 кГц за допомогою ffmpeg (libopus, 64 кбіт/с). WhatsApp надсилає результат через корисне навантаження Baileys audio з ptt: true і audio/ogg; codecs=opus. У разі помилки перекодування Feishu перехоплює помилку й надсилає вихідний файл як звичайне вкладення; WhatsApp не має резервного варіанта, тому саме надсилання завершується помилкою замість публікації несумісного корисного навантаження PTT.
• MiniMax: MP3 (модель speech-2.8-hd, частота дискретизації 32 кГц) для звичайних аудіовкладень; перекодування в Opus із частотою 48 кГц за допомогою ffmpeg для цільових форматів голосових повідомлень, оголошених каналом.
• Xiaomi MiMo: MP3 за замовчуванням або WAV, якщо це налаштовано; перекодування в Opus із частотою 48 кГц за допомогою ffmpeg для цільових форматів голосових повідомлень, оголошених каналом.
• Локальний CLI: використовує налаштований outputFormat. Цільові формати голосових повідомлень перетворюються на Ogg/Opus, а вихідні дані для телефонії — на необроблений монофонічний PCM із частотою 16 кГц за допомогою ffmpeg.
• Google Gemini: повертає необроблений PCM із частотою 24 кГц. OpenClaw обгортає його у WAV для аудіовкладень, перекодовує в Opus із частотою 48 кГц для цільових форматів голосових повідомлень і повертає PCM безпосередньо для Talk/телефонії.
• Gradium: WAV для аудіовкладень, Opus для цільових форматів голосових повідомлень і ulaw_8000 із частотою 8 кГц для телефонії.
• Inworld: MP3 для звичайних аудіовкладень, нативний OGG_OPUS для цільових форматів голосових повідомлень і необроблений PCM із частотою 22050 Гц для Talk/телефонії.
• xAI: MP3 за замовчуванням; для синтезу аудіофайлів можна використовувати mp3, wav, pcm, mulaw або alaw як для буферизованого, так і для потокового виведення. Для цільових форматів голосових повідомлень використовується MP3 під час потокового виведення та як резервний варіант буферизованого виведення, оскільки результати pcm, mulaw і alaw від xAI є необробленим аудіо без заголовків. Буферизований синтез використовує пакетну REST-кінцеву точку xAI /v1/tts; textToSpeechStream використовує нативний wss://api.x.ai/v1/tts. Це не контракт голосового зв’язку в реальному часі. Нативний формат голосових повідомлень 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.
  • Якщо явне перевизначення голосу не задано й використовується стандартний англійський голос, OpenClaw автоматично перемикається на китайський нейронний голос (zh-CN-XiaoxiaoNeural, локаль zh-CN), якщо в тексті відповіді переважають символи CJK.

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

Поведінка автоматичного TTS

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

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

Якщо відповідь перевищує maxLength, OpenClaw ніколи не пропускає аудіо повністю:

• Підсумовування ввімкнено (за замовчуванням) і модель підсумовування доступна: підсумовує текст приблизно до maxLength символів, а потім синтезує підсумок.
• Підсумовування вимкнено, підсумовування завершується помилкою або для моделі підсумовування немає ключа API: скорочує текст до maxLength символів і синтезує скорочений текст.

Відповідь -> TTS увімкнено?  ні  -> надіслати текст  так -> є медіадані / коротка?          так -> надіслати текст          ні  -> довжина > обмеження?                   ні  -> TTS -> додати аудіо                   так -> підсумовування ввімкнене й доступне?                            ні  -> скоротити -> TTS -> додати аудіо                            так -> підсумувати -> TTS -> додати аудіо

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

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

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

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

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

RPC Gateway

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

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

Пов’язане

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