Comprensión de medios

OpenClaw puede resumir medios entrantes (imagen/audio/video) antes de que se ejecute la canalización de respuesta. Detecta automáticamente cuándo 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/URL originales como de costumbre.

El comportamiento de medios específico de cada proveedor lo registran los plugins de proveedor, mientras que el núcleo de OpenClaw es dueño de la configuración compartida tools.media, el orden de respaldo y la integración con la canalización de respuesta.

Objetivos

• Opcional: predigerir los medios entrantes en texto breve para un enrutamiento más rápido y mejor análisis de comandos.
• Preservar la entrega de medios originales al modelo (siempre).
• Admitir API de proveedor y respaldos CLI.
• Permitir varios modelos con respaldo ordenado (error/tamaño/tiempo de espera).

Comportamiento general

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

Resumen de configuración

tools.media admite modelos compartidos más sobrescrituras por capacidad:

{  tools: {    media: {      models: [        /* shared list */      ],      image: {        /* optional overrides */      },      audio: {        /* optional overrides */        echoTranscript: true,        echoFormat: '📝 "{transcript}"',      },      video: {        /* optional overrides */      },    },  },}

Entradas de modelo

Cada entrada models[] puede ser proveedor o CLI:

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

Valores predeterminados y límites

Valores predeterminados recomendados:

• maxChars: 500 para imagen/video (breve, apto para comandos)
• maxChars: sin definir para audio (transcripción completa salvo que definas un límite)
• maxBytes:
  • imagen: 10MB
  • audio: 20MB
  • video: 50MB

Detectar automáticamente la comprensión de medios (predeterminado)

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

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

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

Compatibilidad con entorno de proxy (modelos de proveedor)

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

• HTTPS_PROXY
• HTTP_PROXY
• ALL_PROXY
• https_proxy
• http_proxy
• all_proxy

Si no hay variables de entorno de proxy definidas, la comprensión de medios usa salida directa. Si el valor del proxy tiene un formato incorrecto, OpenClaw registra una advertencia y vuelve a la obtención directa.

Capacidades (opcional)

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

• openai, anthropic, minimax: imagen
• minimax-portal: imagen
• moonshot: imagen + video
• openrouter: imagen + audio
• google (API de Gemini): imagen + audio + video
• qwen: imagen + video
• mistral: audio
• zai: imagen
• groq: audio
• xai: audio
• deepgram: audio
• Cualquier catálogo models.providers.<id>.models[] con un modelo con capacidad de imagen: imagen

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

Matriz de soporte de proveedores (integraciones de OpenClaw)

Guía de selección de modelos

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

Política de adjuntos

attachments por capacidad controla qué adjuntos se procesan:

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

Ejemplos de configuración

{  tools: {    media: {      models: [        { provider: "openai", model: "gpt-5.5", 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.5" },          { 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.",            ],          },        ],      },    },  },}

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

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

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

Notas

• La comprensión es de mejor esfuerzo. Los errores no bloquean las respuestas.
• Los adjuntos se siguen pasando a los modelos incluso cuando la comprensión está deshabilitada.
• Usa scope para limitar dónde se ejecuta la comprensión (por ejemplo, solo mensajes directos).

Relacionado

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