​

Entendimento de mídia - Entrada (2026-01-17)

​

Objetivos

• Opcional: fazer um pré-processamento da mídia de entrada em texto curto para roteamento mais rápido + melhor análise de comandos.
• Preservar sempre a entrega da mídia original ao modelo.
• Oferecer suporte a APIs de provider e fallbacks por CLI.
• Permitir vários modelos com fallback ordenado (erro/tamanho/timeout).

​

Comportamento de alto nível

1. Coletar anexos de entrada (MediaPaths, MediaUrls, MediaTypes).
2. Para cada capacidade ativada (imagem/áudio/vídeo), selecionar anexos conforme a política (padrão: primeiro).
3. Escolher a primeira entrada de modelo elegível (tamanho + capacidade + autenticação).
4. Se um modelo falhar ou a mídia for grande demais, recorrer à próxima entrada.
5. Em caso de sucesso:
   • Body se torna um bloco [Image], [Audio] ou [Video].
   • Áudio define {{Transcript}}; a análise de comandos usa o texto da legenda quando presente, caso contrário usa a transcrição.
   • As legendas são preservadas como User text: dentro do bloco.

​

Visão geral da configuração

• tools.media.models: lista compartilhada de modelos (use capabilities para limitar).
• tools.media.image / tools.media.audio / tools.media.video:
  • padrões (prompt, maxChars, maxBytes, timeoutSeconds, language)
  • substituições de provider (baseUrl, headers, providerOptions)
  • opções de áudio Deepgram via tools.media.audio.providerOptions.deepgram
  • controles de eco da transcrição de áudio (echoTranscript, padrão false; echoFormat)
  • lista models opcional por capacidade (preferida antes dos modelos compartilhados)
  • política de attachments (mode, maxAttachments, prefer)
  • scope (bloqueio opcional por canal/chatType/chave de sessão)
• tools.media.concurrency: número máximo de execuções concorrentes de capacidade (padrão 2).

{
  tools: {
    media: {
      models: [
        /* lista compartilhada */
      ],
      image: {
        /* substituições opcionais */
      },
      audio: {
        /* substituições opcionais */
        echoTranscript: true,
        echoFormat: '📝 "{transcript}"',
      },
      video: {
        /* substituições opcionais */
      },
    },
  },
}

​

Entradas de modelo

{
  type: "provider", // padrão se omitido
  provider: "openai",
  model: "gpt-5.4-mini",
  prompt: "Descreva a imagem em <= 500 caracteres.",
  maxChars: 500,
  maxBytes: 10485760,
  timeoutSeconds: 60,
  capabilities: ["image"], // opcional, usado para entradas multimodais
  profile: "vision-profile",
  preferredProfile: "vision-fallback",
}

{
  type: "cli",
  command: "gemini",
  args: [
    "-m",
    "gemini-3-flash",
    "--allowed-tools",
    "read_file",
    "Leia a mídia em {{MediaPath}} e descreva-a em <= {{MaxChars}} caracteres.",
  ],
  maxChars: 500,
  maxBytes: 52428800,
  timeoutSeconds: 120,
  capabilities: ["video", "image"],
}

• {{MediaDir}} (diretório que contém o arquivo de mídia)
• {{OutputDir}} (diretório temporário criado para esta execução)
• {{OutputBase}} (caminho base do arquivo temporário, sem extensão)

​

Padrões e limites

• maxChars: 500 para imagem/vídeo (curto, amigável para 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

• Se a mídia exceder maxBytes, esse modelo é ignorado e o próximo modelo é tentado.
• Arquivos de áudio menores que 1024 bytes são tratados como vazios/corrompidos e ignorados antes da transcrição por provider/CLI.
• Se o modelo retornar mais que maxChars, a saída será truncada.
• prompt usa por padrão um simples “Descreva a .” mais a orientação de maxChars (somente imagem/vídeo).
• Se o modelo de imagem principal ativo já oferecer suporte nativo a visão, o OpenClaw ignora o bloco de resumo [Image] e passa a imagem original ao modelo.
• Se <capability>.enabled: true, mas nenhum modelo estiver configurado, o OpenClaw tentará o modelo de resposta ativo quando o provider dele oferecer suporte à capacidade.

​

Detecção automática de entendimento de mídia (padrão)

1. Modelo de resposta ativo quando o provider dele oferece suporte à capacidade.
2. agents.defaults.imageModel refs primários/fallbacks (somente imagem).
3. CLIs locais (somente áudio; se instaladas)
   • sherpa-onnx-offline (exige SHERPA_ONNX_MODEL_DIR com encoder/decoder/joiner/tokens)
   • whisper-cli (whisper-cpp; usa WHISPER_CPP_MODEL ou o modelo tiny incluído)
   • whisper (CLI Python; baixa modelos automaticamente)
4. Gemini CLI (gemini) usando read_many_files
5. Autenticação de provider
   • Entradas configuradas em models.providers.* com suporte à capacidade são tentadas antes da ordem de fallback incluída.
   • Providers de config apenas para imagem com um modelo compatível com imagem se registram automaticamente para entendimento de mídia, mesmo quando não são um plugin incluído do fornecedor.
   • Ordem de fallback incluída:
     • Áudio: OpenAI → Groq → Deepgram → Google → Mistral
     • Imagem: OpenAI → Anthropic → Google → MiniMax → MiniMax Portal → Z.AI
     • Vídeo: Google → Qwen → Moonshot

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

​

Suporte a ambiente de proxy (modelos de provider)

• HTTPS_PROXY
• HTTP_PROXY
• https_proxy
• http_proxy

​

Capacidades (opcional)

• openai, anthropic, minimax: image
• minimax-portal: image
• moonshot: image + video
• openrouter: image
• google (Gemini API): image + audio + video
• qwen: image + video
• mistral: audio
• zai: image
• groq: audio
• deepgram: audio
• Qualquer catálogo models.providers.<id>.models[] com um modelo compatível com imagem: image

​

Matriz de suporte de providers (integrações OpenClaw)

• O entendimento de imagem de minimax e minimax-portal vem do provider de mídia MiniMax-VL-01, de propriedade do plugin.
• O catálogo de texto incluído do MiniMax continua começando apenas com texto; entradas explícitas em models.providers.minimax materializam refs de chat M2.7 compatíveis com imagem.

​

Orientação para seleção de modelo

• Prefira o modelo mais forte e de geração mais recente disponível para cada capacidade de mídia quando qualidade e segurança forem importantes.
• Para agentes com ferramentas lidando 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 por CLI (whisper-cli, whisper, gemini) são úteis quando APIs de provider 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 recorrem a stdout.

​

Política de anexos

• mode: first (padrão) ou all
• maxAttachments: limita o número processado (padrão 1)
• prefer: first, last, path, url

• O texto extraído do arquivo é envolvido como conteúdo externo não confiável antes de ser acrescentado ao prompt de mídia.
• O bloco injetado usa marcadores explícitos de limite como <<<EXTERNAL_UNTRUSTED_CONTENT id="...">>> / <<<END_EXTERNAL_UNTRUSTED_CONTENT id="...">>> e inclui uma linha de metadados Source: External.
• Esse caminho de extração de anexos omite intencionalmente o banner longo SECURITY NOTICE: para evitar aumentar demais o prompt de mídia; os marcadores de limite e os metadados ainda permanecem.
• Se um arquivo não tiver texto extraível, o OpenClaw injeta [No extractable text].
• Se um PDF recorrer a imagens renderizadas das páginas nesse caminho, o prompt de mídia mantém o placeholder [PDF content rendered to images; images not forwarded to model] porque essa etapa de extração de anexos encaminha blocos de texto, não as imagens renderizadas do PDF.

​

Exemplos de configuração

​

1) Lista compartilhada de modelos + substituições

{
  tools: {
    media: {
      models: [
        { provider: "openai", model: "gpt-5.4-mini", 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",
            "Leia a mídia em {{MediaPath}} e descreva-a em <= {{MaxChars}} caracteres.",
          ],
          capabilities: ["image", "video"],
        },
      ],
      audio: {
        attachments: { mode: "all", maxAttachments: 2 },
      },
      video: {
        maxChars: 500,
      },
    },
  },
}

​

2) Somente áudio + vídeo (imagem desativada)

{
  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",
              "Leia a mídia em {{MediaPath}} e descreva-a em <= {{MaxChars}} caracteres.",
            ],
          },
        ],
      },
    },
  },
}

​

3) Entendimento opcional de imagem

{
  tools: {
    media: {
      image: {
        enabled: true,
        maxBytes: 10485760,
        maxChars: 500,
        models: [
          { provider: "openai", model: "gpt-5.4-mini" },
          { provider: "anthropic", model: "claude-opus-4-6" },
          {
            type: "cli",
            command: "gemini",
            args: [
              "-m",
              "gemini-3-flash",
              "--allowed-tools",
              "read_file",
              "Leia a mídia em {{MediaPath}} e descreva-a em <= {{MaxChars}} caracteres.",
            ],
          },
        ],
      },
    },
  },
}

​

4) Entrada única multimodal (capacidades explícitas)

{
  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

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

​

Observações

• O entendimento é best-effort. Erros não bloqueiam respostas.
• Os anexos ainda são passados aos modelos mesmo quando o entendimento está desativado.
• Use scope para limitar onde o entendimento é executado (por exemplo, apenas DMs).

​

Documentação relacionada

• Configuration
• Image & Media Support