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

​

Быстрый старт

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

​

Поддерживаемые провайдеры

​

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

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

​

Переопределение голоса для отдельных агентов

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

1. messages.tts
2. активный agents.list[].tts
3. переопределение канала, если канал поддерживает channels.<channel>.tts
4. переопределение учётной записи, если канал передаёт channels.<channel>.accounts.<id>.tts
5. локальные настройки /tts для этого хоста
6. встроенные директивы [[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. Автоматический выбор из реестра.

1. messages.tts.providers.<id>
2. messages.tts.personas.<persona>.providers.<id>
3. Доверенные переопределения запроса
4. Разрешённые переопределения из директив TTS, созданных моделью

​

Как провайдеры используют запросы персоны

​

Политика резервного переключения

​

Директивы, задаваемые моделью

Вот, пожалуйста.

[[tts:speakerVoiceId=pMsXgVXv3BLzUgSXRplE model=eleven_v3 speed=1.1]]
[[tts:text]](смеётся) Прочитай песню ещё раз.[[/tts:text]]

• 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 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 включён.

​

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

​

Форматы вывода

• Перекодирование в 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.

​

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

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

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

Ответ -> TTS включён?
  нет -> отправить текст
  да  -> есть медиафайл / ответ короткий?
          да  -> отправить текст
          нет -> длина > лимита?
                   нет -> TTS -> прикрепить аудио
                   да  -> суммирование включено и доступно?
                            нет -> обрезать -> TTS -> прикрепить аудио
                            да  -> суммировать -> 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

​

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

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