Configura TTS en OpenClaw: ElevenLabs, OpenAI y Microsoft

OpenClaw puede convertir las 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 integrada actual usa node-edge-tts)
OpenAI (proveedor principal o de respaldo; también se usa para resúmenes)

Notas sobre Microsoft speech

La implementación integrada de Microsoft usa actualmente el servicio de TTS neuronal en línea de Microsoft Edge a través de la librería node-edge-tts. Es un servicio alojado (no local), utiliza los endpoints de Microsoft y no requiere una API key. node-edge-tts expone opciones de configuración de voz y formatos de salida, pero el servicio no admite todas las opciones. La configuración heredada y el input 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, tómalo como un servicio de “mejor esfuerzo”. Si necesitas límites garantizados y soporte, te recomiendo usar OpenAI o ElevenLabs.

Claves opcionales

Si quieres usar OpenAI o ElevenLabs, necesitas configurar estas claves:

ELEVENLABS_API_KEY (o XI_API_KEY)
OPENAI_API_KEY

Microsoft speech no requiere una API key.

Si configuras varios proveedores, se usará primero el proveedor seleccionado y los demás funcionarán como opciones de respaldo. El auto-summary 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 de los servicios

¿Está activado por defecto?

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

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

AI Setup Assistant

Configuración

La configuración de TTS se encuentra bajo messages.tts en openclaw.json. Tienes el schema completo en Gateway configuration.

Configuración mínima (activar + provider)

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

OpenAI como principal con ElevenLabs de respaldo

{
  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 Microsoft speech

{
  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-summary 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 entrante.
- tagged solo envía audio cuando la respuesta incluye etiquetas [[tts]].
enabled: interruptor antiguo (el doctor lo migra a auto).
mode: "final" (por defecto) o "all" (incluye respuestas de herramientas/bloques).
provider: ID del proveedor de voz como "elevenlabs", "microsoft", o "openai" (el fallback es automático).
Si provider no está definido, OpenClaw usa el primer proveedor configurado en el orden de auto-selección del registro.
El alias antiguo provider: "edge" sigue funcionando y se normaliza a microsoft.
summaryModel: modelo económico opcional para el auto-resumen; por defecto usa agents.defaults.model.primary.
- Acepta 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 identificados por su ID.
Los bloques de proveedores antiguos (messages.tts.openai, messages.tts.elevenlabs, messages.tts.microsoft, messages.tts.edge) se migran automáticamente a messages.tts.providers.<id> al cargar.
maxTextLength: límite máximo de caracteres para la entrada de TTS. /tts audio fallará si te pasas.
timeoutMs: tiempo de espera de la solicitud (ms).
prefsPath: sobrescribe la ruta local del JSON de preferencias (proveedor/límites/resumen).
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 de TTS compatibles con OpenAI, por lo que se aceptan nombres de modelos y voces propios.
providers.elevenlabs.voiceSettings:
- stability, similarityBoost, style: de 0 a 1.
- useSpeakerBoost: true|false.
- speed: de 0.5 a 2.0 (1.0 es la velocidad normal).
providers.elevenlabs.applyTextNormalization: auto|on|off.
providers.elevenlabs.languageCode: ISO 639-1 de 2 letras (ej. en, es).
providers.elevenlabs.seed: número entero entre 0 y 4294967295 (para intentar obtener resultados deterministas).
providers.microsoft.enabled: permite el uso de Microsoft speech (activo 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).
- Consulta los formatos de salida de Microsoft Speech para ver los valores válidos; no todos son compatibles con el transporte basado en Edge incluido.
providers.microsoft.rate / providers.microsoft.pitch / providers.microsoft.volume: porcentajes en cadena (ej. +10%, -5%).
providers.microsoft.saveSubtitles: guarda subtítulos en formato JSON junto al archivo de audio.
providers.microsoft.proxy: URL del proxy para las solicitudes de Microsoft speech.
providers.microsoft.timeoutMs: sobrescritura del tiempo de espera de la solicitud (ms).
edge.*: alias antiguo para los mismos ajustes de Microsoft.

Overrides controlados por el modelo (activado por defecto)

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

Si esta opción está activa, el modelo puede emitir directivas [[tts:...]] para cambiar la voz en una respuesta específica, además de un bloque opcional [[tts:text]]...[[/tts:text]] para incluir etiquetas expresivas (risas, indicaciones de canto, etc.) que solo deben aparecer 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 directivas disponibles (cuando están activadas):

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

Desactivar todos los overrides del modelo:

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

Lista de permitidos opcional (activa el cambio de proveedor manteniendo otros ajustes configurables):

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

Preferencias por usuario

Los slash commands escriben ajustes locales en prefsPath. Por defecto, la ruta es ~/.openclaw/settings/tts.json, pero puedes cambiarla usando OPENCLAW_TTS_PREFS o messages.tts.prefsPath.

Campos almacenados:

enabled
provider
maxLength (umbral para resúmenes; por defecto 1500 caracteres)
summarize (por defecto true)

Estos valores sobrescriben la configuración de 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). Una configuración de 48kHz / 64kbps es una buena opción para mensajes de voz.
Otros canales: MP3 (mp3_44100_128 de ElevenLabs, mp3 de OpenAI). El balance predeterminado para que la voz sea clara es 44.1kHz / 128kbps.
Microsoft: utiliza microsoft.outputFormat (por defecto audio-24khz-48kbitrate-mono-mp3). El transport incluido acepta un outputFormat, pero ten en cuenta que no todos los formatos del servicio están disponibles. Los valores del formato de salida siguen los formatos de Microsoft Speech (incluyendo Ogg/WebM Opus). Telegram sendVoice acepta OGG/MP3/M4A; te recomiendo usar OpenAI o ElevenLabs si necesitas mensajes de voz Opus garantizados. Si el formato de Microsoft configurado falla, OpenClaw reintenta la operación con MP3.

Los formatos de salida de OpenAI y ElevenLabs son fijos por cada canal.

Comportamiento de Auto-TTS

Cuando activas esta función, OpenClaw sigue estas reglas:

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

Si la respuesta supera el maxLength y el resumen está desactivado (o no tienes una API key para el modelo de resumen), el sistema omite el audio y envía la respuesta de texto normal.

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 existe un comando: /tts. Consulta Slash commands para ver los detalles de activación.

Nota sobre Discord: Como /tts es un comando integrado de Discord, OpenClaw registra /voice como el comando nativo en esa plataforma. De todas formas, escribir /tts ... sigue funcionando sin problemas.

/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).
Debes tener activado commands.text o el registro de comandos nativos.
off|always|inbound|tagged son selectores 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 puntual (no activa el TTS de forma permanente).
/tts status incluye información de fallback para el último intento:
- éxito del fallback: Fallback: <primary> -> <used> junto con Attempts: ...
- fallo: Error: ... junto con Attempts: ...
- diagnósticos detallados: Attempt details: provider:outcome(reasonCode) latency
Los fallos en las API de OpenAI y ElevenLabs ahora incluyen detalles específicos del error del proveedor y el ID de la solicitud (si el proveedor lo devuelve), lo que aparece en los errores y logs de TTS.

Herramienta del Agent

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

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.