Texto a voz

OpenClaw puede convertir respuestas salientes en audio con 14 proveedores de voz y entregar mensajes de voz nativos en Feishu, Matrix, Telegram y WhatsApp, archivos de audio adjuntos en los demás lugares, y flujos PCM/Ulaw para telefonía y Talk.

TTS es la mitad de salida de voz del modo stt-tts de Talk. Las sesiones Talk realtime nativas del proveedor sintetizan voz dentro del proveedor en tiempo real en lugar de llamar a esta ruta de TTS, mientras que las sesiones transcription no sintetizan una respuesta de voz del asistente.

Inicio rápido

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

Proveedores compatibles

Si hay varios proveedores configurados, se usa primero el seleccionado y los demás quedan como opciones de respaldo. El resumen automático usa summaryModel (o agents.defaults.model.primary), por lo que ese proveedor también debe estar autenticado si mantienes los resúmenes habilitados.

Configuración

La configuración de TTS está en messages.tts dentro de ~/.openclaw/openclaw.json. Elige un preset y adapta el bloque del proveedor:

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

Para Xiaomi mimo-v2.5-tts-voicedesign, omite speakerVoice y define style como el prompt de diseño de voz. OpenClaw envía ese prompt como el mensaje TTS user y no envía audio.voice para el modelo voicedesign.

Sobrescrituras de voz por agente

Usa agents.list[].tts cuando un agente deba hablar con un proveedor, voz, modelo, persona o modo auto-TTS diferente. El bloque del agente se fusiona en profundidad sobre messages.tts, de modo que las credenciales del proveedor pueden permanecer en la configuración global del proveedor:

{  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 fijar una persona por agente, define agents.list[].tts.persona junto con la configuración del proveedor; anula messages.tts.persona global solo para ese agente.

Orden de precedencia para respuestas automáticas, /tts audio, /tts status y la herramienta de agente tts:

1. messages.tts
2. agents.list[].tts activo
3. anulación de canal, cuando el canal admite channels.<channel>.tts
4. anulación de cuenta, cuando el canal pasa channels.<channel>.accounts.<id>.tts
5. preferencias locales de /tts para este host
6. directivas en línea [[tts:...]] cuando las anulaciones del modelo están habilitadas

Las anulaciones de canal y cuenta usan la misma forma que messages.tts y se fusionan en profundidad sobre las capas anteriores, de modo que las credenciales compartidas del proveedor pueden permanecer en messages.tts mientras un canal o una cuenta de bot cambia solo la voz del hablante, el modelo, la persona o el 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

Una persona es una identidad hablada estable que puede aplicarse de forma determinista entre proveedores. Puede preferir un proveedor, definir intención de prompt neutral respecto del proveedor y llevar enlaces específicos del proveedor para voces, modelos, plantillas de prompt, semillas y ajustes 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 neutral respecto del proveedor)

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

Resolución de persona

La persona activa se selecciona de forma determinista:

1. Preferencia local /tts persona <id>, si está definida.
2. messages.tts.persona, si está definida.
3. Sin persona.

La selección de proveedor se ejecuta con prioridad explícita:

1. Anulaciones directas (CLI, Gateway, Talk, directivas TTS permitidas).
2. Preferencia local /tts provider <id>.
3. provider de la persona activa.
4. messages.tts.provider.
5. Selección automática del registro.

Para cada intento de proveedor, OpenClaw fusiona las configuraciones en este orden:

1. messages.tts.providers.<id>
2. messages.tts.personas.<persona>.providers.<id>
3. Anulaciones de solicitud de confianza
4. Anulaciones permitidas de directivas TTS emitidas por el modelo

Cómo usan los proveedores los prompts de persona

Los campos de prompt de persona (profile, scene, sampleContext, style, accent, pacing, constraints) son neutrales respecto del proveedor. Cada proveedor decide cómo usarlos:

Política de fallback

fallbackPolicy controla el comportamiento cuando una persona no tiene enlace para el proveedor intentado:

La solicitud TTS completa solo falla cuando todos los proveedores intentados se omiten o fallan.

La selección de proveedor de sesión de Talk está limitada a la sesión. Un cliente Talk debe elegir ids de proveedor, ids de modelo, ids de voz y configuraciones regionales desde talk.catalog y pasarlos a través de la sesión Talk o la solicitud de traspaso. Abrir una sesión de voz no debe mutar messages.tts ni los valores predeterminados globales del proveedor de Talk.

Directivas controladas por el modelo

De forma predeterminada, el asistente puede emitir directivas [[tts:...]] para anular voz, modelo o velocidad para una sola respuesta, además de un bloque opcional [[tts:text]]...[[/tts:text]] para señales expresivas que solo deben aparecer en el audio:

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

Cuando messages.tts.auto es "tagged", se requieren directivas para activar audio. La entrega de bloques en streaming elimina las directivas del texto visible antes de que el canal las vea, incluso cuando están divididas entre bloques adyacentes.

provider=... se ignora salvo que modelOverrides.allowProvider: true. Cuando una respuesta declara provider=..., las demás claves de esa directiva son analizadas solo por ese proveedor; las claves no admitidas se eliminan y se reportan como advertencias de directiva TTS.

Claves de directiva disponibles:

• provider (id de proveedor registrado; requiere allowProvider: true)
• speakerVoice / speakerVoiceId (alias heredados: voice, voiceName, voice_name, google_voice, voiceId)
• model / google_model
• stability, similarityBoost, style, speed, useSpeakerBoost
• vol / volume (volumen de MiniMax, 0-10)
• pitch (tono entero de MiniMax, -12 a 12; los valores fraccionarios se truncan)
• emotion (etiqueta de emoción de Volcengine)
• applyTextNormalization (auto|on|off)
• languageCode (ISO 639-1)
• seed

Deshabilitar por completo las anulaciones del modelo:

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

Permitir el cambio de proveedor mientras se mantienen configurables otros controles:

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

Comandos de barra

Comando único /tts. En Discord, OpenClaw también registra /voice porque /tts es un comando integrado de Discord; el texto /tts ... sigue 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>

Notas de comportamiento:

• /tts on escribe la preferencia TTS local en always; /tts off la escribe en off.
• /tts chat on|off|default escribe una anulación auto-TTS limitada a la sesión para el chat actual.
• /tts persona <id> escribe la preferencia local de persona; /tts persona off la borra.
• /tts latest lee la última respuesta del asistente de la transcripción de la sesión actual y la envía como audio una vez. Solo almacena un hash de esa respuesta en la entrada de sesión para suprimir envíos de voz duplicados.
• /tts audio genera una respuesta de audio puntual (no activa TTS).
• limit y summary se almacenan en preferencias locales, no en la configuración principal.
• /tts status incluye diagnósticos de fallback para el último intento: Fallback: <primary> -> <used>, Attempts: ... y detalle por intento (provider:outcome(reasonCode) latency).
• /status muestra el modo TTS activo más el proveedor, modelo, voz y metadatos saneados de endpoint personalizado configurados cuando TTS está habilitado.

Preferencias por usuario

Los comandos de barra escriben anulaciones locales en prefsPath. El valor predeterminado es ~/.openclaw/settings/tts.json; anúlalo con la variable de entorno OPENCLAW_TTS_PREFS o messages.tts.prefsPath.

Estos anulan la configuración efectiva de messages.tts más el bloque agents.list[].tts activo para ese host.

Formatos de salida (fijos)

La entrega de voz TTS se basa en las capacidades del canal. Los Plugins de canal anuncian si TTS de estilo voz debe pedir a los proveedores un destino nativo voice-note o mantener la síntesis normal audio-file y solo marcar la salida compatible para la entrega de voz.

• Canales compatibles con notas de voz: las respuestas de notas de voz prefieren Opus (opus_48000_64 de ElevenLabs, opus de OpenAI).
  • 48 kHz / 64 kbps es un buen equilibrio para mensajes de voz.
• Feishu / WhatsApp: cuando una respuesta de nota de voz se produce como MP3/WebM/WAV/M4A u otro archivo probablemente de audio, el Plugin de canal lo transcodifica a Ogg/Opus de 48 kHz con ffmpeg antes de enviar el mensaje de voz nativo. WhatsApp envía el resultado mediante la carga útil audio de Baileys con ptt: true y audio/ogg; codecs=opus. Si la conversión falla, Feishu recibe el archivo original como adjunto; el envío de WhatsApp falla en lugar de publicar una carga útil PTT incompatible.
• Otros canales: MP3 (mp3_44100_128 de ElevenLabs, mp3 de OpenAI).
  • 44,1 kHz / 128 kbps es el equilibrio predeterminado para la claridad del habla.
• MiniMax: MP3 (modelo speech-2.8-hd, frecuencia de muestreo de 32 kHz) para adjuntos de audio normales. Para destinos de notas de voz anunciados por el canal, OpenClaw transcodifica el MP3 de MiniMax a Opus de 48 kHz con ffmpeg antes de la entrega cuando el canal anuncia transcodificación.
• Xiaomi MiMo: MP3 de forma predeterminada, o WAV cuando se configura. Para destinos de notas de voz anunciados por el canal, OpenClaw transcodifica la salida de Xiaomi a Opus de 48 kHz con ffmpeg antes de la entrega cuando el canal anuncia transcodificación.
• CLI local: usa el outputFormat configurado. Los destinos de notas de voz se convierten a Ogg/Opus y la salida de telefonía se convierte a PCM mono sin procesar de 16 kHz con ffmpeg.
• Google Gemini: la TTS de la API Gemini devuelve PCM sin procesar de 24 kHz. OpenClaw lo envuelve como WAV para adjuntos de audio, lo transcodifica a Opus de 48 kHz para destinos de notas de voz y devuelve PCM directamente para Talk/telefonía.
• Gradium: WAV para adjuntos de audio, Opus para destinos de notas de voz y ulaw_8000 a 8 kHz para telefonía.
• Inworld: MP3 para adjuntos de audio normales, OGG_OPUS nativo para destinos de notas de voz y PCM sin procesar a 22050 Hz para Talk/telefonía.
• xAI: MP3 de forma predeterminada; responseFormat puede ser mp3, wav, pcm, mulaw o alaw. OpenClaw usa el endpoint TTS REST por lotes de xAI y devuelve un adjunto de audio completo; el WebSocket de TTS en streaming de xAI no se usa en esta ruta de proveedor. Esta ruta no admite el formato nativo Opus para notas de voz.
• Microsoft: usa microsoft.outputFormat (predeterminado audio-24khz-48kbitrate-mono-mp3).
  • El transporte incluido acepta un outputFormat, pero no todos los formatos están disponibles en el servicio.
  • Los valores de formato de salida siguen los formatos de salida de Microsoft Speech (incluido Ogg/WebM Opus).
  • sendVoice de Telegram acepta OGG/MP3/M4A; usa OpenAI/ElevenLabs si necesitas mensajes de voz Opus garantizados.
  • Si falla el formato de salida de Microsoft configurado, OpenClaw reintenta con MP3.

Los formatos de salida de OpenAI/ElevenLabs son fijos por canal (consulta arriba).

Comportamiento de TTS automático

Cuando messages.tts.auto está habilitado, OpenClaw:

• Omite TTS si la respuesta ya contiene medios estructurados.
• Omite respuestas muy cortas (menos de 10 caracteres).
• Resume respuestas largas cuando los resúmenes están habilitados, usando summaryModel (o agents.defaults.model.primary).
• Adjunta el audio generado a la respuesta.
• En mode: "final", sigue enviando TTS solo de audio para respuestas finales en streaming después de que se completa el flujo de texto; los medios generados pasan por la misma normalización de medios del canal que los adjuntos de respuesta normales.

Si la respuesta supera maxLength y el resumen está desactivado (o no hay clave de API para el modelo de resumen), se omite el audio y se envía la respuesta de texto normal.

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 salida por canal

Notas por proveedor:

• Transcodificación de Feishu / WhatsApp: cuando una respuesta de nota de voz llega como MP3/WebM/WAV/M4A, el Plugin de canal la transcodifica a Ogg/Opus de 48 kHz con ffmpeg. WhatsApp envía mediante Baileys con ptt: true y audio/ogg; codecs=opus. Si la conversión falla: Feishu recurre a adjuntar el archivo original; el envío de WhatsApp falla en lugar de publicar una carga útil PTT incompatible.
• MiniMax / Xiaomi MiMo: MP3 predeterminado (32 kHz para MiniMax speech-2.8-hd); transcodificado a Opus de 48 kHz para destinos de notas de voz mediante ffmpeg.
• CLI local: usa el outputFormat configurado. Los destinos de notas de voz se convierten a Ogg/Opus y la salida de telefonía a PCM mono sin procesar de 16 kHz.
• Google Gemini: devuelve PCM sin procesar de 24 kHz. OpenClaw lo envuelve como WAV para adjuntos, lo transcodifica a Opus de 48 kHz para destinos de notas de voz y devuelve PCM directamente para Talk/telefonía.
• Inworld: adjuntos MP3, nota de voz OGG_OPUS nativa, PCM sin procesar de 22050 Hz para Talk/telefonía.
• xAI: MP3 de forma predeterminada; responseFormat puede ser mp3|wav|pcm|mulaw|alaw. Usa el endpoint REST por lotes de xAI; la TTS por WebSocket en streaming no se usa. El formato nativo Opus para notas de voz no es compatible.
• Microsoft: usa microsoft.outputFormat (predeterminado audio-24khz-48kbitrate-mono-mp3). sendVoice de Telegram acepta OGG/MP3/M4A; usa OpenAI/ElevenLabs si necesitas mensajes de voz Opus garantizados. Si falla el formato de Microsoft configurado, OpenClaw reintenta con MP3.

Los formatos de salida de OpenAI y ElevenLabs son fijos por canal como se indica arriba.

Referencia de campos

Herramienta de agente

La herramienta tts convierte texto a voz y devuelve un adjunto de audio para la entrega de respuestas. En Feishu, Matrix, Telegram y WhatsApp, el audio se entrega como mensaje de voz en lugar de como adjunto de archivo. Feishu y WhatsApp pueden transcodificar la salida TTS que no sea Opus en esta ruta cuando ffmpeg está disponible.

WhatsApp envía audio a través de Baileys como una nota de voz PTT (audio con ptt: true) y envía el texto visible por separado del audio PTT porque los clientes no siempre renderizan subtítulos en las notas de voz.

La herramienta acepta los campos opcionales channel y timeoutMs; timeoutMs es un tiempo de espera de solicitud al proveedor por llamada en milisegundos. Los valores por llamada sobrescriben messages.tts.timeoutMs; los tiempos de espera TTS configurados sobrescriben cualquier valor predeterminado de proveedor creado por un Plugin.

RPC de Gateway

Enlaces de servicio

• Guía de texto a voz de OpenAI
• Referencia de la API de audio de OpenAI
• Texto a voz REST de Azure Speech
• Proveedor Azure Speech
• Texto a voz de ElevenLabs
• Autenticación de ElevenLabs
• Gradium
• API TTS de Inworld
• API MiniMax T2A v2
• API HTTP TTS de Volcengine
• Síntesis de voz de Xiaomi MiMo
• node-edge-tts
• Formatos de salida de Microsoft Speech
• Texto a voz de xAI

Relacionado

• Resumen de medios
• Generación de música
• Generación de video
• Comandos slash
• Plugin de llamada de voz