Преобразование текста в речь

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

TTS — это половина речевого вывода в режиме Talk stt-tts. Провайдер-нативные realtime-сеансы Talk синтезируют речь внутри 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 как подсказку для дизайна голоса. 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" },            },          },        },      },    },  },}

Персоны

Персона — это стабильная речевая идентичность, которую можно детерминированно применять у разных провайдеров. Она может предпочитать одного провайдера, определять независимое от провайдера намерение промпта и хранить привязки для конкретных провайдеров: голоса, модели, шаблоны промптов, 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) независимы от провайдера. Каждый провайдер сам решает, как их использовать:

Политика fallback

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

Слэш-команды

Одна команда /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 для последней попытки — Fallback: <primary> -> <used>, Attempts: ... и подробности по каждой попытке (provider:outcome(reasonCode) latency).
• /status показывает активный режим TTS, а также настроенного провайдера, модель, голос и очищенные метаданные пользовательского endpoint, когда TTS включён.

Пользовательские настройки

Слэш-команды записывают локальные переопределения в 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.
• Другие каналы: MP3 (mp3_44100_128 от ElevenLabs, mp3 от OpenAI).
  • 44,1 кГц / 128 кбит/с — баланс по умолчанию для четкости речи.
• MiniMax: MP3 (модель speech-2.8-hd, частота дискретизации 32 кГц) для обычных аудиовложений. Для целей голосовых заметок, объявленных каналом, OpenClaw перекодирует MiniMax MP3 в Opus 48 кГц с помощью ffmpeg перед доставкой, когда канал объявляет перекодирование.
• Xiaomi MiMo: по умолчанию MP3 или WAV при соответствующей настройке. Для целей голосовых заметок, объявленных каналом, OpenClaw перекодирует вывод Xiaomi в Opus 48 кГц с помощью ffmpeg перед доставкой, когда канал объявляет перекодирование.
• Локальный CLI: использует настроенный outputFormat. Цели голосовых заметок преобразуются в Ogg/Opus, а телефонный вывод преобразуется в необработанный моно PCM 16 кГц с помощью ffmpeg.
• Google Gemini: Gemini API TTS возвращает необработанный PCM 24 кГц. OpenClaw упаковывает его как WAV для аудиовложений, перекодирует в Opus 48 кГц для целей голосовых заметок и возвращает 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 и возвращает полное аудиовложение; потоковый WebSocket TTS 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" все равно отправляет 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 text to speech

См. также

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