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",
          // 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}",
          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 inline [[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: { speakerVoice: "shimmer" },
            },
          },
        },
      },
    },
  },
}

​

Personas

​

Persona minimale

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

​

Persona complète (prompt neutre vis-à-vis 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",
              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 du registre.

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

​

Comment les fournisseurs utilisent les prompts de persona

​

Politique de fallback

​

Directives pilotées par le modèle

Here you go.

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

• provider (ID de fournisseur enregistré; nécessite allowProvider: true)
• speakerVoice / speakerVoiceId (alias hérités: 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 la conversation actuelle.
• /tts persona <id> écrit la préférence de persona locale; /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 d’audio. Elle ne stocke qu’un hash de cette réponse sur 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 fallback pour la dernière tentative — Fallback: <primary> -> <used>, Attempts: ..., et le détail par tentative (provider:outcome(reasonCode) latency).
• /status affiche le mode TTS actif ainsi que le fournisseur, le modèle, la voix configurés et les métadonnées de point de terminaison personnalisé assainies 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 kbit/s offre 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 format 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 d’origine en pièce jointe ; l’envoi WhatsApp échoue plutôt que de publier une charge utile PTT incompatible.
• Autres canaux: MP3 (mp3_44100_128 depuis ElevenLabs, mp3 depuis OpenAI).
  • 44,1 kHz / 128 kbit/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 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 la prise en charge du transcodage.
• Xiaomi MiMo: MP3 par défaut, ou WAV lorsque 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 la prise en charge du transcodage.
• CLI locale: utilise le outputFormat configuré. Les cibles de notes vocales sont converties en Ogg/Opus, et la sortie de téléphonie est convertie en PCM mono brut 16 kHz avec ffmpeg.
• Google Gemini: la TTS de l’API Gemini renvoie du PCM brut 24 kHz. OpenClaw l’encapsule en WAV pour les pièces jointes audio, la transcode en Opus 48 kHz pour les cibles de notes vocales, et renvoie directement le PCM pour Talk/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/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 inclus 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 la TTS 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, en utilisant summaryModel (ou agents.defaults.model.primary).
• Joint l’audio généré à la réponse.
• En mode: "final", envoie toujours une TTS audio seule pour les réponses finales diffusées en streaming après la fin du flux de texte ; le média généré passe par la même normalisation des médias de canal que les pièces jointes de réponse normales.

Reply -> TTS enabled?
  no  -> send text
  yes -> has media / short?
          yes -> send text
          no  -> length > limit?
                   no  -> TTS -> attach audio
                   yes -> summary enabled?
                            no  -> send text
                            yes -> summarize -> TTS -> attach 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 la 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 à la pièce jointe du fichier d’origine ; l’envoi WhatsApp échoue au lieu 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 note vocale via ffmpeg.
• CLI locale : utilise le outputFormat configuré. Les cibles de note vocale sont converties en Ogg/Opus et la sortie téléphonique 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 note vocale, et renvoie directement le PCM pour Discussion/téléphonie.
• Inworld : pièces jointes MP3, note vocale native OGG_OPUS, PCM brut 22050 Hz pour Discussion/téléphonie.
• xAI : MP3 par défaut ; responseFormat peut être 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 note vocale 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 Inworld TTS
• 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 de musique
• Génération de vidéo
• Commandes slash
• Plugin d’appel vocal