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 casos; y transmisiones PCM/Ulaw para telefonía y Talk.

TTS es la mitad de salida de voz del modo stt-tts de Talk (talk.speak utiliza esta misma ruta de síntesis). 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

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

Proveedores compatibles

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

Configuración

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

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

{tts: {auto: "always",provider: "elevenlabs",providers: {  elevenlabs: {    apiKey: "${ELEVENLABS_API_KEY}",    model: "eleven_multilingual_v2",    speakerVoiceId: "EXAVITQu4vr4xnSDxMaL",  },},},}

{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 tranquilo, como quien presenta un pódcast.",    // speakerName: "Alex",  },},},}

{tts: {auto: "always",provider: "gradium",providers: {  gradium: {    apiKey: "${GRADIUM_API_KEY}",    speakerVoiceId: "YTpq7expH9539ERJ",  },},},}

{tts: {auto: "always",provider: "inworld",providers: {  inworld: {    apiKey: "${INWORLD_API_KEY}",    modelId: "inworld-tts-1.5-max",    speakerVoiceId: "Sarah",    temperature: 0.7,  },},},}

{tts: {auto: "always",provider: "tts-local-cli",providers: {  "tts-local-cli": {    command: "say",    args: ["-o", "{{OutputPath}}", "{{Text}}"],    outputFormat: "wav",    timeoutMs: 120000,  },},},}

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

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

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

{tts: {auto: "always",provider: "openrouter",providers: {  openrouter: {    apiKey: "${OPENROUTER_API_KEY}",    model: "hexgrad/kokoro-82m",    speakerVoice: "af_alloy",    responseFormat: "mp3",  },},},}

{tts: {auto: "always",provider: "volcengine",providers: {  volcengine: {    apiKey: "${VOLCENGINE_TTS_API_KEY}",    resourceId: "seed-tts-1.0",    speakerVoice: "en_female_anna_mars_bigtts",  },},},}

{tts: {auto: "always",provider: "xai",providers: {  xai: {    apiKey: "${XAI_API_KEY}",    speakerVoiceId: "eve",    language: "en",    responseFormat: "mp3",  },},},}

{tts: {auto: "always",provider: "xiaomi",providers: {  xiaomi: {    apiKey: "${XIAOMI_API_KEY}",    model: "mimo-v2.5-tts",    speakerVoice: "mimo_default",    format: "mp3",  },},},}

Para mimo-v2.5-tts-voicedesign de Xiaomi, omita speakerVoice y establezca style con 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 voicedesign.

Reemplazos de voz por agente

Utilice agents.entries.*.tts cuando un agente deba hablar con un proveedor, una voz, un modelo, una personalidad o un modo de TTS automático distintos. El bloque del agente se combina de forma profunda sobre tts, por lo que las credenciales del proveedor pueden permanecer en la configuración global del proveedor:

{  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, configure agents.entries.*.tts.persona junto con la configuración del proveedor; esto anula el valor global de 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. tts
2. agents.entries.*.tts activo
3. anulación del canal, cuando el canal admite channels.<channel>.tts
4. anulación de la cuenta, cuando el canal pasa channels.<channel>.accounts.<id>.tts
5. preferencias locales de /tts para este host
6. directivas [[tts:...]] en línea cuando están habilitadas las anulaciones controladas por el modelo

Las anulaciones de canal y cuenta usan la misma estructura que tts y se combinan en profundidad sobre las capas anteriores, por lo que las credenciales compartidas del proveedor pueden permanecer en tts mientras un canal o una cuenta de bot cambia únicamente la voz del hablante, el modelo, la persona o el modo automático:

{  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 la intención del prompt independientemente del proveedor y contener vinculaciones específicas del proveedor para voces, modelos, plantillas de prompt, semillas y ajustes de voz.

Persona mínima

{  tts: {    auto: "always",    persona: "narrator",    personas: {      narrator: {        label: "Narrator",        provider: "elevenlabs",        providers: {          elevenlabs: {            speakerVoiceId: "EXAVITQu4vr4xnSDxMaL",            modelId: "eleven_multilingual_v2",          },        },      },    },  },}

Persona completa (configuración específica del proveedor)

{  tts: {    auto: "always",    persona: "alfred",    personas: {      alfred: {        label: "Alfred",        description: "Dry, warm British butler narrator.",        provider: "google",        fallbackPolicy: "preserve-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á configurada.
2. tts.persona, si está configurada.
3. Ninguna persona.

La selección del proveedor evalúa primero las opciones explícitas:

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

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

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

Configuración personalizada de personas

La configuración personas.<id>.prompt.* independiente del proveedor está retirada. Doctor elimina esos campos y remite al punto de extensión del proveedor de voz. Coloque los ajustes integrados del proveedor en personas.<id>.providers.<provider> (por ejemplo, personaPrompt de Google o instructions de OpenAI). Para una configuración personalizada, implemente un plugin de proveedor de voz con prepareSynthesis(ctx) y devuelva texto ajustado, configuración del proveedor o anulaciones antes de que se ejecute synthesize(). Esto mantiene la construcción expresiva de prompts en el código del proveedor, donde se conoce la semántica de las solicitudes.

Política de respaldo

fallbackPolicy controla el comportamiento cuando una persona no tiene 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 pasarlos mediante la sesión de Talk o la solicitud de transferencia. Abrir una sesión de voz no debe modificar 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 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í tiene. [[tts:speakerVoiceId=pMsXgVXv3BLzUgSXRplE model=eleven_v3 speed=1.1]][[tts:text]](ríe) Lee la canción una vez más.[[/tts:text]]

Cuando tts.auto es "tagged", se requieren directivas para activar el audio. La entrega de bloques en 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 anulaciones del modelo:

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

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

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

Comandos de barra diagonal

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 de TTS automático limitada a la sesión para el chat actual.
• /tts persona <id> escribe la preferencia de persona local; /tts persona off la borra.
• /tts latest lee la respuesta más reciente del asistente en 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 evitar 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 mensajes o pies de foto de Telegram); se rechazan los valores fuera de ese intervalo.
• limit y summary se almacenan en las preferencias locales, no en la configuración principal.
• /tts status incluye diagnósticos de respaldo para el 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, modelo y voz configurados, y los metadatos saneados del endpoint personalizado cuando TTS está habilitado.

Preferencias por usuario

Los comandos de barra diagonal escriben anulaciones locales en la ruta de preferencias TTS. El valor predeterminado es ~/.openclaw/settings/tts.json; anúlelo con OPENCLAW_TTS_PREFS. Doctor traslada el valor global retirado tts.prefsPath al estado compartido de la máquina. Las configuraciones multiagente avanzadas aún pueden establecer agents.entries.<id>.tts.prefsPath cuando los agentes usan intencionadamente almacenes de preferencias separados.

Estas opciones anulan la configuración efectiva de tts junto con el bloque agents.entries.*.tts activo para ese host.

Formatos de salida

La entrega de voz 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 con nota de voz llega como MP3/WebM/WAV/M4A u otro archivo probablemente de audio, el plugin del 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 captura el error y recurre al envío del archivo original como un archivo adjunto normal; WhatsApp no tiene 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 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 Talk/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 Talk/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 como alternativa con búfer porque las salidas pcm, mulaw y alaw de xAI son audio sin procesar y sin cabecera. La síntesis con 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 notas de voz Opus nativo.
• Microsoft: utiliza microsoft.outputFormat (valor 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 del formato de salida siguen los formatos de salida de Microsoft Speech (incluido Opus Ogg/WebM).
  • El sendVoice de Telegram acepta OGG/MP3/M4A; utilice OpenAI/ElevenLabs si necesita garantizar mensajes de voz Opus.
  • Si falla el formato de salida configurado de Microsoft, OpenClaw vuelve a intentarlo con MP3.
  • Cuando no se establece una sustitución explícita de voz y se utiliza la voz inglesa predeterminada, OpenClaw cambia automáticamente a una voz neuronal china (zh-CN-XiaoxiaoNeural, configuración regional zh-CN) si el texto de la respuesta está dominado por caracteres CJK.

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

Comportamiento de TTS automático

Cuando 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 solo de audio para las respuestas finales transmitidas después de que se complete el flujo de texto; el contenido multimedia generado pasa por la misma normalización de contenido multimedia del canal que los archivos adjuntos de respuesta normales.

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

• Resumen activado (valor predeterminado) y hay disponible un modelo de resumen: resume el texto a aproximadamente maxLength caracteres y, a continuación, sintetiza el resumen.
• Resumen desactivado, la generación del 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 entregar 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 en esta ruta la salida TTS que no sea Opus cuando ffmpeg está disponible.

WhatsApp envía el audio mediante Baileys como 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 coherente 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 solicitudes al proveedor, en milisegundos. Los valores por llamada sustituyen tts.timeoutMs; los tiempos de espera de TTS configurados sustituyen 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 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

Temas relacionados

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