Texto a voz (TTS)

OpenClaw puede convertir las respuestas salientes en audio usando ElevenLabs, OpenAI o Edge TTS. Funciona en cualquier lugar donde OpenClaw pueda enviar audio; en Telegram se muestra como una burbuja redonda de nota de voz.

Servicios soportados

ElevenLabs (proveedor principal o de respaldo)
OpenAI (proveedor principal o de respaldo; también se usa para resúmenes)
Edge TTS (proveedor principal o de respaldo; usa node-edge-tts, por defecto cuando no hay claves API)

Notas sobre Edge TTS

Edge TTS usa 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), usa los endpoints de Microsoft y no requiere clave API. node-edge-tts expone opciones de configuración de voz y formatos de salida, pero no todas las opciones son soportadas por el servicio Edge. citeturn2search0

Como Edge TTS es un servicio web público sin SLA ni cuota publicados, considéralo como best-effort. Si necesitas límites y soporte garantizados, usa OpenAI o ElevenLabs. La API REST de Speech de Microsoft documenta un límite de 10 minutos de audio por solicitud; Edge TTS no publica límites, así que asume límites similares o menores. citeturn0search3

Claves opcionales

Si quieres usar OpenAI o ElevenLabs:

ELEVENLABS_API_KEY (o XI_API_KEY)
OPENAI_API_KEY

Edge TTS no requiere clave API. Si no se encuentran claves API, OpenClaw usa Edge TTS por defecto (a menos que se desactive vía messages.tts.edge.enabled=false).

Si hay múltiples proveedores configurados, se usa primero el proveedor seleccionado y los demás son opciones de respaldo. El auto-resumen usa el summaryModel configurado (o agents.defaults.model.primary), así que ese proveedor también debe estar autenticado si habilitas resúmenes.

Enlaces de servicios

¿Está habilitado 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).

Edge TTS sí está habilitado por defecto una vez que TTS está activo, y se usa automáticamente cuando no hay claves API de OpenAI o ElevenLabs disponibles.

Configuración

La configuración de TTS está bajo messages.tts en openclaw.json. El esquema completo está en Configuración del Gateway.

Configuración mínima (activar + proveedor)

{
  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,
      },
      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,
        },
      },
    },
  },
}

Edge TTS como principal (sin clave API)

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

Desactivar Edge TTS

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

Límites personalizados + ruta de preferencias

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

Solo responder con audio después de una nota 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 de auto-TTS (off, always, inbound, tagged).
- inbound solo envía audio después de una nota de voz entrante.
- tagged solo envía audio cuando la respuesta incluye etiquetas [[tts]].
enabled: toggle legacy (doctor lo migra a auto).
mode: "final" (por defecto) o "all" (incluye respuestas de herramientas/bloques).
provider: "elevenlabs", "openai" o "edge" (el respaldo es automático).
Si provider no está definido, OpenClaw prefiere openai (si hay clave), luego elevenlabs (si hay clave), de lo contrario edge.
summaryModel: modelo económico opcional para auto-resumen; por defecto agents.defaults.model.primary.
- Acepta provider/model o un alias de modelo configurado.
modelOverrides: permite al modelo emitir directivas TTS (activado por defecto).
- allowProvider por defecto es false (el cambio de proveedor es opt-in).
maxTextLength: límite máximo de entrada para TTS (caracteres). /tts audio falla si se excede.
timeoutMs: timeout de solicitud (ms).
prefsPath: sobreescribir la ruta del JSON de preferencias locales (proveedor/límite/resumen).
Los valores de apiKey recurren a variables de entorno (ELEVENLABS_API_KEY/XI_API_KEY, OPENAI_API_KEY).
elevenlabs.baseUrl: sobreescribir la URL base de la API de ElevenLabs.
openai.baseUrl: sobreescribir el endpoint de TTS de OpenAI.
- Orden de resolución: messages.tts.openai.baseUrl -> OPENAI_TTS_BASE_URL -> https://api.openai.com/v1
- Los valores no predeterminados se tratan como endpoints de TTS compatibles con OpenAI, así que se aceptan nombres personalizados de modelo y voz.
elevenlabs.voiceSettings:
- stability, similarityBoost, style: 0..1
- useSpeakerBoost: true|false
- speed: 0.5..2.0 (1.0 = normal)
elevenlabs.applyTextNormalization: auto|on|off
elevenlabs.languageCode: ISO 639-1 de 2 letras (ej., en, de)
elevenlabs.seed: entero 0..4294967295 (determinismo best-effort)
edge.enabled: permitir uso de Edge TTS (por defecto true; sin clave API).
edge.voice: nombre de voz neuronal de Edge (ej., en-US-MichelleNeural).
edge.lang: código de idioma (ej., en-US).
edge.outputFormat: formato de salida de Edge (ej., audio-24khz-48kbitrate-mono-mp3).
- Consulta los formatos de salida de Microsoft Speech para valores válidos; no todos los formatos son soportados por Edge.
edge.rate / edge.pitch / edge.volume: cadenas de porcentaje (ej., +10%, -5%).
edge.saveSubtitles: escribir subtítulos JSON junto al archivo de audio.
edge.proxy: URL de proxy para solicitudes de Edge TTS.
edge.timeoutMs: sobreescritura de timeout de solicitud (ms).

Sobreescrituras del modelo (activas por defecto)

Por defecto, el modelo puede emitir directivas TTS para una sola respuesta. Cuando messages.tts.auto es tagged, estas directivas son necesarias para activar el audio.

Cuando está habilitado, el modelo puede emitir directivas [[tts:...]] para sobreescribir la voz de una sola respuesta, más un bloque opcional [[tts:text]]...[[/tts:text]] para proporcionar etiquetas expresivas (risas, indicaciones de canto, etc.) que solo deben aparecer en el audio.

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

Ejemplo de payload 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 (cuando están habilitadas):

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

Desactivar todas las sobreescrituras del modelo:

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

Allowlist opcional (habilitar cambio de proveedor manteniendo otros controles configurables):

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

Preferencias por usuario

Los comandos slash escriben sobreescrituras locales en prefsPath (por defecto: ~/.openclaw/settings/tts.json, sobreescribible 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 sobreescriben messages.tts.* para ese host.

Formatos de salida (fijos)

Telegram: nota de voz Opus (opus_48000_64 de ElevenLabs, opus de OpenAI).
- 48kHz / 64kbps es un buen equilibrio para notas de voz y es necesario para la burbuja redonda.
Otros canales: MP3 (mp3_44100_128 de ElevenLabs, mp3 de OpenAI).
- 44.1kHz / 128kbps es el balance por defecto para claridad de voz.
Edge TTS: usa edge.outputFormat (por defecto audio-24khz-48kbitrate-mono-mp3).
- node-edge-tts acepta un outputFormat, pero no todos los formatos están disponibles en el servicio Edge. citeturn2search0
- Los valores de formato de salida siguen los formatos de salida de Microsoft Speech (incluyendo Ogg/WebM Opus). citeturn1search0
- sendVoice de Telegram acepta OGG/MP3/M4A; usa OpenAI/ElevenLabs si necesitas notas de voz Opus garantizadas. citeturn1search1
- Si el formato de salida configurado de Edge falla, OpenClaw reintenta con MP3.

Los formatos de OpenAI/ElevenLabs son fijos; Telegram espera Opus para la experiencia de nota de voz.

Comportamiento del auto-TTS

Cuando está habilitado, OpenClaw:

omite TTS si la respuesta ya contiene multimedia o una directiva MEDIA:.
omite respuestas muy cortas (< 10 caracteres).
resume respuestas largas cuando está habilitado usando agents.defaults.model.primary (o summaryModel).
adjunta el audio generado a la respuesta.

Si la respuesta excede maxLength y el resumen está desactivado (o no hay clave API para el modelo de resumen), el audio se omite y se envía la respuesta de texto normal.

Diagrama de flujo

Respuesta -> ¿TTS habilitado?
  no  -> enviar texto
  sí  -> ¿tiene multimedia / MEDIA: / es corta?
          sí  -> enviar texto
          no  -> ¿longitud > límite?
                   no  -> TTS -> adjuntar audio
                   sí  -> ¿resumen habilitado?
                            no  -> enviar texto
                            sí  -> resumir (summaryModel o agents.defaults.model.primary)
                                      -> TTS -> adjuntar audio

Uso del comando slash

Hay un único comando: /tts. Consulta Comandos slash para detalles de activación.

Nota de Discord: /tts es un comando nativo de Discord, así que OpenClaw registra /voice como el comando nativo allí. El texto /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 debe estar habilitado.
off|always|inbound|tagged son toggles por sesión (/tts on es un alias de /tts always).
limit y summary se almacenan en preferencias locales, no en la configuración principal.
/tts audio genera una respuesta de audio única (no activa TTS de forma permanente).

Herramienta del agente

La herramienta tts convierte texto a voz y devuelve una ruta MEDIA:. Cuando el resultado es compatible con Telegram, la herramienta incluye [[audio_as_voice]] para que Telegram envíe una burbuja de voz.

RPC del Gateway

Métodos del Gateway:

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