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

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

TTS — це половина виведення мовлення в режимі stt-tts Talk. Нативні для постачальника realtime сеанси Talk синтезують мовлення всередині постачальника реального часу замість виклику цього шляху 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",
      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",
      // Необов’язкові підказки стилю природною мовою:
      // audioProfile: "Говоріть спокійним тоном ведучого подкасту.",
      // 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" },
            },
          },
        },
      },
    },
  },
}

# Персони

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

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

{
  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 або запит передавання. Відкриття голосового сеансу не має змінювати 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: <primary> -> <used>, Attempts: ... і деталі кожної спроби (provider:outcome(reasonCode) latency).
• /status показує активний режим TTS, а також налаштованого провайдера, модель, голос і очищені метадані користувацької кінцевої точки, коли TTS увімкнено.

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

Slash-команди записують локальні перевизначення в prefsPath. Типове значення: ~/.openclaw/settings/tts.json; перевизначте за допомогою env var 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 надсилає результат через корисне навантаження Baileys audio з ptt: true і audio/ogg; codecs=opus. Якщо конвертація завершується помилкою, Feishu отримує оригінальний файл як вкладення; надсилання WhatsApp завершується помилкою, а не публікацією несумісного PTT-навантаження.
• BlueBubbles: залишає синтез провайдера на звичайному шляху аудіофайлів; вихідні MP3 і CAF позначаються для доставки голосових нотаток iMessage.
• Інші канали: MP3 (mp3_44100_128 від ElevenLabs, mp3 від OpenAI).
  • 44,1 кГц / 128 кбіт/с — типовий баланс для чіткості мовлення.
• MiniMax: MP3 (модель speech-2.8-hd, частота дискретизації 32 кГц) для звичайних аудіовкладень. Для цілей голосових нотаток, оголошених каналом, OpenClaw транскодує MP3 від MiniMax у 48 кГц Opus за допомогою ffmpeg перед доставкою, коли канал оголошує підтримку транскодування.
• Xiaomi MiMo: MP3 за замовчуванням або WAV, якщо налаштовано. Для цілей голосових нотаток, оголошених каналом, OpenClaw транскодує вихід Xiaomi у 48 кГц Opus за допомогою ffmpeg перед доставкою, коли канал оголошує підтримку транскодування.
• Локальний CLI: використовує налаштований outputFormat. Цілі голосових нотаток конвертуються в Ogg/Opus, а вихід для телефонії конвертується в сирий моно PCM 16 кГц за допомогою ffmpeg.
• Google Gemini: TTS API Gemini повертає сирий 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 використовує пакетну REST TTS кінцеву точку xAI і повертає повне аудіовкладення; потоковий 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" усе одно надсилає аудіо-only TTS для потокових фінальних відповідей після завершення текстового потоку; згенеровані медіа проходять таку саму нормалізацію медіа каналу, як і звичайні вкладення відповідей.

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

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 завершується помилкою замість публікації несумісного корисного навантаження PTT.
• MiniMax / Xiaomi MiMo: MP3 за замовчуванням (32 кГц для MiniMax speech-2.8-hd); перекодовується у 48 кГц Opus для цілей голосових нотаток через ffmpeg.
• Локальний CLI: Використовує налаштований outputFormat. Цілі голосових нотаток конвертуються в Ogg/Opus, а телефонний вивід — у сирий 16 кГц моно PCM.
• Google Gemini: Повертає сирий 24 кГц PCM. OpenClaw обгортає його як WAV для вкладень, перекодовує у 48 кГц Opus для цілей голосових нотаток, повертає PCM напряму для розмови/телефонії.
• Inworld: Вкладення MP3, нативна голосова нотатка OGG_OPUS, сирий PCM 22050 Гц для розмови/телефонії.
• 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 — це час очікування запиту до провайдера для окремого виклику в мілісекундах.

# 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 перетворення тексту на мовлення

# Пов’язане

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