Synthèse vocale

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

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",
          voice: "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",
          voiceId: "EXAVITQu4vr4xnSDxMaL",
        },
      },
    },
  },
}

{
  messages: {
    tts: {
      auto: "always",
      provider: "google",
      providers: {
        google: {
          apiKey: "${GEMINI_API_KEY}",
          model: "gemini-3.1-flash-tts-preview",
          voiceName: "Kore",
          // Optional natural-language style prompts:
          // audioProfile: "Speak in a calm, podcast-host tone.",
          // speakerName: "Alex",
        },
      },
    },
  },
}

{
  messages: {
    tts: {
      auto: "always",
      provider: "gradium",
      providers: {
        gradium: {
          apiKey: "${GRADIUM_API_KEY}",
          voiceId: "YTpq7expH9539ERJ",
        },
      },
    },
  },
}

{
  messages: {
    tts: {
      auto: "always",
      provider: "inworld",
      providers: {
        inworld: {
          apiKey: "${INWORLD_API_KEY}",
          modelId: "inworld-tts-1.5-max",
          voiceId: "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,
          voice: "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",
          voiceId: "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",
          voice: "alloy",
        },
        elevenlabs: {
          apiKey: "${ELEVENLABS_API_KEY}",
          model: "eleven_multilingual_v2",
          voiceId: "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",
          voice: "af_alloy",
          responseFormat: "mp3",
        },
      },
    },
  },
}

{
  messages: {
    tts: {
      auto: "always",
      provider: "volcengine",
      providers: {
        volcengine: {
          apiKey: "${VOLCENGINE_TTS_API_KEY}",
          resourceId: "seed-tts-1.0",
          voice: "en_female_anna_mars_bigtts",
        },
      },
    },
  },
}

{
  messages: {
    tts: {
      auto: "always",
      provider: "xai",
      providers: {
        xai: {
          apiKey: "${XAI_API_KEY}",
          voiceId: "eve",
          language: "en",
          responseFormat: "mp3",
        },
      },
    },
  },
}

{
  messages: {
    tts: {
      auto: "always",
      provider: "xiaomi",
      providers: {
        xiaomi: {
          apiKey: "${XIAOMI_API_KEY}",
          model: "mimo-v2.5-tts",
          voice: "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: { voiceId: "EXAVITQu4vr4xnSDxMaL" },
          },
        },
      },
    ],
  },
}

1. messages.tts
2. agents.list[].tts actif
3. remplacement de canal, lorsque le canal prend en charge channels.<channel>.tts
4. remplacement de compte, lorsque le canal transmet channels.<channel>.accounts.<id>.tts
5. préférences locales /tts pour cet hôte
6. directives intégrées [[tts:...]] 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: { voice: "shimmer" },
            },
          },
        },
      },
    },
  },
}

​

Personas

​

Persona minimale

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

​

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

{
  messages: {
    tts: {
      auto: "always",
      persona: "alfred",
      personas: {
        alfred: {
          label: "Alfred",
          description: "Dry, warm British butler narrator.",
          provider: "google",
          fallbackPolicy: "preserve-persona",
          prompt: {
            profile: "A brilliant British butler. Dry, witty, warm, charming, emotionally expressive, never generic.",
            scene: "A quiet late-night study. Close-mic narration for a trusted operator.",
            sampleContext: "The speaker is answering a private technical request with concise confidence and dry warmth.",
            style: "Refined, understated, lightly amused.",
            accent: "British English.",
            pacing: "Measured, with short dramatic pauses.",
            constraints: ["Do not read configuration values aloud.", "Do not explain the persona."],
          },
          providers: {
            google: {
              model: "gemini-3.1-flash-tts-preview",
              voiceName: "Algieba",
              promptTemplate: "audio-profile-v1",
            },
            openai: { model: "gpt-4o-mini-tts", voice: "cedar" },
            elevenlabs: {
              voiceId: "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 du registre.

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

​

Utilisation des invites de persona par les fournisseurs

​

Politique de repli

​

Directives pilotées par le modèle

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 enregistré ; nécessite allowProvider: true)
• voice / voiceName / voice_name / google_voice / voiceId
• model / google_model
• stability, similarityBoost, style, speed, useSpeakerBoost
• vol / volume (volume MiniMax, 0–10)
• pitch (hauteur entière MiniMax, −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 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 écrit la préférence TTS locale sur always ; /tts off l’écrit sur off.
• /tts chat on|off|default écrit un remplacement auto-TTS limité à la session pour le chat courant.
• /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 courante et l’envoie une fois en audio. Elle stocke uniquement un hachage de cette réponse dans l’entrée de session afin de supprimer les envois vocaux en double.
• /tts audio génère une réponse audio ponctuelle (n’active pas TTS).
• limit et summary sont stockés dans les préférences locales, pas dans la configuration principale.
• /tts status inclut les diagnostics de repli pour la dernière tentative — Fallback: <primary> -> <used>, Attempts: ..., et les détails par 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 de point de terminaison personnalisé nettoyées configurés lorsque TTS est activé.

​

Préférences par utilisateur

​

Formats de sortie (fixes)

• Canaux compatibles avec les notes vocales : les réponses sous forme de note vocale privilégient Opus (opus_48000_64 depuis ElevenLabs, opus depuis OpenAI).
  • 48 kHz / 64 kbps constitue un bon compromis pour les messages vocaux.
• Feishu / WhatsApp : lorsqu’une réponse sous forme de note vocale est produite en MP3/WebM/WAV/M4A ou dans un autre fichier probablement audio, le plugin de canal la transcode en Ogg/Opus 48 kHz avec ffmpeg avant d’envoyer le message vocal natif. WhatsApp envoie le résultat via la charge utile Baileys audio avec ptt: true et audio/ogg; codecs=opus. Si la conversion échoue, Feishu reçoit le fichier original en pièce jointe ; l’envoi WhatsApp échoue au lieu de publier une charge utile PTT incompatible.
• Autres canaux : MP3 (mp3_44100_128 depuis ElevenLabs, mp3 depuis OpenAI).
  • 44,1 kHz / 128 kbps est 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) pour les pièces jointes audio normales. Pour les cibles de notes vocales annoncées par le canal, OpenClaw transcode le MP3 MiniMax en Opus 48 kHz avec ffmpeg avant la livraison lorsque le canal annonce le transcodage.
• Xiaomi MiMo : MP3 par défaut, ou WAV lorsqu’il est configuré. Pour les cibles de notes vocales annoncées par le canal, OpenClaw transcode la sortie Xiaomi en Opus 48 kHz avec ffmpeg avant la livraison lorsque le canal annonce le transcodage.
• CLI locale : utilise le outputFormat configuré. Les cibles de notes vocales sont converties en Ogg/Opus et la sortie téléphonique est convertie en PCM mono brut 16 kHz avec ffmpeg.
• Google Gemini : le TTS de l’API Gemini renvoie du PCM brut 24 kHz. OpenClaw l’encapsule en WAV pour les pièces jointes audio, le transcode en Opus 48 kHz pour les cibles de notes vocales, et renvoie directement le PCM pour Talk/la téléphonie.
• Gradium : WAV pour les pièces jointes audio, Opus pour les cibles de notes vocales, 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 notes vocales, et PCM brut à 22050 Hz pour Talk/la téléphonie.
• xAI : MP3 par défaut ; responseFormat peut être mp3, wav, pcm, mulaw ou alaw. OpenClaw utilise le point de terminaison TTS REST par lots de xAI et renvoie une pièce jointe audio complète ; le WebSocket TTS en streaming de xAI n’est pas utilisé par ce chemin de fournisseur. Le format natif Opus pour les notes vocales n’est pas pris en charge par ce chemin.
• 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 Auto-TTS

• Ignore le TTS si la réponse contient déjà un média ou une directive MEDIA:.
• 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.
• En mode: "final", envoie toujours le TTS audio seul pour les réponses finales diffusées une fois le flux de texte terminé ; le média généré passe par la même normalisation des médias du canal que les pièces jointes de réponse normales.

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 -> TTS -> joindre l’audio

​

Formats de sortie par canal

• Transcodage Feishu / WhatsApp : lorsqu’une réponse par note vocale arrive en MP3/WebM/WAV/M4A, le Plugin de canal transcode en Ogg/Opus 48 kHz avec ffmpeg. WhatsApp envoie via Baileys avec ptt: true et audio/ogg; codecs=opus. Si la conversion échoue : Feishu revient à l’ajout du fichier original en pièce jointe ; l’envoi WhatsApp échoue plutôt que de publier une charge utile PTT incompatible.
• MiniMax / Xiaomi MiMo : MP3 par défaut (32 kHz pour MiniMax speech-2.8-hd) ; transcodé en Opus 48 kHz pour les cibles de notes vocales via ffmpeg.
• CLI locale : utilise le outputFormat configuré. Les cibles de notes vocales sont converties en Ogg/Opus et la sortie téléphonie en PCM mono 16 kHz brut.
• Google Gemini : renvoie du PCM 24 kHz brut. OpenClaw l’encapsule en WAV pour les pièces jointes, le transcode en Opus 48 kHz pour les cibles de notes vocales, renvoie directement le PCM pour Talk/la téléphonie.
• Inworld : pièces jointes MP3, note vocale native OGG_OPUS, PCM brut 22050 Hz pour Talk/la téléphonie.
• xAI : MP3 par défaut ; responseFormat peut valoir mp3|wav|pcm|mulaw|alaw. Utilise le point de terminaison REST par lot de xAI — le TTS WebSocket en streaming n’est pas utilisé. Le format natif Opus pour notes vocales n’est pas pris en charge.
• Microsoft : utilise microsoft.outputFormat (par défaut audio-24khz-48kbitrate-mono-mp3). Telegram sendVoice accepte OGG/MP3/M4A ; utilisez OpenAI/ElevenLabs si vous avez besoin de messages vocaux Opus garantis. Si le format Microsoft configuré échoue, OpenClaw réessaie avec MP3.

​

Référence des champs

​

Outil d’agent

​

RPC Gateway

​

Liens de service

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

​

Connexe

• Vue d’ensemble des médias
• Génération musicale
• Génération vidéo
• Commandes slash
• Plugin d’appel vocal