Comprensión de medios (entrantes) — 2026-01-17

OpenClaw puede resumir medios entrantes (imagen/audio/video) antes de que se ejecute el pipeline de respuesta. Detecta automáticamente cuando hay herramientas locales o claves de proveedor disponibles, y se puede desactivar o personalizar. Si la comprensión está desactivada, los modelos siguen recibiendo los archivos/URLs originales de forma habitual.

Objetivos

  • Opcional: pre-digerir medios entrantes en texto corto para enrutamiento más rápido + mejor análisis de comandos.
  • Preservar la entrega original de medios al modelo (siempre).
  • Soportar APIs de proveedores y respaldos por CLI.
  • Permitir múltiples modelos con respaldo ordenado (error/tamaño/timeout).

Comportamiento general

  1. Recopilar adjuntos entrantes (MediaPaths, MediaUrls, MediaTypes).
  2. Para cada capacidad habilitada (imagen/audio/video), seleccionar adjuntos según la política (por defecto: primero).
  3. Elegir la primera entrada de modelo elegible (tamaño + capacidad + auth).
  4. Si un modelo falla o el medio es demasiado grande, pasar a la siguiente entrada.
  5. En caso de éxito:
    • Body se convierte en un bloque [Image], [Audio] o [Video].
    • Audio establece {{Transcript}}; el análisis de comandos usa el texto del subtítulo cuando existe, en caso contrario la transcripción.
    • Los subtítulos se preservan como User text: dentro del bloque.

Si la comprensión falla o está desactivada, el flujo de respuesta continúa con el cuerpo + adjuntos originales.

Resumen de configuración

tools.media soporta modelos compartidos más sobreescrituras por capacidad:

  • tools.media.models: lista de modelos compartidos (usar capabilities para filtrar).
  • tools.media.image / tools.media.audio / tools.media.video:
    • valores por defecto (prompt, maxChars, maxBytes, timeoutSeconds, language)
    • sobreescrituras de proveedor (baseUrl, headers, providerOptions)
    • opciones de audio Deepgram vía tools.media.audio.providerOptions.deepgram
    • controles de eco de transcripción de audio (echoTranscript, por defecto false; echoFormat)
    • lista opcional de models por capacidad (se prefiere antes que los modelos compartidos)
    • política de attachments (mode, maxAttachments, prefer)
    • scope (filtrado opcional por canal/chatType/clave de sesión)
  • tools.media.concurrency: ejecuciones concurrentes máximas por capacidad (por defecto 2).
{
  tools: {
    media: {
      models: [
        /* lista compartida */
      ],
      image: {
        /* sobreescrituras opcionales */
      },
      audio: {
        /* sobreescrituras opcionales */
        echoTranscript: true,
        echoFormat: '📝 "{transcript}"',
      },
      video: {
        /* sobreescrituras opcionales */
      },
    },
  },
}

Entradas de modelo

Cada entrada de models[] puede ser proveedor o CLI:

{
  type: "provider", // por defecto si se omite
  provider: "openai",
  model: "gpt-5.2",
  prompt: "Describe the image in <= 500 chars.",
  maxChars: 500,
  maxBytes: 10485760,
  timeoutSeconds: 60,
  capabilities: ["image"], // opcional, usado para entradas multimodales
  profile: "vision-profile",
  preferredProfile: "vision-fallback",
}
{
  type: "cli",
  command: "gemini",
  args: [
    "-m",
    "gemini-3-flash",
    "--allowed-tools",
    "read_file",
    "Read the media at {{MediaPath}} and describe it in <= {{MaxChars}} characters.",
  ],
  maxChars: 500,
  maxBytes: 52428800,
  timeoutSeconds: 120,
  capabilities: ["video", "image"],
}

Las plantillas CLI también pueden usar:

  • {{MediaDir}} (directorio que contiene el archivo de medios)
  • {{OutputDir}} (directorio temporal creado para esta ejecución)
  • {{OutputBase}} (ruta base del archivo temporal, sin extensión)

Valores por defecto y límites

Valores recomendados:

  • maxChars: 500 para imagen/video (corto, compatible con comandos)
  • maxChars: sin límite para audio (transcripción completa a menos que establezcas un límite)
  • maxBytes:
    • imagen: 10MB
    • audio: 20MB
    • video: 50MB

Reglas:

  • Si el medio excede maxBytes, ese modelo se omite y se prueba el siguiente modelo.
  • Los archivos de audio menores a 1024 bytes se tratan como vacíos/corruptos y se omiten antes de la transcripción por proveedor/CLI.
  • Si el modelo devuelve más de maxChars, la salida se recorta.
  • prompt por defecto es un simple “Describe the {media}.” más la guía de maxChars (solo imagen/video).
  • Si <capability>.enabled: true pero no hay modelos configurados, OpenClaw prueba el modelo de respuesta activo cuando su proveedor soporta la capacidad.

Detección automática de comprensión de medios (por defecto)

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

  1. CLIs locales (solo audio; si están instalados)
    • sherpa-onnx-offline (requiere SHERPA_ONNX_MODEL_DIR con encoder/decoder/joiner/tokens)
    • whisper-cli (whisper-cpp; usa WHISPER_CPP_MODEL o el modelo tiny incluido)
    • whisper (CLI de Python; descarga modelos automáticamente)
  2. Gemini CLI (gemini) usando read_many_files
  3. Claves de proveedor
    • Audio: OpenAI → Groq → Deepgram → Google
    • Imagen: OpenAI → Anthropic → Google → MiniMax
    • Video: Google

Para desactivar la detección automática, configura:

{
  tools: {
    media: {
      audio: {
        enabled: false,
      },
    },
  },
}

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.

Soporte de proxy (modelos de proveedor)

Cuando la comprensión de medios de audio y video basada en proveedores está habilitada, OpenClaw respeta las variables de entorno estándar de proxy para llamadas HTTP a proveedores:

  • HTTPS_PROXY
  • HTTP_PROXY
  • https_proxy
  • http_proxy

Si no hay variables de proxy configuradas, la comprensión de medios usa conexión directa. Si el valor del proxy es incorrecto, OpenClaw registra una advertencia y recurre a la conexión directa.

Capacidades (opcional)

Si configuras capabilities, la entrada solo se ejecuta para esos tipos de medios. Para listas compartidas, OpenClaw puede inferir valores por defecto:

  • openai, anthropic, minimax: image
  • google (API Gemini): image + audio + video
  • groq: audio
  • deepgram: audio

Para entradas CLI, configura capabilities explícitamente para evitar coincidencias inesperadas. Si omites capabilities, la entrada es elegible para la lista en la que aparece.

Matriz de soporte de proveedores (integraciones de OpenClaw)

CapacidadIntegración de proveedorNotas
ImagenOpenAI / Anthropic / Google / otros vía pi-aiCualquier modelo con capacidad de imagen del registro funciona.
AudioOpenAI, Groq, Deepgram, Google, MistralTranscripción por proveedor (Whisper/Deepgram/Gemini/Voxtral).
VideoGoogle (API Gemini)Comprensión de video por proveedor.

Guía de selección de modelos

  • Prefiere el modelo más potente de última generación disponible para cada capacidad de medios cuando la calidad y seguridad importan.
  • Para agentes con herramientas que manejan entradas no confiables, evita modelos de medios antiguos/débiles.
  • Mantén al menos un respaldo por capacidad para disponibilidad (modelo de calidad + modelo más rápido/barato).
  • Los respaldos por CLI (whisper-cli, whisper, gemini) son útiles cuando las APIs de proveedores no están disponibles.
  • Nota sobre parakeet-mlx: con --output-dir, OpenClaw lee <output-dir>/<media-basename>.txt cuando el formato de salida es txt (o no se especifica); formatos no-txt recurren a stdout.

Política de adjuntos

attachments por capacidad controla qué adjuntos se procesan:

  • mode: first (por defecto) o all
  • maxAttachments: límite del número procesado (por defecto 1)
  • prefer: first, last, path, url

Cuando mode: "all", las salidas se etiquetan como [Image 1/2], [Audio 2/2], etc.

Ejemplos de configuración

1) Lista de modelos compartidos + sobreescrituras

{
  tools: {
    media: {
      models: [
        { provider: "openai", model: "gpt-5.2", capabilities: ["image"] },
        {
          provider: "google",
          model: "gemini-3-flash-preview",
          capabilities: ["image", "audio", "video"],
        },
        {
          type: "cli",
          command: "gemini",
          args: [
            "-m",
            "gemini-3-flash",
            "--allowed-tools",
            "read_file",
            "Read the media at {{MediaPath}} and describe it in <= {{MaxChars}} characters.",
          ],
          capabilities: ["image", "video"],
        },
      ],
      audio: {
        attachments: { mode: "all", maxAttachments: 2 },
      },
      video: {
        maxChars: 500,
      },
    },
  },
}

2) Solo audio + video (imagen desactivada)

{
  tools: {
    media: {
      audio: {
        enabled: true,
        models: [
          { provider: "openai", model: "gpt-4o-mini-transcribe" },
          {
            type: "cli",
            command: "whisper",
            args: ["--model", "base", "{{MediaPath}}"],
          },
        ],
      },
      video: {
        enabled: true,
        maxChars: 500,
        models: [
          { provider: "google", model: "gemini-3-flash-preview" },
          {
            type: "cli",
            command: "gemini",
            args: [
              "-m",
              "gemini-3-flash",
              "--allowed-tools",
              "read_file",
              "Read the media at {{MediaPath}} and describe it in <= {{MaxChars}} characters.",
            ],
          },
        ],
      },
    },
  },
}

3) Comprensión de imagen opcional

{
  tools: {
    media: {
      image: {
        enabled: true,
        maxBytes: 10485760,
        maxChars: 500,
        models: [
          { provider: "openai", model: "gpt-5.2" },
          { provider: "anthropic", model: "claude-opus-4-6" },
          {
            type: "cli",
            command: "gemini",
            args: [
              "-m",
              "gemini-3-flash",
              "--allowed-tools",
              "read_file",
              "Read the media at {{MediaPath}} and describe it in <= {{MaxChars}} characters.",
            ],
          },
        ],
      },
    },
  },
}

4) Entrada multimodal única (capacidades explícitas)

{
  tools: {
    media: {
      image: {
        models: [
          {
            provider: "google",
            model: "gemini-3.1-pro-preview",
            capabilities: ["image", "video", "audio"],
          },
        ],
      },
      audio: {
        models: [
          {
            provider: "google",
            model: "gemini-3.1-pro-preview",
            capabilities: ["image", "video", "audio"],
          },
        ],
      },
      video: {
        models: [
          {
            provider: "google",
            model: "gemini-3.1-pro-preview",
            capabilities: ["image", "video", "audio"],
          },
        ],
      },
    },
  },
}

Salida de estado

Cuando la comprensión de medios se ejecuta, /status incluye una línea de resumen:

📎 Media: image ok (openai/gpt-5.2) · audio skipped (maxBytes)

Esto muestra resultados por capacidad y el proveedor/modelo elegido cuando corresponda.

Notas

  • La comprensión es best-effort. Los errores no bloquean las respuestas.
  • Los adjuntos se siguen pasando a los modelos incluso cuando la comprensión está desactivada.
  • Usa scope para limitar dónde se ejecuta la comprensión (p. ej. solo DMs).

Documentación relacionada

arrow_back
Anterior
Troubleshooting
Siguiente
Images
arrow_forward