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/URLs originales como siempre.

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

# Objetivos

• Opcional: predigerir medios entrantes en texto breve para un enrutamiento más rápido y un mejor análisis de comandos.
• Preservar la entrega de medios originales al modelo (siempre).
• Admitir API de proveedor y reservas de CLI.
• Permitir varios modelos con reserva ordenada (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 establecer para audio (transcripción completa salvo que establezcas un límite)
• maxBytes:
  • imagen: 10MB
  • audio: 20MB
  • video: 50MB

# 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 funcional:

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

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

# Compatibilidad con entorno proxy (modelos de proveedor)

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

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

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

# Capacidades (opcional)

Si estableces 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
• 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 de CLI, establece 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)

# Guía de selección de modelos

• Prefiere el modelo de generación más reciente y potente 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 más antiguos o más débiles.
• Mantén al menos una reserva por capacidad para disponibilidad (modelo de calidad + modelo más rápido/barato).
• Las reservas de CLI (whisper-cli, whisper, gemini) son útiles cuando las API de proveedor 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); 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 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 corresponde.

# 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á desactivada.
• Usa scope para limitar dónde se ejecuta la comprensión (por ejemplo, solo mensajes directos).

# Relacionado

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