Comprensión de contenido multimedia

OpenClaw puede resumir los medios entrantes (imagen/audio/vídeo) antes de que se ejecute el flujo de respuestas, 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, aunque también puede configurar modelos explícitos. Los medios originales siempre se entregan al modelo de la forma habitual; cuando la comprensión falla o está deshabilitada, el flujo de respuestas continúa sin cambios.

Los plugins de proveedores registran metadatos de capacidades (qué proveedor admite cada tipo de medio, modelo predeterminado y prioridad). El núcleo de OpenClaw gestiona la configuración compartida tools.media, el orden de alternativas y la integración con el flujo de respuestas.

Cómo funciona

Configuración

tools.media contiene una lista compartida de modelos y anulaciones por capacidad:

{  tools: {    media: {      concurrency: 2, // max concurrent capability runs (default)      models: [/* shared list, gate with capabilities */],      image: {/* optional overrides */},      audio: {        /* optional overrides */        echoTranscript: true,        echoFormat: '📝 "{transcript}"',      },      video: {/* optional overrides */},    },  },}

Claves por capacidad (image/audio/video):

Las opciones específicas de Deepgram se colocan en providerOptions.deepgram (el campo de nivel superior deepgram: { detectLanguage, punctuate, smartFormat } está obsoleto, pero aún se procesa).

Entradas de modelos

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

{  type: "provider", // default if omitted  provider: "openai",  model: "gpt-5.6-sol",  prompt: "Describe the image in <= 500 chars.",  maxChars: 500,  maxBytes: 10485760,  timeoutSeconds: 60,  capabilities: ["image"], // optional, for multi-modal shared entries  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"],}

Credenciales del proveedor

La comprensión de medios mediante proveedores usa la misma resolución de autenticación que las llamadas normales a modelos: perfiles de autenticación, variables de entorno y, después, 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>" },    },  },}

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

Reglas y comportamiento

• Los medios 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; el agente recibe en su lugar 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 medios MiniMax-VL-01, gestionado 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 capaces de procesar visión de forma nativa).
• Si el modelo principal de Gateway/WebChat solo admite texto, los archivos adjuntos de imagen se conservan como referencias externalizadas media://inbound/*, para que las herramientas de imagen/PDF o un modelo de imagen configurado todavía puedan inspeccionarlos en lugar de perder el archivo adjunto.
• La ejecución explícita de openclaw infer image describe --file <path> --model <provider/model> (alias: openclaw capability image describe) utiliza 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 (predeterminada)

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 funcione:

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

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

Compatibilidad con proxy (llamadas de proveedores de audio/vídeo)

La comprensión de audio y vídeo basada en proveedores respeta las variables de entorno estándar de 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 escritas en mayúsculas. Si no se establece ninguna, la comprensión de medios usa una salida directa; si el valor del proxy tiene un formato incorrecto, OpenClaw registra una advertencia y recurre a la obtención directa. La comprensión de imágenes no utiliza esta ruta de proxy.

Capacidades

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

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

Matriz de compatibilidad de proveedores

Orientación para seleccionar modelos

• Prefiera el modelo de la generación actual más potente para cada capacidad multimedia cuando la calidad y la seguridad sean importantes.
• Para agentes con herramientas que procesan entradas no confiables, evite 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 archivos 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: use --output-format txt (o all) con --output-dir y la plantilla de salida predeterminada {filename}. También se respetan las variables de entorno ascendentes 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 usando stdout.

Política de archivos adjuntos

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

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

Extracción de archivos adjuntos

• El texto extraído de los archivos se encapsula como contenido externo no confiable antes de añadirse al mensaje multimedia, mediante marcadores de límites 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 deliberadamente el encabezado largo SECURITY NOTICE: para mantener breve el mensaje multimedia; los marcadores de límites y los metadatos siguen aplicándose.
• Un archivo sin texto extraíble recibe [No extractable text].
• Si un PDF recurre a imágenes renderizadas de sus páginas, OpenClaw envía esas imágenes a los modelos de respuesta con capacidad de visión y conserva el marcador [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",            "Read the media at {{MediaPath}} and describe it in <= {{MaxChars}} characters.",          ],          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", "{{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.",            ],          },        ],      },    },  },}

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

{  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:

📎 Media: image ok (openai/gpt-5.6-sol) · audio ok (whisper-cli observed=metal)

Para obtener el inventario previo, ejecute openclaw capability audio providers. Las filas locales muestran el proveedor alternativo local seleccionado por separado de la selección global de proveedores, la disponibilidad y los campos independientes de backend compatible, solicitado y 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 se realiza en la medida de lo posible. Los errores no bloquean las respuestas.
• Los archivos adjuntos se siguen enviando a los modelos aunque la comprensión esté desactivada.
• Use 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