Sintesi vocale

​

Avvio rapido

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

​

Provider supportati

​

Configurazione

{
  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",
          // Prompt di stile facoltativi in linguaggio naturale:
          // audioProfile: "Parla con un tono calmo da conduttore di 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",
        },
      },
    },
  },
}

​

Override vocali per agente

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

1. messages.tts
2. agents.list[].tts attivo
3. override del canale, quando il canale supporta channels.<channel>.tts
4. override dell’account, quando il canale passa channels.<channel>.accounts.<id>.tts
5. preferenze /tts locali per questo host
6. direttive [[tts:...]] inline quando gli override determinati dal modello sono abilitati

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

​

Persone

​

Persona minima

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

​

Persona completa (prompt indipendente dal provider)

{
  messages: {
    tts: {
      auto: "always",
      persona: "alfred",
      personas: {
        alfred: {
          label: "Alfred",
          description: "Narratore maggiordomo britannico, asciutto e cordiale.",
          provider: "google",
          fallbackPolicy: "preserve-persona",
          prompt: {
            profile: "Un brillante maggiordomo britannico. Asciutto, arguto, cordiale, affascinante, emotivamente espressivo, mai generico.",
            scene: "Uno studio silenzioso a tarda notte. Narrazione ravvicinata al microfono per un operatore fidato.",
            sampleContext: "Il parlante risponde a una richiesta tecnica privata con sicurezza concisa e asciutta cordialità.",
            style: "Raffinato, misurato, lievemente divertito.",
            accent: "Inglese britannico.",
            pacing: "Misurato, con brevi pause drammatiche.",
            constraints: ["Non leggere ad alta voce i valori di configurazione.", "Non spiegare la 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,
              },
            },
          },
        },
      },
    },
  },
}

​

Risoluzione della persona

1. Preferenza locale /tts persona <id>, se impostata.
2. messages.tts.persona, se impostata.
3. Nessuna persona.

1. Override diretti (CLI, Gateway, Talk, direttive TTS consentite).
2. Preferenza locale /tts provider <id>.
3. provider della persona attiva.
4. messages.tts.provider.
5. Selezione automatica dal registro.

1. messages.tts.providers.<id>
2. messages.tts.personas.<persona>.providers.<id>
3. Override della richiesta attendibile
4. Override consentiti delle direttive TTS emesse dal modello

​

Come i provider usano i prompt delle persone

​

Criterio di fallback

​

Direttive determinate dal modello

Ecco fatto.

[[tts:speakerVoiceId=pMsXgVXv3BLzUgSXRplE model=eleven_v3 speed=1.1]]
[[tts:text]](ride) Leggi la canzone ancora una volta.[[/tts:text]]

• provider (ID del provider registrato; richiede allowProvider: true)
• speakerVoice / speakerVoiceId (alias precedenti: voice, voiceName, voice_name, google_voice, voiceId)
• model / google_model
• stability, similarityBoost, style, speed, useSpeakerBoost
• vol / volume (volume MiniMax, (0, 10])
• pitch (intonazione MiniMax intera, da −12 a 12; i valori frazionari vengono troncati)
• emotion (tag emotivo Volcengine)
• applyTextNormalization (auto|on|off)
• languageCode (ISO 639-1)
• seed

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

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

​

Comandi slash

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

• /tts on scrive la preferenza TTS locale in always; /tts off la scrive in off.
• /tts chat on|off|default scrive un override TTS automatico limitato alla sessione per la chat corrente.
• /tts persona <id> scrive la preferenza locale della persona; /tts persona off la cancella.
• /tts latest legge l’ultima risposta dell’assistente dalla trascrizione della sessione corrente e la invia una volta come audio. Memorizza solo un hash di tale risposta nella voce della sessione per impedire invii vocali duplicati.
• /tts audio genera una risposta audio una tantum (non attiva o disattiva TTS).
• /tts limit <chars> accetta 100–4096 (4096 è il massimo per didascalie/messaggi di Telegram); i valori al di fuori di questo intervallo vengono rifiutati.
• limit e summary vengono memorizzati nelle preferenze locali, non nella configurazione principale.
• /tts status include la diagnostica di fallback per l’ultimo tentativo: Fallback: <primary> -> <used>, Attempts: ... e i dettagli di ciascun tentativo (provider:outcome(reasonCode) latency).
• /status mostra la modalità TTS attiva insieme al provider, al modello, alla voce e ai metadati sanitizzati dell’endpoint personalizzato configurati quando TTS è abilitato.

​

Preferenze per utente

​

Formati di output

• Transcodifica per Feishu / WhatsApp: quando una risposta con messaggio vocale arriva come MP3/WebM/WAV/M4A o come un altro probabile file audio, il Plugin del canale la transcodifica in Ogg/Opus a 48 kHz con ffmpeg (libopus, 64 kbps) prima di inviare il messaggio vocale nativo. WhatsApp invia il risultato tramite il payload Baileys audio con ptt: true e audio/ogg; codecs=opus. In caso di errore di transcodifica: Feishu intercetta l’errore e ripiega sull’invio del file originale come semplice allegato; WhatsApp non dispone di un ripiego, quindi l’invio stesso non riesce anziché pubblicare un payload PTT incompatibile.
• MiniMax: MP3 (modello speech-2.8-hd, frequenza di campionamento di 32 kHz) per i normali allegati audio; transcodificato in Opus a 48 kHz con ffmpeg per le destinazioni di messaggi vocali indicate dal canale.
• Xiaomi MiMo: MP3 per impostazione predefinita oppure WAV quando configurato; transcodificato in Opus a 48 kHz con ffmpeg per le destinazioni di messaggi vocali indicate dal canale.
• CLI locale: usa il valore outputFormat configurato. Le destinazioni di messaggi vocali vengono convertite in Ogg/Opus e l’output telefonico viene convertito in PCM mono raw a 16 kHz con ffmpeg.
• Google Gemini: restituisce PCM raw a 24 kHz. OpenClaw lo incapsula come WAV per gli allegati audio, lo transcodifica in Opus a 48 kHz per le destinazioni di messaggi vocali e restituisce direttamente PCM per Conversazione/telefonia.
• Gradium: WAV per gli allegati audio, Opus per le destinazioni di messaggi vocali e ulaw_8000 a 8 kHz per la telefonia.
• Inworld: MP3 per i normali allegati audio, OGG_OPUS nativo per le destinazioni di messaggi vocali e PCM raw a 22050 Hz per Conversazione/telefonia.
• xAI: MP3 per impostazione predefinita; la sintesi di file audio può usare mp3, wav, pcm, mulaw o alaw sia per l’output con buffering sia per quello in streaming. Le destinazioni di messaggi vocali usano MP3 per lo streaming e come ripiego con buffering, perché gli output pcm, mulaw e alaw di xAI sono audio raw senza intestazione. La sintesi con buffering usa l’endpoint REST batch /v1/tts di xAI; textToSpeechStream usa wss://api.x.ai/v1/tts nativo. Questo non è il contratto vocale in tempo reale. Il formato vocale Opus nativo non è supportato.
• Microsoft: usa microsoft.outputFormat (valore predefinito: audio-24khz-48kbitrate-mono-mp3).
  • Il trasporto incluso accetta un valore outputFormat, ma il servizio non rende disponibili tutti i formati.
  • I valori del formato di output seguono i formati di output di Microsoft Speech (incluso Ogg/WebM Opus).
  • Il valore sendVoice di Telegram accetta OGG/MP3/M4A; usare OpenAI/ElevenLabs se sono necessari messaggi vocali Opus garantiti.
  • Se il formato di output Microsoft configurato non riesce, OpenClaw riprova con MP3.
  • Quando non è impostato alcun override esplicito della voce e viene usata la voce inglese predefinita, OpenClaw passa automaticamente a una voce neurale cinese (zh-CN-XiaoxiaoNeural, impostazioni locali zh-CN) se il testo della risposta è prevalentemente CJK.

​

Comportamento del TTS automatico

• Ignora la sintesi vocale se la risposta contiene già contenuti multimediali strutturati.
• Ignora le risposte molto brevi (meno di 10 caratteri).
• Riassume le risposte lunghe quando i riepiloghi sono abilitati, utilizzando summaryModel (o agents.defaults.model.primary).
• Allega l’audio generato alla risposta.
• In mode: "final", invia comunque solo l’audio della sintesi vocale per le risposte finali trasmesse in streaming al termine del flusso di testo; i contenuti multimediali generati vengono sottoposti alla stessa normalizzazione dei contenuti multimediali del canale applicata ai normali allegati delle risposte.

• Riepilogo attivo (impostazione predefinita) e disponibilità di un modello di riepilogo: riassume il testo fino a circa maxLength caratteri, quindi sintetizza il riepilogo.
• Riepilogo disattivato, errore del riepilogo o nessuna chiave API disponibile per il modello di riepilogo: tronca il testo a maxLength caratteri e sintetizza il testo troncato.

Risposta -> sintesi vocale abilitata?
  no  -> invia testo
  sì  -> contiene contenuti multimediali / è breve?
          sì -> invia testo
          no  -> lunghezza > limite?
                   no  -> sintesi vocale -> allega audio
                   sì  -> riepilogo abilitato e disponibile?
                            no  -> tronca -> sintesi vocale -> allega audio
                            sì  -> riassumi -> sintesi vocale -> allega audio

​

Riferimento dei campi

​

Strumento dell’agente

​

RPC del Gateway

​

Link ai servizi

• Guida alla sintesi vocale di OpenAI
• Riferimento dell’API Audio di OpenAI
• Sintesi vocale tramite REST di Azure Speech
• Provider Azure Speech
• Sintesi vocale di ElevenLabs
• Autenticazione di ElevenLabs
• Gradium
• API TTS di Inworld
• API MiniMax T2A v2
• API HTTP TTS di Volcengine
• Sintesi vocale Xiaomi MiMo
• node-edge-tts
• Formati di output di Microsoft Speech
• Sintesi vocale di xAI

​

Argomenti correlati

• Panoramica dei contenuti multimediali
• Generazione musicale
• Generazione video
• Comandi slash
• Plugin per chiamate vocali