Synteza mowy

OpenClaw przekształca odpowiedzi wychodzące w dźwięk za pomocą 14 dostawców syntezy mowy: natywnych wiadomości głosowych w Feishu, Matrix, Telegram i WhatsApp; załączników audio we wszystkich pozostałych usługach; oraz strumieni PCM/Ulaw dla telefonii i Talk.

TTS stanowi część Talk odpowiedzialną za generowanie mowy w trybie stt-tts (talk.speak korzysta z tej samej ścieżki syntezy). Sesje Talk realtime obsługiwane natywnie przez dostawcę syntetyzują mowę wewnątrz dostawcy czasu rzeczywistego; sesje transcription nigdy nie syntetyzują głosowej odpowiedzi asystenta.

Szybki start

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

Obsługiwani dostawcy

Jeśli skonfigurowano wielu dostawców, najpierw używany jest wybrany dostawca, a pozostali służą jako opcje awaryjne. Automatyczne podsumowania używają summaryModel (lub agents.defaults.model.primary), dlatego ten dostawca również musi być uwierzytelniony, jeśli podsumowania pozostają włączone.

Konfiguracja

Konfiguracja TTS znajduje się w sekcji messages.tts w pliku ~/.openclaw/openclaw.json. Wybierz ustawienie wstępne i dostosuj blok dostawcy. Pokazane poniżej pola speakerVoice/speakerVoiceId są kanoniczne; własne nazwy pól voice/voiceId/ voiceName każdego dostawcy nadal działają jako starsze aliasy.

{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",      // Opcjonalne monity stylu w języku naturalnym:      // audioProfile: "Mów spokojnym tonem prowadzącego podcast.",      // 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",    },  },},},}

W przypadku Xiaomi mimo-v2.5-tts-voicedesign pomiń speakerVoice i ustaw style na monit projektowania głosu. OpenClaw wysyła ten monit jako wiadomość TTS user i nie wysyła audio.voice dla modelu voicedesign.

Ustawienia głosu dla poszczególnych agentów

Użyj agents.list[].tts, gdy jeden agent ma korzystać z innego dostawcy, głosu, modelu, persony lub trybu automatycznego TTS. Blok agenta jest głęboko scalany z messages.tts, dzięki czemu dane uwierzytelniające 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: { speakerVoiceId: "EXAVITQu4vr4xnSDxMaL" },          },        },      },    ],  },}

Aby przypisać personę do 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. ustawienie kanału, gdy kanał obsługuje channels.<channel>.tts
4. ustawienie konta, gdy kanał przekazuje channels.<channel>.accounts.<id>.tts
5. lokalne preferencje /tts dla tego hosta
6. dyrektywy śródwierszowe [[tts:...]], gdy włączone są dyrektywy sterowane przez model

Ustawienia kanału i konta mają ten sam kształt co messages.tts i są głęboko scalane z wcześniejszymi warstwami, dzięki czemu współdzielone dane uwierzytelniające dostawcy mogą pozostać w messages.tts, podczas gdy kanał lub konto bota zmienia tylko głos mówcy, model, personę lub tryb automatyczny:

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

Persony

Persona to stabilna tożsamość głosowa, którą można deterministycznie stosować u różnych dostawców. Może preferować jednego dostawcę, definiować niezależną od dostawcy intencję promptu oraz zawierać powiązania specyficzne dla dostawcy dotyczące 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: {              speakerVoiceId: "EXAVITQu4vr4xnSDxMaL",              modelId: "eleven_multilingual_v2",            },          },        },      },    },  },}

Pełna persona (prompt niezależny od dostawcy)

{  messages: {    tts: {      auto: "always",      persona: "alfred",      personas: {        alfred: {          label: "Alfred",          description: "Powściągliwy, serdeczny brytyjski kamerdyner-narrator.",          provider: "google",          fallbackPolicy: "preserve-persona",          prompt: {            profile: "Błyskotliwy brytyjski kamerdyner. Powściągliwy, dowcipny, serdeczny, czarujący, emocjonalnie ekspresyjny, nigdy bezbarwny.",            scene: "Cichy gabinet późną nocą. Narracja z bliska dla zaufanego operatora.",            sampleContext: "Mówca odpowiada na prywatną prośbę techniczną ze zwięzłą pewnością siebie i subtelnym ciepłem.",            style: "Wyrafinowany, dyskretny, lekko rozbawiony.",            accent: "Brytyjski angielski.",            pacing: "Miarkowane tempo z krótkimi dramatycznymi pauzami.",            constraints: ["Nie odczytuj na głos wartości konfiguracyjnych.", "Nie wyjaśniaj persony."],          },          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,              },            },          },        },      },    },  },}

Rozpoznawanie persony

Aktywna persona jest wybierana deterministycznie:

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

Wybór dostawcy rozpoczyna się od ustawień jawnych:

1. Bezpośrednie ustawienia (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.

Przy każdej próbie użycia dostawcy OpenClaw scala konfiguracje w następującej kolejności:

1. messages.tts.providers.<id>
2. messages.tts.personas.<persona>.providers.<id>
3. Zaufane ustawienia żądania
4. Dozwolone ustawienia z dyrektywy TTS wyemitowanej przez model

Jak dostawcy używają promptów persony

Pola promptu persony (profile, scene, sampleContext, style, accent, pacing, constraints) są niezależne od dostawcy. Każdy dostawca decyduje, jak ich używać:

Zasady mechanizmu rezerwowego

fallbackPolicy steruje zachowaniem, gdy persona nie ma powiązania z wypróbowywanym dostawcą:

Całe żądanie TTS kończy się niepowodzeniem tylko wtedy, gdy każdy wypróbowywany dostawca został pominięty lub zawiódł.

Wybór dostawcy sesji Talk ma zakres sesji. Klient Talk powinien wybierać identyfikatory dostawców, modeli, głosów i ustawienia regionalne z talk.catalog oraz przekazywać je za pośrednictwem żądania sesji Talk lub przekazania. Otwarcie sesji głosowej nie powinno modyfikować messages.tts ani globalnych domyślnych ustawień dostawcy Talk.

Dyrektywy sterowane przez model

Domyślnie asystent może emitować dyrektywy [[tts:...]], aby zastąpić głos, model lub szybkość dla pojedynczej odpowiedzi, wraz z opcjonalnym blokiem [[tts:text]]...[[/tts:text]] na ekspresyjne wskazówki, które powinny występować wyłącznie w dźwięku:

Proszę. [[tts:speakerVoiceId=pMsXgVXv3BLzUgSXRplE model=eleven_v3 speed=1.1]][[tts:text]](śmieje się) Przeczytaj piosenkę jeszcze raz.[[/tts:text]]

Gdy messages.tts.auto ma wartość "tagged", dyrektywy są wymagane do uruchomienia dźwięku. Strumieniowe dostarczanie bloków usuwa dyrektywy z widocznego tekstu, zanim kanał je zobaczy, nawet gdy są podzielone między sąsiednie bloki.

provider=... jest ignorowane, chyba że modelOverrides.allowProvider: true. Gdy odpowiedź deklaruje provider=..., pozostałe klucze w tej dyrektywie są analizowane wyłącznie 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)
• speakerVoice / speakerVoiceId (starsze aliasy: 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łkowita wysokość dźwięku MiniMax, od −12 do 12; wartości ułamkowe są obcinane)
• emotion (znacznik emocji Volcengine)
• applyTextNormalization (auto|on|off)
• languageCode (ISO 639-1)
• seed

Całkowite wyłączenie ustawień modelu:

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

Zezwolenie na przełączanie dostawców przy zachowaniu możliwości konfiguracji pozostałych parametrów:

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

Polecenia ukośnikowe

Pojedyncze polecenie /tts. W Discord OpenClaw rejestruje również /voice, ponieważ /tts jest wbudowanym poleceniem Discord — 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 w always; /tts off zapisuje ją w off.
• /tts chat on|off|default zapisuje ustawienie automatycznego TTS o zakresie sesji dla bieżącego czatu.
• /tts persona <id> zapisuje lokalną preferencję persony; /tts persona off ją usuwa.
• /tts latest odczytuje najnowszą odpowiedź asystenta z transkrypcji bieżącej sesji i jednorazowo wysyła ją jako dźwięk. Wpis sesji przechowuje wyłącznie skrót tej odpowiedzi, aby zapobiec wysyłaniu zduplikowanych wiadomości głosowych.
• /tts audio generuje jednorazową odpowiedź dźwiękową (nie włącza TTS).
• /tts limit <chars> akceptuje wartości 100–4096 (4096 to maksymalna długość podpisu/wiadomości Telegram); wartości spoza tego zakresu są odrzucane.
• limit i summary są przechowywane w lokalnych preferencjach, a nie w głównej konfiguracji.
• /tts status zawiera diagnostykę mechanizmu rezerwowego dla ostatniej próby — Fallback: <primary> -> <used>, Attempts: ... oraz szczegóły poszczególnych prób (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 ustawienia w prefsPath. Wartością domyślną jest ~/.openclaw/settings/tts.json; można ją zastąpić zmienną środowiskową OPENCLAW_TTS_PREFS lub messages.tts.prefsPath.

Te ustawienia zastępują efektywną konfigurację z messages.tts oraz aktywnego bloku agents.list[].tts dla tego hosta.

Formaty wyjściowe

Dostarczanie głosu TTS zależy od możliwości kanału. Pluginy kanałów deklarują, czy TTS w stylu wiadomości głosowej powinien zażądać od dostawców natywnego celu voice-note, czy zachować standardową syntezę audio-file, a także czy kanał transkoduje nienatywny format wyjściowy przed wysłaniem.

Uwagi dotyczące poszczególnych dostawców:

• Transkodowanie w Feishu / WhatsApp: gdy odpowiedź w formie wiadomości głosowej ma format MP3/WebM/WAV/M4A lub inny prawdopodobny format pliku audio, Plugin kanału przed wysłaniem natywnej wiadomości głosowej transkoduje ją do formatu Ogg/Opus 48 kHz za pomocą ffmpeg (libopus, 64 kbps). WhatsApp wysyła wynik poprzez ładunek Baileys audio z ptt: true i audio/ogg; codecs=opus. W przypadku niepowodzenia transkodowania: Feishu przechwytuje błąd i wysyła oryginalny plik jako zwykły załącznik; WhatsApp nie ma mechanizmu rezerwowego, więc samo wysyłanie kończy się niepowodzeniem zamiast opublikowania niezgodnego ładunku PTT.
• MiniMax: MP3 (model speech-2.8-hd, częstotliwość próbkowania 32 kHz) dla zwykłych załączników audio; transkodowany do Opus 48 kHz za pomocą ffmpeg dla celów wiadomości głosowych deklarowanych przez kanał.
• Xiaomi MiMo: domyślnie MP3 lub WAV, jeśli tak skonfigurowano; transkodowany do Opus 48 kHz za pomocą ffmpeg dla celów wiadomości głosowych deklarowanych przez kanał.
• Lokalny CLI: używa skonfigurowanego outputFormat. Cele wiadomości głosowych są konwertowane do Ogg/Opus, a format wyjściowy dla telefonii jest konwertowany do surowego, monofonicznego PCM 16 kHz za pomocą ffmpeg.
• Google Gemini: zwraca surowy PCM 24 kHz. OpenClaw opakowuje go jako WAV dla załączników audio, transkoduje do Opus 48 kHz 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, natywny OGG_OPUS dla celów wiadomości głosowych oraz surowy PCM przy 22050 Hz dla Talk/telefonii.
• xAI: domyślnie MP3; synteza plików audio może używać mp3, wav, pcm, mulaw lub alaw zarówno dla buforowanego, jak i strumieniowego formatu wyjściowego. Cele wiadomości głosowych używają MP3 w trybie strumieniowym oraz jako buforowanego rozwiązania rezerwowego, ponieważ formaty wyjściowe xAI pcm, mulaw i alaw są surowymi danymi audio bez nagłówków. Synteza buforowana używa punktu końcowego wsadowego interfejsu REST xAI /v1/tts; textToSpeechStream używa natywnego wss://api.x.ai/v1/tts. Nie jest to kontrakt głosowy czasu rzeczywistego. Natywny format wiadomości głosowych Opus nie jest obsługiwany.
• Microsoft: używa microsoft.outputFormat (domyślnie audio-24khz-48kbitrate-mono-mp3).
  • Dołączony 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; należy użyć OpenAI/ElevenLabs, jeśli wymagane są wiadomości głosowe w gwarantowanym formacie Opus.
  • Jeśli skonfigurowany format wyjściowy Microsoft zawiedzie, OpenClaw ponawia próbę z użyciem MP3.
  • Jeśli nie ustawiono jawnego nadpisania głosu i używany jest domyślny głos angielski, OpenClaw automatycznie przełącza się na chiński głos neuronowy (zh-CN-XiaoxiaoNeural, ustawienia regionalne zh-CN), gdy tekst odpowiedzi zawiera głównie znaki CJK.

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

Działanie automatycznego TTS

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

• Pomija TTS, jeśli odpowiedź zawiera już ustrukturyzowane multimedia.
• Pomija bardzo krótkie odpowiedzi (poniżej 10 znaków).
• Podsumowuje długie odpowiedzi, gdy podsumowania są włączone, używając summaryModel (lub agents.defaults.model.primary).
• Dołącza wygenerowany dźwięk do odpowiedzi.
• W trybie mode: "final" nadal wysyła wyłącznie dźwięk TTS dla strumieniowanych odpowiedzi końcowych po zakończeniu strumienia tekstowego; wygenerowane multimedia przechodzą tę samą normalizację multimediów kanału co zwykłe załączniki odpowiedzi.

Jeśli odpowiedź przekracza maxLength, OpenClaw nigdy nie pomija całkowicie dźwięku:

• Podsumowanie włączone (domyślnie) i dostępny jest model podsumowujący: podsumowuje tekst do około maxLength znaków, a następnie syntetyzuje podsumowanie.
• Podsumowanie wyłączone, podsumowanie kończy się niepowodzeniem lub nie jest dostępny klucz API dla modelu podsumowującego: skraca tekst do maxLength znaków i syntetyzuje skrócony tekst.

Odpowiedź -> TTS włączone?  nie -> wyślij tekst  tak -> zawiera multimedia / jest krótka?          tak -> wyślij tekst          nie -> długość > limit?                   nie -> TTS -> dołącz dźwięk                   tak -> podsumowanie włączone i dostępne?                            nie -> skróć -> TTS -> dołącz dźwięk                            tak -> podsumuj -> TTS -> dołącz dźwięk

Dokumentacja pól

Narzędzie agenta

Narzędzie tts konwertuje tekst na mowę i zwraca załącznik audio do dostarczenia odpowiedzi. W Feishu, Matrix, Telegram i WhatsApp dźwięk jest dostarczany jako wiadomość głosowa zamiast załącznika plikowego. Feishu i WhatsApp mogą transkodować na tej ścieżce dane wyjściowe TTS inne niż Opus, gdy dostępne jest ffmpeg.

WhatsApp wysyła dźwięk przez Baileys jako notatkę głosową PTT (audio z ptt: true) i wysyła widoczny tekst oddzielnie od dźwięku PTT, ponieważ klienty nie zawsze wyświetlają podpisy notatek głosowych.

Narzędzie akceptuje opcjonalne pola channel i timeoutMs; timeoutMs to limit czasu żądania dostawcy dla pojedynczego wywołania, podany w milisekundach. Wartości dla poszczególnych wywołań nadpisują messages.tts.timeoutMs; skonfigurowane limity czasu TTS nadpisują każdą wartość domyślną dostawcy określoną przez plugin.

RPC Gateway

Łącza do usług

• Przewodnik OpenAI dotyczący zamiany tekstu na mowę
• Dokumentacja referencyjna OpenAI Audio API
• Zamiana tekstu na mowę za pomocą interfejsu REST usługi Azure Speech
• Dostawca Azure Speech
• Zamiana tekstu na mowę w ElevenLabs
• Uwierzytelnianie w ElevenLabs
• Gradium
• Interfejs Inworld TTS API
• Interfejs MiniMax T2A v2 API
• Interfejs HTTP API syntezy mowy Volcengine
• Synteza mowy Xiaomi MiMo
• node-edge-tts
• Formaty wyjściowe mowy firmy Microsoft
• Zamiana tekstu na mowę w xAI

Powiązane

• Omówienie multimediów
• Generowanie muzyki
• Generowanie wideo
• Polecenia z ukośnikiem
• Plugin połączeń głosowych