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 adjuntos de audio en todos los demás lugares, y transmisiones PCM/Ulaw para telefonía y Talk.

TTS es la mitad de salida de voz del modo stt-tts de Talk. Las sesiones de 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 de transcription no sintetizan una respuesta de voz del asistente.

# Inicio rápido

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

# Proveedores compatibles

Si se configuran varios proveedores, 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 activados.

# Configuración

La configuración de TTS vive 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",
      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 combina 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: { voiceId: "EXAVITQu4vr4xnSDxMaL" },
          },
        },
      },
    ],
  },
}

Para fijar una personalidad por agente, define agents.list[].tts.persona junto con la configuración del proveedor; sobrescribe la 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. sobrescritura de canal, cuando el canal admite channels.<channel>.tts
4. sobrescritura 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 sobrescrituras del modelo están habilitadas

Las sobrescrituras 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, 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 llevar vinculaciones específicas de 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 personas

La persona activa se selecciona de forma determinista:

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

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

1. Sobrescrituras 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 configuraciones en este orden:

1. messages.tts.providers.<id>
2. messages.tts.personas.<persona>.providers.<id>
3. Sobrescrituras de solicitud de confianza
4. Sobrescrituras 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 al proveedor. Cada proveedor decide cómo usarlos:

# Política de reserva

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 del proveedor de sesión de Talk tiene alcance de sesión. Un cliente de Talk debe elegir ids de proveedor, ids de modelo, ids de voz y locales desde talk.catalog y pasarlos a través de la sesión de Talk o la solicitud de traspaso. Abrir una sesión de voz no debería mutar messages.tts ni los valores predeterminados globales del proveedor de Talk.

# Directivas impulsadas por el modelo

De forma predeterminada, el asistente puede emitir directivas [[tts:...]] para sobrescribir voz, modelo o velocidad para una sola respuesta, además de un bloque opcional [[tts:text]]...[[/tts:text]] para indicaciones expresivas que deberían aparecer solo en 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", las directivas son obligatorias 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 notifican como advertencias de directivas TTS.

Claves de directiva disponibles:

• provider (id 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 sobrescrituras 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 slash

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 sobrescritura de auto-TTS con alcance de 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 desde 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 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 reserva para el último intento: Fallback: <primary> -> <used>, Attempts: ... y detalle por intento (provider:outcome(reasonCode) latency).
• /status muestra el modo TTS activo además del proveedor, modelo, voz y metadatos sanitizados de endpoint personalizado configurados cuando TTS está habilitado.

# Preferencias por usuario

Los comandos slash escriben sobrescrituras locales en prefsPath. El valor predeterminado es ~/.openclaw/settings/tts.json; sobrescríbelo con la variable de entorno OPENCLAW_TTS_PREFS o messages.tts.prefsPath.

Estos sobrescriben 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á impulsada por 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 nota de voz prefieren Opus (opus_48000_64 de ElevenLabs, opus de OpenAI).
  • 48 kHz / 64 kbps es una buena compensación para mensajes de voz.
• Feishu / WhatsApp: cuando una respuesta de nota de voz se produce como MP3/WebM/WAV/M4A u otro archivo que probablemente sea de audio, el plugin del canal la 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.
• BlueBubbles: mantiene la síntesis del proveedor en la ruta normal de archivos de audio; las salidas MP3 y CAF se marcan para la entrega de notas de voz de iMessage.
• Otros canales: MP3 (mp3_44100_128 de ElevenLabs, mp3 de OpenAI).
  • 44,1 kHz / 128 kbps es el equilibrio predeterminado para la claridad de voz.
• 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 telefónica se convierte a PCM mono sin procesar de 16 kHz con ffmpeg.
• Google Gemini: la TTS de la API de Gemini devuelve PCM sin procesar a 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 (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 de formato de salida siguen los formatos de salida de Microsoft Speech (incluidos Ogg/WebM Opus).
  • Telegram sendVoice acepta OGG/MP3/M4A; usa OpenAI/ElevenLabs si necesitas mensajes de voz Opus garantizados.
  • Si el formato de salida de Microsoft configurado falla, OpenClaw reintenta con MP3.

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

# Comportamiento de TTS automático

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

• Omite TTS si la respuesta ya contiene medios 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 de solo audio para respuestas finales transmitidas en streaming después de que se complete 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), el audio se omite y se envía la respuesta de texto normal.

Respuesta -> TTS habilitado?
  no  -> enviar texto
  sí -> tiene medios / MEDIA: / corta?
          sí -> enviar texto
          no  -> longitud > límite?
                   no  -> TTS -> adjuntar audio
                   sí -> resumen habilitado?
                            no  -> enviar texto
                            sí -> resumir -> TTS -> adjuntar 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 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 vuelve 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); transcodificado 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; TTS por WebSocket en streaming no se usa. El formato nativo Opus para nota 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 el formato configurado de Microsoft falla, OpenClaw reintenta con MP3.

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

# Referencia de campos

# Herramienta del 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 no Opus en esta ruta cuando ffmpeg está disponible.

WhatsApp envía 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 consistente los 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 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 de barra
• Plugin de llamada de voz