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

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

TTS — это отвечающая за речевой вывод часть режима stt-tts в Talk (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: "Алекс",    },  },},},}

{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: "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]] для выразительных указаний, которые должны присутствовать только в аудио:

Вот, пожалуйста. [[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 определяется возможностями канала. Плагины каналов объявляют, следует ли для озвучки в стиле голосового сообщения запрашивать у провайдеров нативный целевой формат 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 напрямую для разговора/телефонии.
• Gradium: WAV для аудиовложений, Opus для целевых голосовых сообщений и ulaw_8000 с частотой 8 кГц для телефонии.
• Inworld: MP3 для обычных аудиовложений, нативный OGG_OPUS для целевых голосовых сообщений и необработанный PCM с частотой 22050 Гц для разговора/телефонии.
• xAI: по умолчанию MP3; для синтеза аудиофайлов могут использоваться mp3, wav, pcm, mulaw или alaw как для буферизованного, так и для потокового вывода. Для целевых голосовых сообщений используется MP3 при потоковой передаче и буферизованном резервном варианте, поскольку выходные данные xAI в форматах pcm, mulaw и alaw представляют собой необработанное аудио без заголовков. Буферизованный синтез использует пакетную конечную точку 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

Связанные материалы

• Обзор работы с медиа
• Генерация музыки
• Генерация видео
• Команды с косой чертой
• Плагин голосовых вызовов