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 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 se configuran varios proveedores, se utiliza primero el seleccionado y los demás sirven como opciones de respaldo. 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 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 un presentador de 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 Xiaomi mimo-v2.5-tts-voicedesign, omita speakerVoice y establezca style como 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

Utilice agents.entries.*.tts cuando un agente deba hablar con un proveedor, una voz, un modelo, una personalidad o un modo de TTS automática diferentes. El bloque del agente se fusiona de forma recursiva 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 sustituye 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 activa
3. sustitución del canal, cuando el canal admite channels.<channel>.tts
4. sustitución de la cuenta, cuando el canal proporciona channels.<channel>.accounts.<id>.tts
5. preferencias locales de /tts para este host
6. directivas [[tts:...]] insertadas cuando están habilitadas las sustituciones controladas por el modelo

Las sustituciones de canal y cuenta usan la misma estructura que tts y se combinan de forma profunda 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 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

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

Persona completa (adaptació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. Sin persona.

La selección del proveedor da prioridad a 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. tts.provider.
5. Selección automática del registro.

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

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

Adaptación personalizada de personas

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

Política de reserva

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 que se han intentado 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 proporcionarlos mediante la solicitud de sesión o transferencia de Talk. 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 sustituir la voz, el modelo o la velocidad en una sola respuesta, además de un bloque [[tts:text]]...[[/tts:text]] opcional para indicaciones expresivas que solo deben aparecer en el audio:

Aquí está. [[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", 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 son analizadas solo por ese proveedor; las claves no admitidas se eliminan y se notifican como advertencias de directivas TTS.

Claves de directivas 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 cambiar de proveedor mientras los demás parámetros siguen siendo configurables:

{ 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 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 en 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 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 los pies de foto/mensajes 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 reserva 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, el modelo y la voz configurados, así como los metadatos depurados del endpoint personalizado cuando TTS está habilitado.

Preferencias por usuario

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

Estos valores sustituyen la configuración efectiva de tts más 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 con estilo de 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 de 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 archivo adjunto simple; 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 se configura; 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 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 usar 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 usan MP3 para el streaming y como 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 usa el endpoint REST por lotes /v1/tts de xAI; textToSpeechStream usa 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 (incluidos Ogg/WebM Opus).
  • Telegram sendVoice acepta OGG/MP3/M4A; use OpenAI/ElevenLabs si necesita mensajes de voz Opus garantizados.
  • Si falla el formato de salida de Microsoft configurado, OpenClaw vuelve a intentarlo con MP3.
  • Cuando no se establece ninguna anulació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 contiene predominantemente 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 de solo audio para las respuestas finales transmitidas una vez completado el flujo de texto; el contenido multimedia generado pasa por la misma normalización multimedia del canal que los archivos adjuntos de respuesta normales.

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

• Resumen activado (predeterminado) y hay disponible un modelo de resumen: resume el texto a aproximadamente maxLength caracteres y, a continuación, sintetiza el resumen.
• Resumen desactivado, falla el resumen 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 adjunto de audio 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 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 pies de texto 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 sustituyen a 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 texto a voz de OpenAI
• Referencia de la API de audio de OpenAI
• Texto a voz mediante REST de Azure Speech
• Proveedor de Azure Speech
• 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
• 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
• Plugin de llamadas de voz