Compreensão de mídia

OpenClaw pode resumir mídia recebida (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 a compreensão estiver desativada, os modelos ainda recebem os arquivos/URLs originais como de costume.

O comportamento de mídia específico de fornecedor é 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é-processar mídia recebida em texto curto para roteamento mais rápido + melhor parsing de comandos.
• Preservar a entrega da mídia original ao modelo (sempre).
• Compatibilizar APIs de provedor e fallbacks de CLI.
• Permitir vários modelos com fallback ordenado (erro/tamanho/timeout).

Comportamento de alto nível

Se a compreensão falhar ou estiver desativada, o fluxo de resposta continua com o corpo + anexos originais.

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

Credenciais de provedor (apiKey)

A compreensão de mídia por provedor usa a mesma resolução de autenticação de provedor que chamadas de modelo normais: perfis de autenticação, variáveis de ambiente e depois models.providers.<providerId>.apiKey.

Entradas tools.media.*.models[] não aceitam um campo apiKey inline. O valor de provider em uma entrada de modelo de mídia, como openai ou moonshot, deve ter credenciais disponíveis por uma das fontes padrão de autenticação de provedor.

Exemplo mínimo:

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

Para a referência completa de autenticação de provedor, incluindo perfis, variáveis de ambiente e URLs base personalizadas, consulte Ferramentas e provedores personalizados.

Padrões e limites

Padrões recomendados:

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

Detectar automaticamente compreensão de mídia (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 a compreensão de mídia de áudio e vídeo baseada em provedor está habilitada, o OpenClaw respeita variáveis de ambiente padrão de proxy de saída 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, a compreensão 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 + áudio
• 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 compatível com imagem: imagem

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

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

Orientação para seleção de modelos

• 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/fracos.
• Mantenha pelo menos um fallback por capacidade para disponibilidade (modelo de qualidade + modelo mais rápido/mais barato).
• Fallbacks da CLI (whisper-cli, whisper, gemini) são úteis quando APIs de provedores estão indisponí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 diferentes de 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 é de melhor esforço. Erros não bloqueiam respostas.
• Anexos ainda são passados para modelos mesmo quando a compreensão está desabilitada.
• Use scope para limitar onde a compreensão é executada (por exemplo, somente DMs).

Relacionado

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