> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

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

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

TTS — это отвечающая за речевой вывод часть режима `stt-tts` в Talk (`talk.speak` использует
тот же путь синтеза). В нативных для провайдера сеансах Talk `realtime` речь синтезируется
внутри провайдера реального времени; в сеансах `transcription` голосовой ответ
ассистента никогда не синтезируется.

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

**1. Выберите провайдера**

OpenAI и ElevenLabs — наиболее надёжные облачные варианты. Microsoft и
локальный CLI работают без ключа API. Полный список см. в [матрице провайдеров](#supported-providers).

**2. Задайте ключ API**

Экспортируйте переменную среды для своего провайдера (например, `OPENAI_API_KEY`,
`ELEVENLABS_API_KEY`). Для Microsoft и локального CLI ключ не нужен.

**3. Включите в конфигурации**

Задайте `messages.tts.auto: "always"` и `messages.tts.provider`:

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  messages: {
    tts: {
      auto: "always",
      provider: "elevenlabs",
    },
  },
}
```

**4. Попробуйте в чате**

`/tts status` показывает текущее состояние. `/tts audio Hello from OpenClaw`
отправляет однократный аудиоответ.

> [!NOTE]
>
> Автоматический TTS **отключён** по умолчанию. Если `messages.tts.provider` не задан,
> OpenClaw выбирает первого настроенного провайдера в порядке автоматического выбора из реестра.
> Встроенный агентский инструмент `tts` используется только при явно выраженном намерении: обычный чат остаётся
> текстовым, если пользователь не запросит аудио, не использует `/tts` или не включит автоматический TTS либо
> синтез речи посредством директивы.

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

| Провайдер | Аутентификация | Примечания |
| - | - | - |
| **Azure Speech** | `AZURE_SPEECH_KEY` + `AZURE_SPEECH_REGION` (также `AZURE_SPEECH_API_KEY`, `SPEECH_KEY`, `SPEECH_REGION`) | Нативный вывод голосовых сообщений Ogg/Opus и телефония. |
| **DeepInfra** | `DEEPINFRA_API_KEY` | TTS, совместимый с OpenAI. По умолчанию используется `hexgrad/Kokoro-82M`. |
| **ElevenLabs** | `ELEVENLABS_API_KEY` или `XI_API_KEY` | Клонирование голоса, многоязычность, детерминированность через `seed`; потоковая передача для воспроизведения голоса в Discord. |
| **Google Gemini** | `GEMINI_API_KEY` или `GOOGLE_API_KEY` | Пакетный TTS через Gemini API; учитывает персону через `promptTemplate: "audio-profile-v1"`. |
| **Gradium** | `GRADIUM_API_KEY` | Вывод голосовых сообщений и телефония. |
| **Inworld** | `INWORLD_API_KEY` | Потоковый API TTS. Нативные голосовые сообщения Opus и телефония PCM. |
| **Локальный CLI** | нет | Запускает настроенную локальную команду TTS. |
| **Microsoft** | нет | Общедоступный нейронный TTS Edge через `node-edge-tts`. Предоставляется по мере возможности, без SLA. |
| **MiniMax** | `MINIMAX_API_KEY` (или Token Plan: `MINIMAX_OAUTH_TOKEN`, `MINIMAX_CODE_PLAN_KEY`, `MINIMAX_CODING_API_KEY`) | API T2A v2. По умолчанию используется `speech-2.8-hd`. |
| **OpenAI** | `OPENAI_API_KEY` | Также используется для автоматического резюмирования; поддерживает персону `instructions`. |
| **OpenRouter** | `OPENROUTER_API_KEY` (можно повторно использовать `models.providers.openrouter.apiKey`) | Модель по умолчанию — `hexgrad/kokoro-82m`. |
| **Volcengine** | `VOLCENGINE_TTS_API_KEY` или `BYTEPLUS_SEED_SPEECH_API_KEY` (устаревшие AppID/токен: `VOLCENGINE_TTS_APPID`/`_TOKEN`) | HTTP API BytePlus Seed Speech. |
| **Vydra** | `VYDRA_API_KEY` | Общий провайдер изображений, видео и речи. |
| **xAI** | `XAI_API_KEY` | Пакетный TTS xAI. Нативные голосовые сообщения Opus **не** поддерживаются. |
| **Xiaomi MiMo** | `XIAOMI_API_KEY` | TTS MiMo через дополнения чата Xiaomi. |

Если настроено несколько провайдеров, сначала используется выбранный, а
остальные служат резервными вариантами. Для автоматического резюмирования используется `summaryModel` (или
`agents.defaults.model.primary`), поэтому этот провайдер также должен быть аутентифицирован,
если резюмирование остаётся включённым.

> [!WARNING]
>
> Встроенный провайдер **Microsoft** использует онлайн-службу нейронного TTS Microsoft Edge
> через `node-edge-tts`. Это общедоступная веб-служба без опубликованных
> SLA или квоты — рассчитывайте только на предоставление по мере возможности. Устаревший идентификатор провайдера `edge`
> нормализуется в `microsoft`, а `openclaw doctor --fix` перезаписывает сохранённую
> конфигурацию; в новых конфигурациях всегда следует использовать `microsoft`.

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

Конфигурация TTS находится в разделе `messages.tts` файла `~/.openclaw/openclaw.json`. Выберите
предустановку и адаптируйте блок провайдера. Показанные ниже поля `speakerVoice`/`speakerVoiceId`
являются каноническими; собственные имена полей `voice`/`voiceId`/
`voiceName` каждого провайдера по-прежнему работают как устаревшие псевдонимы.

> [tab] Azure Speech
>
> ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
> {
>   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",
>         },
>       },
>     },
>   },
> }
> ```

> [tab] ElevenLabs
>
> ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
> {
>   messages: {
>     tts: {
>       auto: "always",
>       provider: "elevenlabs",
>       providers: {
>         elevenlabs: {
>           apiKey: "${ELEVENLABS_API_KEY}",
>           model: "eleven_multilingual_v2",
>           speakerVoiceId: "EXAVITQu4vr4xnSDxMaL",
>         },
>       },
>     },
>   },
> }
> ```

> [tab] Google Gemini
>
> ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
> {
>   messages: {
>     tts: {
>       auto: "always",
>       provider: "google",
>       providers: {
>         google: {
>           apiKey: "${GEMINI_API_KEY}",
>           model: "gemini-3.1-flash-tts-preview",
>           speakerVoice: "Kore",
>           // Необязательные подсказки по стилю на естественном языке:
>           // audioProfile: "Говори спокойным тоном ведущего подкаста.",
>           // speakerName: "Алекс",
>         },
>       },
>     },
>   },
> }
> ```

> [tab] Gradium
>
> ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
> {
>   messages: {
>     tts: {
>       auto: "always",
>       provider: "gradium",
>       providers: {
>         gradium: {
>           apiKey: "${GRADIUM_API_KEY}",
>           speakerVoiceId: "YTpq7expH9539ERJ",
>         },
>       },
>     },
>   },
> }
> ```

> [tab] Inworld
>
> ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
> {
>   messages: {
>     tts: {
>       auto: "always",
>       provider: "inworld",
>       providers: {
>         inworld: {
>           apiKey: "${INWORLD_API_KEY}",
>           modelId: "inworld-tts-1.5-max",
>           speakerVoiceId: "Sarah",
>           temperature: 0.7,
>         },
>       },
>     },
>   },
> }
> ```

> [tab] Локальный CLI
>
> ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
> {
>   messages: {
>     tts: {
>       auto: "always",
>       provider: "tts-local-cli",
>       providers: {
>         "tts-local-cli": {
>           command: "say",
>           args: ["-o", "{{OutputPath}}", "{{Text}}"],
>           outputFormat: "wav",
>           timeoutMs: 120000,
>         },
>       },
>     },
>   },
> }
> ```

> [tab] Microsoft (без ключа)
>
> ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
> {
>   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%",
>         },
>       },
>     },
>   },
> }
> ```

> [tab] MiniMax
>
> ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
> {
>   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,
>         },
>       },
>     },
>   },
> }
> ```

> [tab] OpenAI + ElevenLabs
>
> ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
> {
>   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",
>         },
>       },
>     },
>   },
> }
> ```

> [tab] OpenRouter
>
> ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
> {
>   messages: {
>     tts: {
>       auto: "always",
>       provider: "openrouter",
>       providers: {
>         openrouter: {
>           apiKey: "${OPENROUTER_API_KEY}",
>           model: "hexgrad/kokoro-82m",
>           speakerVoice: "af_alloy",
>           responseFormat: "mp3",
>         },
>       },
>     },
>   },
> }
> ```

> [tab] Volcengine
>
> ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
> {
>   messages: {
>     tts: {
>       auto: "always",
>       provider: "volcengine",
>       providers: {
>         volcengine: {
>           apiKey: "${VOLCENGINE_TTS_API_KEY}",
>           resourceId: "seed-tts-1.0",
>           speakerVoice: "en_female_anna_mars_bigtts",
>         },
>       },
>     },
>   },
> }
> ```

> [tab] xAI
>
> ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
> {
>   messages: {
>     tts: {
>       auto: "always",
>       provider: "xai",
>       providers: {
>         xai: {
>           apiKey: "${XAI_API_KEY}",
>           speakerVoiceId: "eve",
>           language: "en",
>           responseFormat: "mp3",
>         },
>       },
>     },
>   },
> }
> ```

> [tab] Xiaomi MiMo
>
> ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
> {
>   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`, поэтому учётные данные провайдера могут оставаться в глобальной конфигурации провайдера:

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  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:...]]`, если включены [переопределения, задаваемые моделью](#model-driven-directives)

Переопределения канала и учётной записи имеют ту же структуру, что и `messages.tts`, и
глубоко объединяются поверх предыдущих уровней, поэтому общие учётные данные провайдера могут оставаться в
`messages.tts`, а канал или учётная запись бота изменяет только голос диктора, модель, персону
или автоматический режим:

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  messages: {
    tts: {
      provider: "openai",
      providers: {
        openai: { apiKey: "${OPENAI_API_KEY}", model: "gpt-4o-mini-tts" },
      },
    },
  },
  channels: {
    feishu: {
      accounts: {
        english: {
          tts: {
            providers: {
              openai: { speakerVoice: "shimmer" },
            },
          },
        },
      },
    },
  },
}
```

## Персоны

**Персона** — это стабильная речевая идентичность, которую можно детерминированно
применять к разным провайдерам. Она может отдавать предпочтение одному провайдеру, задавать
независимый от провайдера замысел запроса и содержать привязки для конкретных провайдеров:
голоса, модели, шаблоны запросов, начальные значения и настройки голоса.

### Минимальная персона

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  messages: {
    tts: {
      auto: "always",
      persona: "narrator",
      personas: {
        narrator: {
          label: "Narrator",
          provider: "elevenlabs",
          providers: {
            elevenlabs: {
              speakerVoiceId: "EXAVITQu4vr4xnSDxMaL",
              modelId: "eleven_multilingual_v2",
            },
          },
        },
      },
    },
  },
}
```

### Полная персона (независимый от провайдера запрос)

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  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`) **не зависят от провайдера**. Каждый провайдер сам решает, как
их использовать:

> [accordion] Google Gemini
>
> Оборачивает поля запроса персоны в структуру запроса Gemini TTS **только тогда**,
> когда в действующей конфигурации провайдера Google задано `promptTemplate: "audio-profile-v1"`
> или `personaPrompt`. Более старые поля `audioProfile` и `speakerName`
> по-прежнему добавляются в начало как текст запроса, специфичный для Google. Встроенные аудиотеги, такие как
> `[whispers]` или `[laughs]`, внутри блока `[[tts:text]]` сохраняются
> в расшифровке Gemini; OpenClaw не создаёт эти теги.

> [accordion] OpenAI
>
> Сопоставляет поля запроса персоны с полем запроса `instructions` **только тогда**,
> когда не настроено явное значение OpenAI `instructions`. Явное значение `instructions`
> всегда имеет приоритет.

> [accordion] Другие провайдеры
>
> Используют только привязки персоны для конкретного провайдера в
> `personas.<id>.providers.<provider>`. Поля запроса персоны игнорируются,
> если провайдер не реализует собственное сопоставление запросов персоны.

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

`fallbackPolicy` управляет поведением, когда у персоны **нет привязки** для
провайдера, к которому выполняется попытка обращения:

| Политика | Поведение |
| - | - |
| `preserve-persona` | **По умолчанию.** Независимые от провайдера поля запроса остаются доступными; провайдер может использовать или игнорировать их. |
| `provider-defaults` | Персона исключается из подготовки запроса для этой попытки; провайдер использует нейтральные значения по умолчанию, пока продолжается резервное переключение на другие провайдеры. |
| `fail` | Пропустить попытку обращения к этому провайдеру с `reasonCode: "not_configured"` и `personaBinding: "missing"`. Резервные провайдеры всё равно будут опробованы. |

Весь запрос TTS завершается ошибкой, только если **каждый** опробованный провайдер был пропущен
или завершился ошибкой.

Выбор провайдера сеанса Talk действует в пределах сеанса. Клиент Talk должен выбирать
идентификаторы провайдеров, моделей, голосов и локали из `talk.catalog` и передавать
их через запрос сеанса Talk или передачи управления. Открытие голосового сеанса не должно
изменять `messages.tts` или глобальные значения провайдера Talk по умолчанию.

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

По умолчанию ассистент **может** создавать директивы `[[tts:...]]`, чтобы переопределить
голос, модель или скорость для одного ответа, а также необязательный
блок `[[tts:text]]...[[/tts:text]]` для выразительных указаний, которые должны присутствовать
только в аудио:

```text theme={"theme":{"light":"min-light","dark":"min-dark"}}
Вот, пожалуйста.

[[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`

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

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{ messages: { tts: { modelOverrides: { enabled: false } } } }
```

**Разрешить переключение провайдеров, сохранив возможность настройки остальных параметров:**

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{ messages: { tts: { modelOverrides: { enabled: true, allowProvider: true, allowSeed: false } } } }
```

## Команды с косой чертой

Единая команда `/tts`. В Discord OpenClaw также регистрирует `/voice`, поскольку
`/tts` — встроенная команда Discord; текстовая команда `/tts ...` по-прежнему работает.

```text theme={"theme":{"light":"min-light","dark":"min-dark"}}
/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>
```

> [!NOTE]
>
> Для команд требуется авторизованный отправитель (применяются правила списка разрешённых отправителей/владельца), а также
> должно быть включено `commands.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`.

| Сохраняемое поле | Эффект |
| - | - |
| `auto` | Локальное переопределение автоматического TTS (`always`, `off`, …) |
| `provider` | Локальное переопределение основного провайдера |
| `persona` | Локальное переопределение персоны |
| `maxLength` | Порог суммаризации/усечения (по умолчанию `1500` символов, диапазон `/tts limit`: 100–4096) |
| `summarize` | Переключатель суммаризации (по умолчанию `true`) |

Они переопределяют итоговую конфигурацию из `messages.tts` вместе с активным
блоком `agents.list[].tts` для данного хоста.

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

Передача озвучки TTS определяется возможностями канала. Плагины каналов объявляют,
следует ли для озвучки в стиле голосового сообщения запрашивать у провайдеров нативный целевой формат `voice-note` или
использовать обычный синтез `audio-file`, а также должен ли канал перекодировать
вывод в ненативном формате перед отправкой.

| Цель | Формат |
| - | - |
| Feishu / Matrix / Telegram / WhatsApp | Для ответов в виде голосовых сообщений предпочтителен **Opus** (`opus_48000_64` от ElevenLabs, `opus` от OpenAI). 48 кГц / 64 кбит/с обеспечивают баланс разборчивости и размера. |
| Другие каналы | **MP3** (`mp3_44100_128` от ElevenLabs, `mp3` от OpenAI). 44,1 кГц / 128 кбит/с — стандартный баланс для речи. |
| Разговор / телефония | Нативный для провайдера **PCM** (Inworld 22050 Гц, Google 24 кГц) или `ulaw_8000` от Gradium для телефонии. |

Примечания по провайдерам:

* **Перекодирование в 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` символов и
  синтезирует обрезанный текст.

```text theme={"theme":{"light":"min-light","dark":"min-dark"}}
Ответ -> TTS включён?
  нет -> отправить текст
  да  -> есть медиафайл / ответ короткий?
          да  -> отправить текст
          нет -> длина > лимита?
                   нет -> TTS -> прикрепить аудио
                   да  -> суммирование включено и доступно?
                            нет -> обрезать -> TTS -> прикрепить аудио
                            да  -> суммировать -> TTS -> прикрепить аудио
```

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

> [accordion] Верхнеуровневые параметры messages.tts.\*
>
> **auto** `"off" | "always" | "inbound" | "tagged"`
>
> Режим автоматического TTS. `inbound` отправляет аудио только после входящего голосового сообщения; `tagged` отправляет аудио только тогда, когда ответ содержит директивы `[[tts:...]]` или блок `[[tts:text]]`.
>
> **enabled** `boolean` *deprecated*
>
> Устаревший переключатель. `openclaw doctor --fix` переносит его в `auto`.
>
> **mode** `"final" | "all"` (default: final)
>
> `"all"` включает ответы инструментов и блоков в дополнение к финальным ответам.
>
> **provider** `string`
>
> Идентификатор поставщика синтеза речи. Если значение не задано, OpenClaw использует первого настроенного поставщика в порядке автоматического выбора из реестра. Устаревший `provider: "edge"` заменяется на `"microsoft"` с помощью `openclaw doctor --fix`.
>
> **persona** `string`
>
> Идентификатор активной персоны из `personas`. Нормализуется в нижний регистр.
>
> **personas.\<id>** `object`
>
> Стабильная речевая идентичность. Поля: `label`, `description`, `provider`, `fallbackPolicy`, `prompt`, `providers.<provider>`. См. [Персоны](#personas).
>
> **summaryModel** `string`
>
> Недорогая модель для автоматического суммирования; по умолчанию `agents.defaults.model.primary`. Принимает `provider/model` или настроенный псевдоним модели.
>
> **modelOverrides** `object`
>
> Разрешает модели выдавать директивы TTS. Значение `enabled` по умолчанию — `true`; значение `allowProvider` по умолчанию — `false`.
>
> **providers.\<id>** `object`
>
> Настройки, принадлежащие поставщику и индексируемые по идентификатору поставщика синтеза речи. Устаревшие непосредственные блоки (`messages.tts.openai`, `.elevenlabs`, `.microsoft`, `.edge`) преобразуются с помощью `openclaw doctor --fix`; сохраняйте только `messages.tts.providers.<id>`.
>
> **maxTextLength** `number` (default: 4096)
>
> Жёсткое ограничение количества символов во входных данных TTS. `/tts audio`, `tts.convert` и `tts.speak` завершаются с ошибкой при его превышении.
>
> **timeoutMs** `number` (default: 30000)
>
> Тайм-аут запроса в миллисекундах. Если для отдельного вызова задан `timeoutMs` (инструмент агента, Gateway), используется он; в противном случае явно настроенный `messages.tts.timeoutMs` имеет приоритет над любым значением по умолчанию поставщика, заданным плагином.
>
> **prefsPath** `string`
>
> Переопределяет локальный путь к JSON-файлу настроек (поставщик/ограничение/суммирование). По умолчанию `~/.openclaw/settings/tts.json`.

> [accordion] Azure Speech
>
> **apiKey** `string`
>
> Переменная среды: `AZURE_SPEECH_KEY`, `AZURE_SPEECH_API_KEY` или `SPEECH_KEY`.
>
> **region** `string`
>
> Регион Azure Speech (например, `eastus`). Переменная среды: `AZURE_SPEECH_REGION` или `SPEECH_REGION`.
>
> **endpoint** `string`
>
> Необязательное переопределение конечной точки Azure Speech (псевдоним `baseUrl`).
>
> **speakerVoice** `string`
>
> ShortName голоса Azure. По умолчанию `en-US-JennyNeural`. Устаревший псевдоним: `voice`.
>
> **lang** `string`
>
> Код языка SSML. По умолчанию `en-US`.
>
> **outputFormat** `string`
>
> Azure `X-Microsoft-OutputFormat` для стандартного аудио. По умолчанию `audio-24khz-48kbitrate-mono-mp3`.
>
> **voiceNoteOutputFormat** `string`
>
> Azure `X-Microsoft-OutputFormat` для вывода голосовых заметок. По умолчанию `ogg-24khz-16bit-mono-opus`.

> [accordion] ElevenLabs
>
> **apiKey** `string`
>
> При отсутствии значения использует `ELEVENLABS_API_KEY` или `XI_API_KEY`.
>
> **model** `string`
>
> Идентификатор модели. По умолчанию `eleven_multilingual_v2`. Устаревшие идентификаторы `eleven_turbo_v2_5`/`eleven_turbo_v2` нормализуются в соответствующую модель `flash`.
>
> **speakerVoiceId** `string`
>
> Идентификатор голоса ElevenLabs. По умолчанию `pMsXgVXv3BLzUgSXRplE`. Устаревший псевдоним: `voiceId`.
>
> **voiceSettings** `object`
>
> `stability`, `similarityBoost`, `style` (каждое — `0..1`, значения по умолчанию — `0.5`/`0.75`/`0`), `useSpeakerBoost` (`true|false`, по умолчанию `true`), `speed` (`0.5..2.0`, по умолчанию `1.0`).
>
> **applyTextNormalization** `"auto" | "on" | "off"`
>
> Режим нормализации текста.
>
> **languageCode** `string`
>
> Двухбуквенный код ISO 639-1 (например, `en`, `de`).
>
> **seed** `number`
>
> Целое число `0..4294967295` для обеспечения детерминизма по мере возможности.
>
> **baseUrl** `string`
>
> Переопределяет базовый URL API ElevenLabs.

> [accordion] Google Gemini
>
> **apiKey** `string`
>
> При отсутствии значения используются `GEMINI_API_KEY` / `GOOGLE_API_KEY`. Если параметр не задан, TTS может повторно использовать `models.providers.google.apiKey`, прежде чем обращаться к переменным окружения.
>
> **model** `string`
>
> Модель Gemini TTS. По умолчанию `gemini-3.1-flash-tts-preview`.
>
> **speakerVoice** `string`
>
> Имя встроенного голоса Gemini. По умолчанию `Kore`. Устаревшие псевдонимы: `voiceName`, `voice`.
>
> **audioProfile** `string`
>
> Текстовая инструкция по стилю на естественном языке, добавляемая перед произносимым текстом.
>
> **speakerName** `string`
>
> Необязательная метка говорящего, добавляемая перед произносимым текстом, если в инструкции используется именованный говорящий.
>
> **promptTemplate** `"audio-profile-v1"`
>
> Укажите `audio-profile-v1`, чтобы заключить поля инструкции активной персоны в детерминированную структуру инструкции Gemini TTS.
>
> **personaPrompt** `string`
>
> Дополнительный текст инструкции персоны для Google, добавляемый к режиссёрским примечаниям шаблона.
>
> **baseUrl** `string`
>
> Допускается только `https://generativelanguage.googleapis.com`.

> [accordion] Gradium
>
> **apiKey** `string`
>
> Переменная окружения: `GRADIUM_API_KEY`.
>
> **baseUrl** `string`
>
> URL API Gradium по HTTPS на `api.gradium.ai`. По умолчанию `https://api.gradium.ai`.
>
> **speakerVoiceId** `string`
>
> По умолчанию Emma (`YTpq7expH9539ERJ`). Устаревший псевдоним: `voiceId`.

> [accordion] Inworld
>
> ### Основной Inworld
>
> **apiKey** `string`
>
> Переменная окружения: `INWORLD_API_KEY`.
>
> **baseUrl** `string`
>
> По умолчанию `https://api.inworld.ai`.
>
> **modelId** `string`
>
> По умолчанию `inworld-tts-1.5-max`. Также: `inworld-tts-1.5-mini`, `inworld-tts-1-max`, `inworld-tts-1`.
>
> **speakerVoiceId** `string`
>
> По умолчанию `Sarah`. Устаревший псевдоним: `voiceId`.
>
> **temperature** `number`
>
> Температура сэмплирования `0..2` (не включая 0).

> [accordion] Локальный CLI (tts-local-cli)
>
> **command** `string`
>
> Локальный исполняемый файл или строка команды для TTS через CLI.
>
> **args** `string[]`
>
> Аргументы команды. Поддерживаются заполнители `{{Text}}`, `{{OutputPath}}`, `{{OutputDir}}`, `{{OutputBase}}`.
>
> **outputFormat** `"mp3" | "opus" | "wav"`
>
> Ожидаемый формат вывода CLI. По умолчанию `mp3` для звуковых вложений.
>
> **timeoutMs** `number`
>
> Время ожидания команды в миллисекундах. По умолчанию `120000`.
>
> **cwd** `string`
>
> Необязательный рабочий каталог команды.
>
> **env** `Record\<string, string\>`
>
> Необязательные переопределения переменных окружения для команды.
>
> Размер стандартного вывода команды и созданного или преобразованного аудио ограничен 50 МиБ. Размер диагностического стандартного потока ошибок ограничен 1 МиБ. При превышении любого из ограничений OpenClaw завершает команду и синтез оканчивается ошибкой.

> [accordion] Microsoft (без ключа API)
>
> **enabled** `boolean` (default: true)
>
> Разрешить использование синтеза речи Microsoft.
>
> **speakerVoice** `string`
>
> Имя нейросетевого голоса Microsoft (например, `en-US-MichelleNeural`). Устаревший псевдоним: `voice`. Если используется стандартный английский голос, а в тексте ответа преобладают символы CJK, OpenClaw автоматически переключается на `zh-CN-XiaoxiaoNeural`.
>
> **lang** `string`
>
> Код языка (например, `en-US`).
>
> **outputFormat** `string`
>
> Формат вывода Microsoft. По умолчанию `audio-24khz-48kbitrate-mono-mp3`. Встроенный транспорт на базе Edge поддерживает не все форматы.
>
> **rate / pitch / volume** `string`
>
> Строки с процентными значениями (например, `+10%`, `-5%`).
>
> **saveSubtitles** `boolean`
>
> Записывать субтитры JSON рядом с аудиофайлом.
>
> **proxy** `string`
>
> URL прокси-сервера для запросов синтеза речи Microsoft.
>
> **timeoutMs** `number`
>
> Переопределение времени ожидания запроса (мс).
>
> **edge.**\* `object` *deprecated*
>
> Устаревший псевдоним. Выполните `openclaw doctor --fix`, чтобы преобразовать сохранённую конфигурацию в `providers.microsoft`.

> [accordion] MiniMax
>
> **apiKey** `string`
>
> При отсутствии значения используется `MINIMAX_API_KEY`. Авторизация Token Plan через `MINIMAX_OAUTH_TOKEN`, `MINIMAX_CODE_PLAN_KEY` или `MINIMAX_CODING_API_KEY`.
>
> **baseUrl** `string`
>
> По умолчанию `https://api.minimax.io`. Переменная окружения: `MINIMAX_API_HOST`.
>
> **model** `string`
>
> По умолчанию `speech-2.8-hd`. Переменная окружения: `MINIMAX_TTS_MODEL`.
>
> **speakerVoiceId** `string`
>
> По умолчанию `English_expressive_narrator`. Переменная окружения: `MINIMAX_TTS_VOICE_ID`. Устаревший псевдоним: `voiceId`.
>
> **speed** `number`
>
> `0.5..2.0`. По умолчанию `1.0`.
>
> **vol** `number`
>
> `(0, 10]`. По умолчанию `1.0`.
>
> **pitch** `number`
>
> Целое число `-12..12`. По умолчанию `0`. Дробные значения перед запросом усекаются.

> [accordion] OpenAI
>
> **apiKey** `string`
>
> При отсутствии значения используется `OPENAI_API_KEY`.
>
> **model** `string`
>
> Идентификатор модели OpenAI TTS. По умолчанию `gpt-4o-mini-tts`.
>
> **speakerVoice** `string`
>
> Имя голоса (например, `alloy`, `cedar`). По умолчанию `coral`. Устаревший псевдоним: `voice`.
>
> **instructions** `string`
>
> Явное поле OpenAI `instructions`. Если оно задано, поля инструкции персоны **не** сопоставляются автоматически.
>
> **extraBody / extra\_body** `Record\<string, unknown\>`
>
> Дополнительные поля JSON, объединяемые с телами запросов `/audio/speech` после сгенерированных полей OpenAI TTS. Используйте их для совместимых с OpenAI конечных точек, например Kokoro, которым требуются специфичные для поставщика ключи, такие как `lang`; небезопасные ключи прототипа игнорируются.
>
> **baseUrl** `string`
>
> Переопределяет конечную точку OpenAI TTS. Порядок разрешения: конфигурация → `OPENAI_TTS_BASE_URL` → `https://api.openai.com/v1`. Значения, отличные от стандартного, рассматриваются как совместимые с OpenAI конечные точки TTS, поэтому допускаются пользовательские имена моделей и голосов, а для `speed` больше не проверяется диапазон `0.25..4.0`.

> [accordion] OpenRouter
>
> **apiKey** `string`
>
> Переменная окружения: `OPENROUTER_API_KEY`. Можно повторно использовать `models.providers.openrouter.apiKey`.
>
> **baseUrl** `string`
>
> По умолчанию `https://openrouter.ai/api/v1`. Устаревшее значение `https://openrouter.ai/v1` нормализуется.
>
> **model** `string`
>
> По умолчанию `hexgrad/kokoro-82m`. Псевдоним: `modelId`.
>
> **speakerVoice** `string`
>
> По умолчанию `af_alloy`. Устаревшие псевдонимы: `voice`, `voiceId`.
>
> **responseFormat** `"mp3" | "pcm"`
>
> По умолчанию `mp3`.
>
> **speed** `number`
>
> Переопределение скорости в собственном формате поставщика.

> [accordion] Volcengine (BytePlus Seed Speech)
>
> **apiKey** `string`
>
> Переменная окружения: `VOLCENGINE_TTS_API_KEY` или `BYTEPLUS_SEED_SPEECH_API_KEY`.
>
> **resourceId** `string`
>
> По умолчанию `seed-tts-1.0`. Переменная окружения: `VOLCENGINE_TTS_RESOURCE_ID`. Используйте `seed-tts-2.0`, если в вашем проекте предоставлено право на TTS 2.0.
>
> **appKey** `string`
>
> Заголовок ключа приложения. По умолчанию `aGjiRDfUWi`. Переменная окружения: `VOLCENGINE_TTS_APP_KEY`.
>
> **baseUrl** `string`
>
> Переопределяет конечную точку HTTP Seed Speech TTS. Переменная окружения: `VOLCENGINE_TTS_BASE_URL`.
>
> **speakerVoice** `string`
>
> Тип голоса. По умолчанию `en_female_anna_mars_bigtts`. Переменная окружения: `VOLCENGINE_TTS_VOICE`. Устаревший псевдоним: `voice`.
>
> **speedRatio** `number`
>
> Коэффициент скорости в собственном формате поставщика, `0.2..3`.
>
> **emotion** `string`
>
> Тег эмоции в собственном формате поставщика.
>
> **appId / token / cluster** `string` *deprecated*
>
> Устаревшие поля Volcengine Speech Console. Переменные окружения: `VOLCENGINE_TTS_APPID`, `VOLCENGINE_TTS_TOKEN`, `VOLCENGINE_TTS_CLUSTER` (по умолчанию `volcano_tts`).

> [accordion] xAI
>
> **apiKey** `string`
>
> Переменная окружения: `XAI_API_KEY`.
>
> **baseUrl** `string`
>
> По умолчанию `https://api.x.ai/v1`. Переменная окружения: `XAI_BASE_URL`.
>
> **speakerVoiceId** `string`
>
> По умолчанию `eve`. При наличии авторизации `openclaw infer tts voices --provider xai` получает текущий встроенный каталог; без авторизации выводится список автономных резервных вариантов: `ara`, `eve`, `leo`, `rex` и `sal`. Идентификаторы пользовательских голосов учётной записи передаются дальше, даже если их нет во встроенном списке. Устаревший псевдоним: `voiceId`.
>
> **language** `string`
>
> Код языка BCP-47 или `auto`. По умолчанию `en`.
>
> **responseFormat** `"mp3" | "wav" | "pcm" | "mulaw" | "alaw"`
>
> По умолчанию `mp3`.
>
> **speed** `number`
>
> Переопределение скорости в собственном формате поставщика, `0.7..1.5`.

> [accordion] Xiaomi MiMo
>
> **apiKey** `string`
>
> Переменная окружения: `XIAOMI_API_KEY`.
>
> **baseUrl** `string`
>
> По умолчанию `https://api.xiaomimimo.com/v1`. Переменная окружения: `XIAOMI_BASE_URL`.
>
> **model** `string`
>
> По умолчанию `mimo-v2.5-tts`. Переменная окружения: `XIAOMI_TTS_MODEL`. Также поддерживаются `mimo-v2-tts` и `mimo-v2.5-tts-voicedesign`.
>
> **speakerVoice** `string`
>
> По умолчанию `mimo_default` для моделей с предустановленными голосами. Переменная окружения: `XIAOMI_TTS_VOICE`. Устаревший псевдоним: `voice`. Не отправляется для `mimo-v2.5-tts-voicedesign`.
>
> **format** `"mp3" | "wav"`
>
> По умолчанию `mp3`. Переменная окружения: `XIAOMI_TTS_FORMAT`.
>
> **style** `string`
>
> Необязательная инструкция по стилю на естественном языке, отправляемая как сообщение пользователя; она не произносится. Для `mimo-v2.5-tts-voicedesign` это инструкция по созданию голоса; если она не задана, OpenClaw предоставляет значение по умолчанию.

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

Инструмент `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

| Метод | Назначение |
| - | - |
| `tts.status` | Получить текущее состояние TTS и данные последней попытки. |
| `tts.enable` | Установить локальную настройку автоматического режима в значение `always`. |
| `tts.disable` | Установить локальную настройку автоматического режима в значение `off`. |
| `tts.convert` | Однократное преобразование текста в аудио. |
| `tts.setProvider` | Установить локальное предпочтение провайдера. |
| `tts.personas` | Вывести список настроенных персон и активную персону. |
| `tts.setPersona` | Установить локальное предпочтение персоны. |
| `tts.providers` | Вывести список настроенных провайдеров и их состояние. |

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

* [Руководство OpenAI по преобразованию текста в речь](https://platform.openai.com/docs/guides/text-to-speech)
* [Справочник по OpenAI Audio API](https://platform.openai.com/docs/api-reference/audio)
* [Преобразование текста в речь через Azure Speech REST](https://learn.microsoft.com/azure/ai-services/speech-service/rest-text-to-speech)
* [Провайдер Azure Speech](https://docs2.openclaw.ai/ru/providers/azure-speech.md)
* [Преобразование текста в речь в ElevenLabs](https://elevenlabs.io/docs/api-reference/text-to-speech)
* [Аутентификация в ElevenLabs](https://elevenlabs.io/docs/api-reference/authentication)
* [Gradium](https://docs2.openclaw.ai/ru/providers/gradium.md)
* [API TTS от Inworld](https://docs.inworld.ai/tts/tts)
* [API MiniMax T2A v2](https://platform.minimaxi.com/document/T2A%20V2)
* [HTTP API TTS от Volcengine](https://docs2.openclaw.ai/ru/providers/volcengine.md#text-to-speech)
* [Синтез речи Xiaomi MiMo](https://docs2.openclaw.ai/ru/providers/xiaomi.md#text-to-speech)
* [node-edge-tts](https://github.com/SchneeHertz/node-edge-tts)
* [Форматы вывода Microsoft Speech](https://learn.microsoft.com/azure/ai-services/speech-service/rest-text-to-speech#audio-outputs)
* [Преобразование текста в речь в xAI](https://docs.x.ai/developers/rest-api-reference/inference/voice#text-to-speech-rest)

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

* [Обзор работы с медиа](https://docs2.openclaw.ai/ru/tools/media-overview.md)
* [Генерация музыки](https://docs2.openclaw.ai/ru/tools/music-generation.md)
* [Генерация видео](https://docs2.openclaw.ai/ru/tools/video-generation.md)
* [Команды с косой чертой](https://docs2.openclaw.ai/ru/tools/slash-commands.md)
* [Плагин голосовых вызовов](https://docs2.openclaw.ai/ru/plugins/voice-call.md)