Conversão de texto em fala

OpenClaw pode converter respostas de saída em áudio em 14 provedores de fala e entregar mensagens de voz nativas no Feishu, Matrix, Telegram e WhatsApp, anexos de áudio em todos os outros lugares e streams PCM/Ulaw para telefonia e Talk.

TTS é a metade de saída de fala do modo stt-tts do Talk. Sessões Talk realtime nativas do provedor sintetizam fala dentro do provedor em tempo real em vez de chamar este caminho de TTS, enquanto sessões transcription não 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 é usado primeiro e os outros são opções de fallback. O resumo automático usa summaryModel (ou agents.defaults.model.primary), então esse provedor também precisa estar autenticado se você mantiver resumos habilitados.

# Configuração

A configuração de TTS fica em messages.tts em ~/.openclaw/openclaw.json. Escolha uma predefinição e adapte o bloco do provedor:

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

# Substituições de voz por agente

Use agents.list[].tts quando um agente deve falar com um provedor, voz, modelo, persona ou modo Auto-TTS diferente. O bloco do agente faz uma mesclagem profunda sobre messages.tts, então 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: { voiceId: "EXAVITQu4vr4xnSDxMaL" },
          },
        },
      },
    ],
  },
}

Para fixar uma persona por agente, defina agents.list[].tts.persona junto com a configuração do provedor — ela substitui a messages.tts.persona global apenas 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 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 embutidas [[tts:...]] quando substituições de modelo estão habilitadas

Substituições de canal e conta usam o mesmo formato de messages.tts e fazem mesclagem profunda sobre as camadas anteriores, para que credenciais compartilhadas de provedor possam permanecer em messages.tts enquanto um canal ou conta de bot altera apenas a voz, 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: { voice: "shimmer" },
            },
          },
        },
      },
    },
  },
}

# Personas

Uma persona é uma identidade falada estável que pode ser aplicada deterministicamente entre provedores. Ela pode preferir um provedor, definir uma intenção de prompt neutra em relação ao provedor e carregar associações específicas de provedor para vozes, modelos, modelos de prompt, sementes e configurações de voz.

# Persona mínima

{
  messages: {
    tts: {
      auto: "always",
      persona: "narrator",
      personas: {
        narrator: {
          label: "Narrator",
          provider: "elevenlabs",
          providers: {
            elevenlabs: { voiceId: "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",
              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,
              },
            },
          },
        },
      },
    },
  },
}

# Resolução da persona

A persona ativa é selecionada deterministicamente:

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

A seleção de provedor executa primeiro as opções explícitas:

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.

Para cada tentativa de provedor, o OpenClaw mescla 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 de diretivas TTS emitidas pelo modelo

# Como os provedores usam prompts de persona

Os campos de prompt de persona (profile, scene, sampleContext, style, accent, pacing, constraints) são neutros em relação ao provedor. Cada provedor decide como usá-los:

# Política de contingência

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

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

A seleção de provedor da sessão Talk tem escopo de sessão. Um cliente Talk deve escolher ids de provedor, ids de modelo, ids de voz e localidades a partir de talk.catalog e passá-los pela sessão Talk ou pela solicitação de transferência. Abrir uma sessão de voz não deve alterar messages.tts nem os padrões globais de provedor Talk.

# Diretivas orientadas por modelo

Por padrão, o assistente pode emitir diretivas [[tts:...]] para substituir voz, modelo ou 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:

Here you go.

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

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

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

Chaves de diretiva disponíveis:

• provider (id de provedor registrado; requer allowProvider: true)
• voice / voiceName / voice_name / google_voice / voiceId
• model / google_model
• stability, similarityBoost, style, speed, useSpeakerBoost
• vol / volume (volume do MiniMax, 0-10)
• pitch (tom inteiro do 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

Desativar completamente as substituições de modelo:

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

Permitir troca de provedor mantendo 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 — texto /tts ... ainda funciona.

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

Notas de 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 auto-TTS com escopo de 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 somente 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 ativa o TTS).
• limit e summary são armazenados em 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 detalhes por tentativa (provider:outcome(reasonCode) latency).
• /status mostra o modo TTS ativo, além de provedor, modelo, voz e metadados sanitizados de endpoint personalizado configurados quando o TTS está habilitado.

# Preferências por usuário

Comandos de barra gravam substituições locais em prefsPath. O padrão é ~/.openclaw/settings/tts.json; substitua com a variável de ambiente OPENCLAW_TTS_PREFS ou messages.tts.prefsPath.

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

# Formatos de saída (fixos)

A entrega de voz TTS é orientada pelos recursos do canal. Plugins de canal anunciam se o TTS em estilo de voz deve pedir aos provedores um destino nativo voice-note ou manter a síntese normal de audio-file e apenas marcar a saída compatível para entrega de voz.

• Canais compatíveis com mensagens de voz: respostas em mensagem 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 em mensagem 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 pelo payload audio do 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.
• BlueBubbles: mantém a síntese do provedor no caminho normal de arquivo de áudio; saídas MP3 e CAF são marcadas para entrega como memo de voz do iMessage.
• 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 normais. Para destinos de mensagem 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 mensagem 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 mensagem 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: a TTS da API Gemini retorna PCM bruto de 24 kHz. O OpenClaw o encapsula como WAV para anexos de áudio, o transcodifica para Opus a 48 kHz para destinos de mensagem de voz e retorna PCM diretamente para Talk/telefonia.
• Gradium: WAV para anexos de áudio, Opus para destinos de mensagem de voz e ulaw_8000 a 8 kHz para telefonia.
• Inworld: MP3 para anexos de áudio normais, OGG_OPUS nativo para destinos de mensagem 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 em streaming da xAI não é usado por este caminho de provedor. O formato Opus nativo para mensagens 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.
  • Os 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.

Os formatos de saída da OpenAI/ElevenLabs são fixos por canal (veja acima).

# Comportamento de TTS automático

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

• Ignora TTS se a resposta já contém mídia ou uma diretiva MEDIA:.
• 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 em áudio para respostas finais transmitidas por streaming após o fluxo de texto ser concluído; a mídia gerada passa pela mesma normalização de mídia do canal que anexos de resposta normais.

Se a resposta exceder maxLength e o resumo estiver desativado (ou não houver chave de API para o modelo de resumo), o áudio será ignorado e a resposta de texto normal será enviada.

Reply -> TTS enabled?
  no  -> send text
  yes -> has media / 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

Observações por provedor:

• Transcodificação Feishu / WhatsApp: Quando uma resposta em nota de voz chega como MP3/WebM/WAV/M4A, o Plugin do canal transcodifica para Ogg/Opus a 48 kHz com ffmpeg. WhatsApp envia por meio do Baileys com ptt: true e audio/ogg; codecs=opus. Se a conversão falhar: Feishu recorre a anexar o arquivo original; o envio pelo WhatsApp falha em vez de publicar uma carga 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. OpenClaw encapsula como WAV para anexos, transcodifica para Opus a 48 kHz para destinos de nota de voz, retorna PCM diretamente para Talk/telefonia.
• Inworld: Anexos MP3, nota de voz nativa OGG_OPUS, 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 nativo Opus para 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 Microsoft configurado falhar, OpenClaw tenta novamente com MP3.

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

# 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. Feishu e WhatsApp podem transcodificar a saída de TTS que não seja Opus nesse caminho quando ffmpeg está disponível.

O WhatsApp envia áudio pelo Baileys como uma nota 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 notas de voz.

A ferramenta aceita os campos opcionais channel e timeoutMs; timeoutMs é um tempo limite de solicitação do provedor por chamada em milissegundos.

# 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 de TTS da Inworld
• API MiniMax T2A v2
• API HTTP de TTS da Volcengine
• Síntese de fala Xiaomi MiMo
• node-edge-tts
• Formatos de saída do Microsoft Speech
• Texto para fala da xAI

# Relacionado

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