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

​

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

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

​

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

{
  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, сгенерированных моделью

​

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

​

Политика fallback

​

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

Here you go.

[[tts:speakerVoiceId=pMsXgVXv3BLzUgSXRplE model=eleven_v3 speed=1.1]]
[[tts:text]](laughs) Read the song once more.[[/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).
• limit и summary хранятся в локальных настройках, а не в основной конфигурации.
• /tts status включает диагностику fallback для последней попытки — Fallback: <primary> -> <used>, Attempts: ... и подробности по каждой попытке (provider:outcome(reasonCode) latency).
• /status показывает активный режим TTS, а также настроенного провайдера, модель, голос и очищенные метаданные пользовательского endpoint, когда TTS включён.

​

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

​

Форматы вывода (фиксированные)

• Каналы с поддержкой голосовых заметок: для ответов голосовыми заметками предпочтителен 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.

​

Поведение Auto-TTS

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

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.

​

Справочник полей

​

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

​

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 голосовых вызовов