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 todos 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, el seleccionado se usa primero y los demás son 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 activados.

Configuración

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

{messages: {tts: {  auto: "always",  provider: "azure-speech",  providers: {    "azure-speech": {      apiKey: "${AZURE_SPEECH_KEY}",      region: "eastus",      voice: "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",      voiceId: "EXAVITQu4vr4xnSDxMaL",    },  },},},}

{messages: {tts: {  auto: "always",  provider: "google",  providers: {    google: {      apiKey: "${GEMINI_API_KEY}",      model: "gemini-3.1-flash-tts-preview",      voiceName: "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}",      voiceId: "YTpq7expH9539ERJ",    },  },},},}

{messages: {tts: {  auto: "always",  provider: "inworld",  providers: {    inworld: {      apiKey: "${INWORLD_API_KEY}",      modelId: "inworld-tts-1.5-max",      voiceId: "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,      voice: "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",      voiceId: "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",      voice: "alloy",    },    elevenlabs: {      apiKey: "${ELEVENLABS_API_KEY}",      model: "eleven_multilingual_v2",      voiceId: "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",      voice: "af_alloy",      responseFormat: "mp3",    },  },},},}

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

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

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

Sobrescrituras de voz por agente

Usa agents.list[].tts cuando un agente deba hablar con un proveedor, voz, modelo, personalidad o modo Auto-TTS diferente. El bloque del agente se fusiona 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: { voiceId: "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 controladas por el modelo están habilitadas

Las anulaciones de canal y cuenta usan la misma forma que messages.tts y se combinan 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, 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: { voice: "shimmer" },            },          },        },      },    },  },}

Personas

Una persona es una identidad hablada estable que puede aplicarse de forma determinista entre proveedores. Puede preferir un proveedor, definir una intención de prompt neutral respecto al proveedor y contener vinculaciones específicas 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: { voiceId: "EXAVITQu4vr4xnSDxMaL", modelId: "eleven_multilingual_v2" },          },        },      },    },  },}

Persona completa (prompt neutral respecto al 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",              voiceName: "Algieba",              promptTemplate: "audio-profile-v1",            },            openai: { model: "gpt-4o-mini-tts", voice: "cedar" },            elevenlabs: {              voiceId: "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 del proveedor se ejecuta dando prioridad a lo explícito:

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 combina las configuraciones en este orden:

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

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 al proveedor. Cada proveedor decide cómo usarlos:

Política de fallback

fallbackPolicy controla el comportamiento cuando una persona no tiene vinculación 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 tiene alcance de sesión. Un cliente de Talk debe elegir identificadores de proveedor, identificadores de modelo, identificadores de voz y configuraciones regionales desde talk.catalog y pasarlos mediante la sesión de 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 la voz, el modelo o la velocidad de una sola respuesta, además de un bloque opcional [[tts:text]]...[[/tts:text]] para indicaciones expresivas que deben aparecer solo en el audio:

Here you go. [[tts:voiceId=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 el 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 a menos que modelOverrides.allowProvider: true. Cuando una respuesta declara provider=..., las demás claves de esa directiva solo las analiza ese proveedor; las claves no admitidas se eliminan y se informan como advertencias de directiva TTS.

Claves de directiva disponibles:

• provider (identificador de proveedor registrado; requiere allowProvider: true)
• 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 los demás controles:

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

Comandos de barra

Un único comando /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ática con alcance de sesión para el chat actual.
• /tts persona <id> escribe la preferencia de persona local; /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. Almacena solo un hash de esa respuesta en la entrada de sesión para evitar 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 junto con el proveedor, el modelo, la voz y los metadatos saneados del 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 está controlada por las capacidades del canal. Los plugins de canal anuncian si la 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 entrega de voz.

• Canales compatibles con notas de voz: las respuestas de nota de voz prefieren Opus (opus_48000_64 de ElevenLabs, opus de OpenAI).
  • 48kHz / 64kbps ofrece un buen equilibrio para mensajes de voz.
• Feishu / WhatsApp: cuando una respuesta de nota de voz se genera como MP3/WebM/WAV/M4A u otro archivo probablemente de audio, el Plugin del canal la transcodifica a Ogg/Opus de 48kHz 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.1kHz / 128kbps es el equilibrio predeterminado para la claridad del habla.
• MiniMax: MP3 (modelo speech-2.8-hd, frecuencia de muestreo de 32kHz) para adjuntos de audio normales. Para destinos de nota de voz anunciados por el canal, OpenClaw transcodifica el MP3 de MiniMax a Opus de 48kHz 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 nota de voz anunciados por el canal, OpenClaw transcodifica la salida de Xiaomi a Opus de 48kHz con ffmpeg antes de la entrega cuando el canal anuncia transcodificación.
• CLI local: usa el outputFormat configurado. Los destinos de nota 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: TTS de la API de Gemini devuelve PCM sin procesar de 24kHz. OpenClaw lo envuelve como WAV para adjuntos de audio, lo transcodifica a Opus de 48kHz para destinos de nota de voz y devuelve PCM directamente para Talk/telefonía.
• Gradium: WAV para adjuntos de audio, Opus para destinos de nota de voz y ulaw_8000 a 8 kHz para telefonía.
• Inworld: MP3 para adjuntos de audio normales, OGG_OPUS nativo para destinos de nota 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 REST TTS por lotes de xAI y devuelve un adjunto de audio completo; el WebSocket TTS de streaming de xAI no se usa en esta ruta de proveedor. Esta ruta no admite formato Opus nativo 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).
  • Telegram sendVoice acepta OGG/MP3/M4A; usa OpenAI/ElevenLabs si necesitas mensajes de voz Opus garantizados.
  • Si el formato de salida configurado de Microsoft falla, OpenClaw reintenta con MP3.

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

Comportamiento de Auto-TTS

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

• Omite TTS si la respuesta ya contiene contenido multimedia o una directiva MEDIA:.
• 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 transmitidas después de que se completa el flujo de texto; el contenido multimedia generado pasa por la misma normalización de contenido multimedia 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 / 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 del 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 PTT incompatible.
• MiniMax / Xiaomi MiMo: MP3 predeterminado (32 kHz para MiniMax speech-2.8-hd); se transcodifica a Opus de 48 kHz para destinos de nota de voz mediante ffmpeg.
• CLI local: Usa el outputFormat configurado. Los destinos de nota 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 nota de voz y devuelve PCM directamente para Talk/telefonía.
• Inworld: Adjuntos MP3, nota de voz nativa OGG_OPUS, 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; no se usa TTS por WebSocket en streaming. El formato nativo de nota de voz Opus no es compatible.
• Microsoft: Usa microsoft.outputFormat (predeterminado audio-24khz-48kbitrate-mono-mp3). Telegram sendVoice acepta OGG/MP3/M4A; usa OpenAI/ElevenLabs si necesitas mensajes de voz Opus garantizados. Si el formato de Microsoft configurado falla, 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 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 salidas TTS que no sean Opus en esta ruta cuando ffmpeg está disponible.

WhatsApp envía 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 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 del proveedor por llamada en milisegundos.

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 de Azure Speech
• Texto a voz de ElevenLabs
• Autenticación de ElevenLabs
• Gradium
• API de TTS de Inworld
• API T2A v2 de MiniMax
• API HTTP de 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