​

Synthèse vocale (TTS)

​

Services pris en charge

• ElevenLabs (fournisseur principal ou de secours)
• 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)

​

Notes sur la synthèse vocale Microsoft

​

Clés facultatives

• ELEVENLABS_API_KEY (ou XI_API_KEY)
• MINIMAX_API_KEY
• OPENAI_API_KEY

​

Liens de service

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

​

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

​

Notes sur les champs

• auto : mode auto‑TTS (off, always, inbound, tagged).
  • inbound n’envoie de l’audio qu’après un message vocal entrant.
  • tagged n’envoie de l’audio que lorsque la réponse inclut des balises [[tts]].
• enabled : bascule héritée (doctor la migre vers auto).
• mode : "final" (par défaut) ou "all" (inclut les réponses d’outils/blocs).
• provider : id du fournisseur vocal tel que "elevenlabs", "microsoft", "minimax" ou "openai" (la solution de 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é vers microsoft.
• summaryModel : modèle économique facultatif pour le résumé automatique ; la valeur par défaut est agents.defaults.model.primary.
  • Accepte provider/model ou un alias de modèle configuré.
• modelOverrides : autoriser le modèle à émettre des directives TTS (activé par défaut).
  • allowProvider vaut par défaut false (le changement de fournisseur se fait par adhésion explicite).
• providers.<id> : paramètres détenus par le fournisseur, indexés par id de fournisseur vocal.
• Les anciens blocs de fournisseur directs (messages.tts.openai, messages.tts.elevenlabs, messages.tts.microsoft, messages.tts.edge) sont automatiquement migrés 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 reviennent aux variables d’environnement (ELEVENLABS_API_KEY/XI_API_KEY, MINIMAX_API_KEY, OPENAI_API_KEY).
• providers.elevenlabs.baseUrl : remplace l’URL de base de l’API ElevenLabs.
• providers.openai.baseUrl : remplace l’endpoint 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 endpoints TTS compatibles OpenAI, donc les noms personnalisés de modèle et de voix 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 exemple 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.microsoft.enabled : autoriser l’utilisation de la synthèse vocale Microsoft (par défaut true ; pas de clé API).
• providers.microsoft.voice : nom de voix neurale Microsoft (par exemple en-US-MichelleNeural).
• providers.microsoft.lang : code langue (par exemple en-US).
• providers.microsoft.outputFormat : format de sortie Microsoft (par exemple 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é adossé à Edge.
• providers.microsoft.rate / providers.microsoft.pitch / providers.microsoft.volume : chaînes de pourcentage (par exemple +10%, -5%).
• providers.microsoft.saveSubtitles : écrire 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 : remplacement du 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 (id de fournisseur vocal enregistré, par exemple openai, elevenlabs, minimax ou microsoft ; nécessite allowProvider: true)
• voice (voix OpenAI) ou voiceId (ElevenLabs / MiniMax)
• model (modèle TTS OpenAI, id de modèle ElevenLabs ou modèle MiniMax)
• 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 provenant de ElevenLabs, opus provenant de OpenAI).
  • 48 kHz / 64 kb/s constitue un bon compromis pour les messages vocaux.
• Autres canaux : MP3 (mp3_44100_128 provenant de ElevenLabs, mp3 provenant de OpenAI).
  • 44,1 kHz / 128 kb/s est l’équilibre par défaut pour la clarté de la parole.
• MiniMax : MP3 (modèle speech-2.8-hd, fréquence d’échantillonnage 32 kHz). Le format note vocale n’est pas pris en charge nativement ; utilisez OpenAI ou ElevenLabs pour des messages vocaux Opus garantis.
• 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 depuis 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 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 lorsque cette option est activée à l’aide de agents.defaults.model.primary (ou summaryModel).
• joint l’audio généré à la réponse.

​

Diagramme de flux

Réponse -> TTS activé ?
  non -> envoyer le texte
  oui -> contient un média / MEDIA: / court ?
           oui -> envoyer le texte
           non -> longueur > limite ?
                    non -> TTS -> joindre l’audio
                    oui -> résumé activé ?
                             non -> envoyer le texte
                             oui -> résumer (summaryModel ou agents.defaults.model.primary)
                                       -> TTS -> joindre l’audio

​

Utilisation des commandes 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

• 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é.
• off|always|inbound|tagged sont des bascules par session (/tts on est un alias pour /tts always).
• 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 (n’active pas TTS).
• /tts status inclut la visibilité de 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 d’erreur analysé du fournisseur et l’id de requête (lorsqu’il est renvoyé par le fournisseur), qui apparaissent dans les erreurs/journaux TTS.

​

Outil d’agent

​

RPC gateway

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