Compreensão de mídia

O OpenClaw pode resumir mídias recebidas (imagem/áudio/vídeo) antes da execução do pipeline de resposta, para que a análise e o roteamento de comandos operem com um texto curto em vez de bytes brutos. A compreensão detecta automaticamente ferramentas locais ou chaves de provedores, ou você pode configurar modelos explícitos. A mídia original é sempre entregue ao modelo normalmente; quando a compreensão falha ou está desativada, o fluxo de resposta continua sem alterações.

Os plugins dos fornecedores registram metadados de recursos (qual provedor oferece suporte a qual tipo de mídia, modelo padrão e prioridade). O núcleo do OpenClaw controla a configuração compartilhada tools.media, a ordem de fallback e a integração com o pipeline de resposta.

Como funciona

Configuração

tools.media contém uma lista compartilhada de modelos e substituições específicas para cada recurso:

{  tools: {    media: {      concurrency: 2, // máximo de execuções simultâneas de recursos (padrão)      models: [/* lista compartilhada, restrinja com capabilities */],      image: {/* substituições opcionais */},      audio: {        /* substituições opcionais */        echoTranscript: true,        echoFormat: '📝 "{transcript}"',      },      video: {/* substituições opcionais */},    },  },}

Chaves específicas de cada recurso (image/audio/video):

As opções específicas do Deepgram ficam em providerOptions.deepgram (o campo de nível superior deepgram: { detectLanguage, punctuate, smartFormat } está obsoleto, mas ainda é lido).

Entradas de modelo

Cada entrada em models[] é uma entrada de provedor (padrão) ou uma entrada de CLI:

{  type: "provider", // padrão se omitido  provider: "openai",  model: "gpt-5.6-sol",  prompt: "Describe the image in <= 500 chars.",  maxChars: 500,  maxBytes: 10485760,  timeoutSeconds: 60,  capabilities: ["image"], // opcional, para entradas multimodais compartilhadas  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 do provedor

A compreensão de mídia pelo provedor usa a mesma resolução de autenticação das chamadas normais de modelos: perfis de autenticação, variáveis de ambiente e, em seguida, models.providers.<providerId>.apiKey. As entradas tools.media.*.models[] não aceitam um campo apiKey embutido.

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

Consulte Ferramentas e provedores personalizados para obter informações sobre perfis, variáveis de ambiente e URLs-base personalizados.

Regras e comportamento

• Mídias que ultrapassam maxBytes ignoram esse modelo e tentam o próximo.
• Arquivos de áudio com menos de 1024 bytes são tratados como vazios/corrompidos e ignorados antes da transcrição; em vez disso, o agente recebe uma transcrição de espaço reservado determinística.
• Se o modelo de imagem principal ativo já oferecer suporte nativo à visão, o OpenClaw ignora o bloco de resumo [Image] e passa a imagem original diretamente ao modelo. O MiniMax é uma exceção: minimax, minimax-cn, minimax-portal e minimax-portal-cn sempre encaminham a compreensão de imagens pelo provedor de mídia MiniMax-VL-01, controlado pelo plugin, mesmo que os metadados legados de chat do MiniMax M2.x afirmem aceitar entrada de imagem (somente MiniMax-M3 e posteriores são tratados como compatíveis nativamente com visão).
• Se um modelo principal do Gateway/WebChat aceitar somente texto, os anexos de imagem são preservados como referências descarregadas media://inbound/*, para que ferramentas de imagem/PDF ou um modelo de imagem configurado ainda possam inspecioná-los, em vez de perder o anexo.
• O comando explícito openclaw infer image describe --file <path> --model <provider/model> (alias: openclaw capability image describe) executa diretamente esse provedor/modelo compatível com imagens, incluindo referências do Ollama como ollama/qwen2.5vl:7b quando um modelo correspondente compatível com imagens está configurado em models.providers.ollama.models[].
• Se <capability>.enabled não for false, mas nenhum modelo estiver configurado, o OpenClaw tentará usar o modelo de resposta ativo quando o provedor dele oferecer suporte ao recurso.

Detecção automática (padrão)

Quando tools.media.<capability>.enabled não é false e nenhum modelo está configurado, o OpenClaw tenta as opções a seguir, em ordem, e para na primeira que funcionar:

Para desativar a detecção automática de um recurso:

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

Suporte a proxy (chamadas de provedores de áudio/vídeo)

A compreensão de áudio e vídeo baseada em provedores respeita as variáveis de ambiente padrão de proxy de saída, incluindo as regras de desvio NO_PROXY/no_proxy: HTTPS_PROXY, HTTP_PROXY, ALL_PROXY, https_proxy, http_proxy, all_proxy. As variáveis em minúsculas têm precedência sobre as maiúsculas. Se nenhuma 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 usa a busca direta como fallback. A compreensão de imagens não passa por esse caminho de proxy.

Recursos

Defina capabilities em uma entrada models[] para restringi-la a tipos de mídia específicos. Para listas compartilhadas, o OpenClaw infere os padrões de cada provedor incluído:

Para entradas da CLI, defina capabilities explicitamente para evitar correspondências inesperadas; se omitido, a entrada será elegível para todas as listas de recursos em que aparecer.

Matriz de compatibilidade dos provedores

Orientações para seleção de modelos

• Prefira o modelo mais avançado da geração atual para cada recurso de mídia quando qualidade e segurança forem importantes.
• Para agentes com ferramentas que processam entradas não confiáveis, evite modelos de mídia mais antigos ou menos avançados.
• Mantenha pelo menos uma alternativa por recurso para garantir disponibilidade (um modelo de qualidade + um modelo mais rápido ou barato).
• As alternativas da CLI (whisper-cli, whisper, gemini) ajudam quando as APIs dos provedores estão indisponíveis.
• Os modos conhecidos de saída em arquivo são determinantes: um arquivo de transcrição inferido vazio ou ausente não produz transcrição, em vez de recorrer à saída de progresso da CLI.
• parakeet-mlx: use --output-format txt (ou all) com --output-dir e o modelo de saída padrão {filename}. As variáveis de ambiente upstream PARAKEET_OUTPUT_FORMAT e PARAKEET_OUTPUT_TEMPLATE também são respeitadas. O OpenClaw lê <output-dir>/<media-basename>.txt; o formato padrão srt, outros formatos e modelos de saída personalizados continuam usando stdout.

Política de anexos

A opção attachments de cada recurso controla quais anexos são processados:

Quando mode: "all", as saídas recebem rótulos como [Imagem 1/2], [Áudio 2/2] etc.

Extração de anexos de arquivo

• O texto extraído do arquivo é encapsulado como conteúdo externo não confiável antes de ser acrescentado ao prompt de mídia, usando marcadores de limite como <<&lt;EXTERNAL_UNTRUSTED_CONTENT id=&quot;...&quot;&gt;>> / <<&lt;END_EXTERNAL_UNTRUSTED_CONTENT id=&quot;...&quot;&gt;>>, além de uma linha de metadados Source: External.
• Esse caminho omite intencionalmente o longo banner SECURITY NOTICE: para manter o prompt de mídia curto; os marcadores de limite e os metadados continuam sendo aplicados.
• Um arquivo sem texto extraível recebe [Nenhum texto extraível].
• Se um PDF recorrer a imagens renderizadas das páginas, o OpenClaw encaminhará essas imagens aos modelos de resposta com capacidade de visão e manterá o espaço reservado [Conteúdo do PDF renderizado como imagens] no bloco do arquivo.

Exemplos de configuração

{  tools: {    media: {      models: [        { provider: "openai", model: "gpt-5.6-sol", 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.6-sol" },          { provider: "anthropic", model: "claude-opus-4-8" },          {            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 de resumo por recurso:

📎 Media: image ok (openai/gpt-5.6-sol) · audio ok (whisper-cli observed=metal)

Para o inventário de pré-verificação, execute openclaw capability audio providers. As linhas locais mostram separadamente a alternativa local selecionada, a seleção global de provedores, a prontidão e os campos distintos de back-end compatível, solicitado e observado. A mesma seleção local está disponível como uma constatação informativa do doctor:

openclaw doctor --lint --only core/doctor/local-audio-acceleration --severity-min info

Observações

• A compreensão é feita com o melhor esforço possível. Erros não bloqueiam as respostas.
• Os anexos ainda são enviados aos modelos mesmo quando a compreensão está desativada.
• Use scope para limitar onde a compreensão é executada (por exemplo, somente em mensagens diretas).

Relacionado

• Configuração
• Compatibilidade com imagens e mídia