Synthèse vocale

​

Démarrage rapide

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

​

Fournisseurs pris en charge

​

Configuration

{
  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",
          // Invites facultatives de style en langage naturel :
          // audioProfile: "Parlez d’un ton calme, comme lors de l’animation d’un 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",
        },
      },
    },
  },
}

​

Remplacements de voix par agent

{
  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 actif
3. remplacement du canal, lorsque le canal prend en charge channels.<channel>.tts
4. remplacement du compte, lorsque le canal transmet channels.<channel>.accounts.<id>.tts
5. préférences /tts locales pour cet hôte
6. directives [[tts:...]] intégrées lorsque les remplacements pilotés par le modèle sont activés

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

​

Personas

​

Persona minimale

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

​

Persona complète (invite indépendante du fournisseur)

{
  messages: {
    tts: {
      auto: "always",
      persona: "alfred",
      personas: {
        alfred: {
          label: "Alfred",
          description: "Narrateur majordome britannique, pince-sans-rire et chaleureux.",
          provider: "google",
          fallbackPolicy: "preserve-persona",
          prompt: {
            profile: "Un brillant majordome britannique. Pince-sans-rire, spirituel, chaleureux, charmant, expressif sur le plan émotionnel, jamais générique.",
            scene: "Un bureau silencieux tard dans la nuit. Narration de proximité au microphone pour un opérateur de confiance.",
            sampleContext: "Le locuteur répond à une demande technique privée avec une assurance concise et une chaleur teintée d’humour pince-sans-rire.",
            style: "Raffiné, sobre, légèrement amusé.",
            accent: "Anglais britannique.",
            pacing: "Mesuré, avec de courtes pauses dramatiques.",
            constraints: ["Ne lisez pas les valeurs de configuration à voix haute.", "N’expliquez pas 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,
              },
            },
          },
        },
      },
    },
  },
}

​

Résolution de la persona

1. préférence locale /tts persona <id>, si elle est définie.
2. messages.tts.persona, si elle est définie.
3. Aucune persona.

1. Remplacements directs (CLI, Gateway, Talk, directives TTS autorisées).
2. Préférence locale /tts provider <id>.
3. provider de la persona active.
4. messages.tts.provider.
5. Sélection automatique par le registre.

1. messages.tts.providers.<id>
2. messages.tts.personas.<persona>.providers.<id>
3. Remplacements de requête fiables
4. Remplacements autorisés des directives TTS émises par le modèle

​

Utilisation des invites de persona par les fournisseurs

​

Politique de repli

​

Directives pilotées par le modèle

Voilà.

[[tts:speakerVoiceId=pMsXgVXv3BLzUgSXRplE model=eleven_v3 speed=1.1]]
[[tts:text]](rit) Lisez la chanson une fois de plus.[[/tts:text]]

• provider (identifiant de fournisseur enregistré ; nécessite allowProvider: true)
• speakerVoice / speakerVoiceId (anciens alias : voice, voiceName, voice_name, google_voice, voiceId)
• model / google_model
• stability, similarityBoost, style, speed, useSpeakerBoost
• vol / volume (volume MiniMax, (0, 10])
• pitch (hauteur MiniMax entière, de −12 à 12 ; les valeurs fractionnaires sont tronquées)
• emotion (balise d’émotion Volcengine)
• applyTextNormalization (auto|on|off)
• languageCode (ISO 639-1)
• seed

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

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

​

Commandes à barre oblique

/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 écrit la préférence TTS locale dans always ; /tts off l’écrit dans off.
• /tts chat on|off|default écrit un remplacement TTS automatique limité à la session pour la discussion actuelle.
• /tts persona <id> écrit la préférence locale de persona ; /tts persona off l’efface.
• /tts latest lit la dernière réponse de l’assistant dans la transcription de la session actuelle et l’envoie une fois sous forme audio. Seul un hachage de cette réponse est stocké dans l’entrée de session afin d’éviter les envois vocaux en double.
• /tts audio génère une réponse audio ponctuelle (n’active pas le TTS).
• /tts limit <chars> accepte 100–4096 (4096 correspond au maximum de légende ou de message Telegram) ; les valeurs hors de cette plage sont rejetées.
• limit et summary sont stockés dans les préférences locales, et non dans la configuration principale.
• /tts status inclut les diagnostics de repli de la dernière tentative : Fallback: <primary> -> <used>, Attempts: ... et les détails de chaque tentative (provider:outcome(reasonCode) latency).
• /status affiche le mode TTS actif ainsi que le fournisseur, le modèle, la voix et les métadonnées nettoyées du point de terminaison personnalisé configurés lorsque le TTS est activé.

​

Préférences par utilisateur

​

Formats de sortie

• Transcodage Feishu / WhatsApp : lorsqu’une réponse sous forme de message vocal arrive au format MP3/WebM/WAV/M4A ou dans un autre fichier probablement audio, le plugin de canal la transcode en Ogg/Opus 48 kHz avec ffmpeg (libopus, 64 kbps) avant d’envoyer le message vocal natif. WhatsApp envoie le résultat au moyen de la charge utile Baileys audio avec ptt: true et audio/ogg; codecs=opus. En cas d’échec du transcodage : Feishu intercepte l’erreur et envoie à la place le fichier d’origine comme simple pièce jointe ; WhatsApp ne dispose d’aucune solution de repli, l’envoi lui-même échoue donc au lieu de publier une charge utile PTT incompatible.
• MiniMax : MP3 (modèle speech-2.8-hd, fréquence d’échantillonnage de 32 kHz) pour les pièces jointes audio normales ; transcodé en Opus 48 kHz avec ffmpeg pour les cibles de message vocal annoncées par le canal.
• Xiaomi MiMo : MP3 par défaut, ou WAV selon la configuration ; transcodé en Opus 48 kHz avec ffmpeg pour les cibles de message vocal annoncées par le canal.
• CLI locale : utilise le outputFormat configuré. Les cibles de message vocal sont converties en Ogg/Opus et la sortie téléphonique est convertie en PCM mono brut 16 kHz avec ffmpeg.
• Google Gemini : renvoie du PCM brut 24 kHz. OpenClaw l’encapsule au format WAV pour les pièces jointes audio, le transcode en Opus 48 kHz pour les cibles de message vocal et renvoie directement le PCM pour Talk/la téléphonie.
• Gradium : WAV pour les pièces jointes audio, Opus pour les cibles de message vocal et ulaw_8000 à 8 kHz pour la téléphonie.
• Inworld : MP3 pour les pièces jointes audio normales, OGG_OPUS natif pour les cibles de message vocal et PCM brut à 22050 Hz pour Talk/la téléphonie.
• xAI : MP3 par défaut ; la synthèse de fichiers audio peut utiliser mp3, wav, pcm, mulaw ou alaw pour les sorties mises en mémoire tampon comme pour les sorties en streaming. Les cibles de message vocal utilisent le MP3 pour le streaming et comme solution de repli mise en mémoire tampon, car les sorties pcm, mulaw et alaw de xAI sont des données audio brutes sans en-tête. La synthèse mise en mémoire tampon utilise le point de terminaison REST par lot /v1/tts de xAI ; textToSpeechStream utilise le wss://api.x.ai/v1/tts natif. Il ne s’agit pas du contrat vocal en temps réel. Le format vocal Opus natif n’est pas pris en charge.
• Microsoft : utilise microsoft.outputFormat (audio-24khz-48kbitrate-mono-mp3 par défaut).
  • Le transport intégré accepte un outputFormat, mais tous les formats ne sont pas disponibles auprès du service.
  • Les valeurs du format de sortie suivent les formats de sortie de Microsoft Speech (notamment Ogg/WebM Opus).
  • Le sendVoice de Telegram 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 en MP3.
  • Lorsqu’aucun remplacement vocal explicite n’est défini et que la voix anglaise par défaut est utilisée, OpenClaw bascule automatiquement vers une voix neuronale chinoise (zh-CN-XiaoxiaoNeural, paramètres régionaux zh-CN) si le texte de la réponse est majoritairement en caractères CJK.

​

Comportement du TTS automatique

• Ignore la synthèse vocale si la réponse contient déjà des médias structurés.
• Ignore les réponses très courtes (moins de 10 caractères).
• Résume les réponses longues lorsque les résumés sont activés, à l’aide de summaryModel (ou agents.defaults.model.primary).
• Joint l’audio généré à la réponse.
• Dans mode: "final", envoie toujours une synthèse vocale uniquement audio pour les réponses finales diffusées en continu une fois la diffusion du texte terminée ; le média généré passe par la même normalisation des médias du canal que les pièces jointes habituelles des réponses.

• Résumé activé (par défaut) et un modèle de résumé est disponible : résume le texte à environ maxLength caractères, puis synthétise le résumé.
• Résumé désactivé, échec du résumé ou aucune clé API disponible pour le modèle de résumé : tronque le texte à maxLength caractères et synthétise le texte tronqué.

Réponse -> Synthèse vocale activée ?
  non -> envoyer le texte
  oui -> contient un média / est courte ?
           oui -> envoyer le texte
           non -> longueur > limite ?
                    non -> synthèse vocale -> joindre l’audio
                    oui -> résumé activé et disponible ?
                             non -> tronquer -> synthèse vocale -> joindre l’audio
                             oui -> résumer -> synthèse vocale -> joindre l’audio

​

Référence des champs

​

Outil de l’agent

​

RPC du Gateway

​

Liens vers les services

• Guide de synthèse vocale d’OpenAI
• Référence de l’API Audio d’OpenAI
• Synthèse vocale avec l’API REST Azure Speech
• Fournisseur Azure Speech
• Synthèse vocale ElevenLabs
• Authentification ElevenLabs
• Gradium
• API TTS d’Inworld
• API MiniMax T2A v2
• API HTTP TTS de Volcengine
• Synthèse vocale Xiaomi MiMo
• node-edge-tts
• Formats de sortie Microsoft Speech
• Synthèse vocale xAI

​

Ressources connexes

• Présentation des médias
• Génération de musique
• Génération de vidéos
• Commandes slash
• Plugin d’appel vocal