​

Texto a voz (TTS)

​

Servicios compatibles

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

​

Notas sobre la voz de Microsoft

​

Claves opcionales

• ELEVENLABS_API_KEY (o XI_API_KEY)
• MINIMAX_API_KEY
• OPENAI_API_KEY

​

Enlaces de servicios

• Guía de texto a voz de OpenAI
• Referencia de la API de audio de OpenAI
• Texto a voz de ElevenLabs
• Autenticación de ElevenLabs
• API T2A v2 de MiniMax
• node-edge-tts
• Formatos de salida de voz de Microsoft

​

¿Está habilitado de forma predeterminada?

​

Configuración

​

Configuración mínima (habilitar + proveedor)

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

​

OpenAI como principal con ElevenLabs como 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 clave de API)

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

​

MiniMax como principal

{
  messages: {
    tts: {
      auto: "always",
      provider: "minimax",
      providers: {
        minimax: {
          apiKey: "minimax_api_key",
          baseUrl: "https://api.minimax.io",
          model: "speech-2.8-hd",
          voiceId: "English_expressive_narrator",
          speed: 1.0,
          vol: 1.0,
          pitch: 0,
        },
      },
    },
  },
}

​

Desactivar la 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 solo con audio después de un mensaje de voz entrante

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

​

Desactivar el resumen automático para respuestas largas

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

/tts summary off

​

Notas sobre los campos

• auto: modo de TTS automático (off, always, inbound, tagged).
  • inbound solo envía audio después de un mensaje de voz entrante.
  • tagged solo envía audio cuando la respuesta incluye etiquetas [[tts]].
• enabled: interruptor heredado (doctor migra esto a auto).
• mode: "final" (predeterminado) o "all" (incluye respuestas de herramientas/bloques).
• provider: id del proveedor de voz, como "elevenlabs", "microsoft", "minimax" u "openai" (el respaldo es automático).
• Si provider no está definido, OpenClaw usa el primer proveedor de voz configurado según el orden de selección automática del registro.
• El valor heredado provider: "edge" sigue funcionando y se normaliza a microsoft.
• summaryModel: modelo económico opcional para resumen automático; usa de forma predeterminada agents.defaults.model.primary.
  • Acepta provider/model o un alias de modelo configurado.
• modelOverrides: permite que el modelo emita directivas TTS (activado de forma predeterminada).
  • allowProvider usa false de forma predeterminada (el cambio de proveedor es opcional).
• providers.<id>: configuración propiedad del proveedor, indexada por el id del proveedor de voz.
• Los bloques heredados de proveedor directo (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 estricto para la entrada de TTS (caracteres). /tts audio falla si se supera.
• timeoutMs: tiempo de espera de la solicitud (ms).
• prefsPath: reemplaza la ruta del JSON local de preferencias (proveedor/límite/resumen).
• Los valores de apiKey usan como respaldo variables de entorno (ELEVENLABS_API_KEY/XI_API_KEY, MINIMAX_API_KEY, OPENAI_API_KEY).
• providers.elevenlabs.baseUrl: reemplaza la URL base de la API de ElevenLabs.
• providers.openai.baseUrl: reemplaza el endpoint TTS de OpenAI.
  • Orden de resolución: messages.tts.providers.openai.baseUrl -> OPENAI_TTS_BASE_URL -> https://api.openai.com/v1
  • Los valores no predeterminados se tratan como endpoints TTS compatibles con OpenAI, por lo que se aceptan nombres personalizados de modelo y voz.
• providers.elevenlabs.voiceSettings:
  • stability, similarityBoost, style: 0..1
  • useSpeakerBoost: true|false
  • speed: 0.5..2.0 (1.0 = normal)
• providers.elevenlabs.applyTextNormalization: auto|on|off
• providers.elevenlabs.languageCode: ISO 639-1 de 2 letras (por ejemplo, en, de)
• providers.elevenlabs.seed: entero 0..4294967295 (determinismo de mejor esfuerzo)
• providers.minimax.baseUrl: reemplaza la URL base de la API de MiniMax (predeterminado https://api.minimax.io, entorno: MINIMAX_API_HOST).
• providers.minimax.model: modelo TTS (predeterminado speech-2.8-hd, entorno: MINIMAX_TTS_MODEL).
• providers.minimax.voiceId: identificador de voz (predeterminado English_expressive_narrator, entorno: MINIMAX_TTS_VOICE_ID).
• providers.minimax.speed: velocidad de reproducción 0.5..2.0 (predeterminado 1.0).
• providers.minimax.vol: volumen (0, 10] (predeterminado 1.0; debe ser mayor que 0).
• providers.minimax.pitch: cambio de tono -12..12 (predeterminado 0).
• providers.microsoft.enabled: permite el uso de la voz de Microsoft (predeterminado true; sin clave de API).
• providers.microsoft.voice: nombre de voz neural de Microsoft (por ejemplo, en-US-MichelleNeural).
• providers.microsoft.lang: código de idioma (por ejemplo, en-US).
• providers.microsoft.outputFormat: formato de salida de Microsoft (por ejemplo, audio-24khz-48kbitrate-mono-mp3).
  • Consulta los formatos de salida de voz de Microsoft para ver valores válidos; no todos los formatos son compatibles con el transporte incluido basado en Edge.
• providers.microsoft.rate / providers.microsoft.pitch / providers.microsoft.volume: cadenas de porcentaje (por ejemplo, +10%, -5%).
• providers.microsoft.saveSubtitles: escribe subtítulos JSON junto al archivo de audio.
• providers.microsoft.proxy: URL de proxy para solicitudes de voz de Microsoft.
• providers.microsoft.timeoutMs: reemplazo del tiempo de espera de la solicitud (ms).
• edge.*: alias heredado para la misma configuración de Microsoft.

​

Reemplazos controlados por el modelo (activados de forma predeterminada)

Here you go.

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

• provider (id del proveedor de voz registrado, por ejemplo openai, elevenlabs, minimax o microsoft; requiere allowProvider: true)
• voice (voz de OpenAI) o voiceId (ElevenLabs / MiniMax)
• model (modelo TTS de OpenAI, id de modelo de ElevenLabs o modelo de MiniMax)
• stability, similarityBoost, style, speed, useSpeakerBoost
• vol / volume (volumen de MiniMax, 0-10)
• pitch (tono de MiniMax, -12 a 12)
• applyTextNormalization (auto|on|off)
• languageCode (ISO 639-1)
• seed

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

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

​

Preferencias por usuario

• enabled
• provider
• maxLength (umbral del resumen; 1500 caracteres de forma predeterminada)
• summarize (true de forma predeterminada)

​

Formatos de salida (fijos)

• Feishu / Matrix / Telegram / WhatsApp: mensaje de voz Opus (opus_48000_64 de ElevenLabs, opus de OpenAI).
  • 48 kHz / 64 kbps es un buen equilibrio para mensajes de voz.
• Otros canales: MP3 (mp3_44100_128 de ElevenLabs, mp3 de OpenAI).
  • 44.1 kHz / 128 kbps es el equilibrio predeterminado para la claridad del habla.
• MiniMax: MP3 (modelo speech-2.8-hd, frecuencia de muestreo de 32 kHz). El formato de nota de voz no es compatible de forma nativa; usa OpenAI o ElevenLabs para mensajes de voz Opus garantizados.
• 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 voz de Microsoft (incluidos 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.

​

Comportamiento del TTS automático

• omite TTS si la respuesta ya contiene medios 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.

​

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 del comando de barra

/tts off
/tts on
/tts status
/tts provider openai
/tts limit 2000
/tts summary off
/tts audio Hello from OpenClaw

• Los comandos requieren un remitente autorizado (las reglas de allowlist/owner siguen aplicándose).
• commands.text o el registro de comandos nativos debe estar habilitado.
• La configuración messages.tts.auto acepta off|always|inbound|tagged.
• /tts on escribe la preferencia local de TTS como always; /tts off la escribe como off.
• Usa la configuración cuando quieras valores predeterminados inbound o tagged.
• limit y summary se almacenan en preferencias locales, no en la configuración principal.
• /tts audio genera una respuesta de audio puntual (no activa TTS).
• /tts status incluye visibilidad del respaldo para el intento más reciente:
  • respaldo exitoso: Fallback: <primary> -> <used> más Attempts: ...
  • error: Error: ... más Attempts: ...
  • diagnósticos detallados: Attempt details: provider:outcome(reasonCode) latency
• Los fallos de API de OpenAI y ElevenLabs ahora incluyen el detalle del error del proveedor analizado y el id de la solicitud (cuando el proveedor lo devuelve), que aparece en los errores/registros de TTS.

​

Herramienta del agente

​

RPC de Gateway

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