​

Sintesi vocale (TTS)

​

Servizi supportati

• ElevenLabs (provider primario o di fallback)
• Google Gemini (provider primario o di fallback; usa Gemini API TTS)
• Microsoft (provider primario o di fallback; l’implementazione bundled corrente usa node-edge-tts)
• MiniMax (provider primario o di fallback; usa l’API T2A v2)
• OpenAI (provider primario o di fallback; usato anche per i riepiloghi)

​

Note sulla sintesi vocale Microsoft

​

Chiavi facoltative

• ELEVENLABS_API_KEY (o XI_API_KEY)
• GEMINI_API_KEY (o GOOGLE_API_KEY)
• MINIMAX_API_KEY
• OPENAI_API_KEY

​

Link ai servizi

• Guida OpenAI Text-to-Speech
• Riferimento OpenAI Audio API
• ElevenLabs Text to Speech
• Autenticazione ElevenLabs
• API MiniMax T2A v2
• node-edge-tts
• Formati di output Microsoft Speech

​

È abilitato per impostazione predefinita?

​

Configurazione

​

Configurazione minima (abilitazione + provider)

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

​

OpenAI primario con fallback 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 primario (senza chiave 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 primario

{
  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,
        },
      },
    },
  },
}

​

Google Gemini primario

{
  messages: {
    tts: {
      auto: "always",
      provider: "google",
      providers: {
        google: {
          apiKey: "gemini_api_key",
          model: "gemini-3.1-flash-tts-preview",
          voiceName: "Kore",
        },
      },
    },
  },
}

​

Disattivare la sintesi vocale Microsoft

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

​

Limiti personalizzati + percorso prefs

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

​

Rispondere con audio solo dopo un messaggio vocale in ingresso

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

​

Disattivare il riepilogo automatico per le risposte lunghe

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

/tts summary off

​

Note sui campi

• auto: modalità auto‑TTS (off, always, inbound, tagged).
  • inbound invia audio solo dopo un messaggio vocale in ingresso.
  • tagged invia audio solo quando la risposta include direttive [[tts:key=value]] o un blocco [[tts:text]]...[[/tts:text]].
• enabled: interruttore legacy (doctor lo migra in auto).
• mode: "final" (predefinito) o "all" (include risposte di strumenti/blocchi).
• provider: id del provider vocale, ad esempio "elevenlabs", "google", "microsoft", "minimax" o "openai" (il fallback è automatico).
• Se provider non è impostato, OpenClaw usa il primo provider vocale configurato nell’ordine di selezione automatica del registro.
• Il legacy provider: "edge" continua a funzionare e viene normalizzato in microsoft.
• summaryModel: modello economico facoltativo per il riepilogo automatico; per impostazione predefinita usa agents.defaults.model.primary.
  • Accetta provider/model o un alias di modello configurato.
• modelOverrides: consente al modello di emettere direttive TTS (attivato per impostazione predefinita).
  • allowProvider è false per impostazione predefinita (il cambio di provider è opt-in).
• providers.<id>: impostazioni gestite dal provider, indicizzate per id del provider vocale.
• I blocchi provider legacy diretti (messages.tts.openai, messages.tts.elevenlabs, messages.tts.microsoft, messages.tts.edge) vengono migrati automaticamente in messages.tts.providers.<id> al caricamento.
• maxTextLength: limite rigido per l’input TTS (caratteri). /tts audio fallisce se viene superato.
• timeoutMs: timeout della richiesta (ms).
• prefsPath: sovrascrive il percorso JSON delle preferenze locali (provider/limite/riepilogo).
• I valori apiKey usano come fallback le variabili d’ambiente (ELEVENLABS_API_KEY/XI_API_KEY, GEMINI_API_KEY/GOOGLE_API_KEY, MINIMAX_API_KEY, OPENAI_API_KEY).
• providers.elevenlabs.baseUrl: sovrascrive l’URL base dell’API ElevenLabs.
• providers.openai.baseUrl: sovrascrive l’endpoint OpenAI TTS.
  • Ordine di risoluzione: messages.tts.providers.openai.baseUrl -> OPENAI_TTS_BASE_URL -> https://api.openai.com/v1
  • I valori diversi da quello predefinito vengono trattati come endpoint TTS compatibili con OpenAI, quindi sono accettati nomi personalizzati di modello e voce.
• providers.elevenlabs.voiceSettings:
  • stability, similarityBoost, style: 0..1
  • useSpeakerBoost: true|false
  • speed: 0.5..2.0 (1.0 = normale)
• providers.elevenlabs.applyTextNormalization: auto|on|off
• providers.elevenlabs.languageCode: ISO 639-1 a 2 lettere (ad esempio en, de)
• providers.elevenlabs.seed: intero 0..4294967295 (determinismo best-effort)
• providers.minimax.baseUrl: sovrascrive l’URL base dell’API MiniMax (predefinito https://api.minimax.io, env: MINIMAX_API_HOST).
• providers.minimax.model: modello TTS (predefinito speech-2.8-hd, env: MINIMAX_TTS_MODEL).
• providers.minimax.voiceId: identificatore della voce (predefinito English_expressive_narrator, env: MINIMAX_TTS_VOICE_ID).
• providers.minimax.speed: velocità di riproduzione 0.5..2.0 (predefinita 1.0).
• providers.minimax.vol: volume (0, 10] (predefinito 1.0; deve essere maggiore di 0).
• providers.minimax.pitch: variazione di tonalità -12..12 (predefinita 0).
• providers.google.model: modello Gemini TTS (predefinito gemini-3.1-flash-tts-preview).
• providers.google.voiceName: nome della voce predefinita Gemini (predefinito Kore; è accettato anche voice).
• providers.google.baseUrl: sovrascrive l’URL base della Gemini API. È accettato solo https://generativelanguage.googleapis.com.
  • Se messages.tts.providers.google.apiKey è omesso, TTS può riutilizzare models.providers.google.apiKey prima del fallback alle variabili d’ambiente.
• providers.microsoft.enabled: consente l’uso della sintesi vocale Microsoft (predefinito true; nessuna chiave API).
• providers.microsoft.voice: nome della voce neurale Microsoft (ad esempio en-US-MichelleNeural).
• providers.microsoft.lang: codice lingua (ad esempio en-US).
• providers.microsoft.outputFormat: formato di output Microsoft (ad esempio audio-24khz-48kbitrate-mono-mp3).
  • Consulta i formati di output Microsoft Speech per i valori validi; non tutti i formati sono supportati dal trasporto bundled basato su Edge.
• providers.microsoft.rate / providers.microsoft.pitch / providers.microsoft.volume: stringhe percentuali (ad esempio +10%, -5%).
• providers.microsoft.saveSubtitles: scrive sottotitoli JSON accanto al file audio.
• providers.microsoft.proxy: URL proxy per le richieste Microsoft speech.
• providers.microsoft.timeoutMs: sovrascrittura del timeout della richiesta (ms).
• edge.*: alias legacy per le stesse impostazioni Microsoft.

​

Override guidati dal modello (attivi per impostazione predefinita)

Ecco qui.

[[tts:voiceId=pMsXgVXv3BLzUgSXRplE model=eleven_v3 speed=1.1]]
[[tts:text]](ride) Leggi di nuovo la canzone.[[/tts:text]]

• provider (id del provider vocale registrato, per esempio openai, elevenlabs, google, minimax o microsoft; richiede allowProvider: true)
• voice (voce OpenAI), voiceName / voice_name / google_voice (voce Google), o voiceId (ElevenLabs / MiniMax)
• model (modello OpenAI TTS, id del modello ElevenLabs o modello MiniMax) oppure google_model (modello Google TTS)
• stability, similarityBoost, style, speed, useSpeakerBoost
• vol / volume (volume MiniMax, 0-10)
• pitch (tonalità MiniMax, da -12 a 12)
• applyTextNormalization (auto|on|off)
• languageCode (ISO 639-1)
• seed

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

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

​

Preferenze per utente

• enabled
• provider
• maxLength (soglia del riepilogo; predefinita 1500 caratteri)
• summarize (predefinito true)

​

Formati di output (fissi)

• Feishu / Matrix / Telegram / WhatsApp: messaggio vocale Opus (opus_48000_64 da ElevenLabs, opus da OpenAI).
  • 48kHz / 64kbps è un buon compromesso per i messaggi vocali.
• Altri canali: MP3 (mp3_44100_128 da ElevenLabs, mp3 da OpenAI).
  • 44.1kHz / 128kbps è il bilanciamento predefinito per la chiarezza del parlato.
• MiniMax: MP3 (modello speech-2.8-hd, frequenza di campionamento 32kHz). Il formato nota vocale non è supportato nativamente; usa OpenAI o ElevenLabs per messaggi vocali Opus garantiti.
• Google Gemini: Gemini API TTS restituisce PCM grezzo a 24kHz. OpenClaw lo incapsula come WAV per gli allegati audio e restituisce PCM direttamente per Talk/telefonia. Il formato nota vocale Opus nativo non è supportato da questo percorso.
• Microsoft: usa microsoft.outputFormat (predefinito audio-24khz-48kbitrate-mono-mp3).
  • Il trasporto bundled accetta un outputFormat, ma non tutti i formati sono disponibili dal servizio.
  • I valori del formato di output seguono i formati di output Microsoft Speech (inclusi Ogg/WebM Opus).
  • Telegram sendVoice accetta OGG/MP3/M4A; usa OpenAI/ElevenLabs se ti servono messaggi vocali Opus garantiti.
  • Se il formato di output Microsoft configurato fallisce, OpenClaw riprova con MP3.

​

Comportamento auto-TTS

• salta il TTS se la risposta contiene già contenuti multimediali o una direttiva MEDIA:.
• salta le risposte molto brevi (< 10 caratteri).
• riepiloga le risposte lunghe quando abilitato usando agents.defaults.model.primary (o summaryModel).
• allega l’audio generato alla risposta.

​

Diagramma di flusso

Risposta -> TTS abilitato?
  no  -> invia testo
  sì -> contiene media / MEDIA: / è breve?
          sì -> invia testo
          no  -> lunghezza > limite?
                   no  -> TTS -> allega audio
                   sì -> riepilogo abilitato?
                            no  -> invia testo
                            sì -> riepiloga (`summaryModel` o `agents.defaults.model.primary`)
                                      -> TTS -> allega audio

​

Utilizzo del comando slash

/tts off
/tts on
/tts status
/tts provider openai
/tts limit 2000
/tts summary off
/tts audio Hello from OpenClaw

• I comandi richiedono un mittente autorizzato (continuano ad applicarsi le regole di allowlist/proprietario).
• commands.text o la registrazione dei comandi nativi devono essere abilitati.
• La configurazione messages.tts.auto accetta off|always|inbound|tagged.
• /tts on scrive la preferenza TTS locale su always; /tts off la scrive su off.
• Usa la configurazione quando vuoi impostazioni predefinite inbound o tagged.
• limit e summary vengono memorizzati nelle preferenze locali, non nella configurazione principale.
• /tts audio genera una risposta audio una tantum (non attiva il TTS).
• /tts status include la visibilità del fallback per l’ultimo tentativo:
  • fallback riuscito: Fallback: <primary> -> <used> più Attempts: ...
  • errore: Error: ... più Attempts: ...
  • diagnostica dettagliata: Attempt details: provider:outcome(reasonCode) latency
• Gli errori API di OpenAI ed ElevenLabs ora includono i dettagli dell’errore del provider analizzati e l’id richiesta (quando restituito dal provider), che viene mostrato negli errori/log TTS.

​

Strumento dell’agente

​

RPC Gateway

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