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

​

Швидкий початок

{
  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: "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: "Оповідач",
          provider: "elevenlabs",
          providers: {
            elevenlabs: {
              speakerVoiceId: "EXAVITQu4vr4xnSDxMaL",
              modelId: "eleven_multilingual_v2",
            },
          },
        },
      },
    },
  },
}

​

Повна персона (незалежна від провайдера підказка)

{
  messages: {
    tts: {
      auto: "always",
      persona: "alfred",
      personas: {
        alfred: {
          label: "Альфред",
          description: "Стриманий, доброзичливий британський дворецький-оповідач.",
          provider: "google",
          fallbackPolicy: "preserve-persona",
          prompt: {
            profile: "Блискучий британський дворецький. Стриманий, дотепний, доброзичливий, чарівний, емоційно виразний, ніколи не шаблонний.",
            scene: "Тихий нічний кабінет. Оповідь близько до мікрофона для довіреного оператора.",
            sampleContext: "Мовець відповідає на приватний технічний запит стисло, впевнено та зі стриманою доброзичливістю.",
            style: "Вишуканий, стриманий, з легкою усмішкою.",
            accent: "Британська англійська.",
            pacing: "Розмірений, із короткими драматичними паузами.",
            constraints: ["Не зачитувати значення конфігурації вголос.", "Не пояснювати персону."],
          },
          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 безпосередньо для Talk/телефонії.
• Gradium: WAV для аудіовкладень, Opus для цільових форматів голосових повідомлень і ulaw_8000 із частотою 8 кГц для телефонії.
• Inworld: MP3 для звичайних аудіовкладень, нативний OGG_OPUS для цільових форматів голосових повідомлень і необроблений PCM із частотою 22050 Гц для Talk/телефонії.
• xAI: MP3 за замовчуванням; для синтезу аудіофайлів можна використовувати mp3, wav, pcm, mulaw або alaw як для буферизованого, так і для потокового виведення. Для цільових форматів голосових повідомлень використовується MP3 під час потокового виведення та як резервний варіант буферизованого виведення, оскільки результати pcm, mulaw і alaw від xAI є необробленим аудіо без заголовків. Буферизований синтез використовує пакетну 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

​

Пов’язане

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