Notas de audio y voz

Lo que funciona

Comprensión de medios (audio): Si la comprensión de audio está habilitada (o se detecta automáticamente), OpenClaw:
1. Localiza el primer archivo de audio adjunto (ruta local o URL) y lo descarga si es necesario.
2. Fuerza maxBytes antes de enviarlo a cada entrada del modelo.
3. Ejecuta la primera entrada de modelo elegible en orden (proveedor o CLI).
4. Si falla o se omite (tamaño/tiempo de espera), intenta 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 en la transcripción para que los comandos de barra diagonal sigan funcionando.
Registro detallado: En --verbose, registramos cuándo se ejecuta la transcripción y cuándo reemplaza el cuerpo.

Detección automática (predeterminada)

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

Modelo de respuesta activo cuando su proveedor admite la comprensión de audio.
CLIs locales (si están instaladas)
- sherpa-onnx-offline (requiere SHERPA_ONNX_MODEL_DIR con codificador/decodificador/unidor/tokens)
- whisper-cli (de whisper-cpp; usa WHISPER_CPP_MODEL o el modelo pequeño incluido)
- whisper (CLI de Python; descarga modelos automáticamente)
Autenticación del proveedor
- Las entradas models.providers.* configuradas que soportan audio se intentan primero
- Orden de reserva integrado: OpenAI → Groq → xAI → Deepgram → Google → SenseAudio → ElevenLabs → Mistral

A partir del 2026-05-22, la autodetección de Gemini CLI ya no es compatible con la comprensión de medios. Google está haciendo la transición de los usuarios de Gemini CLI a Antigravity CLI; el audio debe usar la transcripción local o del proveedor, mientras que la reserva de CLI para imagen/video debería pasar a Antigravity CLI (agy).

Para desactivar la autodetección, establezca tools.media.audio.enabled: false. Para personalizar, establezca tools.media.audio.models. Nota: La detección binaria se hace con el mejor esfuerzo posible en macOS/Linux/Windows; asegúrese de que la CLI esté en PATH (nosotros expandimos ~), o establezca un modelo de CLI explícito con una ruta de comando completa.

Ejemplos de configuración

Proveedor + respaldo CLI (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 control de ámbito

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

Solo proveedor (SenseAudio)

{
  tools: {
    media: {
      audio: {
        enabled: true,
        models: [{ provider: "senseaudio", model: "senseaudio-asr-pro-1.5-260319" }],
      },
    },
  },
}

Hacer eco de la transcripción en el chat (opcional)

{
  tools: {
    media: {
      audio: {
        enabled: true,
        echoTranscript: true, // default is false
        echoFormat: '📝 "{transcript}"', // optional, supports {transcript}
        models: [{ provider: "openai", model: "gpt-4o-mini-transcribe" }],
      },
    },
  },
}

Notas y límites

La autenticación del proveedor sigue el orden estándar de autenticación de modelos (perfiles de autenticación, variables de entorno, models.providers.*.apiKey).
Detalles de configuración de Groq: Groq.
Deepgram recoge DEEPGRAM_API_KEY cuando se usa provider: "deepgram".
Detalles de configuración de Deepgram: Deepgram (transcripción de audio).
Detalles de configuración de Mistral: Mistral.
SenseAudio recoge SENSEAUDIO_API_KEY cuando se usa provider: "senseaudio".
Detalles de configuración de SenseAudio: SenseAudio.
Los proveedores de audio pueden anular baseUrl, headers y providerOptions a través de tools.media.audio.
El límite de tamaño predeterminado es 20 MB (tools.media.audio.maxBytes). El audio demasiado grande se omite para ese modelo y se intenta la siguiente entrada.
Los archivos de audio pequeños o vacíos de menos de 1024 bytes se omiten antes de la transcripción del proveedor/CLI.
El maxChars predeterminado para el audio está sin establecer (transcripción completa). Establezca tools.media.audio.maxChars o el maxChars por entrada para recortar la salida.
El valor predeterminado automático de OpenAI es gpt-4o-mini-transcribe; establezca model: "gpt-4o-transcribe" para mayor precisión.
Use tools.media.audio.attachments para procesar múltiples notas de voz (mode: "all" + maxAttachments).
La transcripción está disponible para las plantillas como {{Transcript}}.
tools.media.audio.echoTranscript está desactivado por defecto; actívelo para enviar la confirmación de la transcripción de vuelta al chat de origen antes del procesamiento del agente.
tools.media.audio.echoFormat personaliza el texto de eco (marcador de posición: {transcript}).
La salida estándar de la CLI está limitada (5 MB); mantenga la salida de la CLI concisa.
La CLI args debe usar {{MediaPath}} para la ruta del archivo de audio local. Ejecute openclaw doctor --fix para migrar los marcadores de posición {input} en desuso de configuraciones audio.transcription.command anteriores.

Soporte de entorno de proxy

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

HTTPS_PROXY
HTTP_PROXY
ALL_PROXY
https_proxy
http_proxy
all_proxy

Si no se configuran variables de entorno de proxy, se utiliza una salida directa. Si la configuración del proxy tiene un formato incorrecto, OpenClaw registra una advertencia y recurre a una recuperación directa.

Detección de menciones en grupos

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

Cómo funciona:

Si un mensaje de voz no tiene cuerpo de texto y el grupo requiere menciones, OpenClaw realiza una transcripción de “prevuelo”.
La transcripción se verifica para patrones de mención (por ejemplo, @BotName, activadores de emoji).
Si se encuentra una mención, el mensaje continúa a través de la canalización completa de respuesta.
La transcripción se utiliza para la detección de menciones, de modo que las notas de voz puedan pasar el filtro de menciones.

Comportamiento de reserva:

Si la transcripción falla durante el prevuelo (tiempo de espera, error de API, etc.), el mensaje se procesa basándose únicamente en la detección de menciones por texto.
Esto garantiza que los mensajes mixtos (texto + audio) nunca se descarten incorrectamente.

Opt-out por grupo/tema de Telegram:

Configure channels.telegram.groups.<chatId>.disableAudioPreflight: true para omitir las verificaciones de mención de transcripción previas para ese grupo.
Configure channels.telegram.groups.<chatId>.topics.<threadId>.disableAudioPreflight para anular por tema (true para omitir, false para forzar la activación).
El valor predeterminado es false (prevuelo habilitado cuando coinciden las condiciones de mención).

Ejemplo: Un usuario envía una nota de voz diciendo “Oye @Claude, cuál es el clima?” en un grupo de Telegram con requireMention: true. La nota de voz se transcribe, la mención se detecta y el agente responde.

Trampas

Las reglas de ámbito utilizan el primer criterio que coincida. chatType se normaliza a direct, group o room.
Asegúrese de que su CLI salga con 0 e imprima texto plano; el JSON debe ser procesado a través de 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); los formatos de salida que no son txt vuelven al análisis de stdout.
Mantén los tiempos de espera razonables (timeoutSeconds, 60s por defecto) para evitar bloquear la cola de respuestas.
La transcripción previa solo procesa el primer archivo de audio para la detección de menciones. El audio adicional se procesa durante la fase principal de comprensión de medios.