Comprensión de contenido multimedia

OpenClaw puede resumir los archivos multimedia entrantes (imagen/audio/video) antes de que se ejecute el pipeline de respuesta, de modo que el análisis de comandos y el enrutamiento trabajen con texto breve en lugar de bytes sin procesar. La comprensión detecta automáticamente las herramientas locales o las claves de proveedores, o se pueden configurar modelos explícitos. Los archivos multimedia originales siempre se entregan al modelo como de costumbre; cuando la comprensión falla o está deshabilitada, el flujo de respuesta continúa sin cambios.

Los plugins de proveedores registran metadatos de capacidades (qué proveedor admite cada tipo de archivo multimedia, modelo predeterminado y prioridad). El núcleo de OpenClaw controla la configuración compartida tools.media, el orden de respaldo y la integración con el pipeline de respuesta.

Cómo funciona

Configuración

tools.media contiene una lista de modelos etiquetados por capacidad y pequeños controles para cada capacidad:

{  tools: {    media: {      concurrency: 2, // máximo de ejecuciones de capacidades simultáneas (valor predeterminado)      models: [        { provider: "openai", model: "gpt-4o-mini-transcribe", capabilities: ["audio"] },        { provider: "google", model: "gemini-3-flash-preview", capabilities: ["image", "video"] },      ],      image: { preferredModel: "google/gemini-3-flash-preview" },      audio: { enabled: true },      video: { enabled: true },    },  },}

Claves por capacidad (image/audio/video):

Los prompts, límites, indicaciones de idioma, reemplazos de solicitudes y opciones de proveedores se pueden establecer como valores predeterminados de la capacidad o reemplazar en entradas tools.media.models[] individuales. Los valores predeterminados de la capacidad también se aplican a los proveedores detectados automáticamente cuando no se configura ningún modelo explícito.

Entradas de modelos

Cada entrada models[] es una entrada de proveedor (valor predeterminado) o una entrada de CLI:

{  type: "provider", // valor predeterminado si se omite  provider: "openai",  model: "gpt-5.6-sol",  prompt: "Describe la imagen en <= 500 caracteres.",  maxChars: 500,  maxBytes: 10485760,  timeoutSeconds: 60,  capabilities: ["image"],  profile: "vision-profile",  preferredProfile: "vision-fallback",}

{  type: "cli",  command: "gemini",  args: [    "-m",    "gemini-3-flash",    "--allowed-tools",    "read_file",    "Lee el archivo multimedia en {{AttachmentPath}} y descríbelo en <= {{MaxChars}} caracteres.",  ],  maxChars: 500,  maxBytes: 52428800,  timeoutSeconds: 120,  capabilities: ["video", "image"],}

Credenciales del proveedor

La comprensión de archivos multimedia mediante proveedores utiliza la misma resolución de autenticación que las llamadas normales a modelos: perfiles de autenticación, variables de entorno y, a continuación, models.providers.<providerId>.apiKey. Las entradas tools.media.models[] no aceptan un campo apiKey en línea.

{  models: {    providers: {      openai: { apiKey: "<OPENAI_API_KEY>" },      moonshot: { apiKey: "<MOONSHOT_API_KEY>" },    },  },}

Consulta Herramientas y proveedores personalizados para obtener información sobre los perfiles, las variables de entorno y las URL base personalizadas.

Reglas y comportamiento

• Los archivos multimedia que superan maxBytes omiten ese modelo y prueban el siguiente.
• Los archivos de audio de menos de 1024 bytes se consideran vacíos o dañados y se omiten antes de la transcripción; en su lugar, el agente recibe una transcripción de marcador de posición determinista.
• Si el modelo de imagen principal activo ya admite visión de forma nativa, OpenClaw omite el bloque de resumen [Image] y pasa la imagen original directamente al modelo. MiniMax es una excepción: minimax, minimax-cn, minimax-portal y minimax-portal-cn siempre enrutan la comprensión de imágenes mediante el proveedor de archivos multimedia MiniMax-VL-01 controlado por el plugin, aunque los metadatos heredados de chat de MiniMax M2.x indiquen que admite entrada de imágenes (solo MiniMax-M3 y versiones posteriores se consideran compatibles con visión de forma nativa).
• Si el modelo principal de Gateway/WebChat solo admite texto, los archivos de imagen adjuntos se conservan como referencias media://inbound/* descargadas, de modo que las herramientas de imagen/PDF o un modelo de imagen configurado puedan inspeccionarlos sin perder el archivo adjunto.
• La configuración explícita de openclaw infer image describe --file <path> --model <provider/model> (alias: openclaw capability image describe) ejecuta directamente ese proveedor/modelo compatible con imágenes, incluidas referencias de Ollama como ollama/qwen2.5vl:7b cuando se configura un modelo compatible con imágenes coincidente en models.providers.ollama.models[].
• Si <capability>.enabled no es false, pero no hay modelos configurados, OpenClaw prueba el modelo de respuesta activo cuando su proveedor admite la capacidad.

Detección automática (valor predeterminado)

Cuando tools.media.<capability>.enabled no es false y no hay modelos configurados, OpenClaw prueba las siguientes opciones en orden y se detiene en la primera que funciona:

Para deshabilitar la detección automática de una capacidad:

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

Compatibilidad con proxy (llamadas de proveedores de audio/video)

La comprensión de audio y video mediante proveedores respeta las variables de entorno estándar del proxy saliente, incluidas las reglas de omisión NO_PROXY/no_proxy: HTTPS_PROXY, HTTP_PROXY, ALL_PROXY, https_proxy, http_proxy, all_proxy. Las variables en minúsculas tienen prioridad sobre las que están en mayúsculas. Si no se establece ninguna, la comprensión de archivos multimedia utiliza una salida directa; si el valor del proxy tiene un formato incorrecto, OpenClaw registra una advertencia y vuelve a la recuperación directa. La comprensión de imágenes no utiliza esta ruta de proxy.

Capacidades

Establece capabilities en una entrada models[] para restringirla a tipos específicos de archivos multimedia. En las listas compartidas, OpenClaw infiere los valores predeterminados para cada proveedor incluido:

Para las entradas de la CLI, establezca capabilities explícitamente para evitar coincidencias inesperadas; si se omite, la entrada será apta para todas las listas de capacidades en las que aparezca.

Matriz de compatibilidad de proveedores

Orientación para seleccionar modelos

• Cuando la calidad y la seguridad sean importantes, utilice el modelo de la generación actual más potente para cada capacidad multimedia.
• En agentes con herramientas que gestionen entradas no confiables, evite los modelos multimedia antiguos o menos potentes.
• Mantenga al menos una alternativa por capacidad para garantizar la disponibilidad (un modelo de calidad y otro más rápido o económico).
• Las alternativas de la CLI (whisper-cli, whisper, gemini) resultan útiles cuando las API de los proveedores no están disponibles.
• Los modos conocidos de salida a archivo son autoritativos: si el archivo de transcripción inferido está vacío o no existe, no se genera ninguna transcripción en lugar de recurrir a la salida de progreso de la CLI.
• parakeet-mlx: utilice --output-format txt (o all) con --output-dir y la plantilla de salida predeterminada {filename}. También se respetan las variables de entorno del proyecto de origen PARAKEET_OUTPUT_FORMAT y PARAKEET_OUTPUT_TEMPLATE. OpenClaw lee <output-dir>/<media-basename>.txt; el formato predeterminado srt, los demás formatos y las plantillas de salida personalizadas siguen utilizando stdout.

Política de archivos adjuntos

La opción attachments de cada capacidad controla qué archivos adjuntos se procesan:

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

Extracción de archivos adjuntos

• El texto extraído de los archivos se delimita como contenido externo no confiable antes de añadirse al prompt multimedia, mediante marcadores de límite como <<&lt;EXTERNAL_UNTRUSTED_CONTENT id=&quot;...&quot;&gt;>> / <<&lt;END_EXTERNAL_UNTRUSTED_CONTENT id=&quot;...&quot;&gt;>> y una línea de metadatos Source: External.
• Esta ruta omite intencionadamente el extenso aviso SECURITY NOTICE: para mantener breve el prompt multimedia; los marcadores de límite y los metadatos siguen aplicándose.
• Los archivos sin texto extraíble reciben [No extractable text].
• Si un PDF recurre a imágenes renderizadas de sus páginas, OpenClaw reenvía esas imágenes a los modelos de respuesta con capacidad de visión y conserva el marcador de posición [PDF content rendered to images] en el bloque del archivo.

Ejemplos de configuración

{  tools: {    media: {      models: [        { provider: "openai", model: "gpt-5.6-sol", 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",            "Lee el contenido multimedia de {{AttachmentPath}} y descríbelo en <= {{MaxChars}} caracteres.",          ],          capabilities: ["image", "video"],        },      ],      audio: {        attachments: { mode: "all", maxAttachments: 2 },      },      video: {        maxChars: 500,      },    },  },}

{  tools: {    media: {      audio: {        enabled: true,        models: [          { provider: "openai", model: "gpt-4o-mini-transcribe" },          {            type: "cli",            command: "whisper",            args: ["--model", "base", "{{AttachmentPath}}"],          },        ],      },      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",              "Lee el contenido multimedia de {{AttachmentPath}} y descríbelo en <= {{MaxChars}} caracteres.",            ],          },        ],      },    },  },}

{  tools: {    media: {      image: {        enabled: true,        maxBytes: 10485760,        maxChars: 500,        models: [          { provider: "openai", model: "gpt-5.6-sol" },          { provider: "anthropic", model: "claude-opus-5" },          {            type: "cli",            command: "gemini",            args: [              "-m",              "gemini-3-flash",              "--allowed-tools",              "read_file",              "Lee el contenido multimedia de {{AttachmentPath}} y descríbelo en <= {{MaxChars}} caracteres.",            ],          },        ],      },    },  },}

{  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 se ejecuta la comprensión multimedia, /status incluye una línea de resumen por capacidad:

📎 Medios: imagen correcta (openai/gpt-5.6-sol) · audio correcto (whisper-cli observado=metal)

Para realizar el inventario previo, ejecute openclaw capability audio providers. Las filas locales muestran por separado la alternativa local elegida, la selección global del proveedor, la disponibilidad y los campos independientes de backend capaz/solicitado/observado. La misma selección local está disponible como hallazgo informativo de doctor:

openclaw doctor --lint --only core/doctor/local-audio-acceleration --severity-min info

Notas

• La comprensión funciona según el mejor esfuerzo posible. Los errores no bloquean las respuestas.
• Los archivos adjuntos se siguen enviando a los modelos aunque la comprensión esté desactivada.
• Utilice scope para limitar dónde se ejecuta la comprensión (por ejemplo, solo en mensajes directos).

Contenido relacionado

• Configuración
• Compatibilidad con imágenes y contenido multimedia