Texto a voz

​

Inicio rápido

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

​

Proveedores compatibles

​

Configuración

{
  tts: {
    auto: "always",
    provider: "azure-speech",
    providers: {
      "azure-speech": {
        apiKey: "${AZURE_SPEECH_KEY}",
        region: "eastus",
        speakerVoice: "en-US-JennyNeural",
        lang: "en-US",
        outputFormat: "audio-24khz-48kbitrate-mono-mp3",
        voiceNoteOutputFormat: "ogg-24khz-16bit-mono-opus",
      },
    },
  },
}

{
  tts: {
    auto: "always",
    provider: "elevenlabs",
    providers: {
      elevenlabs: {
        apiKey: "${ELEVENLABS_API_KEY}",
        model: "eleven_multilingual_v2",
        speakerVoiceId: "EXAVITQu4vr4xnSDxMaL",
      },
    },
  },
}

{
  tts: {
    auto: "always",
    provider: "google",
    providers: {
      google: {
        apiKey: "${GEMINI_API_KEY}",
        model: "gemini-3.1-flash-tts-preview",
        speakerVoice: "Kore",
        // Indicaciones opcionales de estilo en lenguaje natural:
        // audioProfile: "Habla con un tono tranquilo, como un presentador de pódcast.",
        // speakerName: "Alex",
      },
    },
  },
}

{
  tts: {
    auto: "always",
    provider: "gradium",
    providers: {
      gradium: {
        apiKey: "${GRADIUM_API_KEY}",
        speakerVoiceId: "YTpq7expH9539ERJ",
      },
    },
  },
}

{
  tts: {
    auto: "always",
    provider: "inworld",
    providers: {
      inworld: {
        apiKey: "${INWORLD_API_KEY}",
        modelId: "inworld-tts-1.5-max",
        speakerVoiceId: "Sarah",
        temperature: 0.7,
      },
    },
  },
}

{
  tts: {
    auto: "always",
    provider: "tts-local-cli",
    providers: {
      "tts-local-cli": {
        command: "say",
        args: ["-o", "{{OutputPath}}", "{{Text}}"],
        outputFormat: "wav",
        timeoutMs: 120000,
      },
    },
  },
}

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

{
  tts: {
    auto: "always",
    provider: "minimax",
    providers: {
      minimax: {
        apiKey: "${MINIMAX_API_KEY}",
        model: "speech-2.8-hd",
        speakerVoiceId: "English_expressive_narrator",
        speed: 1.0,
        vol: 1.0,
        pitch: 0,
      },
    },
  },
}

{
  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",
        speakerVoice: "alloy",
      },
      elevenlabs: {
        apiKey: "${ELEVENLABS_API_KEY}",
        model: "eleven_multilingual_v2",
        speakerVoiceId: "EXAVITQu4vr4xnSDxMaL",
        voiceSettings: { stability: 0.5, similarityBoost: 0.75, style: 0.0, useSpeakerBoost: true, speed: 1.0 },
        applyTextNormalization: "auto",
        languageCode: "en",
      },
    },
  },
}

{
  tts: {
    auto: "always",
    provider: "openrouter",
    providers: {
      openrouter: {
        apiKey: "${OPENROUTER_API_KEY}",
        model: "hexgrad/kokoro-82m",
        speakerVoice: "af_alloy",
        responseFormat: "mp3",
      },
    },
  },
}

{
  tts: {
    auto: "always",
    provider: "volcengine",
    providers: {
      volcengine: {
        apiKey: "${VOLCENGINE_TTS_API_KEY}",
        resourceId: "seed-tts-1.0",
        speakerVoice: "en_female_anna_mars_bigtts",
      },
    },
  },
}

{
  tts: {
    auto: "always",
    provider: "xai",
    providers: {
      xai: {
        apiKey: "${XAI_API_KEY}",
        speakerVoiceId: "eve",
        language: "en",
        responseFormat: "mp3",
      },
    },
  },
}

{
  tts: {
    auto: "always",
    provider: "xiaomi",
    providers: {
      xiaomi: {
        apiKey: "${XIAOMI_API_KEY}",
        model: "mimo-v2.5-tts",
        speakerVoice: "mimo_default",
        format: "mp3",
      },
    },
  },
}

​

Sustituciones de voz por agente

{
  tts: {
    auto: "always",
    provider: "elevenlabs",
    providers: {
      elevenlabs: { apiKey: "${ELEVENLABS_API_KEY}", model: "eleven_multilingual_v2" },
    },
  },
  agents: {
    list: [
      {
        id: "reader",
        tts: {
          providers: {
            elevenlabs: { speakerVoiceId: "EXAVITQu4vr4xnSDxMaL" },
          },
        },
      },
    ],
  },
}

1. tts
2. agents.entries.*.tts activa
3. sustitución del canal, cuando el canal admite channels.<channel>.tts
4. sustitución de la cuenta, cuando el canal proporciona channels.<channel>.accounts.<id>.tts
5. preferencias locales de /tts para este host
6. directivas [[tts:...]] insertadas cuando están habilitadas las sustituciones controladas por el modelo

{
  tts: {
    provider: "openai",
    providers: {
      openai: { apiKey: "${OPENAI_API_KEY}", model: "gpt-4o-mini-tts" },
    },
  },
  channels: {
    feishu: {
      accounts: {
        english: {
          tts: {
            providers: {
              openai: { speakerVoice: "shimmer" },
            },
          },
        },
      },
    },
  },
}

​

Personas

​

Persona mínima

{
  tts: {
    auto: "always",
    persona: "narrator",
    personas: {
      narrator: {
        label: "Narrator",
        provider: "elevenlabs",
        providers: {
          elevenlabs: {
            speakerVoiceId: "EXAVITQu4vr4xnSDxMaL",
            modelId: "eleven_multilingual_v2",
          },
        },
      },
    },
  },
}

​

Persona completa (adaptación específica del proveedor)

{
  tts: {
    auto: "always",
    persona: "alfred",
    personas: {
      alfred: {
        label: "Alfred",
        description: "Dry, warm British butler narrator.",
        provider: "google",
        fallbackPolicy: "preserve-persona",
        providers: {
          google: {
            model: "gemini-3.1-flash-tts-preview",
            speakerVoice: "Algieba",
            promptTemplate: "audio-profile-v1",
          },
          openai: { model: "gpt-4o-mini-tts", speakerVoice: "cedar" },
          elevenlabs: {
            speakerVoiceId: "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 la persona

1. Preferencia local de /tts persona <id>, si está configurada.
2. tts.persona, si está configurada.
3. Sin persona.

1. Sustituciones directas (CLI, Gateway, Talk y directivas TTS permitidas).
2. Preferencia local de /tts provider <id>.
3. provider de la persona activa.
4. tts.provider.
5. Selección automática del registro.

1. tts.providers.<id>
2. tts.personas.<persona>.providers.<id>
3. Sustituciones de solicitudes de confianza
4. Sustituciones permitidas de directivas TTS emitidas por el modelo

​

Adaptación personalizada de personas

​

Política de reserva

​

Directivas controladas por el modelo

Aquí está.

[[tts:speakerVoiceId=pMsXgVXv3BLzUgSXRplE model=eleven_v3 speed=1.1]]
[[tts:text]](ríe) Lee la canción una vez más.[[/tts:text]]

• provider (identificador de proveedor registrado; requiere allowProvider: true)
• speakerVoice / speakerVoiceId (alias heredados: 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, de −12 a 12; los valores fraccionarios se truncan)
• emotion (etiqueta de emoción de Volcengine)
• applyTextNormalization (auto|on|off)
• languageCode (ISO 639-1)
• seed

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

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

​

Comandos de barra

/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>

• /tts on escribe la preferencia local de TTS en always; /tts off la escribe en off.
• /tts chat on|off|default escribe una sustitución de TTS automático limitada a la 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 en la transcripción de la sesión actual y la envía como audio una vez. Solo almacena un hash de esa respuesta en la entrada de la sesión para evitar envíos de voz duplicados.
• /tts audio genera una respuesta de audio puntual (no activa TTS).
• /tts limit <chars> acepta 100–4096 (4096 es el máximo de los pies de foto/mensajes de Telegram); los valores fuera de ese intervalo se rechazan.
• limit y summary se almacenan en las preferencias locales, no en la configuración principal.
• /tts status incluye diagnósticos de reserva para el intento más reciente: Fallback: <primary> -> <used>, Attempts: ... y detalles de cada intento (provider:outcome(reasonCode) latency).
• /status muestra el modo TTS activo, además del proveedor, el modelo y la voz configurados, así como los metadatos depurados del endpoint personalizado cuando TTS está habilitado.

​

Preferencias por usuario

​

Formatos de salida

• Transcodificación de Feishu / WhatsApp: cuando una respuesta de nota de voz llega como MP3/WebM/WAV/M4A u otro archivo probablemente de audio, el plugin del canal la transcodifica a Ogg/Opus de 48 kHz con ffmpeg (libopus, 64 kbps) 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 falla la transcodificación: Feishu captura el error y recurre al envío del archivo original como archivo adjunto simple; WhatsApp no tiene alternativa, por lo que el propio envío falla en lugar de publicar una carga útil PTT incompatible.
• MiniMax: MP3 (modelo speech-2.8-hd, frecuencia de muestreo de 32 kHz) para archivos adjuntos de audio normales; se transcodifica a Opus de 48 kHz con ffmpeg para destinos de notas de voz anunciados por el canal.
• Xiaomi MiMo: MP3 de forma predeterminada, o WAV cuando se configura; se transcodifica a Opus de 48 kHz con ffmpeg para destinos de notas de voz anunciados por el canal.
• CLI local: utiliza el outputFormat configurado. Los destinos de notas de voz se convierten a Ogg/Opus y la salida de telefonía se convierte a PCM mono sin procesar de 16 kHz con ffmpeg.
• Google Gemini: devuelve PCM sin procesar de 24 kHz. OpenClaw lo encapsula como WAV para archivos adjuntos de audio, lo transcodifica a Opus de 48 kHz para destinos de notas de voz y devuelve PCM directamente para Conversación/telefonía.
• Gradium: WAV para archivos adjuntos de audio, Opus para destinos de notas de voz y ulaw_8000 a 8 kHz para telefonía.
• Inworld: MP3 para archivos adjuntos de audio normales, OGG_OPUS nativo para destinos de notas de voz y PCM sin procesar a 22050 Hz para Conversación/telefonía.
• xAI: MP3 de forma predeterminada; la síntesis de archivos de audio puede usar mp3, wav, pcm, mulaw o alaw tanto para la salida almacenada en búfer como para la salida en streaming. Los destinos de notas de voz usan MP3 para el streaming y como alternativa almacenada en búfer, porque las salidas pcm, mulaw y alaw de xAI son audio sin procesar y sin encabezado. La síntesis almacenada en búfer usa el endpoint REST por lotes /v1/tts de xAI; textToSpeechStream usa wss://api.x.ai/v1/tts nativo. Este no es el contrato de voz en tiempo real. No se admite el formato de notas de voz Opus nativo.
• Microsoft: utiliza 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 del formato de salida siguen los formatos de salida de Microsoft Speech (incluidos Ogg/WebM Opus).
  • Telegram sendVoice acepta OGG/MP3/M4A; use OpenAI/ElevenLabs si necesita mensajes de voz Opus garantizados.
  • Si falla el formato de salida de Microsoft configurado, OpenClaw vuelve a intentarlo con MP3.
  • Cuando no se establece ninguna anulación explícita de voz y se utiliza la voz inglesa predeterminada, OpenClaw cambia automáticamente a una voz neuronal china (zh-CN-XiaoxiaoNeural, configuración regional zh-CN) si el texto de la respuesta contiene predominantemente caracteres CJK.

​

Comportamiento de TTS automático

• Omite TTS si la respuesta ya contiene contenido multimedia estructurado.
• Omite las respuestas muy cortas (menos de 10 caracteres).
• Resume las respuestas largas cuando los resúmenes están habilitados, mediante summaryModel (o agents.defaults.model.primary).
• Adjunta el audio generado a la respuesta.
• En mode: "final", sigue enviando TTS de solo audio para las respuestas finales transmitidas una vez completado el flujo de texto; el contenido multimedia generado pasa por la misma normalización multimedia del canal que los archivos adjuntos de respuesta normales.

• Resumen activado (predeterminado) y hay disponible un modelo de resumen: resume el texto a aproximadamente maxLength caracteres y, a continuación, sintetiza el resumen.
• Resumen desactivado, falla el resumen o no hay ninguna clave de API disponible para el modelo de resumen: trunca el texto a maxLength caracteres y sintetiza el texto truncado.

Respuesta -> ¿TTS habilitado?
  no  -> enviar texto
  sí  -> ¿contiene contenido multimedia / es corta?
          sí -> enviar texto
          no  -> ¿longitud > límite?
                   no  -> TTS -> adjuntar audio
                   sí  -> ¿resumen habilitado y disponible?
                            no  -> truncar -> TTS -> adjuntar audio
                            sí  -> resumir -> TTS -> adjuntar audio

​

Referencia de campos

​

Herramienta del agente

​

RPC del Gateway

​

Enlaces de servicios

• Guía de texto a voz de OpenAI
• Referencia de la API de audio de OpenAI
• Texto a voz mediante REST de Azure Speech
• Proveedor de Azure Speech
• Texto a voz de ElevenLabs
• Autenticación de ElevenLabs
• Gradium
• API de TTS de Inworld
• API MiniMax T2A v2
• API HTTP de TTS de Volcengine
• Síntesis de voz de Xiaomi MiMo
• node-edge-tts
• Formatos de salida de voz de Microsoft
• Texto a voz de xAI

​

Temas relacionados

• Descripción general de medios
• Generación de música
• Generación de vídeo
• Comandos de barra
• Plugin de llamadas de voz