Texto a voz

OpenClaw convierte las respuestas salientes en audio mediante 14 proveedores de voz: mensajes de voz nativos en Feishu, Matrix, Telegram y WhatsApp; archivos adjuntos de audio en los demás servicios; y transmisiones PCM/Ulaw para telefonía y Talk.

TTS es la parte de salida de voz del modo stt-tts de Talk (talk.speak utiliza esta misma ruta de síntesis). En cambio, las sesiones de Talk realtime nativas del proveedor sintetizan la voz dentro del proveedor en tiempo real; las sesiones transcription nunca sintetizan una respuesta de voz del asistente.

Inicio rápido

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

Proveedores compatibles

Si se configuran varios proveedores, se utiliza primero el seleccionado y los demás sirven como opciones alternativas. El resumen automático utiliza summaryModel (o agents.defaults.model.primary), por lo que ese proveedor también debe estar autenticado si se mantienen habilitados los resúmenes.

Configuración

La configuración de TTS se encuentra en messages.tts, dentro de ~/.openclaw/openclaw.json. Elija un preajuste y adapte el bloque del proveedor. Los campos speakerVoice/speakerVoiceId que aparecen a continuación son los canónicos; los nombres de campo voice/voiceId/ voiceName propios de cada proveedor siguen funcionando como alias heredados.

{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",      // Indicaciones opcionales de estilo en lenguaje natural:      // audioProfile: "Habla con un tono sereno de presentador de pódcast.",      // 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, omita speakerVoice y establezca style en la indicación de diseño de voz. OpenClaw envía esa indicación como mensaje user de TTS y no envía audio.voice para el modelo de diseño de voz.

Sustituciones de voz por agente

Use agents.list[].tts cuando un agente deba hablar con un proveedor, una voz, un modelo, una persona o un modo de TTS automático diferentes. El bloque del agente se combina en profundidad sobre messages.tts, por lo 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, establezca agents.list[].tts.persona junto con la configuración del proveedor; esta sustituye el valor global de messages.tts.persona solo para ese agente.

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

1. messages.tts
2. agents.list[].tts activo
3. sustitución del canal, cuando el canal admite channels.<channel>.tts
4. sustitución de la cuenta, cuando el canal transmite channels.<channel>.accounts.<id>.tts
5. preferencias locales de /tts para este host
6. directivas [[tts:...]] insertadas cuando las sustituciones controladas por el modelo están habilitadas

Las sustituciones de canal y cuenta usan la misma estructura que messages.tts y se combinan en profundidad sobre las capas anteriores, por lo que las credenciales compartidas del proveedor pueden permanecer en messages.tts, mientras un canal o una cuenta de bot cambia únicamente 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 oral estable que puede aplicarse de forma determinista entre proveedores. Puede dar preferencia a un proveedor, definir una intención de instrucción independiente del proveedor y contener vinculaciones específicas del proveedor para voces, modelos, plantillas de instrucciones, 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 (instrucción independiente 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 la persona

La persona activa se selecciona de forma determinista:

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

La selección del proveedor prioriza los valores explícitos:

1. Sustituciones directas (CLI, Gateway, Talk y directivas TTS permitidas).
2. Preferencia local de /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 combina las configuraciones en este orden:

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

Cómo usan los proveedores las instrucciones de persona

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

Política de respaldo

fallbackPolicy controla el comportamiento cuando una persona no tiene ninguna vinculación para el proveedor que se intenta usar:

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

La selección del proveedor de una sesión de Talk se limita a la sesión. Un cliente de Talk debe elegir los identificadores de proveedor, modelo y voz, así como las configuraciones regionales, desde talk.catalog y transmitirlos mediante la solicitud de sesión o transferencia de Talk. Abrir una sesión de voz no debe modificar 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 sustituir la voz, el modelo o la velocidad en una sola respuesta, además de un bloque opcional [[tts:text]]...[[/tts:text]] para indicaciones expresivas que solo deben aparecer en el audio:

Aquí está. [[tts:speakerVoiceId=pMsXgVXv3BLzUgSXRplE model=eleven_v3 speed=1.1]][[tts:text]](se ríe) Lee la canción una vez más.[[/tts:text]]

Cuando messages.tts.auto es "tagged", las directivas son obligatorias para activar el audio. La entrega de bloques por streaming elimina las directivas del texto visible antes de que el canal las reciba, 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 solo las analiza ese proveedor; las claves no compatibles se eliminan y se notifican como advertencias de directivas TTS.

Claves de directiva disponibles:

• provider (identificador 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, de −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 sustituciones del modelo:

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

Permitir el cambio de proveedor y mantener configurables los demás controles:

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

Comandos con 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 local de TTS en always; /tts off la escribe en off.
• /tts chat on|off|default escribe una sustitución de TTS automático 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 respuesta más reciente del asistente de la transcripción de la sesión actual y la envía una vez como audio. Solo almacena un hash de esa respuesta en la entrada de la sesión para impedir envíos de voz duplicados.
• /tts audio genera una respuesta de audio puntual (no activa TTS).
• /tts limit <chars> acepta 100–4096 (4096 es el máximo de caracteres para mensajes o pies de foto de Telegram); los valores fuera de ese intervalo se rechazan.
• limit y summary se almacenan en las preferencias locales, no en la configuración principal.
• /tts status incluye diagnósticos de respaldo del intento más reciente: Fallback: <primary> -> <used>, Attempts: ... y detalles de cada intento (provider:outcome(reasonCode) latency).
• /status muestra el modo TTS activo, además del proveedor, el modelo, la voz y los metadatos saneados del endpoint personalizado configurados cuando TTS está habilitado.

Preferencias por usuario

Los comandos con barra escriben sustituciones locales en prefsPath. El valor predeterminado es ~/.openclaw/settings/tts.json; puede sustituirse con la variable de entorno OPENCLAW_TTS_PREFS o messages.tts.prefsPath.

Estos valores anulan la configuración efectiva de messages.tts junto con el bloque agents.list[].tts activo para ese host.

Formatos de salida

La entrega de voz mediante TTS depende de las capacidades del canal. Los plugins de canal anuncian si el TTS de tipo voz debe solicitar a los proveedores un destino voice-note nativo o mantener la síntesis audio-file normal, y si el canal transcodifica la salida no nativa antes de enviarla.

Notas por proveedor:

• Transcodificación de Feishu / WhatsApp: cuando una respuesta en forma de nota de voz llega como MP3/WebM/WAV/M4A u otro archivo que probablemente sea de audio, el plugin de canal la transcodifica a Ogg/Opus de 48 kHz con ffmpeg (libopus, 64 kbps) 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 falla la transcodificación, Feishu detecta el error y recurre al envío del archivo original como un archivo adjunto normal; WhatsApp no dispone de alternativa, por lo que el propio envío falla en lugar de publicar una carga útil PTT incompatible.
• MiniMax: MP3 (modelo speech-2.8-hd, frecuencia de muestreo de 32 kHz) para archivos adjuntos de audio normales; se transcodifica a Opus de 48 kHz con ffmpeg para destinos de notas de voz anunciados por el canal.
• Xiaomi MiMo: MP3 de forma predeterminada, o WAV cuando está configurado; se transcodifica a Opus de 48 kHz con ffmpeg para destinos de notas de voz anunciados por el canal.
• CLI local: utiliza el valor 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: devuelve PCM sin procesar de 24 kHz. OpenClaw lo encapsula como WAV para archivos adjuntos de audio, lo transcodifica a Opus de 48 kHz para destinos de notas de voz y devuelve PCM directamente para Conversación/telefonía.
• Gradium: WAV para archivos adjuntos de audio, Opus para destinos de notas de voz y ulaw_8000 a 8 kHz para telefonía.
• Inworld: MP3 para archivos adjuntos de audio normales, OGG_OPUS nativo para destinos de notas de voz y PCM sin procesar a 22050 Hz para Conversación/telefonía.
• xAI: MP3 de forma predeterminada; la síntesis de archivos de audio puede utilizar mp3, wav, pcm, mulaw o alaw tanto para la salida almacenada en búfer como para la salida en streaming. Los destinos de notas de voz utilizan MP3 para el streaming y la alternativa almacenada en búfer porque las salidas pcm, mulaw y alaw de xAI son audio sin procesar y sin encabezado. La síntesis almacenada en búfer utiliza el endpoint REST por lotes /v1/tts de xAI; textToSpeechStream utiliza wss://api.x.ai/v1/tts nativo. Este no es el contrato de voz en tiempo real. No se admite el formato de nota de voz Opus nativo.
• Microsoft: utiliza microsoft.outputFormat (valor predeterminado: audio-24khz-48kbitrate-mono-mp3).
  • El transporte incluido acepta un valor outputFormat, pero el servicio no ofrece todos los formatos.
  • Los valores del formato de salida siguen los formatos de salida de Microsoft Speech (incluidos Ogg/WebM Opus).
  • El valor sendVoice de Telegram acepta OGG/MP3/M4A; utilice OpenAI/ElevenLabs si necesita garantizar mensajes de voz Opus.
  • Si falla el formato de salida de Microsoft configurado, OpenClaw vuelve a intentarlo con MP3.
  • Cuando no se establece una anulación explícita de la voz y se utiliza la voz predeterminada en inglés, OpenClaw cambia automáticamente a una voz neuronal en chino (zh-CN-XiaoxiaoNeural, configuración regional zh-CN) si el texto de la respuesta es predominantemente CJK.

Los formatos de salida de OpenAI y ElevenLabs son fijos para cada canal, tal como se indica anteriormente.

Comportamiento de TTS automático

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

• Omite TTS si la respuesta ya contiene contenido multimedia estructurado.
• Omite las respuestas muy cortas (menos de 10 caracteres).
• Resume las respuestas largas cuando los resúmenes están habilitados, mediante summaryModel (o agents.defaults.model.primary).
• Adjunta el audio generado a la respuesta.
• En mode: "final", sigue enviando TTS de solo audio para las respuestas finales transmitidas después de que finaliza la transmisión de texto; el contenido multimedia generado pasa por la misma normalización de contenido multimedia del canal que los archivos adjuntos normales de las respuestas.

Si la respuesta supera maxLength, OpenClaw nunca omite el audio por completo:

• Resumen activado (valor predeterminado) y hay un modelo de resumen disponible: resume el texto a aproximadamente maxLength caracteres y, a continuación, sintetiza el resumen.
• Resumen desactivado, el resumen falla o no hay ninguna clave de API disponible para el modelo de resumen: trunca el texto a maxLength caracteres y sintetiza el texto truncado.

Respuesta -> ¿TTS habilitado?  no  -> enviar texto  sí  -> ¿contiene contenido multimedia / es corta?          sí  -> enviar texto          no  -> ¿longitud > límite?                   no  -> TTS -> adjuntar audio                   sí  -> ¿resumen habilitado y disponible?                            no  -> truncar -> TTS -> adjuntar audio                            sí  -> resumir -> TTS -> adjuntar audio

Referencia de campos

Herramienta del agente

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

WhatsApp envía el audio mediante 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 muestran de forma uniforme los subtítulos en las notas de voz.

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

RPC del Gateway

Enlaces de servicios

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

Contenido relacionado

• Descripción general de medios
• Generación de música
• Generación de vídeo
• Comandos con barra diagonal
• Plugin de llamadas de voz