Pular para o conteúdo principal
Além de gerar imagens, o ChatCLI deixa o modelo ver e entender imagens que você anexa — e responder com base nelas. Funciona em chat, /coder, /agent, one-shot (-p) e nos canais do gateway (Telegram, WhatsApp, Slack, Discord, webhook).

​
Como anexar

Use o @file apontando para uma imagem — ele detecta o tipo e anexa como entrada de visão (não inlina como texto): 
@file diagrama.png o que esse fluxo faz?
@file ~/Downloads/erro.jpg por que esse stacktrace acontece?
@file print.png            # só a imagem, sem texto, também funciona
Formatos suportados: PNG, JPEG, GIF, WebP. Caminho local ou imagem dentro de um diretório. Imagens com extensão errada ainda são detectadas pelo conteúdo (sniff de MIME).
Chat é tool-less por design — anexar imagem em chat funciona (é anexo, não tool). Para gerar/editar imagem, use /coder ou /agent com o tool @image.

​
Estratégia híbrida (B + A)

O ChatCLI decide automaticamente, olhando a capability vision do modelo ativo no catálogo:
  • Modelo com visão (GPT-4o/4.1/5.x, Claude 3+/4.x, Gemini, Kimi, GLM, Bedrock Claude…) → a imagem vai nativa, o modelo vê os pixels de verdade. (Caminho B.)
  • Modelo sem visão → describe-fallback: um modelo com visão descreve a imagem e o texto entra no prompt, para que um modelo text-only ainda raciocine sobre o conteúdo. (Caminho A.)
  • Nenhum modelo com visão disponível → aviso claro e a resposta segue só com texto (nunca quebra).
Nenhuma variável é necessária — @file imagem simplesmente funciona. CHATCLI_VISION_PROVIDER/CHATCLI_VISION_MODEL são apenas overrides do legendador do fallback (ex.: gpt-4o-mini como legendador barato). Modelos pegos via API (/models do provider) podem não ter entrada no catálogo. A decisão é em camadas (CHATCLI_VISION_INPUT):
  1. Override CHATCLI_VISION_INPUT=native|describe|off — controle explícito.
  2. Catálogo (vision capability) — autoritativo pros conhecidos.
  3. Heurística conservadora — se o id carrega marcador inequívoco de visão (-vl, vl-, vision, pixtral, llava, internvl, qwen-vl, omni, multimodal), trata como nativo. Esses nomes só existem em modelos multimodais → ~zero falso-positivo.
  4. Senão → describe-fallback.
A heurística casa só marcadores explícitos, nunca prefixos de família (que têm exceções text-only como claude-3-5-haiku/o3-mini), então nunca envia bloco de imagem pra um modelo que quebraria. Sabe que seu modelo off-catalog vê? CHATCLI_VISION_INPUT=native.

​
Cobertura por provider (visão nativa)

A serialização da imagem é feita por um helper compartilhado, em 6 dialetos cobrindo os providers vision-capable:
DialetoProviders
OpenAI image_urlOpenAI, xAI, Z.AI, OpenRouter, Copilot, GitHub Models, Moonshot, MiniMax, Bedrock-OpenAI
Anthropic blocksAnthropic (API-key + OAuth), Bedrock-Claude, MiniMax-Anthropic
Gemini inline_dataGoogle Gemini
Bedrock SDKBedrock Converse
Ollama images[]Ollama
Responses input_imageOpenAI Responses
O gate é genérico: catalog.HasCapability(provider, modelo, "vision"). Providers de API text-only (ex.: StackSpot) caem automaticamente no describe-fallback.

​
No gateway (canais de mensageria)

Receber imagem — mande uma foto no Telegram/WhatsApp/etc. e o gateway baixa, depois o modelo configurado vê (nativo ou describe-fallback, mesma lógica acima). Mensagens só com imagem (sem texto) ganham um pedido padrão de análise. Enviar imagem — se o agent gerou/editou uma imagem durante a resposta (via @image), ela é anexada automaticamente na resposta, em adapters que suportam foto.
VariávelFunçãoPadrão
CHATCLI_GATEWAY_IMAGE_REPLYAnexa imagem gerada/editada na resposta: auto / neverauto
CHATCLI_GATEWAY_MAX_IMAGE_BYTESLimite de download da imagem recebida (bytes)20 MB

​
Configuração

/config integrations          # mostra CHATCLI_VISION_*, CHATCLI_GATEWAY_IMAGE_REPLY etc.
VariávelFunçãoPadrão
CHATCLI_VISION_INPUTModo: auto/native/describe/offauto
CHATCLI_VISION_PROVIDERProvider do describe-fallback(auto)
CHATCLI_VISION_MODELModelo do describe-fallback(auto)
CHATCLI_VISION_COMPRESSCompressão de imagem antes do envio (on/off)on
CHATCLI_VISION_MAX_EDGECap da maior aresta em px1568
CHATCLI_VISION_JPEG_QUALITYQualidade JPEG do re-encode (1–100)82

​
Compressão de imagem (antes do envio)

Quando a visão nativa está ativa, o ChatCLI encolhe a imagem antes de mandá-la ao modelo — keyless e puro-Go (sem dependência nova, sem cgo). Faz parte da Compressão de Contexto:
  • Downscale da maior aresta para CHATCLI_VISION_MAX_EDGE (1568px). Os provedores já reduzem imagens maiores server-side para esse tamanho ao contar tokens, então isso é token-equivalente — só evita subir pixels que seriam descartados — e para imagens acima do cap reduz os tokens de visão cobrados.
  • Re-encode JPEG de fotos (qualidade CHATCLI_VISION_JPEG_QUALITY), bem menor que PNG, preservando transparência (imagens com alpha continuam PNG).
  • Seguro por construção: nunca infla o payload e deixa formatos que não consegue round-trip (GIF animado, WebP) intactos. Imagens só-URL passam sem alteração.
Desative com CHATCLI_VISION_COMPRESS=off.

​
Notas

  • Imagens custam tokens de prompt (uma imagem grande pode valer centenas/milhares de tokens). Confirme antes de anexar lotes grandes em modelos pagos.
  • A imagem permanece no histórico e é reenviada nos turnos seguintes (comportamento multimodal padrão).
  • Para forçar um legendador específico no fallback: CHATCLI_VISION_PROVIDER=openai CHATCLI_VISION_MODEL=gpt-4o-mini.

​
Relacionado