Texto para fala

​

Início rápido

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

​

Provedores compatíveis

​

Configuração

{
  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",
        },
      },
    },
  },
}

​

Substituições de voz por agente

{
  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 ativo
3. substituição de canal, quando o canal oferece suporte a channels.<channel>.tts
4. substituição de conta, quando o canal passa channels.<channel>.accounts.<id>.tts
5. preferências locais de /tts para este host
6. diretivas inline [[tts:...]] quando substituições por modelo estão habilitadas

{
  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 mínima

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

​

Persona completa (prompt neutro em relação ao provedor)

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

​

Resolução de persona

1. Preferência local /tts persona <id>, se definida.
2. messages.tts.persona, se definida.
3. Nenhuma persona.

1. Substituições diretas (CLI, Gateway, Talk, diretivas TTS permitidas).
2. Preferência local /tts provider <id>.
3. provider da persona ativa.
4. messages.tts.provider.
5. Seleção automática do registro.

1. messages.tts.providers.<id>
2. messages.tts.personas.<persona>.providers.<id>
3. Substituições de solicitação confiáveis
4. Substituições de diretiva TTS permitidas emitidas pelo modelo

​

Como os provedores usam prompts de persona

​

Política de fallback

​

Diretivas orientadas por modelo

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 provedor registrado; requer allowProvider: true)
• speakerVoice / speakerVoiceId (aliases legados: voice, voiceName, voice_name, google_voice, voiceId)
• model / google_model
• stability, similarityBoost, style, speed, useSpeakerBoost
• vol / volume (volume MiniMax, 0–10)
• pitch (pitch inteiro MiniMax, −12 a 12; valores fracionários são truncados)
• emotion (tag de emoção Volcengine)
• applyTextNormalization (auto|on|off)
• languageCode (ISO 639-1)
• seed

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

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

​

Comandos 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 grava a preferência local de TTS como always; /tts off grava como off.
• /tts chat on|off|default grava uma substituição de TTS automático escopada à sessão para o chat atual.
• /tts persona <id> grava a preferência local de persona; /tts persona off a limpa.
• /tts latest lê a resposta mais recente do assistente na transcrição da sessão atual e a envia como áudio uma vez. Ele armazena apenas um hash dessa resposta na entrada da sessão para suprimir envios de voz duplicados.
• /tts audio gera uma resposta de áudio avulsa (não alterna TTS para ativado).
• limit e summary são armazenados nas preferências locais, não na configuração principal.
• /tts status inclui diagnósticos de fallback da tentativa mais recente — Fallback: <primary> -> <used>, Attempts: ... e detalhe por tentativa (provider:outcome(reasonCode) latency).
• /status mostra o modo TTS ativo, além do provedor, modelo, voz e metadados sanitizados de endpoint personalizado configurados quando TTS está habilitado.

​

Preferências por usuário

​

Formatos de saída (fixos)

• Canais compatíveis com notas de voz: respostas de nota de voz preferem Opus (opus_48000_64 da ElevenLabs, opus da OpenAI).
  • 48 kHz / 64 kbps é um bom equilíbrio para mensagens de voz.
• Feishu / WhatsApp: quando uma resposta de nota de voz é produzida como MP3/WebM/WAV/M4A ou outro arquivo provavelmente de áudio, o Plugin do canal a transcodifica para Ogg/Opus a 48 kHz com ffmpeg antes de enviar a mensagem de voz nativa. O WhatsApp envia o resultado por meio do payload audio da Baileys com ptt: true e audio/ogg; codecs=opus. Se a conversão falhar, o Feishu recebe o arquivo original como anexo; o envio do WhatsApp falha em vez de publicar um payload PTT incompatível.
• Outros canais: MP3 (mp3_44100_128 da ElevenLabs, mp3 da OpenAI).
  • 44,1 kHz / 128 kbps é o equilíbrio padrão para clareza de fala.
• MiniMax: MP3 (modelo speech-2.8-hd, taxa de amostragem de 32 kHz) para anexos de áudio comuns. Para destinos de nota de voz anunciados pelo canal, o OpenClaw transcodifica o MP3 da MiniMax para Opus a 48 kHz com ffmpeg antes da entrega quando o canal anuncia transcodificação.
• Xiaomi MiMo: MP3 por padrão, ou WAV quando configurado. Para destinos de nota de voz anunciados pelo canal, o OpenClaw transcodifica a saída da Xiaomi para Opus a 48 kHz com ffmpeg antes da entrega quando o canal anuncia transcodificação.
• CLI local: usa o outputFormat configurado. Destinos de nota de voz são convertidos para Ogg/Opus e a saída de telefonia é convertida para PCM mono bruto de 16 kHz com ffmpeg.
• Google Gemini: o TTS da API Gemini retorna PCM bruto de 24 kHz. O OpenClaw o encapsula como WAV para anexos de áudio, transcodifica para Opus a 48 kHz para destinos de nota de voz e retorna PCM diretamente para Talk/telefonia.
• Gradium: WAV para anexos de áudio, Opus para destinos de nota de voz e ulaw_8000 a 8 kHz para telefonia.
• Inworld: MP3 para anexos de áudio comuns, OGG_OPUS nativo para destinos de nota de voz e PCM bruto a 22050 Hz para Talk/telefonia.
• xAI: MP3 por padrão; responseFormat pode ser mp3, wav, pcm, mulaw ou alaw. O OpenClaw usa o endpoint TTS REST em lote da xAI e retorna um anexo de áudio completo; o WebSocket de TTS por streaming da xAI não é usado por este caminho de provedor. O formato Opus nativo de nota de voz não é compatível com este caminho.
• Microsoft: usa microsoft.outputFormat (padrão audio-24khz-48kbitrate-mono-mp3).
  • O transporte incluído aceita um outputFormat, mas nem todos os formatos estão disponíveis no serviço.
  • Valores de formato de saída seguem os formatos de saída do Microsoft Speech (incluindo Ogg/WebM Opus).
  • O sendVoice do Telegram aceita OGG/MP3/M4A; use OpenAI/ElevenLabs se precisar de mensagens de voz Opus garantidas.
  • Se o formato de saída configurado da Microsoft falhar, o OpenClaw tenta novamente com MP3.

​

Comportamento de TTS automático

• Ignora TTS se a resposta já contiver mídia estruturada.
• Ignora respostas muito curtas (menos de 10 caracteres).
• Resume respostas longas quando resumos estão habilitados, usando summaryModel (ou agents.defaults.model.primary).
• Anexa o áudio gerado à resposta.
• Em mode: "final", ainda envia TTS somente de áudio para respostas finais transmitidas por streaming após a conclusão do stream de texto; a mídia gerada passa pela mesma normalização de mídia do canal que anexos normais de resposta.

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

​

Formatos de saída por canal

• Transcodificação Feishu / WhatsApp: quando uma resposta de nota de voz chega como MP3/WebM/WAV/M4A, o Plugin do canal transcodifica para Ogg/Opus a 48 kHz com ffmpeg. O WhatsApp envia pela Baileys com ptt: true e audio/ogg; codecs=opus. Se a conversão falhar: o Feishu recorre a anexar o arquivo original; o envio do WhatsApp falha em vez de publicar um payload PTT incompatível.
• MiniMax / Xiaomi MiMo: MP3 padrão (32 kHz para MiniMax speech-2.8-hd); transcodificado para Opus a 48 kHz para destinos de nota de voz via ffmpeg.
• CLI local: usa o outputFormat configurado. Destinos de nota de voz são convertidos para Ogg/Opus e a saída de telefonia para PCM mono bruto de 16 kHz.
• Google Gemini: retorna PCM bruto de 24 kHz. O OpenClaw encapsula como WAV para anexos, transcodifica para Opus a 48 kHz para destinos de nota de voz e retorna PCM diretamente para Talk/telefonia.
• Inworld: anexos MP3, nota de voz OGG_OPUS nativa, PCM bruto a 22050 Hz para Talk/telefonia.
• xAI: MP3 por padrão; responseFormat pode ser mp3|wav|pcm|mulaw|alaw. Usa o endpoint REST em lote da xAI — TTS por WebSocket em streaming não é usado. O formato Opus nativo de nota de voz não é compatível.
• Microsoft: usa microsoft.outputFormat (padrão audio-24khz-48kbitrate-mono-mp3). O sendVoice do Telegram aceita OGG/MP3/M4A; use OpenAI/ElevenLabs se precisar de mensagens de voz Opus garantidas. Se o formato configurado da Microsoft falhar, o OpenClaw tenta novamente com MP3.

​

Referência de campos

​

Ferramenta do agente

​

RPC do Gateway

​

Links de serviço

• Guia de texto para fala da OpenAI
• Referência da API de áudio da OpenAI
• Texto para fala REST do Azure Speech
• Provedor Azure Speech
• Texto para fala da ElevenLabs
• Autenticação da ElevenLabs
• Gradium
• API TTS da Inworld
• API MiniMax T2A v2
• API HTTP TTS da Volcengine
• Síntese de fala Xiaomi MiMo
• node-edge-tts
• Formatos de saída do Microsoft Speech
• Texto para fala da xAI

​

Relacionados

• Visão geral de mídia
• Geração de música
• Geração de vídeo
• Comandos de barra
• Plugin de chamada de voz