Comprensión multimedia

OpenClaw puede resumir los medios entrantes (imagen/audio/vídeo) antes de que se ejecute la canalización 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/URL originales como de costumbre.

El comportamiento específico del proveedor para medios se registra mediante complementos del proveedor, mientras que el núcleo de OpenClaw posee la configuración compartida tools.media, el orden de alternancia y la integración con la canalización de respuesta.

Objetivos

Opcional: preprocesar los medios entrantes en texto breve para un enrutamiento más rápido + una mejor análise de comandos.
Conservar la entrega de medios original al modelo (siempre).
Soportar APIs de proveedores y reservas de CLI.
Permitir múltiples modelos con reserva ordenada (error/tamaño/tiempo de espera).

Comportamiento de alto nivel

Recopilar archivos adjuntos
Recopila archivos adjuntos entrantes (MediaPaths, MediaUrls, MediaTypes).
Seleccionar por capacidad
Para cada capacidad habilitada (imagen/audio/video), selecciona los archivos adjuntos según la política (predeterminado: primero).
Elegir modelo
Elige la primera entrada de modelo elegible (tamaño + capacidad + autenticación).
Alternativa en caso de fallo
Si un modelo falla o el medio es demasiado grande, recurra a la siguiente entrada.
Aplicar bloque de éxito
En caso de éxito:
- Body se convierte en un bloque [Image], [Audio] o [Video].
- El audio establece {{Transcript}}; el análisis de comandos utiliza el texto de subtítulos cuando está presente, de lo contrario la transcripción.
- Los subtítulos se conservan como User text: dentro del bloque.

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

Resumen de la configuración

tools.media admite modelos compartidos además de anulaciones por capacidad:

Claves de nivel superior

tools.media.models: lista de modelos compartidos (use capabilities para restringir).
tools.media.image / tools.media.audio / tools.media.video:
- valores predeterminados (prompt, maxChars, maxBytes, timeoutSeconds, language)
- anulaciones del proveedor (baseUrl, headers, providerOptions)
- opciones de audio de Deepgram a través de tools.media.audio.providerOptions.deepgram
- controles de eco de transcripción de audio (echoTranscript, predeterminado false; echoFormat)
- lista models por capacidad opcional (preferida antes que los modelos compartidos)
- política de attachments (mode, maxAttachments, prefer)
- scope (restricción opcional por clave de canal/chatType/sesión)
tools.media.concurrency: máximo de ejecuciones simultáneas de capacidades (predeterminado 2).

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

Entradas de modelo

Cada entrada de models[] puede ser de 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"],
}

Las plantillas de CLI también pueden usar:

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

Credenciales del proveedor (`apiKey`)

La comprensión multimedia del proveedor utiliza la misma resolución de autenticación del proveedor que las llamadas a modelos normales: perfiles de autenticación, variables de entorno y luego models.providers.<providerId>.apiKey.

Las entradas tools.media.*.models[] no aceptan un campo apiKey en línea. El valor provider en una entrada de modelo multimedia, como openai o moonshot, debe tener credenciales disponibles a través de una de las fuentes estándar de autenticación del proveedor.

Ejemplo mínimo:

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

Para la referencia completa de autenticación del proveedor, incluyendo perfiles, variables de entorno y URLs base personalizadas, consulte Herramientas y proveedores personalizados.

Valores predeterminados y límites

Valores predeterminados recomendados:

maxChars: 500 para imagen/video (corto, apto para comandos)
maxChars: sin establecer para audio (transcripción completa a menos que establezca 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 de 1024 bytes se tratan como vacíos/corruptos y se omiten antes de la transcripción del proveedor/CLI; el contexto de respuesta entrante recibe una transcripción de marcador de posición determinista para que el agente sepa que la nota era demasiado pequeña.
Si el modelo devuelve más de maxChars, la salida se recorta.
prompt tiene como valor predeterminado un simple “Describa el {media}.” más la guía maxChars (solo imagen/video).
Si el modelo de imagen principal activo ya admite la visión de forma nativa, OpenClaw omite el bloque de resumen [Image] y pasa la imagen original al modelo en su lugar.
Si un modelo principal de Gateway/WebChat es solo de texto, los archivos adjuntos de imagen se conservan como referencias media://inbound/* externalizadas para que las herramientas de imagen/PDF o el modelo de imagen configurado puedan inspeccionarlos en lugar de perder el archivo adjunto.
Las solicitudes explícitas `openclaw infer image describe —model

son diferentes: ejecutan ese proveedor/modelo con capacidad de imagen directamente, incluyendo referencias de Ollama comoollama/qwen2.5vl:7b. - Si

.enabled: true` pero no hay modelos configurados, OpenClaw intenta el modelo de respuesta activo cuando su proveedor admite la capacidad.

Detección automática de 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:

Modelo de respuesta activo
Modelo de respuesta activo cuando su proveedor admite la capacidad.
agents.defaults.imageModel
Referencias agents.defaults.imageModel principal/de respaldo (solo imagen). Se prefieren referencias provider/model. Las referencias simples se califican desde las entradas de modelo de proveedor con capacidad de imagen configuradas solo cuando la coincidencia es única.
CLIs locales (solo audio)
CLIs locales (si están instalados):
- sherpa-onnx-offline (requiere SHERPA_ONNX_MODEL_DIR con codificador/decodificador/unidor/tokens)
- whisper-cli (whisper-cpp; usa WHISPER_CPP_MODEL o el modelo pequeño incluido)
- whisper (CLI de Python; descarga modelos automáticamente)
CLI de Gemini
gemini usando read_many_files.
Autenticación del proveedor
- Las entradas models.providers.* configuradas que admiten la capacidad se prueban antes del orden de respaldo incluido.
- Los proveedores de configuración solo de imagen con un modelo con capacidad de imagen se registran automáticamente para la comprensión de medios incluso cuando no son un complemento de proveedor incluido.
- La comprensión de imágenes de Ollama está disponible cuando se selecciona explícitamente, por ejemplo a través de agents.defaults.imageModel o `openclaw infer image describe —model ollama/
`.
Orden de respaldo incluido: - Audio: OpenAI → Groq → xAI → Deepgram → OpenRouter → Google → SenseAudio → ElevenLabs → Mistral - Imagen: OpenAI → Anthropic → Google → MiniMax → MiniMax Portal → Z.AI - Video: Google → Qwen → Moonshot

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

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

Soporte de entorno proxy (modelos de proveedor)

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

HTTPS_PROXY
HTTP_PROXY
ALL_PROXY
https_proxy
http_proxy
all_proxy

Si no se establecen variables de entorno de proxy, la comprensión de medios usa una salida directa. Si el valor del proxy está malformado, OpenClaw registra una advertencia y recurre a una obtención directa.

Capacidades (opcional)

Si establece capabilities, la entrada solo se ejecuta para esos tipos de medios. Para listas compartidas, OpenClaw puede inferir los 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 las entradas de CLI, establezca capabilities explícitamente para evitar coincidencias sorprendentes. Si omite capabilities, la entrada es elegible para la lista en la que aparece.

Matriz de soporte de proveedor (integraciones de OpenClaw)

Capacidad	Integración del proveedor	Notas
Imagen	OpenAI, OpenAI Codex OAuth, Codex app-server, OpenRouter, Anthropic, Google, MiniMax, Moonshot, Qwen, Z.AI, proveedores de configuración	Los complementos de proveedores registran el soporte de imágenes; `openai/` puede usar routing de API-key o Codex OAuth; `codex/` usa un turno acotado del servidor de aplicaciones Codex; MiniMax y MiniMax OAuth ambos usan `MiniMax-VL-01`; los proveedores de configuración con capacidad de imagen se registran automáticamente.
Audio	OpenAI, Groq, xAI, Deepgram, OpenRouter, Google, SenseAudio, ElevenLabs, Mistral	Transcripción del proveedor (Whisper/Groq/xAI/Deepgram/OpenRouter STT/Gemini/SenseAudio/Scribe/Voxtral).
Vídeo	Google, Qwen, Moonshot	Comprensión de vídeo del proveedor a través de complementos del proveedor; la comprensión de vídeo de Qwen utiliza los endpoints estándar de DashScope.

Guía de selección de modelo

Prefiera el modelo de última generación más fuerte disponible para cada capacidad de medios cuando la calidad y la seguridad son importantes.
Para agentes con herramientas habilitadas que manejen entradas que no son de confianza, evite modelos de medios más antiguos o más débiles.
Mantenga al menos un respaldo por capacidad para disponibilidad (modelo de calidad + modelo más rápido/barato).
Los respaldos de CLI (whisper-cli, whisper, gemini) son útiles cuando las API del 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 está especificado); los formatos que no son txt vuelven a stdout.

Política de archivos adjuntos

El attachments por capacidad controla qué archivos adjuntos se procesan:

Si se debe procesar el primer adjunto seleccionado o todos. Limitar la cantidad procesada. Preferencia de selección entre los adjuntos candidatos.

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

Comportamiento de extracción de archivos adjuntos

El texto extraído del archivo se envuelve como contenido externo que no es de confianza antes de agregarse al aviso de medios.
El bloque inyectado utiliza marcadores de límite explícitos como `<<

/<<

e incluye una línea de metadatosSource: External. - Esta ruta de extracción de adjuntos omite intencionalmente el largo banner SECURITY NOTICE:para evitar inflar el aviso de medios; los marcadores de límite y los metadatos aún permanecen. - Si un archivo no tiene texto extraíble, OpenClaw inyecta[No extractable text]. - Si un PDF recurre a imágenes de página renderizadas en esta ruta, el aviso de medios mantiene el marcador de posición [PDF content rendered to images; images not forwarded to model]` porque este paso de extracción de adjuntos reenvía bloques de texto, no las imágenes PDF renderizadas.

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 de medios, /status incluye una breve línea de resumen:

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

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

Notas

El procesamiento se realiza con el mejor esfuerzo posible. Los errores no bloquean las respuestas.
Los adjuntos aún se pasan a los modelos incluso cuando el procesamiento está deshabilitado.
Use scope para limitar dónde se ejecuta el procesamiento (por ejemplo, solo en mensajes directos).