Audio / Notas de voz — 2026-01-17

Qué funciona

Comprensión de medios (audio): Si la comprensión de audio está habilitada (o se detecta automáticamente), OpenClaw:
1. Localiza el primer adjunto de audio (ruta local o URL) y lo descarga si es necesario.
2. Aplica maxBytes antes de enviarlo a cada entrada de modelo.
3. Ejecuta la primera entrada de modelo elegible en orden (proveedor o CLI).
4. Si falla o se omite (tamaño/timeout), prueba con la siguiente entrada.
5. Si tiene éxito, reemplaza Body con un bloque [Audio] y establece {{Transcript}}.
Análisis de comandos: Cuando la transcripción tiene éxito, CommandBody/RawBody se establecen con la transcripción para que los comandos slash sigan funcionando.
Registro detallado: Con --verbose, se registra cuándo se ejecuta la transcripción y cuándo reemplaza el cuerpo del mensaje.

Detección automática (por defecto)

Si no configuras modelos y tools.media.audio.enabled no está en false, OpenClaw detecta automáticamente en este orden y se detiene en la primera opción funcional:

CLIs locales (si están instalados)
- sherpa-onnx-offline (requiere SHERPA_ONNX_MODEL_DIR con encoder/decoder/joiner/tokens)
- whisper-cli (de whisper-cpp; usa WHISPER_CPP_MODEL o el modelo tiny incluido)
- whisper (CLI de Python; descarga modelos automáticamente)
Gemini CLI (gemini) usando read_many_files
Claves de proveedor (OpenAI → Groq → Deepgram → Google)

Para desactivar la detección automática, establece tools.media.audio.enabled: false. Para personalizar, configura tools.media.audio.models. Nota: La detección de binarios es best-effort en macOS/Linux/Windows; asegúrate de que el CLI esté en el PATH (expandimos ~), o configura un modelo CLI explícito con la ruta completa del comando.

Ejemplos de configuración

Proveedor + CLI de respaldo (OpenAI + Whisper CLI)

{
  tools: {
    media: {
      audio: {
        enabled: true,
        maxBytes: 20971520,
        models: [
          { provider: "openai", model: "gpt-4o-mini-transcribe" },
          {
            type: "cli",
            command: "whisper",
            args: ["--model", "base", "{{MediaPath}}"],
            timeoutSeconds: 45,
          },
        ],
      },
    },
  },
}

Solo proveedor con filtrado por alcance

{
  tools: {
    media: {
      audio: {
        enabled: true,
        scope: {
          default: "allow",
          rules: [{ action: "deny", match: { chatType: "group" } }],
        },
        models: [{ provider: "openai", model: "gpt-4o-mini-transcribe" }],
      },
    },
  },
}

Solo proveedor (Deepgram)

{
  tools: {
    media: {
      audio: {
        enabled: true,
        models: [{ provider: "deepgram", model: "nova-3" }],
      },
    },
  },
}

Solo proveedor (Mistral Voxtral)

{
  tools: {
    media: {
      audio: {
        enabled: true,
        models: [{ provider: "mistral", model: "voxtral-mini-latest" }],
      },
    },
  },
}

Eco de transcripción al chat (opcional)

{
  tools: {
    media: {
      audio: {
        enabled: true,
        echoTranscript: true, // por defecto es false
        echoFormat: '📝 "{transcript}"', // opcional, admite {transcript}
        models: [{ provider: "openai", model: "gpt-4o-mini-transcribe" }],
      },
    },
  },
}

Notas y límites

La autenticación de proveedores sigue el orden estándar de autenticación de modelos (perfiles de auth, variables de entorno, models.providers.*.apiKey).
Deepgram usa DEEPGRAM_API_KEY cuando se utiliza provider: "deepgram".
Detalles de configuración de Deepgram: Deepgram (transcripción de audio).
Detalles de configuración de Mistral: Mistral.
Los proveedores de audio pueden sobreescribir baseUrl, headers y providerOptions a través de tools.media.audio.
El límite de tamaño por defecto es 20MB (tools.media.audio.maxBytes). El audio que exceda el tamaño se omite para ese modelo y se prueba la siguiente entrada.
Los archivos de audio pequeños o vacíos por debajo de 1024 bytes se omiten antes de la transcripción por proveedor/CLI.
El maxChars por defecto para audio es sin límite (transcripción completa). Configura tools.media.audio.maxChars o maxChars por entrada para recortar la salida.
El modelo auto por defecto de OpenAI es gpt-4o-mini-transcribe; usa model: "gpt-4o-transcribe" para mayor precisión.
Usa tools.media.audio.attachments para procesar múltiples notas de voz (mode: "all" + maxAttachments).
La transcripción está disponible para plantillas como {{Transcript}}.
tools.media.audio.echoTranscript está desactivado por defecto; actívalo para enviar la confirmación de transcripción al chat de origen antes del procesamiento del agente.
tools.media.audio.echoFormat personaliza el texto del eco (marcador: {transcript}).
La salida stdout del CLI está limitada (5MB); mantén la salida del CLI concisa.

Soporte de proxy

La transcripción de audio basada en proveedores respeta las variables de entorno estándar para proxy de salida:

HTTPS_PROXY
HTTP_PROXY
https_proxy
http_proxy

Si no hay variables de proxy configuradas, se usa la conexión directa. Si la configuración del proxy es incorrecta, OpenClaw registra una advertencia y recurre a la conexión directa.

Detección de menciones en grupos

Cuando requireMention: true está configurado para un chat grupal, OpenClaw transcribe el audio antes de verificar las menciones. Esto permite procesar notas de voz incluso cuando contienen menciones.

Cómo funciona:

Si un mensaje de voz no tiene texto y el grupo requiere menciones, OpenClaw realiza una transcripción “preflight”.
La transcripción se verifica en busca de patrones de mención (p. ej., @NombreBot, disparadores de emoji).
Si se encuentra una mención, el mensaje continúa por el pipeline completo de respuesta.
La transcripción se usa para la detección de menciones, permitiendo que las notas de voz pasen el filtro de menciones.

Comportamiento de respaldo:

Si la transcripción falla durante el preflight (timeout, error de API, etc.), el mensaje se procesa basándose solo en la detección de menciones por texto.
Esto asegura que los mensajes mixtos (texto + audio) nunca se descarten incorrectamente.

Desactivar por grupo/tema de Telegram:

Configura channels.telegram.groups.<chatId>.disableAudioPreflight: true para omitir las verificaciones de mención por transcripción preflight en ese grupo.
Configura channels.telegram.groups.<chatId>.topics.<threadId>.disableAudioPreflight para sobreescribir por tema (true para omitir, false para forzar la activación).
El valor por defecto es false (preflight habilitado cuando las condiciones de filtrado por mención coinciden).

Ejemplo: Un usuario envía una nota de voz diciendo “Oye @Claude, ¿qué tiempo hace?” en un grupo de Telegram con requireMention: true. La nota de voz se transcribe, se detecta la mención y el agente responde.

Errores comunes

Las reglas de alcance usan “primera coincidencia gana”. chatType se normaliza a direct, group o room.
Asegúrate de que tu CLI termine con código 0 e imprima texto plano; si el JSON necesita procesamiento, usa jq -r .text.
Para parakeet-mlx, si pasas --output-dir, OpenClaw lee <output-dir>/<media-basename>.txt cuando --output-format es txt (o se omite); formatos de salida distintos a txt recurren al análisis de stdout.
Mantén los timeouts razonables (timeoutSeconds, por defecto 60s) para evitar bloquear la cola de respuestas.
La transcripción preflight solo procesa el primer adjunto de audio para la detección de menciones. El audio adicional se procesa durante la fase principal de comprensión de medios.