Configura TTS en OpenClaw: ElevenLabs, OpenAI y Edge

Texto a voz (TTS)

OpenClaw puede convertir tus respuestas salientes en audio usando ElevenLabs, Microsoft o OpenAI. Funciona en cualquier lugar donde OpenClaw pueda enviar audio.

Servicios compatibles

ElevenLabs (proveedor principal o de respaldo)
Microsoft (proveedor principal o de respaldo; la implementación actual incluida usa node-edge-tts)
OpenAI (proveedor principal o de respaldo; también se usa para resúmenes)

Notas sobre la voz de Microsoft

El proveedor de voz de Microsoft incluido utiliza actualmente el servicio TTS neuronal en línea de Microsoft Edge a través de la librería node-edge-tts. Es un servicio alojado (no local), usa endpoints de Microsoft y no requiere una API key. node-edge-tts expone opciones de configuración de voz y formatos de salida, aunque el servicio no admite todas las opciones. La configuración heredada y la entrada de directivas usando edge siguen funcionando y se normalizan a microsoft.

Como esta vía es un servicio web público sin un SLA o cuota publicados, considéralo como un servicio de “mejor esfuerzo”. Si necesitas límites garantizados y soporte, usa OpenAI o ElevenLabs.

Claves opcionales

Si quieres usar OpenAI o ElevenLabs:

ELEVENLABS_API_KEY (o XI_API_KEY)
OPENAI_API_KEY

La voz de Microsoft no requiere una API key.

Si configuras varios proveedores, se usará primero el seleccionado y los demás servirán como opciones de respaldo. El auto-resumen utiliza el summaryModel configurado (o agents.defaults.model.primary), por lo que ese proveedor también debe estar autenticado si activas los resúmenes.

Enlaces del servicio

¿Está activado por defecto?

No. El Auto-TTS está desactivado por defecto. Actívalo en la configuración con messages.tts.auto o por sesión con /tts always (alias: /tts on).

Cuando messages.tts.provider no está establecido, OpenClaw elige el primer proveedor de voz configurado según el orden de selección automática del registro.

Configuración

La configuración de TTS se encuentra bajo messages.tts en openclaw.json. El esquema completo está en Gateway configuration.

Configuración mínima (activación + proveedor)

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

OpenAI como principal con ElevenLabs como fallback

{
  messages: {
    tts: {
      auto: "always",
      provider: "openai",
      summaryModel: "openai/gpt-4.1-mini",
      modelOverrides: {
        enabled: true,
      },
      providers: {
        openai: {
          apiKey: "openai_api_key",
          baseUrl: "https://api.openai.com/v1",
          model: "gpt-4o-mini-tts",
          voice: "alloy",
        },
        elevenlabs: {
          apiKey: "elevenlabs_api_key",
          baseUrl: "https://api.elevenlabs.io",
          voiceId: "voice_id",
          modelId: "eleven_multilingual_v2",
          seed: 42,
          applyTextNormalization: "auto",
          languageCode: "en",
          voiceSettings: {
            stability: 0.5,
            similarityBoost: 0.75,
            style: 0.0,
            useSpeakerBoost: true,
            speed: 1.0,
          },
        },
      },
    },
  },
}

Microsoft como principal (sin API key)

{
  messages: {
    tts: {
      auto: "always",
      provider: "microsoft",
      providers: {
        microsoft: {
          enabled: true,
          voice: "en-US-MichelleNeural",
          lang: "en-US",
          outputFormat: "audio-24khz-48kbitrate-mono-mp3",
          rate: "+10%",
          pitch: "-5%",
        },
      },
    },
  },
}

Desactivar voz de Microsoft

{
  messages: {
    tts: {
      providers: {
        microsoft: {
          enabled: false,
        },
      },
    },
  },
}

Límites personalizados + ruta de preferencias

{
  messages: {
    tts: {
      auto: "always",
      maxTextLength: 4000,
      timeoutMs: 30000,
      prefsPath: "~/.openclaw/settings/tts.json",
    },
  },
}

Responder con audio solo tras un mensaje de voz entrante

{
  messages: {
    tts: {
      auto: "inbound",
    },
  },
}

Desactivar auto-resumen para respuestas largas

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

Luego ejecuta:

/tts summary off

Notas sobre los campos

auto: modo auto-TTS (off, always, inbound, tagged).
- inbound solo envía audio tras recibir un mensaje de voz.
- tagged solo envía audio cuando la respuesta incluye etiquetas [[tts]].
enabled: interruptor heredado (doctor lo migra automáticamente a auto).
mode: "final" (por defecto) o "all" (incluye respuestas de herramientas y bloques).
provider: ID del proveedor de voz como "elevenlabs", "microsoft", "openai" o el fallback automático.
Si provider no está definido, OpenClaw usa el primer proveedor configurado según el orden de selección del registro.
El valor heredado provider: "edge" sigue funcionando y se normaliza a microsoft.
summaryModel: modelo económico opcional para auto-resumen; por defecto usa agents.defaults.model.primary.
- Acepta el formato provider/model o un alias de modelo configurado.
modelOverrides: permite que el modelo emita directivas de TTS (activado por defecto).
- allowProvider por defecto es false (el cambio de proveedor es opcional).
providers.<id>: ajustes específicos del proveedor organizados por su ID de voz.
Los bloques de proveedores directos heredados (messages.tts.openai, messages.tts.elevenlabs, messages.tts.microsoft, messages.tts.edge) se migran a messages.tts.providers.<id> al cargar.
maxTextLength: límite máximo de caracteres para la entrada de TTS. /tts audio fallará si se supera.
timeoutMs: tiempo de espera de la solicitud en milisegundos.
prefsPath: sobrescribe la ruta local del archivo JSON de preferencias.
Los valores de apiKey usan variables de entorno como respaldo (ELEVENLABS_API_KEY/XI_API_KEY, OPENAI_API_KEY).
providers.elevenlabs.baseUrl: sobrescribe la URL base de la API de ElevenLabs.
providers.openai.baseUrl: sobrescribe el endpoint de OpenAI TTS.
- Orden de resolución: messages.tts.providers.openai.baseUrl -> OPENAI_TTS_BASE_URL -> https://api.openai.com/v1.
- Los valores personalizados se tratan como endpoints compatibles con OpenAI, aceptando nombres de modelos y voces propios.
providers.elevenlabs.voiceSettings:
- stability, similarityBoost, style: valores entre 0..1.
- useSpeakerBoost: true|false.
- speed: entre 0.5..2.0 (1.0 es la velocidad normal).
providers.elevenlabs.applyTextNormalization: auto|on|off.
providers.elevenlabs.languageCode: código ISO 639-1 de 2 letras (ej. en, es).
providers.elevenlabs.seed: número entero entre 0..4294967295.
providers.microsoft.enabled: permite el uso de voz de Microsoft (activado por defecto; no requiere API key).
providers.microsoft.voice: nombre de la voz neural de Microsoft (ej. en-US-MichelleNeural).
providers.microsoft.lang: código de idioma (ej. en-US).
providers.microsoft.outputFormat: formato de salida de Microsoft (ej. audio-24khz-48kbitrate-mono-mp3).
- Revisa los formatos de Microsoft Speech para ver valores válidos; no todos son compatibles con el transporte Edge incluido.
providers.microsoft.rate / providers.microsoft.pitch / providers.microsoft.volume: cadenas de porcentaje (ej. +10%, -5%).
providers.microsoft.saveSubtitles: genera subtítulos en formato JSON junto al archivo de audio.
providers.microsoft.proxy: URL del proxy para las solicitudes de voz de Microsoft.
providers.microsoft.timeoutMs: sobrescritura del tiempo de espera para este proveedor.
edge.*: alias heredado para los mismos ajustes de Microsoft.

Sobrescrituras impulsadas por el modelo (activado por defecto)

Por defecto, el modelo puede emitir directivas de TTS para una sola respuesta. Cuando messages.tts.auto está en modo tagged, estas directivas son obligatorias para generar audio.

Si está activado, el modelo puede usar directivas [[tts:...]] para cambiar la voz en una respuesta específica. También puede incluir un bloque opcional [[tts:text]]...[[/tts:text]] para añadir etiquetas expresivas (como risas o indicaciones de canto) que solo se escucharán en el audio.

Las directivas provider=... se ignoran a menos que configures modelOverrides.allowProvider: true.

Ejemplo de respuesta:

Here you go.

[[tts:voiceId=pMsXgVXv3BLzUgSXRplE model=eleven_v3 speed=1.1]]
[[tts:text]](laughs) Read the song once more.[[/tts:text]]

Claves de directiva disponibles:

provider (ID de proveedor registrado como openai, elevenlabs o microsoft; requiere allowProvider: true).
voice (voz de OpenAI) o voiceId (ElevenLabs).
model (modelo OpenAI TTS o ID de modelo de ElevenLabs).
stability, similarityBoost, style, speed, useSpeakerBoost.
applyTextNormalization (auto|on|off).
languageCode (ISO 639-1).
seed.

Desactivar todas las sobrescrituras del modelo:

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

Lista de permitidos opcional (permite cambiar de proveedor manteniendo otros controles configurables):

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

Preferencias por usuario

Los comandos de barra escriben sobrescrituras locales en prefsPath (por defecto: ~/.openclaw/settings/tts.json, puedes cambiarlo con OPENCLAW_TTS_PREFS o messages.tts.prefsPath).

Campos almacenados:

enabled
provider
maxLength (umbral de resumen; por defecto 1500 caracteres)
summarize (por defecto true)

Estos valores sobrescriben messages.tts.* para ese host.

Formatos de salida (fijos)

Feishu / Matrix / Telegram / WhatsApp: Mensaje de voz Opus (opus_48000_64 de ElevenLabs, opus de OpenAI).
- 48kHz / 64kbps es un buen equilibrio para mensajes de voz.
Otros canales: MP3 (mp3_44100_128 de ElevenLabs, mp3 de OpenAI).
- 44.1kHz / 128kbps es el balance predeterminado para la claridad de voz.
Microsoft: usa microsoft.outputFormat (por defecto audio-24khz-48kbitrate-mono-mp3).
- El transporte incluido acepta un outputFormat, pero no todos los formatos están disponibles desde el servicio.
- Los valores del formato de salida siguen los formatos de Microsoft Speech (incluyendo Ogg/WebM Opus).
- sendVoice de Telegram 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 (mira arriba).

AI Setup Assistant

Comportamiento de Auto-TTS

Cuando activas esta función, OpenClaw gestiona el audio de forma inteligente para que la experiencia sea fluida y no gastes recursos innecesarios:

Se salta el TTS si la respuesta ya incluye archivos multimedia o una directiva MEDIA:.
Ignora las respuestas muy cortas (menos de 10 caracteres).
Resume las respuestas largas si tienes la opción activa usando agents.defaults.model.primary (o summaryModel).
Adjunta el audio generado directamente a la respuesta.

Si la respuesta supera el maxLength y el resumen está desactivado (o no configuraste una API key para el modelo de resumen), el sistema omite el audio y envía el texto normal. Te recomiendo tener siempre un modelo de resumen configurado para evitar que los mensajes extensos se queden sin voz.

Diagrama de flujo

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 (summaryModel or agents.defaults.model.primary)
                                      -> TTS -> attach audio

Uso de comandos slash

Solo hay un comando: /tts. Consulta Slash commands para ver los detalles de activación.

Nota de Discord: /tts es un comando integrado de Discord, por lo que OpenClaw registra /voice como el comando nativo allí. Escribir /tts ... sigue funcionando.

/tts off
/tts always
/tts inbound
/tts tagged
/tts status
/tts provider openai
/tts limit 2000
/tts summary off
/tts audio Hello from OpenClaw

Notas:

Los comandos requieren un remitente autorizado (las reglas de allowlist/owner siguen aplicando).
commands.text o el registro de comandos nativos deben estar activados.
off|always|inbound|tagged son interruptores por sesión (/tts on es un alias de /tts always).
limit y summary se guardan en las preferencias locales, no en la configuración principal.
/tts audio genera una respuesta de audio única (no activa el TTS de forma permanente).
/tts status incluye visibilidad de fallback para el último intento:
- fallback exitoso: Fallback: <primary> -> <used> junto con Attempts: ...
- fallo: Error: ... junto con Attempts: ...
- diagnóstico detallado: Attempt details: provider:outcome(reasonCode) latency
Los fallos de las API de OpenAI y ElevenLabs ahora incluyen detalles de error analizados del proveedor e ID de solicitud (cuando el proveedor los devuelve), lo que se muestra en los errores o logs de TTS.

Agent tool

La herramienta tts convierte texto en voz y devuelve un archivo de audio adjunto para entregar la respuesta. Cuando utilizas canales como Feishu, Matrix, Telegram o WhatsApp, el audio se envía como un mensaje de voz en lugar de un archivo adjunto convencional.

Gateway RPC

Métodos de Gateway:

tts.status
tts.enable
tts.disable
tts.convert
tts.setProvider
tts.providers

OpenClaw Expert

Sigues atascado?

Si esta pagina no resolvio tu caso, pregunta a OpenClaw Expert para pasos concretos.