/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):
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 capabilityvision 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).
@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 com visão fora do catálogo
Modelos pegos via API (/models do provider) podem não ter entrada no catálogo. A decisão é em camadas (CHATCLI_VISION_INPUT):
- Override
CHATCLI_VISION_INPUT=native|describe|off— controle explícito. - Catálogo (
visioncapability) — autoritativo pros conhecidos. - 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. - Senão → describe-fallback.
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:
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.
Configuração
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.
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
- Geração e Edição de Imagem (@image) — o modelo cria/edita imagens
- Chat Gateway
- Respostas em Voz