Texto para fala

O OpenClaw converte respostas de saída em áudio por meio de 14 provedores de fala: mensagens de voz nativas no Feishu, Matrix, Telegram e WhatsApp; anexos de áudio em todos os outros lugares; e fluxos PCM/Ulaw para telefonia e Talk.

TTS é a metade de saída de fala do modo stt-tts do Talk (talk.speak chama esse mesmo caminho de síntese). Sessões do Talk realtime nativas do provedor sintetizam a fala dentro do provedor em tempo real; sessões transcription nunca sintetizam uma resposta de voz do assistente.

Início rápido

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

Provedores compatíveis

Se vários provedores estiverem configurados, o selecionado será usado primeiro, e os demais serão opções de fallback. O resumo automático usa summaryModel (ou agents.defaults.model.primary), portanto esse provedor também deve estar autenticado se você mantiver os resumos ativados.

Configuração

A configuração de TTS fica em messages.tts no arquivo ~/.openclaw/openclaw.json. Escolha uma predefinição e adapte o bloco do provedor. Os campos speakerVoice/speakerVoiceId mostrados abaixo são canônicos; os nomes de campo voice/voiceId/voiceName próprios de cada provedor ainda funcionam como aliases legados.

{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",      // Prompts opcionais de estilo em linguagem natural:      // audioProfile: "Fale em um tom calmo de apresentador de 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",    },  },},},}

Para o Xiaomi mimo-v2.5-tts-voicedesign, omita speakerVoice e defina style como o prompt de criação da voz. O OpenClaw envia esse prompt como a mensagem user do TTS e não envia audio.voice para o modelo voicedesign.

Substituições de voz por agente

Use agents.list[].tts quando um agente precisar falar com um provedor, voz, modelo, persona ou modo de TTS automático diferente. O bloco do agente é mesclado profundamente sobre messages.tts, portanto as credenciais do provedor podem permanecer na configuração global do provedor:

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

Para fixar uma persona por agente, defina agents.list[].tts.persona junto à configuração do provedor — isso substitui a messages.tts.persona global somente para esse agente.

Ordem de precedência para respostas automáticas, /tts audio, /tts status e a ferramenta de agente tts:

1. messages.tts
2. agents.list[].tts ativo
3. substituição do canal, quando o canal oferece suporte a channels.<channel>.tts
4. substituição da conta, quando o canal transmite channels.<channel>.accounts.<id>.tts
5. preferências locais de /tts para este host
6. diretivas [[tts:...]] embutidas quando as substituições pelo modelo estão habilitadas

As substituições de canal e conta usam o mesmo formato de messages.tts e são mescladas profundamente sobre as camadas anteriores, portanto as credenciais compartilhadas do provedor podem permanecer em messages.tts, enquanto um canal ou uma conta de bot altera somente a voz do locutor, o modelo, a persona ou o modo automático:

{  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

Uma persona é uma identidade falada estável que pode ser aplicada de forma determinística entre provedores. Ela pode dar preferência a um provedor, definir a intenção do prompt independentemente do provedor e conter vinculações específicas de cada provedor para vozes, modelos, modelos de prompt, seeds e configurações de voz.

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 independente do 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 da persona

A persona ativa é selecionada de forma determinística:

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

A seleção do provedor prioriza configurações explícitas:

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

Para cada tentativa de provedor, o OpenClaw mescla as configurações nesta ordem:

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

Como os provedores usam prompts de persona

Os campos do prompt da persona (profile, scene, sampleContext, style, accent, pacing, constraints) são independentes do provedor. Cada provedor decide como usá-los:

Política de fallback

fallbackPolicy controla o comportamento quando uma persona não tem vinculação para o provedor tentado:

A solicitação TTS inteira só falha quando todos os provedores tentados são ignorados ou falham.

A seleção do provedor da sessão do Talk é definida no escopo da sessão. Um cliente Talk deve escolher IDs de provedor, IDs de modelo, IDs de voz e localidades em talk.catalog e transmiti-los pela solicitação de sessão ou transferência do Talk. Abrir uma sessão de voz não deve alterar messages.tts nem os padrões globais de provedor do Talk.

Diretivas controladas pelo modelo

Por padrão, o assistente pode emitir diretivas [[tts:...]] para substituir a voz, o modelo ou a velocidade em uma única resposta, além de um bloco opcional [[tts:text]]...[[/tts:text]] para indicações expressivas que devem aparecer somente no áudio:

Aqui está. [[tts:speakerVoiceId=pMsXgVXv3BLzUgSXRplE model=eleven_v3 speed=1.1]][[tts:text]](risos) Leia a música mais uma vez.[[/tts:text]]

Quando messages.tts.auto é "tagged", as diretivas são obrigatórias para acionar o áudio. A entrega de blocos por streaming remove as diretivas do texto visível antes que o canal as receba, mesmo quando elas estão divididas entre blocos adjacentes.

provider=... é ignorado, a menos que modelOverrides.allowProvider: true. Quando uma resposta declara provider=..., as outras chaves dessa diretiva são analisadas somente por esse provedor; chaves sem suporte são removidas e informadas como avisos de diretiva TTS.

Chaves de diretiva disponíveis:

• 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 do MiniMax, (0, 10])
• pitch (altura inteira do MiniMax, de −12 a 12; valores fracionários são truncados)
• emotion (tag de emoção do Volcengine)
• applyTextNormalization (auto|on|off)
• languageCode (ISO 639-1)
• seed

Desabilitar completamente as substituições pelo modelo:

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

Permitir a troca de provedor mantendo os outros controles configuráveis:

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

Comandos de barra

Comando único /tts. No Discord, o OpenClaw também registra /voice porque /tts é um comando integrado do Discord — o texto /tts ... continua funcionando.

/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>

Observações sobre o comportamento:

• /tts on grava a preferência local de TTS como always; /tts off a grava como off.
• /tts chat on|off|default grava uma substituição de TTS automático no escopo da 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 uma vez como áudio. Ele armazena somente um hash dessa resposta na entrada da sessão para impedir envios de voz duplicados.
• /tts audio gera uma resposta de áudio avulsa (não ativa o TTS).
• /tts limit <chars> aceita 100–4096 (4096 é o máximo de legenda/mensagem do Telegram); valores fora desse intervalo são rejeitados.
• limit e summary são armazenados nas preferências locais, não na configuração principal.
• /tts status inclui diagnósticos de fallback para a tentativa mais recente — Fallback: <primary> -> <used>, Attempts: ... e detalhes por tentativa (provider:outcome(reasonCode) latency).
• /status mostra o modo TTS ativo, além do provedor, modelo, voz e metadados sanitizados do endpoint personalizado configurados quando o TTS está habilitado.

Preferências por usuário

Os comandos de barra gravam substituições locais em prefsPath. O padrão é ~/.openclaw/settings/tts.json; substitua-o pela variável de ambiente OPENCLAW_TTS_PREFS ou por messages.tts.prefsPath.

Esses valores substituem a configuração efetiva de messages.tts junto ao bloco agents.list[].tts ativo para esse host.

Formatos de saída

A entrega de voz TTS é orientada pelos recursos do canal. Os plugins de canal informam se o TTS em estilo de voz deve solicitar aos provedores um destino nativo voice-note ou manter a síntese normal audio-file, e se o canal transcodifica a saída não nativa antes do envio.

Observações por provedor:

• Transcodificação do Feishu / WhatsApp: quando uma resposta de nota de voz chega como MP3/WebM/WAV/M4A ou outro provável arquivo de áudio, o plugin do canal a transcodifica para Ogg/Opus de 48 kHz com ffmpeg (libopus, 64 kbps) antes de enviar a mensagem de voz nativa. O WhatsApp envia o resultado por meio do payload audio do Baileys com ptt: true e audio/ogg; codecs=opus. Em caso de falha na transcodificação: o Feishu captura o erro e recorre ao envio do arquivo original como um anexo comum; o WhatsApp não tem fallback, portanto o próprio envio falha em vez de publicar um payload PTT incompatível.
• MiniMax: MP3 (modelo speech-2.8-hd, taxa de amostragem de 32 kHz) para anexos de áudio normais; transcodificado para Opus de 48 kHz com ffmpeg para destinos de nota de voz anunciados pelo canal.
• Xiaomi MiMo: MP3 por padrão ou WAV quando configurado; transcodificado para Opus de 48 kHz com ffmpeg para destinos de nota de voz anunciados pelo canal.
• 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: retorna PCM bruto de 24 kHz. O OpenClaw o encapsula como WAV para anexos de áudio, transcodifica-o para Opus de 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 normais, 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. Usa o endpoint REST de TTS 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 do provedor. O formato nativo de nota de voz Opus não é compatível.
• 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.
  • Os valores do 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.
  • Quando nenhuma substituição explícita de voz está definida e a voz padrão em inglês é usada, o OpenClaw muda automaticamente para uma voz neural chinesa (zh-CN-XiaoxiaoNeural, localidade zh-CN) se o texto da resposta tiver predominância de CJK.

Os formatos de saída da OpenAI e da ElevenLabs são fixos por canal, conforme listado acima.

Comportamento do TTS automático

Quando messages.tts.auto está habilitado, o OpenClaw:

• Ignora o TTS se a resposta já contiver mídia estruturada.
• Ignora respostas muito curtas (menos de 10 caracteres).
• Resume respostas longas quando os 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 depois que o fluxo de texto é concluído; a mídia gerada passa pela mesma normalização de mídia do canal usada pelos anexos de resposta normais.

Se a resposta exceder maxLength, o OpenClaw nunca ignora o áudio por completo:

• Resumo ativado (padrão) e um modelo de resumo está disponível: resume o texto para aproximadamente maxLength caracteres e, em seguida, sintetiza o resumo.
• Resumo desativado, a geração do resumo falha ou nenhuma chave de API está disponível para o modelo de resumo: trunca o texto para maxLength caracteres e sintetiza o texto truncado.

Resposta -> TTS habilitado?  não -> enviar texto  sim -> contém mídia / é curta?          sim -> enviar texto          não -> tamanho > limite?                   não -> TTS -> anexar áudio                   sim -> resumo habilitado e disponível?                            não -> truncar -> TTS -> anexar áudio                            sim -> resumir -> TTS -> anexar áudio

Referência de campos

Ferramenta do agente

A ferramenta tts converte texto em fala e retorna um anexo de áudio para entrega da resposta. No Feishu, Matrix, Telegram e WhatsApp, o áudio é entregue como mensagem de voz em vez de anexo de arquivo. O Feishu e o WhatsApp podem transcodificar saídas TTS que não sejam Opus nesse fluxo quando ffmpeg estiver disponível.

O WhatsApp envia áudio por meio do Baileys como uma mensagem de voz PTT (audio com ptt: true) e envia o texto visível separadamente do áudio PTT porque os clientes não renderizam legendas de forma consistente em mensagens de voz.

A ferramenta aceita os campos opcionais channel e timeoutMs; timeoutMs é um tempo limite por chamada para a solicitação ao provedor, em milissegundos. Os valores por chamada substituem messages.tts.timeoutMs; os tempos limites configurados para TTS substituem qualquer valor padrão do provedor definido por um plugin.

RPC do Gateway

Links dos serviços

• Guia de conversão de texto em fala da OpenAI
• Referência da API de áudio da OpenAI
• Conversão de texto em fala pela API REST do Azure Speech
• Provedor Azure Speech
• Conversão de texto em fala do ElevenLabs
• Autenticação do ElevenLabs
• Gradium
• API TTS da Inworld
• API T2A v2 da MiniMax
• API HTTP de TTS da Volcengine
• Síntese de fala do Xiaomi MiMo
• node-edge-tts
• Formatos de saída do Microsoft Speech
• Conversão de texto em 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