Compreensão de mídia

OpenClaw pode resumir mídias recebidas (imagem/áudio/vídeo) antes que o pipeline de resposta seja executado. Ele detecta automaticamente quando ferramentas locais ou chaves de provedor estão disponíveis, e pode ser desativado ou personalizado. Se o entendimento estiver desligado, os modelos ainda recebem os arquivos/URLs originais como de costume.

O comportamento de mídia específico de fornecedores é registrado por plugins de fornecedor, enquanto o núcleo do OpenClaw é responsável pela configuração compartilhada tools.media, pela ordem de fallback e pela integração com o pipeline de resposta.

# Objetivos

• Opcional: pré-digerir mídias recebidas em texto curto para roteamento mais rápido + melhor análise de comandos.
• Preservar a entrega da mídia original ao modelo (sempre).
• Oferecer suporte a APIs de provedor e fallbacks de CLI.
• Permitir vários modelos com fallback ordenado (erro/tamanho/tempo limite).

# Comportamento de alto nível

Se o entendimento falhar ou estiver desativado, o fluxo de resposta continua com o corpo original + anexos.

# Visão geral da configuração

tools.media oferece suporte a modelos compartilhados mais substituições por capacidade:

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

# Entradas de modelo

Cada entrada models[] pode ser provedor ou 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"],
}

# Padrões e limites

Padrões recomendados:

• maxChars: 500 para imagem/vídeo (curto, adequado para comandos)
• maxChars: não definido para áudio (transcrição completa, a menos que você defina um limite)
• maxBytes:
  • imagem: 10 MB
  • áudio: 20 MB
  • vídeo: 50 MB

# Detectar entendimento de mídia automaticamente (padrão)

Se tools.media.<capability>.enabled não estiver definido como false e você não tiver configurado modelos, o OpenClaw detecta automaticamente nesta ordem e para na primeira opção funcional:

Para desativar a detecção automática, defina:

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

# Suporte a ambiente de proxy (modelos de provedor)

Quando o entendimento de mídia baseado em provedor para áudio e vídeo está habilitado, o OpenClaw respeita variáveis de ambiente de proxy de saída padrão para chamadas HTTP de provedor:

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

Se nenhuma variável de ambiente de proxy estiver definida, o entendimento de mídia usa saída direta. Se o valor do proxy estiver malformado, o OpenClaw registra um aviso e faz fallback para busca direta.

# Capacidades (opcional)

Se você definir capabilities, a entrada será executada somente para esses tipos de mídia. Para listas compartilhadas, o OpenClaw pode inferir padrões:

• openai, anthropic, minimax: imagem
• minimax-portal: imagem
• moonshot: imagem + vídeo
• openrouter: imagem
• google (API Gemini): imagem + áudio + vídeo
• qwen: imagem + vídeo
• mistral: áudio
• zai: imagem
• groq: áudio
• xai: áudio
• deepgram: áudio
• Qualquer catálogo models.providers.<id>.models[] com um modelo com capacidade de imagem: imagem

Para entradas de CLI, defina capabilities explicitamente para evitar correspondências inesperadas. Se você omitir capabilities, a entrada será elegível para a lista em que ela aparece.

# Matriz de suporte de provedores (integrações do OpenClaw)

# Orientação para seleção de modelo

• Prefira o modelo de geração mais recente e mais forte disponível para cada capacidade de mídia quando qualidade e segurança forem importantes.
• Para agentes com ferramentas habilitadas que lidam com entradas não confiáveis, evite modelos de mídia mais antigos/mais fracos.
• Mantenha pelo menos um fallback por capacidade para disponibilidade (modelo de qualidade + modelo mais rápido/mais barato).
• Fallbacks de CLI (whisper-cli, whisper, gemini) são úteis quando APIs de provedor não estão disponíveis.
• Observação sobre parakeet-mlx: com --output-dir, o OpenClaw lê <output-dir>/<media-basename>.txt quando o formato de saída é txt (ou não especificado); formatos que não sejam txt fazem fallback para stdout.

# Política de anexos

attachments por capacidade controla quais anexos são processados:

Quando mode: "all", as saídas são rotuladas como [Image 1/2], [Audio 2/2] etc.

# Exemplos de configuração

{
  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"],
          },
        ],
      },
    },
  },
}

# Saída de status

Quando a compreensão de mídia é executada, /status inclui uma linha curta de resumo:

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

Isso mostra os resultados por capacidade e o provedor/modelo escolhido quando aplicável.

# Observações

• A compreensão é baseada em melhor esforço. Erros não bloqueiam respostas.
• Os anexos ainda são passados aos modelos mesmo quando a compreensão está desativada.
• Use scope para limitar onde a compreensão é executada (por exemplo, apenas DMs).

# Relacionado

• Configuração
• Suporte a imagens e mídia