Conversão de texto em 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",
          // Prompts opcionais de estilo em linguagem natural:
          // audioProfile: "Fale em um tom calmo, como 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",
        },
      },
    },
  },
}

​

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 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 orientadas pelo 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: "Narrador",
          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: "Narrador mordomo britânico, espirituoso e acolhedor.",
          provider: "google",
          fallbackPolicy: "preserve-persona",
          prompt: {
            profile: "Um mordomo britânico brilhante. Espirituoso, sagaz, acolhedor, encantador, emocionalmente expressivo, nunca genérico.",
            scene: "Um escritório silencioso tarde da noite. Narração com microfone próximo para um operador de confiança.",
            sampleContext: "O locutor está respondendo a uma solicitação técnica privada com confiança concisa e cordialidade espirituosa.",
            style: "Refinado, discreto, levemente divertido.",
            accent: "Inglês britânico.",
            pacing: "Cadenciado, com breves pausas dramáticas.",
            constraints: ["Não leia valores de configuração em voz alta.", "Não explique a 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

1. Preferência local de /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 de /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ções confiáveis
4. Substituições de diretivas TTS permitidas emitidas pelo modelo

​

Como os provedores usam prompts de persona

​

Política de fallback

​

Diretivas orientadas pelo modelo

Aqui está.

[[tts:speakerVoiceId=pMsXgVXv3BLzUgSXRplE model=eleven_v3 speed=1.1]]
[[tts:text]](risos) Leia a música mais uma vez.[[/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 do MiniMax, (0, 10])
• pitch (tom inteiro do MiniMax, −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

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

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

​

Comandos de barra

/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 em always; /tts off a grava em off.
• /tts chat on|off|default grava uma substituição de TTS automático restrita à 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 da 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

​

Formatos de saída

• Transcodificação do Feishu / WhatsApp: quando uma resposta em mensagem de voz chega como MP3/WebM/WAV/M4A ou outro arquivo que provavelmente seja 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 pelo 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 mensagem 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 mensagem de voz anunciados pelo canal.
• 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: 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 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; a síntese de arquivos de áudio pode usar mp3, wav, pcm, mulaw ou alaw tanto para saída armazenada em buffer quanto para saída por streaming. Os destinos de mensagem de voz usam MP3 para streaming e fallback com buffer porque as saídas pcm, mulaw e alaw da xAI são áudio bruto sem cabeçalho. A síntese com buffer usa o endpoint REST em lote /v1/tts da xAI; textToSpeechStream usa wss://api.x.ai/v1/tts nativo. Esse não é o contrato de voz em tempo real. O formato Opus nativo para mensagens de voz 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.

​

Comportamento do TTS automático

• Ignora o TTS se a resposta já contiver mídia estruturada.
• Ignora respostas muito curtas (com 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 em áudio para respostas finais transmitidas por streaming após a conclusão do fluxo de texto; a mídia gerada passa pela mesma normalização de mídia do canal que os anexos normais de resposta.

• Resumo ativado (padrão) e há um modelo de resumo 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 dos campos

​

Ferramenta do agente

​

RPC do Gateway

​

Links de 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 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 do Xiaomi MiMo
• node-edge-tts
• Formatos de saída de fala da Microsoft
• 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