​

Text-to-speech (TTS)

​

Obsługiwane usługi

• ElevenLabs (dostawca główny lub fallback)
• Microsoft (dostawca główny lub fallback; obecna dołączona implementacja używa node-edge-tts)
• MiniMax (dostawca główny lub fallback; używa API T2A v2)
• OpenAI (dostawca główny lub fallback; używany również do podsumowań)

​

Uwagi dotyczące mowy Microsoft

​

Opcjonalne klucze

• ELEVENLABS_API_KEY (lub XI_API_KEY)
• MINIMAX_API_KEY
• OPENAI_API_KEY

​

Linki do usług

• Przewodnik OpenAI Text-to-Speech
• Odniesienie do OpenAI Audio API
• ElevenLabs Text to Speech
• Uwierzytelnianie ElevenLabs
• MiniMax T2A v2 API
• node-edge-tts
• Formaty wyjściowe Microsoft Speech

​

Czy jest włączone domyślnie?

​

Konfiguracja

​

Minimalna konfiguracja (włączenie + dostawca)

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

​

OpenAI jako główny z fallback do ElevenLabs

{
  messages: {
    tts: {
      auto: "always",
      provider: "openai",
      summaryModel: "openai/gpt-4.1-mini",
      modelOverrides: {
        enabled: true,
      },
      providers: {
        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,
          },
        },
      },
    },
  },
}

​

Microsoft jako główny (bez klucza API)

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

​

MiniMax jako główny

{
  messages: {
    tts: {
      auto: "always",
      provider: "minimax",
      providers: {
        minimax: {
          apiKey: "minimax_api_key",
          baseUrl: "https://api.minimax.io",
          model: "speech-2.8-hd",
          voiceId: "English_expressive_narrator",
          speed: 1.0,
          vol: 1.0,
          pitch: 0,
        },
      },
    },
  },
}

​

Wyłączenie mowy Microsoft

{
  messages: {
    tts: {
      providers: {
        microsoft: {
          enabled: false,
        },
      },
    },
  },
}

​

Niestandardowe limity + ścieżka prefs

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

​

Odpowiadaj audio tylko po przychodzącej wiadomości głosowej

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

​

Wyłączenie auto-podsumowania dla długich odpowiedzi

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

/tts summary off

​

Uwagi dotyczące pól

• auto: tryb auto‑TTS (off, always, inbound, tagged).
  • inbound wysyła audio tylko po przychodzącej wiadomości głosowej.
  • tagged wysyła audio tylko wtedy, gdy odpowiedź zawiera tagi [[tts]].
• enabled: starszy przełącznik (doctor migruje go do auto).
• mode: "final" (domyślnie) lub "all" (obejmuje odpowiedzi narzędzi/bloków).
• provider: identyfikator dostawcy mowy, taki jak "elevenlabs", "microsoft", "minimax" lub "openai" (fallback jest automatyczny).
• Jeśli provider nie jest ustawiony, OpenClaw używa pierwszego skonfigurowanego dostawcy mowy w kolejności automatycznego wyboru rejestru.
• Starsze provider: "edge" nadal działa i jest normalizowane do microsoft.
• summaryModel: opcjonalny tani model do auto-podsumowania; domyślnie agents.defaults.model.primary.
  • Akceptuje provider/model albo skonfigurowany alias modelu.
• modelOverrides: pozwala modelowi emitować dyrektywy TTS (domyślnie włączone).
  • allowProvider domyślnie ma wartość false (przełączanie dostawcy jest opt-in).
• providers.<id>: ustawienia należące do dostawcy, z kluczami według identyfikatora dostawcy mowy.
• Starsze bezpośrednie bloki dostawców (messages.tts.openai, messages.tts.elevenlabs, messages.tts.microsoft, messages.tts.edge) są automatycznie migrowane podczas ładowania do messages.tts.providers.<id>.
• maxTextLength: twardy limit wejścia TTS (znaki). /tts audio kończy się błędem po jego przekroczeniu.
• timeoutMs: limit czasu żądania (ms).
• prefsPath: nadpisuje lokalną ścieżkę JSON preferencji (dostawca/limit/podsumowanie).
• Wartości apiKey wracają do zmiennych środowiskowych (ELEVENLABS_API_KEY/XI_API_KEY, MINIMAX_API_KEY, OPENAI_API_KEY).
• providers.elevenlabs.baseUrl: nadpisuje bazowy URL API ElevenLabs.
• providers.openai.baseUrl: nadpisuje punkt końcowy OpenAI TTS.
  • Kolejność rozstrzygania: messages.tts.providers.openai.baseUrl -> OPENAI_TTS_BASE_URL -> https://api.openai.com/v1
  • Wartości inne niż domyślne są traktowane jako punkty końcowe TTS zgodne z OpenAI, więc akceptowane są niestandardowe nazwy modeli i głosów.
• providers.elevenlabs.voiceSettings:
  • stability, similarityBoost, style: 0..1
  • useSpeakerBoost: true|false
  • speed: 0.5..2.0 (1.0 = normalnie)
• providers.elevenlabs.applyTextNormalization: auto|on|off
• providers.elevenlabs.languageCode: 2-literowy ISO 639-1 (np. en, de)
• providers.elevenlabs.seed: liczba całkowita 0..4294967295 (deterministyczność best-effort)
• providers.minimax.baseUrl: nadpisuje bazowy URL API MiniMax (domyślnie https://api.minimax.io, env: MINIMAX_API_HOST).
• providers.minimax.model: model TTS (domyślnie speech-2.8-hd, env: MINIMAX_TTS_MODEL).
• providers.minimax.voiceId: identyfikator głosu (domyślnie English_expressive_narrator, env: MINIMAX_TTS_VOICE_ID).
• providers.minimax.speed: prędkość odtwarzania 0.5..2.0 (domyślnie 1.0).
• providers.minimax.vol: głośność (0, 10] (domyślnie 1.0; musi być większa niż 0).
• providers.minimax.pitch: przesunięcie wysokości tonu -12..12 (domyślnie 0).
• providers.microsoft.enabled: zezwala na użycie mowy Microsoft (domyślnie true; bez klucza API).
• providers.microsoft.voice: nazwa głosu neuronowego Microsoft (np. en-US-MichelleNeural).
• providers.microsoft.lang: kod języka (np. en-US).
• providers.microsoft.outputFormat: format wyjściowy Microsoft (np. audio-24khz-48kbitrate-mono-mp3).
  • Prawidłowe wartości znajdziesz w formatach wyjściowych Microsoft Speech; nie wszystkie formaty są obsługiwane przez dołączony transport oparty na Edge.
• providers.microsoft.rate / providers.microsoft.pitch / providers.microsoft.volume: ciągi procentowe (np. +10%, -5%).
• providers.microsoft.saveSubtitles: zapisuje napisy JSON obok pliku audio.
• providers.microsoft.proxy: URL proxy dla żądań Microsoft speech.
• providers.microsoft.timeoutMs: nadpisanie limitu czasu żądania (ms).
• edge.*: starszy alias dla tych samych ustawień Microsoft.

​

Nadpisania sterowane modelem (domyślnie włączone)

Here you go.

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

• provider (zarejestrowany identyfikator dostawcy mowy, np. openai, elevenlabs, minimax lub microsoft; wymaga allowProvider: true)
• voice (głos OpenAI) lub voiceId (ElevenLabs / MiniMax)
• model (model OpenAI TTS, identyfikator modelu ElevenLabs lub model MiniMax)
• stability, similarityBoost, style, speed, useSpeakerBoost
• vol / volume (głośność MiniMax, 0-10)
• pitch (wysokość tonu MiniMax, -12 do 12)
• applyTextNormalization (auto|on|off)
• languageCode (ISO 639-1)
• seed

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

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

​

Preferencje per użytkownik

• enabled
• provider
• maxLength (próg podsumowania; domyślnie 1500 znaków)
• summarize (domyślnie true)

​

Formaty wyjściowe (stałe)

• Feishu / Matrix / Telegram / WhatsApp: wiadomość głosowa Opus (opus_48000_64 z ElevenLabs, opus z OpenAI).
  • 48 kHz / 64 kb/s to dobry kompromis dla wiadomości głosowych.
• Inne kanały: MP3 (mp3_44100_128 z ElevenLabs, mp3 z OpenAI).
  • 44,1 kHz / 128 kb/s to domyślny balans dla czytelności mowy.
• MiniMax: MP3 (model speech-2.8-hd, częstotliwość próbkowania 32 kHz). Format notatki głosowej nie jest obsługiwany natywnie; użyj OpenAI lub ElevenLabs, jeśli potrzebujesz gwarantowanych wiadomości głosowych Opus.
• 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 są zgodne z formatami wyjściowymi 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 się nie powiedzie, OpenClaw ponawia próbę z MP3.

​

Zachowanie auto-TTS

• pomija TTS, jeśli odpowiedź już zawiera media lub dyrektywę MEDIA:.
• pomija bardzo krótkie odpowiedzi (< 10 znaków).
• podsumowuje długie odpowiedzi, gdy ta opcja jest włączona, przy użyciu agents.defaults.model.primary (lub summaryModel).
• dołącza wygenerowane audio do odpowiedzi.

​

Schemat przepływu

Reply -> TTS enabled?
  no  -> wyślij tekst
  yes -> zawiera media / MEDIA: / jest krótka?
          yes -> wyślij tekst
          no  -> długość > limit?
                   no  -> TTS -> dołącz audio
                   yes -> summary enabled?
                            no  -> wyślij tekst
                            yes -> podsumuj (summaryModel lub agents.defaults.model.primary)
                                      -> TTS -> dołącz audio

​

Użycie poleceń slash

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

• Polecenia wymagają autoryzowanego nadawcy (nadal obowiązują zasady allowlist/owner).
• commands.text lub rejestracja natywnych poleceń musi być włączona.
• off|always|inbound|tagged to przełączniki per sesja (/tts on to alias dla /tts always).
• limit i summary są zapisywane w lokalnych preferencjach, a nie w głównej konfiguracji.
• /tts audio generuje jednorazową odpowiedź audio (nie przełącza TTS na włączone).
• /tts status zawiera widoczność fallback dla ostatniej próby:
  • fallback zakończony sukcesem: Fallback: <primary> -> <used> plus Attempts: ...
  • błąd: Error: ... plus Attempts: ...
  • szczegółowa diagnostyka: Attempt details: provider:outcome(reasonCode) latency
• Błędy API OpenAI i ElevenLabs zawierają teraz sparsowane szczegóły błędu dostawcy oraz identyfikator żądania (jeśli został zwrócony przez dostawcę), który jest ujawniany w błędach/logach TTS.

​

Narzędzie agenta

​

Gateway RPC

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