​

Synthèse vocale (TTS)

​

Services pris en charge

• ElevenLabs (fournisseur principal ou de secours)
• Google Gemini (fournisseur principal ou de secours ; utilise la synthèse vocale TTS de l’API Gemini)
• Microsoft (fournisseur principal ou de secours ; l’implémentation groupée actuelle utilise node-edge-tts)
• MiniMax (fournisseur principal ou de secours ; utilise l’API T2A v2)
• OpenAI (fournisseur principal ou de secours ; également utilisé pour les résumés)

​

Remarques sur la synthèse vocale Microsoft

​

Clés facultatives

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

​

Liens des services

• Guide OpenAI Text-to-Speech
• Référence de l’API Audio OpenAI
• ElevenLabs Text to Speech
• Authentification ElevenLabs
• API MiniMax T2A v2
• node-edge-tts
• Formats de sortie Microsoft Speech

​

Est-ce activé par défaut ?

​

Configuration

​

Configuration minimale (activation + fournisseur)

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

​

OpenAI principal avec ElevenLabs en secours

{
  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 principal (sans clé 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 principal

{
  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 principal

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

​

Désactiver la synthèse vocale Microsoft

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

​

Limites personnalisées + chemin des préférences

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

​

Répondre uniquement avec de l’audio après un message vocal entrant

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

​

Désactiver le résumé automatique pour les réponses longues

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

/tts summary off

​

Remarques sur les champs

• auto : mode auto‑TTS (off, always, inbound, tagged).
  • inbound envoie de l’audio uniquement après un message vocal entrant.
  • tagged envoie de l’audio uniquement lorsque la réponse inclut des directives [[tts:key=value]] ou un bloc [[tts:text]]...[[/tts:text]].
• enabled : bascule héritée (doctor la migre vers auto).
• mode : "final" (par défaut) ou "all" (inclut les réponses d’outil/de bloc).
• provider : identifiant du fournisseur vocal tel que "elevenlabs", "google", "microsoft", "minimax" ou "openai" (le secours est automatique).
• Si provider n’est pas défini, OpenClaw utilise le premier fournisseur vocal configuré selon l’ordre de sélection automatique du registre.
• L’ancien provider: "edge" fonctionne toujours et est normalisé en microsoft.
• summaryModel : modèle économique facultatif pour le résumé automatique ; par défaut agents.defaults.model.primary.
  • Accepte provider/model ou un alias de modèle configuré.
• modelOverrides : permet au modèle d’émettre des directives TTS (activé par défaut).
  • allowProvider vaut false par défaut (le changement de fournisseur est opt-in).
• providers.<id> : paramètres propres au fournisseur, indexés par identifiant de fournisseur vocal.
• Les anciens blocs de fournisseur directs (messages.tts.openai, messages.tts.elevenlabs, messages.tts.microsoft, messages.tts.edge) sont migrés automatiquement vers messages.tts.providers.<id> au chargement.
• maxTextLength : limite stricte pour l’entrée TTS (caractères). /tts audio échoue si elle est dépassée.
• timeoutMs : délai d’expiration de la requête (ms).
• prefsPath : remplace le chemin JSON local des préférences (fournisseur/limite/résumé).
• Les valeurs apiKey se replient sur les variables d’environnement (ELEVENLABS_API_KEY/XI_API_KEY, GEMINI_API_KEY/GOOGLE_API_KEY, MINIMAX_API_KEY, OPENAI_API_KEY).
• providers.elevenlabs.baseUrl : remplace l’URL de base de l’API ElevenLabs.
• providers.openai.baseUrl : remplace le point de terminaison TTS OpenAI.
  • Ordre de résolution : messages.tts.providers.openai.baseUrl -> OPENAI_TTS_BASE_URL -> https://api.openai.com/v1
  • Les valeurs non par défaut sont traitées comme des points de terminaison TTS compatibles OpenAI, donc les noms de modèle et de voix personnalisés sont acceptés.
• providers.elevenlabs.voiceSettings :
  • stability, similarityBoost, style : 0..1
  • useSpeakerBoost : true|false
  • speed : 0.5..2.0 (1.0 = normal)
• providers.elevenlabs.applyTextNormalization : auto|on|off
• providers.elevenlabs.languageCode : ISO 639-1 à 2 lettres (par ex. en, de)
• providers.elevenlabs.seed : entier 0..4294967295 (déterminisme au mieux)
• providers.minimax.baseUrl : remplace l’URL de base de l’API MiniMax (par défaut https://api.minimax.io, env : MINIMAX_API_HOST).
• providers.minimax.model : modèle TTS (par défaut speech-2.8-hd, env : MINIMAX_TTS_MODEL).
• providers.minimax.voiceId : identifiant de voix (par défaut English_expressive_narrator, env : MINIMAX_TTS_VOICE_ID).
• providers.minimax.speed : vitesse de lecture 0.5..2.0 (par défaut 1.0).
• providers.minimax.vol : volume (0, 10] (par défaut 1.0 ; doit être supérieur à 0).
• providers.minimax.pitch : décalage de hauteur -12..12 (par défaut 0).
• providers.google.model : modèle TTS Gemini (par défaut gemini-3.1-flash-tts-preview).
• providers.google.voiceName : nom de voix préconstruit Gemini (par défaut Kore ; voice est également accepté).
• providers.google.baseUrl : remplace l’URL de base de l’API Gemini. Seul https://generativelanguage.googleapis.com est accepté.
  • Si messages.tts.providers.google.apiKey est omis, TTS peut réutiliser models.providers.google.apiKey avant le repli sur l’environnement.
• providers.microsoft.enabled : autorise l’utilisation de la synthèse vocale Microsoft (par défaut true ; sans clé API).
• providers.microsoft.voice : nom de voix neurale Microsoft (par ex. en-US-MichelleNeural).
• providers.microsoft.lang : code langue (par ex. en-US).
• providers.microsoft.outputFormat : format de sortie Microsoft (par ex. audio-24khz-48kbitrate-mono-mp3).
  • Voir les formats de sortie Microsoft Speech pour les valeurs valides ; tous les formats ne sont pas pris en charge par le transport groupé basé sur Edge.
• providers.microsoft.rate / providers.microsoft.pitch / providers.microsoft.volume : chaînes de pourcentage (par ex. +10%, -5%).
• providers.microsoft.saveSubtitles : écrit des sous-titres JSON à côté du fichier audio.
• providers.microsoft.proxy : URL de proxy pour les requêtes de synthèse vocale Microsoft.
• providers.microsoft.timeoutMs : remplace le délai d’expiration de la requête (ms).
• edge.* : alias hérité pour les mêmes paramètres Microsoft.

​

Remplacements pilotés par le modèle (activés par défaut)

Here you go.

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

• provider (identifiant de fournisseur vocal enregistré, par exemple openai, elevenlabs, google, minimax ou microsoft ; nécessite allowProvider: true)
• voice (voix OpenAI), voiceName / voice_name / google_voice (voix Google), ou voiceId (ElevenLabs / MiniMax)
• model (modèle TTS OpenAI, identifiant de modèle ElevenLabs ou modèle MiniMax) ou google_model (modèle TTS Google)
• stability, similarityBoost, style, speed, useSpeakerBoost
• vol / volume (volume MiniMax, 0-10)
• pitch (hauteur MiniMax, -12 à 12)
• applyTextNormalization (auto|on|off)
• languageCode (ISO 639-1)
• seed

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

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

​

Préférences par utilisateur

• enabled
• provider
• maxLength (seuil de résumé ; 1500 caractères par défaut)
• summarize (true par défaut)

​

Formats de sortie (fixes)

• Feishu / Matrix / Telegram / WhatsApp : message vocal Opus (opus_48000_64 depuis ElevenLabs, opus depuis OpenAI).
  • 48 kHz / 64 kb/s offre un bon compromis pour les messages vocaux.
• Autres canaux : MP3 (mp3_44100_128 depuis ElevenLabs, mp3 depuis OpenAI).
  • 44,1 kHz / 128 kb/s correspond à l’équilibre par défaut pour la clarté de la parole.
• MiniMax : MP3 (modèle speech-2.8-hd, fréquence d’échantillonnage de 32 kHz). Le format note vocale n’est pas pris en charge nativement ; utilisez OpenAI ou ElevenLabs pour des messages vocaux Opus garantis.
• Google Gemini : la synthèse vocale TTS de l’API Gemini renvoie du PCM brut à 24 kHz. OpenClaw l’encapsule dans du WAV pour les pièces jointes audio et renvoie directement du PCM pour Talk/la téléphonie. Le format natif de note vocale Opus n’est pas pris en charge par cette voie.
• Microsoft : utilise microsoft.outputFormat (par défaut audio-24khz-48kbitrate-mono-mp3).
  • Le transport groupé accepte un outputFormat, mais tous les formats ne sont pas disponibles dans le service.
  • Les valeurs de format de sortie suivent les formats de sortie Microsoft Speech (y compris Ogg/WebM Opus).
  • Telegram sendVoice accepte OGG/MP3/M4A ; utilisez OpenAI/ElevenLabs si vous avez besoin de messages vocaux Opus garantis.
  • Si le format de sortie Microsoft configuré échoue, OpenClaw réessaie avec MP3.

​

Comportement de l’auto-TTS

• ignore la TTS si la réponse contient déjà un média ou une directive MEDIA:.
• ignore les réponses très courtes (< 10 caractères).
• résume les réponses longues lorsqu’elle est activée à l’aide de agents.defaults.model.primary (ou summaryModel).
• joint l’audio généré à la réponse.

​

Diagramme du flux

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 (summaryModel or agents.defaults.model.primary)
                                      -> TTS -> attach audio

​

Utilisation des commandes slash

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

• Les commandes nécessitent un expéditeur autorisé (les règles de liste d’autorisation/propriétaire s’appliquent toujours).
• commands.text ou l’enregistrement de commandes natives doit être activé.
• La configuration messages.tts.auto accepte off|always|inbound|tagged.
• /tts on écrit la préférence TTS locale à always ; /tts off l’écrit à off.
• Utilisez la configuration si vous voulez des valeurs par défaut inbound ou tagged.
• limit et summary sont stockés dans les préférences locales, pas dans la configuration principale.
• /tts audio génère une réponse audio ponctuelle (cela n’active pas la TTS).
• /tts status inclut la visibilité du secours pour la dernière tentative :
  • secours réussi : Fallback: <primary> -> <used> plus Attempts: ...
  • échec : Error: ... plus Attempts: ...
  • diagnostics détaillés : Attempt details: provider:outcome(reasonCode) latency
• Les échecs d’API OpenAI et ElevenLabs incluent désormais le détail de l’erreur fournisseur analysée et l’identifiant de requête (quand il est renvoyé par le fournisseur), ce qui est exposé dans les erreurs/journaux TTS.

​

Outil de l’agent

​

RPC Gateway

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