Visão e colagem de imagem

O Hermes Agent tem visão multimodal — você cola imagens da área de transferência direto na CLI e pede para o agente analisar, descrever ou trabalhar com elas. As imagens vão para o modelo como blocos de conteúdo codificados em base64, então qualquer modelo com visão consegue processar.

dica

Assinantes do Portal têm modelos com visão (Claude, GPT-5, Gemini) no mesmo catálogo — sem credencial extra. Veja Nous Portal.

Como funciona

1. Copie uma imagem para a área de transferência (captura de tela, imagem do navegador etc.)
2. Anexe por um dos métodos abaixo
3. Escreva sua pergunta e aperte Enter
4. A imagem aparece como um selo [📎 Image #1] acima da entrada
5. No envio, ela vai para o modelo como bloco de conteúdo de visão

Dá para anexar várias imagens antes de enviar — cada uma ganha o próprio selo. Aperte Ctrl+C para limpar todas.

As imagens são salvas em ~/.hermes/images/, como PNG, com o horário no nome do arquivo.

Formas de colar

Depende do seu terminal. Nem todo método funciona em todo lugar — o quadro completo:

Comando /paste

A alternativa explícita mais confiável.

/paste

Digite /paste e aperte Enter. O Hermes olha a área de transferência atrás de uma imagem e anexa. É a opção mais segura quando o seu terminal reescreve o Cmd+V ou o Ctrl+V, ou quando você copiou só uma imagem e não há texto nenhum para inspecionar.

Ctrl+V e Cmd+V

O Hermes trata a colagem em camadas:

• primeiro, colagem normal de texto
• depois, área de transferência nativa ou OSC52, se o terminal não entregou o texto direito
• por fim, anexo de imagem, quando a área de transferência ou o conteúdo colado resolve para uma imagem ou para um caminho de imagem

Ou seja: caminhos temporários de captura de tela do macOS e URIs file://... de imagem são anexados na hora, em vez de ficarem no campo como texto cru.

aviso

Se a sua área de transferência tem só uma imagem (sem texto), os terminais ainda assim não conseguem mandar bytes de imagem diretamente. Use o /paste como alternativa explícita.

/terminal-setup no VS Code, Cursor e Windsurf

Se você roda a TUI dentro de um terminal integrado da família VS Code, localmente, no macOS, o Hermes consegue instalar os atalhos recomendados de workbench.action.terminal.sendSequence, para melhor paridade de várias linhas e de desfazer e refazer:

/terminal-setup

É especialmente útil quando o Cmd+Enter, o Cmd+Z ou o Shift+Cmd+Z estão sendo interceptados pelo editor. Rode só na máquina local — não dentro de uma sessão SSH.

Compatibilidade por ambiente

Ambiente	/paste	Cmd/Ctrl+V	/terminal-setup	Observações
Terminal do macOS / iTerm2	Sim	Sim	—	Melhor experiência — área de transferência nativa e recuperação de caminho de captura
Terminal.app	Sim	Sim	—	Se Cmd+←/→/⌫ for reescrito, use Ctrl+A, Ctrl+E e Ctrl+U
Linux com X11	Sim	Sim	—	Precisa do xclip (apt install xclip)
Linux com Wayland	Sim	Sim	—	Precisa do wl-paste (apt install wl-clipboard)
WSL2 (Windows Terminal)	Sim	Sim	—	Usa o powershell.exe — nada a instalar
VS Code, Cursor, Windsurf (local)	Sim	Sim	Sim	Recomendado, para melhor paridade de Cmd+Enter, desfazer e refazer
VS Code, Cursor, Windsurf (por SSH)	Não²	Não²	Não³	Rode o /terminal-setup na máquina local
Terminal por SSH (qualquer)	Não²	Não²	—	A área de transferência remota não é acessível

² Veja SSH e sessões remotas, abaixo. ³ O comando grava atalhos do editor local, e não deve ser rodado a partir da máquina remota.

Preparação por sistema

macOS

Nada a fazer. O Hermes usa o osascript, que já vem no macOS, para ler a área de transferência. Para mais velocidade, dá para instalar o pngpaste:

brew install pngpaste

Linux (X11)

Instale o xclip:

# Ubuntu e Debian
sudo apt install xclip

# Fedora
sudo dnf install xclip

# Arch
sudo pacman -S xclip

Linux (Wayland)

Ambientes modernos (Ubuntu 22.04+, Fedora 34+) costumam usar Wayland por padrão. Instale o wl-clipboard:

# Ubuntu e Debian
sudo apt install wl-clipboard

# Fedora
sudo dnf install wl-clipboard

# Arch
sudo pacman -S wl-clipboard

Como saber se você está no Wayland

echo $XDG_SESSION_TYPE
# "wayland" = Wayland, "x11" = X11, "tty" = sem servidor gráfico

WSL2

Nada a fazer. O Hermes detecta o WSL2 sozinho (pelo /proc/version) e usa o powershell.exe para acessar a área de transferência do Windows, pelo System.Windows.Forms.Clipboard do .NET. Isso faz parte da interoperabilidade do WSL2 — o powershell.exe está disponível por padrão.

Os dados vêm como PNG em base64 pela saída padrão, então não é preciso converter caminho nem criar arquivo temporário.

Sobre o WSLg

No WSLg (WSL2 com suporte gráfico), o Hermes tenta primeiro o caminho do PowerShell e depois recua para o wl-paste. A ponte de área de transferência do WSLg só suporta BMP para imagem — o Hermes converte de BMP para PNG sozinho, com o Pillow (se instalado) ou com o convert do ImageMagick.

Conferir o acesso à área de transferência no WSL2

# 1. Confere a detecção do WSL
grep -i microsoft /proc/version

# 2. Confere se o PowerShell está acessível
which powershell.exe

# 3. Copie uma imagem e então rode
powershell.exe -NoProfile -Command "Add-Type -AssemblyName System.Windows.Forms; [System.Windows.Forms.Clipboard]::ContainsImage()"
# Deve imprimir "True"

SSH e sessões remotas

Colar imagem não funciona direito por SSH. Quando você entra numa máquina remota, a CLI do Hermes roda lá. As ferramentas de área de transferência (xclip, wl-paste, powershell.exe, osascript) leem a área de transferência da máquina em que rodam — o servidor remoto, não o seu computador. A imagem que está na sua área de transferência local é, portanto, inacessível do outro lado.

Texto às vezes ainda atravessa, pela colagem do terminal ou por OSC52, mas o acesso à imagem e aos caminhos temporários de captura fica preso à máquina que roda o Hermes.

Contornos para SSH

1. Envie o arquivo — salve a imagem localmente e mande para o servidor por scp, pelo explorador de arquivos do VS Code (arrastando) ou por qualquer outro método. Depois, cite o caminho. (Um comando /attach <arquivo> está planejado.)
2. Use uma URL — se a imagem está acessível na internet, cole a URL na mensagem. O agente usa o vision_analyze para olhar qualquer URL de imagem direto.
3. Encaminhamento de X11 — conecte com ssh -X. Assim o xclip na máquina remota acessa a sua área de transferência do X11 local. Exige um servidor X rodando localmente (XQuartz no macOS, já embutido nos ambientes X11 do Linux). É lento para imagens grandes.
4. Use uma plataforma de mensagem — mande as imagens ao Hermes pelo Telegram, Discord, Slack ou WhatsApp. Essas plataformas cuidam do envio de imagem nativamente e não sofrem com as limitações do terminal.

Por que terminais não colam imagem

Essa é uma confusão comum, então vale a explicação técnica.

Terminais são interfaces de texto. Quando você aperta Ctrl+V (ou Cmd+V), o emulador de terminal:

1. Lê a área de transferência atrás de conteúdo de texto
2. Embrulha numa sequência de escape de colagem entre colchetes
3. Manda para o programa pelo fluxo de texto do terminal

Se a área de transferência tem só uma imagem, não há nada para mandar. Não existe sequência de escape padrão para dados binários de imagem. O terminal simplesmente não faz nada.

É por isso que o Hermes faz uma checagem separada — em vez de receber a imagem pelo evento de colagem, ele chama as ferramentas do sistema (osascript, powershell.exe, xclip, wl-paste) por subprocesso, e lê a área de transferência de forma independente.

Modelos suportados

A colagem funciona com qualquer modelo com visão. A imagem vai como URL de dados em base64, no formato de conteúdo de visão da OpenAI:

{
  "type": "image_url",
  "image_url": {
    "url": "data:image/png;base64,..."
  }
}

A maioria dos modelos modernos aceita esse formato, incluindo GPT-4 Vision, Claude com visão, Gemini e modelos multimodais abertos servidos pelo OpenRouter.

Roteamento de imagem: modelo com visão ou só texto

Quando alguém anexa uma imagem — pela área de transferência na CLI, pelo gateway (foto no Telegram ou no Discord), ou por qualquer outra entrada — o Hermes decide o caminho conforme o seu modelo atual suportar visão ou não:

Seu modelo	O que acontece com a imagem
Com visão (GPT-4V, Claude com visão, Gemini, Qwen-VL, MiMo-VL etc.)	Vai como pixels de verdade, no formato nativo de imagem do provedor. Sem camada de resumo em texto.
Só texto (DeepSeek V3, modelos abertos menores, endpoints antigos de conversa)	Passa pela ferramenta auxiliar vision_analyze — um modelo de visão auxiliar descreve a imagem, e a descrição em texto entra na conversa.

Você não configura nada — o Hermes consulta a capacidade do seu modelo nos metadados do provedor e escolhe o caminho sozinho. Na prática, dá para trocar entre modelos com e sem visão no meio da sessão, e o tratamento de imagem simplesmente funciona, sem mudar seu jeito de trabalhar. Modelos só de texto recebem contexto coerente sobre a imagem, em vez de um conteúdo multimodal quebrado que teriam de recusar.

Qual modelo auxiliar faz a descrição é configurável em auxiliary.vision — veja Modelos auxiliares.

O vision_analyze tem o mesmo comportamento duplo

A própria ferramenta vision_analyze segue o mesmo roteamento. Quando o modelo principal ativo tem visão e o provedor dele suporta conteúdo de imagem dentro de resultado de ferramenta (hoje, as pilhas da Anthropic, da OpenAI, do Azure OpenAI e do Gemini 3.x), o vision_analyze pula o descritor auxiliar e devolve os pixels crus, num envelope multimodal de resultado. O modelo principal vê a imagem nativamente no turno seguinte — sem chamada auxiliar, sem perda de informação por resumo, sem espera extra.

Para modelos principais só de texto (ou provedores cujo canal de resultado de ferramenta não carrega imagem), o vision_analyze volta ao caminho antigo: pede ao modelo de visão auxiliar que descreva a imagem e devolve a descrição como texto. De qualquer forma, a assinatura da chamada é a mesma — a ferramenta decide o caminho em tempo de execução, conforme o modelo ativo.