Перейти к основному содержимому

Медиа и устройства

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

OpenClaw может преобразовывать исходящие ответы в аудио с помощью ElevenLabs, OpenAI или Edge TTS. Это работает везде, где OpenClaw может отправлять аудио; в Telegram ответы приходят в круглом пузырьке голосового сообщения.

Поддерживаемые сервисы​

  • ElevenLabs (основной или резервный провайдер)
  • OpenAI (основной или резервный провайдер; также используется для суммаризации)
  • Edge TTS (основной или резервный провайдер; использует node-edge-tts, используется по умолчанию при отсутствии API-ключей)

Примечания по Edge TTS​

Edge TTS использует онлайн-нейронный сервис синтеза речи Microsoft Edge через библиотеку node-edge-tts. Это хостируемый сервис (не локальный), использующий конечные точки Microsoft, и не требующий API-ключа. node-edge-tts предоставляет опции конфигурации речи и форматы вывода, но не все опции поддерживаются сервисом Edge. citeturn2search0 Поскольку Edge TTS — это публичный веб-сервис без опубликованного SLA или квот, рассматривайте его как сервис по принципу "как получится". Если вам нужны гарантированные лимиты и поддержка, используйте OpenAI или ElevenLabs. В документации к REST API Microsoft Speech указано ограничение в 10 минут аудио на запрос; Edge TTS не публикует лимиты, поэтому предполагайте аналогичные или более низкие ограничения. citeturn0search3

Необязательные ключи​

Если вы хотите использовать OpenAI или ElevenLabs:

  • ELEVENLABS_API_KEY (или XI_API_KEY)
  • OPENAI_API_KEY

Edge TTS не требует API-ключа. Если API-ключи не найдены, OpenClaw по умолчанию использует Edge TTS (если не отключено через messages.tts.edge.enabled=false). Если настроено несколько провайдеров, выбранный провайдер используется первым, а остальные служат резервными вариантами. Авто-суммаризация использует настроенную summaryModel (или agents.defaults.model.primary), поэтому этот провайдер также должен быть аутентифицирован, если вы включаете суммаризацию.

Ссылки на сервисы​

Включено ли по умолчанию?​

Нет. Авто‑TTS по умолчанию выключен. Включите его в конфиге с помощью messages.tts.auto или для сессии командой /tts always (алиас: /tts on). Edge TTS по умолчанию включен, как только TTS активирован, и используется автоматически, когда нет доступных API-ключей OpenAI или ElevenLabs.

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

Конфигурация TTS находится в openclaw.json в разделе messages.tts. Полная схема в Конфигурации шлюза.

Минимальная конфигурация (включение + провайдер)​

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

OpenAI основной с ElevenLabs резервным​

{
  messages: {
    tts: {
      auto: "always",
      provider: "openai",
      summaryModel: "openai/gpt-4.1-mini",
      modelOverrides: {
        enabled: true,
      },
      openai: {
        apiKey: "openai_api_key",
        baseUrl: "https://api.openai.com/v1",
        model: "gpt-4o-mini-tts",
        voice: "alloy",
      },
      elevenlabs: {
        apiKey: "elevenlabs_api_key",
        baseUrl: "https://api.elevenlabs.io",
        voiceId: "voice_id",
        modelId: "eleven_multilingual_v2",
        seed: 42,
        applyTextNormalization: "auto",
        languageCode: "en",
        voiceSettings: {
          stability: 0.5,
          similarityBoost: 0.75,
          style: 0.0,
          useSpeakerBoost: true,
          speed: 1.0,
        },
      },
    },
  },
}

Edge TTS основной (без API-ключа)​

{
  messages: {
    tts: {
      auto: "always",
      provider: "edge",
      edge: {
        enabled: true,
        voice: "en-US-MichelleNeural",
        lang: "en-US",
        outputFormat: "audio-24khz-48kbitrate-mono-mp3",
        rate: "+10%",
        pitch: "-5%",
      },
    },
  },
}

Отключить Edge TTS​

{
  messages: {
    tts: {
      edge: {
        enabled: false,
      },
    },
  },
}

Пользовательские лимиты + путь к настройкам​

{
  messages: {
    tts: {
      auto: "always",
      maxTextLength: 4000,
      timeoutMs: 30000,
      prefsPath: "~/.openclaw/settings/tts.json",
    },
  },
}

Отправлять аудио только после входящего голосового сообщения​

{
  messages: {
    tts: {
      auto: "inbound",
    },
  },
}

Отключить авто-суммаризацию для длинных ответов​

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

Затем выполните:

/tts summary off

Примечания к полям​

  • auto: режим авто‑TTS (off, always, inbound, tagged).
    • inbound отправляет аудио только после входящего голосового сообщения.
    • tagged отправляет аудио только когда ответ содержит теги [[tts]].
  • enabled: устаревший переключатель (доктор мигрирует это в auto).
  • mode: "final" (по умолчанию) или "all" (включает ответы инструментов/блоков).
  • provider: "elevenlabs", "openai" или "edge" (резервный провайдер выбирается автоматически).
  • Если provider не задан, OpenClaw предпочитает openai (если есть ключ), затем elevenlabs (если есть ключ), иначе edge.
  • summaryModel: необязательная дешёвая модель для авто-суммаризации; по умолчанию agents.defaults.model.primary.
    • Принимает provider/model или настроенный алиас модели.
  • modelOverrides: разрешить модели отправлять TTS-директивы (включено по умолчанию).
    • allowProvider по умолчанию false (переключение провайдера требует явного разрешения).
  • maxTextLength: жёсткое ограничение на входной текст для TTS (символы). /tts audio завершится ошибкой при превышении.
  • timeoutMs: таймаут запроса (мс).
  • prefsPath: переопределить путь к локальному JSON с настройками (провайдер/лимит/суммаризация).
  • Значения apiKey используют переменные окружения как запасной вариант (ELEVENLABS_API_KEY/XI_API_KEY, OPENAI_API_KEY).
  • elevenlabs.baseUrl: переопределить базовый URL API ElevenLabs.
  • openai.baseUrl: переопределить конечную точку OpenAI TTS.
    • Порядок определения: messages.tts.openai.baseUrl -> OPENAI_TTS_BASE_URL -> https://api.openai.com/v1
    • Нестандартные значения рассматриваются как совместимые с OpenAI TTS конечные точки, поэтому принимаются пользовательские имена моделей и голосов.
  • elevenlabs.voiceSettings:
    • stability, similarityBoost, style: 0..1
    • useSpeakerBoost: true|false
    • speed: 0.5..2.0 (1.0 = нормальная скорость)
  • elevenlabs.applyTextNormalization: auto|on|off
  • elevenlabs.languageCode: 2-буквенный код ISO 639-1 (например, en, de)
  • elevenlabs.seed: целое число 0..4294967295 (детерминированность по возможности)
  • edge.enabled: разрешить использование Edge TTS (по умолчанию true; без API-ключа).
  • edge.voice: имя нейронного голоса Edge (например, en-US-MichelleNeural).
  • edge.lang: код языка (например, en-US).
  • edge.outputFormat: формат вывода Edge (например, audio-24khz-48kbitrate-mono-mp3).
    • См. форматы вывода Microsoft Speech для допустимых значений; не все форматы поддерживаются Edge.
  • edge.rate / edge.pitch / edge.volume: строки процентов (например, +10%, -5%).
  • edge.saveSubtitles: записывать JSON-субтитры рядом с аудиофайлом.
  • edge.proxy: URL прокси для запросов Edge TTS.
  • edge.timeoutMs: переопределение таймаута запроса (мс).

Переопределения на уровне модели (включено по умолчанию)​

По умолчанию модель может отправлять TTS-директивы для одного ответа. Когда messages.tts.auto установлен в tagged, эти директивы необходимы для запуска аудио. При включении модель может отправлять директивы [[tts:...]] для переопределения голоса для одного ответа, плюс необязательный блок [[tts:text]]...[[/tts:text]] для предоставления выразительных тегов (смех, реплики для пения и т.д.), которые должны появляться только в аудио. Директивы provider=... игнорируются, если не установлено modelOverrides.allowProvider: true. Пример полезной нагрузки ответа:

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

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

Доступные ключи директив (при включении):

  • provider (openai | elevenlabs | edge, требует allowProvider: true)
  • voice (голос OpenAI) или voiceId (ElevenLabs)
  • model (модель TTS OpenAI или идентификатор модели ElevenLabs)
  • stability, similarityBoost, style, speed, useSpeakerBoost
  • applyTextNormalization (auto|on|off)
  • languageCode (ISO 639-1)
  • seed

Отключить все переопределения модели:

{
  messages: {
    tts: {
      modelOverrides: {
        enabled: false,
      },
    },
  },
}

Необязательный белый список (разрешить переключение провайдера, оставляя другие настройки конфигурируемыми):

{
  messages: {
    tts: {
      modelOverrides: {
        enabled: true,
        allowProvider: true,
        allowSeed: false,
      },
    },
  },
}

Пользовательские предпочтения​

Слэш-команды записывают локальные переопределения в prefsPath (по умолчанию: ~/.openclaw/settings/tts.json, можно переопределить через OPENCLAW_TTS_PREFS или messages.tts.prefsPath). Сохраняемые поля:

  • enabled
  • provider
  • maxLength (порог для суммаризации; по умолчанию 1500 символов)
  • summarize (по умолчанию true)

Они переопределяют messages.tts.* для данного хоста.

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

  • Telegram: голосовое сообщение Opus (opus_48000_64 от ElevenLabs, opus от OpenAI).
    • 48 кГц / 64 кбит/с — хороший компромисс для голосовых сообщений и требуется для круглого пузырька.
  • Другие каналы: MP3 (mp3_44100_128 от ElevenLabs, mp3 от OpenAI).
    • 44.1 кГц / 128 кбит/с — баланс по умолчанию для чёткости речи.
  • Edge TTS: использует edge.outputFormat (по умолчанию audio-24khz-48kbitrate-mono-mp3).
    • node-edge-tts принимает outputFormat, но не все форматы доступны в сервисе Edge. citeturn2search0
    • Значения форматов вывода следуют форматам вывода Microsoft Speech (включая Ogg/WebM Opus). citeturn1search0
    • Telegram sendVoice принимает OGG/MP3/M4A; используйте OpenAI/ElevenLabs, если вам нужны гарантированные голосовые сообщения Opus. citeturn1search1
    • Если настроенный формат вывода Edge не срабатывает, OpenClaw повторяет попытку с MP3.

Форматы OpenAI/ElevenLabs фиксированы; Telegram ожидает Opus для UX голосовых сообщений.

Поведение авто-TTS​

При включении OpenClaw:

  • пропускает TTS, если ответ уже содержит медиа или директиву MEDIA:.
  • пропускает очень короткие ответы (< 10 символов).
  • суммаризирует длинные ответы, когда включено, используя agents.defaults.model.primary (или summaryModel).
  • прикрепляет сгенерированное аудио к ответу.

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

Диаграмма потока​

Ответ -> TTS включен?
  нет  -> отправить текст
  да -> есть медиа / MEDIA: / короткий?
          да -> отправить текст
          нет  -> длина > лимит?
                   нет  -> TTS -> прикрепить аудио
                   да -> суммаризация включена?
                            нет  -> отправить текст
                            да -> суммаризировать (summaryModel или agents.defaults.model.primary)
                                      -> TTS -> прикрепить аудио

Использование слэш-команд​

Есть одна команда: /tts. Подробности о включении см. в Слэш-командах. Примечание для Discord: /tts — это встроенная команда Discord, поэтому OpenClaw регистрирует /voice как нативную команду там. Текст /tts ... всё равно работает.

/tts off
/tts always
/tts inbound
/tts tagged
/tts status
/tts provider openai
/tts limit 2000
/tts summary off
/tts audio Hello from OpenClaw

Примечания:

  • Команды требуют авторизованного отправителя (правила белого списка/владельца всё ещё применяются).
  • commands.text или регистрация нативных команд должны быть включены.
  • off|always|inbound|tagged — это переключатели для сессии (/tts on — это алиас для /tts always).
  • limit и summary сохраняются в локальных настройках, а не в основном конфиге.
  • /tts audio генерирует разовый аудиоответ (не включает TTS).

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

Инструмент tts преобразует текст в речь и возвращает путь MEDIA:. Когда результат совместим с Telegram, инструмент включает [[audio_as_voice]], чтобы Telegram отправил голосовой пузырёк.

RPC шлюза​

Методы шлюза:

  • tts.status
  • tts.enable
  • tts.disable
  • tts.convert
  • tts.setProvider
  • tts.providers

Команда Location