Zamiana tekstu na mowę

OpenClaw może konwertować odpowiedzi wychodzące na dźwięk u 14 dostawców mowy oraz dostarczać natywne wiadomości głosowe w Feishu, Matrix, Telegram i WhatsApp, załączniki audio wszędzie indziej oraz strumienie PCM/Ulaw dla telefonii i Talk.

TTS to wyjściowa połowa mowy w trybie stt-tts Talk. Sesje Talk realtime natywne dla dostawcy syntetyzują mowę wewnątrz dostawcy czasu rzeczywistego zamiast wywoływać tę ścieżkę TTS, natomiast sesje transcription nie syntetyzują głosowej odpowiedzi asystenta.

Szybki start

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

Obsługiwani dostawcy

Jeśli skonfigurowano wielu dostawców, wybrany dostawca jest używany jako pierwszy, a pozostali są opcjami zapasowymi. Automatyczne podsumowania używają summaryModel (lub agents.defaults.model.primary), więc ten dostawca również musi być uwierzytelniony, jeśli pozostawisz podsumowania włączone.

Konfiguracja

Konfiguracja TTS znajduje się w messages.tts w ~/.openclaw/openclaw.json. Wybierz preset i dostosuj blok dostawcy:

{messages: {tts: {  auto: "always",  provider: "azure-speech",  providers: {    "azure-speech": {      apiKey: "${AZURE_SPEECH_KEY}",      region: "eastus",      voice: "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",      voiceId: "EXAVITQu4vr4xnSDxMaL",    },  },},},}

{messages: {tts: {  auto: "always",  provider: "google",  providers: {    google: {      apiKey: "${GEMINI_API_KEY}",      model: "gemini-3.1-flash-tts-preview",      voiceName: "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}",      voiceId: "YTpq7expH9539ERJ",    },  },},},}

{messages: {tts: {  auto: "always",  provider: "inworld",  providers: {    inworld: {      apiKey: "${INWORLD_API_KEY}",      modelId: "inworld-tts-1.5-max",      voiceId: "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,      voice: "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",      voiceId: "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",      voice: "alloy",    },    elevenlabs: {      apiKey: "${ELEVENLABS_API_KEY}",      model: "eleven_multilingual_v2",      voiceId: "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",      voice: "af_alloy",      responseFormat: "mp3",    },  },},},}

{messages: {tts: {  auto: "always",  provider: "volcengine",  providers: {    volcengine: {      apiKey: "${VOLCENGINE_TTS_API_KEY}",      resourceId: "seed-tts-1.0",      voice: "en_female_anna_mars_bigtts",    },  },},},}

{messages: {tts: {  auto: "always",  provider: "xai",  providers: {    xai: {      apiKey: "${XAI_API_KEY}",      voiceId: "eve",      language: "en",      responseFormat: "mp3",    },  },},},}

{messages: {tts: {  auto: "always",  provider: "xiaomi",  providers: {    xiaomi: {      apiKey: "${XIAOMI_API_KEY}",      model: "mimo-v2.5-tts",      voice: "mimo_default",      format: "mp3",    },  },},},}

Nadpisania głosu dla poszczególnych agentów

Użyj agents.list[].tts, gdy jeden agent powinien mówić z innym dostawcą, głosem, modelem, personą lub trybem Auto-TTS. Blok agenta jest głęboko scalany z messages.tts, więc poświadczenia dostawcy mogą pozostać w globalnej konfiguracji dostawcy:

{  messages: {    tts: {      auto: "always",      provider: "elevenlabs",      providers: {        elevenlabs: { apiKey: "${ELEVENLABS_API_KEY}", model: "eleven_multilingual_v2" },      },    },  },  agents: {    list: [      {        id: "reader",        tts: {          providers: {            elevenlabs: { voiceId: "EXAVITQu4vr4xnSDxMaL" },          },        },      },    ],  },}

Aby przypiąć personę dla konkretnego agenta, ustaw agents.list[].tts.persona obok konfiguracji dostawcy — zastępuje ona globalne messages.tts.persona tylko dla tego agenta.

Kolejność pierwszeństwa dla automatycznych odpowiedzi, /tts audio, /tts status oraz narzędzia agenta tts:

1. messages.tts
2. aktywne agents.list[].tts
3. nadpisanie kanału, gdy kanał obsługuje channels.<channel>.tts
4. nadpisanie konta, gdy kanał przekazuje channels.<channel>.accounts.<id>.tts
5. lokalne preferencje /tts dla tego hosta
6. dyrektywy wbudowane [[tts:...]], gdy włączone są nadpisania modelu

Nadpisania kanału i konta używają tego samego kształtu co messages.tts i są głęboko scalane z wcześniejszymi warstwami, więc współdzielone dane uwierzytelniające dostawcy mogą pozostać w messages.tts, podczas gdy kanał lub konto bota zmienia tylko głos, model, personę albo tryb automatyczny:

{  messages: {    tts: {      provider: "openai",      providers: {        openai: { apiKey: "${OPENAI_API_KEY}", model: "gpt-4o-mini-tts" },      },    },  },  channels: {    feishu: {      accounts: {        english: {          tts: {            providers: {              openai: { voice: "shimmer" },            },          },        },      },    },  },}

Persony

Persona to stabilna tożsamość mówiona, którą można deterministycznie stosować u różnych dostawców. Może preferować jednego dostawcę, definiować neutralny wobec dostawców zamiar promptu oraz przenosić powiązania specyficzne dla dostawcy dla głosów, modeli, szablonów promptów, ziaren i ustawień głosu.

Minimalna persona

{  messages: {    tts: {      auto: "always",      persona: "narrator",      personas: {        narrator: {          label: "Narrator",          provider: "elevenlabs",          providers: {            elevenlabs: { voiceId: "EXAVITQu4vr4xnSDxMaL", modelId: "eleven_multilingual_v2" },          },        },      },    },  },}

Pełna persona (prompt neutralny wobec dostawcy)

{  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",              voiceName: "Algieba",              promptTemplate: "audio-profile-v1",            },            openai: { model: "gpt-4o-mini-tts", voice: "cedar" },            elevenlabs: {              voiceId: "voice_id",              modelId: "eleven_multilingual_v2",              seed: 42,              voiceSettings: {                stability: 0.65,                similarityBoost: 0.8,                style: 0.25,                useSpeakerBoost: true,                speed: 0.95,              },            },          },        },      },    },  },}

Rozstrzyganie persony

Aktywna persona jest wybierana deterministycznie:

1. lokalna preferencja /tts persona <id>, jeśli jest ustawiona.
2. messages.tts.persona, jeśli jest ustawione.
3. Brak persony.

Wybór dostawcy działa według zasady najpierw jawne ustawienia:

1. Bezpośrednie nadpisania (CLI, Gateway, Talk, dozwolone dyrektywy TTS).
2. lokalna preferencja /tts provider <id>.
3. provider aktywnej persony.
4. messages.tts.provider.
5. Automatyczny wybór z rejestru.

Dla każdej próby dostawcy OpenClaw scala konfiguracje w tej kolejności:

1. messages.tts.providers.<id>
2. messages.tts.personas.<persona>.providers.<id>
3. Zaufane nadpisania żądania
4. Dozwolone nadpisania z dyrektyw TTS wyemitowanych przez model

Jak dostawcy używają promptów persony

Pola promptu persony (profile, scene, sampleContext, style, accent, pacing, constraints) są neutralne wobec dostawców. Każdy dostawca decyduje, jak ich używać:

Zasada awaryjna

fallbackPolicy steruje zachowaniem, gdy persona nie ma powiązania dla próbowanego dostawcy:

Całe żądanie TTS kończy się niepowodzeniem tylko wtedy, gdy każdy próbowany dostawca zostanie pominięty albo zakończy się błędem.

Wybór dostawcy sesji Talk ma zakres sesji. Klient Talk powinien wybierać identyfikatory dostawców, identyfikatory modeli, identyfikatory głosów i ustawienia regionalne z talk.catalog oraz przekazywać je przez sesję Talk albo żądanie przekazania. Otwarcie sesji głosowej nie powinno modyfikować messages.tts ani globalnych domyślnych dostawców Talk.

Dyrektywy sterowane przez model

Domyślnie asystent może emitować dyrektywy [[tts:...]], aby nadpisać głos, model albo szybkość dla pojedynczej odpowiedzi, a także opcjonalny blok [[tts:text]]...[[/tts:text]] dla ekspresyjnych wskazówek, które powinny pojawić się tylko w audio:

Here you go. [[tts:voiceId=pMsXgVXv3BLzUgSXRplE model=eleven_v3 speed=1.1]][[tts:text]](laughs) Read the song once more.[[/tts:text]]

Gdy messages.tts.auto ma wartość "tagged", dyrektywy są wymagane, aby wyzwolić audio. Dostarczanie bloków strumieniowych usuwa dyrektywy z widocznego tekstu, zanim kanał je zobaczy, nawet gdy są podzielone między sąsiadujące bloki.

provider=... jest ignorowane, chyba że modelOverrides.allowProvider: true. Gdy odpowiedź deklaruje provider=..., pozostałe klucze w tej dyrektywie są parsowane tylko przez tego dostawcę; nieobsługiwane klucze są usuwane i zgłaszane jako ostrzeżenia dyrektyw TTS.

Dostępne klucze dyrektyw:

• provider (zarejestrowany identyfikator dostawcy; wymaga allowProvider: true)
• voice / voiceName / voice_name / google_voice / voiceId
• model / google_model
• stability, similarityBoost, style, speed, useSpeakerBoost
• vol / volume (głośność MiniMax, 0–10)
• pitch (całkowitoliczbowy ton MiniMax, −12 do 12; wartości ułamkowe są obcinane)
• emotion (znacznik emocji Volcengine)
• applyTextNormalization (auto|on|off)
• languageCode (ISO 639-1)
• seed

Całkowicie wyłącz nadpisania modelu:

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

Zezwól na przełączanie dostawców, zachowując konfigurowalność innych ustawień:

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

Polecenia ukośnikowe

Pojedyncze polecenie /tts. Na Discordzie OpenClaw rejestruje też /voice, ponieważ /tts jest wbudowanym poleceniem Discorda — tekstowe /tts ... nadal działa.

/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>

Uwagi dotyczące zachowania:

• /tts on zapisuje lokalną preferencję TTS jako always; /tts off zapisuje ją jako off.
• /tts chat on|off|default zapisuje nadpisanie automatycznego TTS o zakresie sesji dla bieżącego czatu.
• /tts persona <id> zapisuje lokalną preferencję persony; /tts persona off ją czyści.
• /tts latest odczytuje najnowszą odpowiedź asystenta z transkryptu bieżącej sesji i wysyła ją raz jako audio. Przechowuje tylko hash tej odpowiedzi we wpisie sesji, aby zapobiec zduplikowanym wysyłkom głosowym.
• /tts audio generuje jednorazową odpowiedź audio (nie włącza TTS).
• limit i summary są przechowywane w lokalnych preferencjach, nie w głównej konfiguracji.
• /tts status zawiera diagnostykę przejścia awaryjnego dla najnowszej próby — Fallback: <primary> -> <used>, Attempts: ... oraz szczegóły każdej próby (provider:outcome(reasonCode) latency).
• /status pokazuje aktywny tryb TTS oraz skonfigurowanego dostawcę, model, głos i oczyszczone metadane niestandardowego punktu końcowego, gdy TTS jest włączony.

Preferencje poszczególnych użytkowników

Polecenia ukośnikowe zapisują lokalne nadpisania w prefsPath. Wartość domyślna to ~/.openclaw/settings/tts.json; nadpisz ją zmienną środowiskową OPENCLAW_TTS_PREFS albo messages.tts.prefsPath.

Nadpisują one efektywną konfigurację z messages.tts oraz aktywnego bloku agents.list[].tts dla tego hosta.

Formaty wyjściowe (stałe)

Dostarczanie głosu TTS jest sterowane możliwościami kanału. Pluginy kanałów deklarują, czy TTS w stylu wiadomości głosowej powinien prosić dostawców o natywny cel voice-note, czy zachować normalną syntezę audio-file i tylko oznaczać zgodne dane wyjściowe do dostarczania głosowego.

• Kanały obsługujące wiadomości głosowe: odpowiedzi jako wiadomości głosowe preferują Opus (opus_48000_64 z ElevenLabs, opus z OpenAI).
  • 48 kHz / 64 kbps to dobry kompromis dla wiadomości głosowych.
• Feishu / WhatsApp: gdy odpowiedź jako wiadomość głosowa jest tworzona jako MP3/WebM/WAV/M4A lub inny prawdopodobny plik audio, Plugin kanału transkoduje ją do 48 kHz Ogg/Opus za pomocą ffmpeg przed wysłaniem natywnej wiadomości głosowej. WhatsApp wysyła wynik przez ładunek audio Baileys z ptt: true i audio/ogg; codecs=opus. Jeśli konwersja się nie powiedzie, Feishu otrzymuje oryginalny plik jako załącznik; wysyłka przez WhatsApp kończy się niepowodzeniem zamiast opublikowania niezgodnego ładunku PTT.
• Inne kanały: MP3 (mp3_44100_128 z ElevenLabs, mp3 z OpenAI).
  • 44,1 kHz / 128 kbps to domyślny balans dla wyrazistości mowy.
• MiniMax: MP3 (model speech-2.8-hd, częstotliwość próbkowania 32 kHz) dla zwykłych załączników audio. Dla celów wiadomości głosowych deklarowanych przez kanał OpenClaw transkoduje MP3 MiniMax do 48 kHz Opus za pomocą ffmpeg przed dostarczeniem, gdy kanał deklaruje transkodowanie.
• Xiaomi MiMo: domyślnie MP3 albo WAV, gdy skonfigurowano. Dla celów wiadomości głosowych deklarowanych przez kanał OpenClaw transkoduje wyjście Xiaomi do 48 kHz Opus za pomocą ffmpeg przed dostarczeniem, gdy kanał deklaruje transkodowanie.
• Lokalny CLI: używa skonfigurowanego outputFormat. Cele wiadomości głosowych są konwertowane do Ogg/Opus, a wyjście telefoniczne jest konwertowane do surowego 16 kHz mono PCM za pomocą ffmpeg.
• Google Gemini: TTS API Gemini zwraca surowe 24 kHz PCM. OpenClaw opakowuje je jako WAV dla załączników audio, transkoduje je do 48 kHz Opus dla celów wiadomości głosowych i zwraca PCM bezpośrednio dla Talk/telefonii.
• Gradium: WAV dla załączników audio, Opus dla celów wiadomości głosowych oraz ulaw_8000 przy 8 kHz dla telefonii.
• Inworld: MP3 dla zwykłych załączników audio, natywne OGG_OPUS dla celów wiadomości głosowych oraz surowe PCM przy 22050 Hz dla Talk/telefonii.
• xAI: domyślnie MP3; responseFormat może mieć wartość mp3, wav, pcm, mulaw lub alaw. OpenClaw używa wsadowego punktu końcowego REST TTS xAI i zwraca kompletny załącznik audio; streamingowy WebSocket TTS xAI nie jest używany przez tę ścieżkę dostawcy. Natywny format Opus dla wiadomości głosowych nie jest obsługiwany przez tę ścieżkę.
• Microsoft: używa microsoft.outputFormat (domyślnie audio-24khz-48kbitrate-mono-mp3).
  • Wbudowany transport akceptuje outputFormat, ale nie wszystkie formaty są dostępne w usłudze.
  • Wartości formatu wyjściowego odpowiadają formatom wyjściowym Microsoft Speech (w tym Ogg/WebM Opus).
  • Telegram sendVoice akceptuje OGG/MP3/M4A; użyj OpenAI/ElevenLabs, jeśli potrzebujesz gwarantowanych wiadomości głosowych Opus.
  • Jeśli skonfigurowany format wyjściowy Microsoft zawiedzie, OpenClaw ponawia próbę z MP3.

Formaty wyjściowe OpenAI/ElevenLabs są stałe dla każdego kanału (zobacz wyżej).

Zachowanie Auto-TTS

Gdy messages.tts.auto jest włączone, OpenClaw:

• Pomija TTS, jeśli odpowiedź zawiera już media lub dyrektywę MEDIA:.
• Pomija bardzo krótkie odpowiedzi (poniżej 10 znaków).
• Streszcza długie odpowiedzi, gdy streszczenia są włączone, używając summaryModel (lub agents.defaults.model.primary).
• Dołącza wygenerowane audio do odpowiedzi.
• W mode: "final" nadal wysyła TTS tylko audio dla strumieniowanych odpowiedzi końcowych po zakończeniu strumienia tekstu; wygenerowane media przechodzą przez tę samą normalizację mediów kanału co zwykłe załączniki odpowiedzi.

Jeśli odpowiedź przekracza maxLength, a streszczenie jest wyłączone (lub nie ma klucza API dla modelu streszczeń), audio jest pomijane i wysyłana jest zwykła odpowiedź tekstowa.

Reply -> TTS enabled?  no  -> send text  yes -> has media / MEDIA: / short?          yes -> send text          no  -> length > limit?                   no  -> TTS -> attach audio                   yes -> summary enabled?                            no  -> send text                            yes -> summarize -> TTS -> attach audio

Formaty wyjściowe według kanału

Uwagi dotyczące dostawców:

• Transkodowanie Feishu / WhatsApp: Gdy odpowiedź jako wiadomość głosowa trafia jako MP3/WebM/WAV/M4A, Plugin kanału transkoduje ją do 48 kHz Ogg/Opus za pomocą ffmpeg. WhatsApp wysyła przez Baileys z ptt: true i audio/ogg; codecs=opus. Jeśli konwersja się nie powiedzie: Feishu awaryjnie dołącza oryginalny plik; wysyłka przez WhatsApp kończy się niepowodzeniem zamiast opublikowania niezgodnego ładunku PTT.
• MiniMax / Xiaomi MiMo: Domyślnie MP3 (32 kHz dla MiniMax speech-2.8-hd); transkodowane do 48 kHz Opus dla celów wiadomości głosowych przez ffmpeg.
• Lokalny CLI: Używa skonfigurowanego outputFormat. Cele wiadomości głosowych są konwertowane do Ogg/Opus, a wyjście telefoniczne do surowego 16 kHz mono PCM.
• Google Gemini: Zwraca surowe 24 kHz PCM. OpenClaw opakowuje jako WAV dla załączników, transkoduje do 48 kHz Opus dla celów wiadomości głosowych, zwraca PCM bezpośrednio dla Talk/telefonii.
• Inworld: Załączniki MP3, natywna wiadomość głosowa OGG_OPUS, surowe PCM 22050 Hz dla Talk/telefonii.
• xAI: Domyślnie MP3; responseFormat może mieć wartość mp3|wav|pcm|mulaw|alaw. Używa wsadowego punktu końcowego REST xAI — streamingowe WebSocket TTS nie jest używane. Natywny format Opus dla wiadomości głosowych nie jest obsługiwany.
• Microsoft: Używa microsoft.outputFormat (domyślnie audio-24khz-48kbitrate-mono-mp3). Telegram sendVoice akceptuje OGG/MP3/M4A; użyj OpenAI/ElevenLabs, jeśli potrzebujesz gwarantowanych wiadomości głosowych Opus. Jeśli skonfigurowany format Microsoft zawiedzie, OpenClaw ponawia próbę z MP3.

Formaty wyjściowe OpenAI i ElevenLabs są stałe dla każdego kanału zgodnie z powyższą listą.

Dokumentacja pól

Narzędzie agenta

Narzędzie tts konwertuje tekst na mowę i zwraca załącznik audio do dostarczenia w odpowiedzi. W Feishu, Matrix, Telegram i WhatsApp audio jest dostarczane jako wiadomość głosowa, a nie jako załącznik pliku. Feishu i WhatsApp mogą transkodować wyjście TTS inne niż Opus na tej ścieżce, gdy ffmpeg jest dostępny.

WhatsApp wysyła audio przez Baileys jako notatkę głosową PTT (audio z ptt: true) i wysyła widoczny tekst oddzielnie od audio PTT, ponieważ klienci nie renderują konsekwentnie podpisów przy notatkach głosowych.

Narzędzie akceptuje opcjonalne pola channel i timeoutMs; timeoutMs jest limitem czasu żądania providera dla pojedynczego wywołania, w milisekundach.

Gateway RPC

Linki do usług

• Przewodnik OpenAI po zamianie tekstu na mowę
• Dokumentacja referencyjna OpenAI Audio API
• Azure Speech REST: zamiana tekstu na mowę
• Provider Azure Speech
• ElevenLabs Text to Speech
• Uwierzytelnianie ElevenLabs
• Gradium
• Inworld TTS API
• MiniMax T2A v2 API
• Volcengine TTS HTTP API
• Synteza mowy Xiaomi MiMo
• node-edge-tts
• Formaty wyjścia Microsoft Speech
• xAI text to speech

Powiązane

• Omówienie mediów
• Generowanie muzyki
• Generowanie wideo
• Polecenia slash
• Plugin połączeń głosowych