비전 및 이미지 붙여넣기
Hermes 에이전트는 멀티모달 비전을 지원합니다 — 클립보드에서 이미지를 직접 CLI에 붙여넣고 에이전트에게 분석, 설명 또는 처리를 요청할 수 있습니다. 이미지는 base64로 인코딩된 콘텐츠 블록으로 모델에 전송되므로, 비전 기능이 있는 어떤 모델이라도 이를 처리할 수 있습니다.
작동 방식
- 이미지를 클립보드에 복사합니다 (스크린샷, 브라우저 이미지 등)
- 아래 방법 중 하나를 사용하여 첨부합니다
- 질문을 입력하고 Enter 키를 누릅니다
- 이미지는 입력 위에
[📎 Image #1]배지로 표시됩니다 - 제출 시, 이미지가 시각 콘텐츠 블록으로 모델에 전송됩니다
전송하기 전에 여러 이미지를 첨부할 수 있습니다 — 각 이미지마다 별도의 배지가 생깁니다. 첨부된 모든 이미지를 지우려면 Ctrl+C을 누르세요.
이미지는 타임스탬프가 포함된 파일 이름으로 PNG 파일 형식으로 ~/.hermes/images/에 저장됩니다.
붙여넣기 방법
이미지를 첨부하는 방법은 사용 중인 터미널 환경에 따라 다릅니다. 모든 방법이 모든 곳에서 작동하는 것은 아니며 — 전체 설명은 다음과 같습니다:
/paste 명령
가장 신뢰할 수 있는 명시적 이미지 첨부 대체 수단.
/paste
``/paste`를 입력하고 Enter를 누르세요. Hermes는 클립보드에서 이미지를 확인하고 첨부합니다. 터미널이 `Cmd+V`/`Ctrl+V`를 다시 작성할 때나 이미지만 복사했고 검사할 대괄호-붙여넣기 텍스트 페이로드가 없을 때 가장 안전한 옵션입니다.
### Ctrl+V / Cmd+V \{#ctrlv--cmdv}
Hermes는 이제 페이스트를 층류로 처리합니다:
- 일반 텍스트 먼저 붙이기
- 터미널이 텍스트를 깨끗하게 전달하지 못할 경우 네이티브 클립보드 / OSC52 텍스트 대체
- 클립보드나 붙여넣은 페이로드가 이미지 또는 이미지 경로로 해결될 때 이미지 첨부
이것은 붙여넣은 macOS 스크린샷 임시 경로와 `file://...` 이미지 URI가 작성기 내에 원시 텍스트로 남아 있는 대신 즉시 첨부될 수 있음을 의미합니다.
:::warning
클립보드에 **이미지 하나만** 있는 경우(텍스트 없음), 터미널은 여전히 바이너리 이미지 바이트를 직접 전송할 수 없습니다. 명시적인 이미지 첨부 대체 방법으로 `/paste`을 사용하세요.
:::
### `/terminal-setup` for VS Code / 커서 / 윈드서핑 \{#terminal-setup-for-vs-code--cursor--windsurf}
만약 macOS에서 로컬 VS Code 계열 통합 터미널 안에서 TUI를 실행하면, Hermes는 더 나은 멀티라인 및 실행 취소/다시 실행 동등성을 위해 권장되는 `workbench.action.terminal.sendSequence` 바인딩을 설치할 수 있습니다:
```text
/terminal-setup
이는 특히 Cmd+Enter, Cmd+Z, 또는 Shift+Cmd+Z가 IDE에 의해 가로채질 때 유용합니다. 로컬 머신에서만 실행하세요 — SSH 세션 안에서는 실행하지 마세요.
플랫폼 호환성
| 환경 | /paste | Cmd/Ctrl+V | /terminal-setup | 노트 |
|---|---|---|---|---|
| macOS 터미널 / iTerm2 | ✅ | ✅ | 해당 없음 | 최고의 경험 — 네이티브 클립보드 + 스크린샷 경로 복구 |
| 애플 터미널 | ✅ | ✅ | 해당 없음 | Cmd+←/→/⌫가 재작성되면 Ctrl+A / Ctrl+E / Ctrl+U 대체 키를 사용하세요 |
| 리눅스 X11 데스크톱 | ✅ | ✅ | 해당 없음 | 필요한 xclip (apt install xclip) |
| 리눅스 웨이랜드 데스크톱 | ✅ | ✅ | 해당 없음 | 필요한 wl-paste (apt install wl-clipboard) |
| WSL2 (윈도우 터미널) | ✅ | ✅ | 해당 없음 | powershell.exe 사용 — 추가 설치 불필요 |
| VS 코드 / 커서 / 윈드서핑 (로컬) | ✅ | ✅ | ✅ | Cmd+Enter / 실행 취소 / 다시 실행 동기화를 위해 권장 |
| VS 코드 / 커서 / 윈드서핑 (SSH) | ❌² | ❌² | ❌³ | 대신 로컬 컴퓨터에서 /terminal-setup을 실행하세요 |
| SSH 터미널(모든 종류) | ❌² | ❌² | 해당 없음 | 원격 클립보드에 접근할 수 없습니다 |
² 아래 SSH 및 원격 세션을 참조하세요 ³ 이 명령은 로컬 IDE 키 바인딩을 작성하며 원격 호스트에서 실행해서는 안 됩니다
플랫폼별 설정
macOS
설정 필요 없음. Hermes는 클립보드를 읽기 위해 osascript (macOS에 내장)을 사용합니다. 더 빠른 성능을 위해 선택적으로 pngpaste을 설치할 수 있습니다:
brew install pngpaste
리눅스 (X11)
xclip 설치:
# Ubuntu/Debian
sudo apt install xclip
# Fedora
sudo dnf install xclip
# Arch
sudo pacman -S xclip
리눅스(웨이랜드)
현대적인 리눅스 데스크톱(Ubuntu 22.04+, Fedora 34+)은 종종 기본적으로 Wayland를 사용합니다. wl-clipboard을 설치하세요:
# Ubuntu/Debian
sudo apt install wl-clipboard
# Fedora
sudo dnf install wl-clipboard
# Arch
sudo pacman -S wl-clipboard
echo $XDG_SESSION_TYPE
# "wayland" = Wayland, "x11" = X11, "tty" = no display server
WSL2
추가 설정 불필요. Hermes는 WSL2를 자동으로 감지(/proc/version)하고.NET의 System.Windows.Forms.Clipboard를 통해 Windows 클립보드에 접근하기 위해 powershell.exe을 사용합니다. 이는 WSL2의 Windows 상호 운용성에 내장되어 있으며 — powershell.exe은 기본적으로 사용할 수 있습니다.
클립보드 데이터는 stdout을 통해 base64로 인코딩된 PNG로 전송되므로, 파일 경로 변환이나 임시 파일이 필요하지 않습니다.
만약 당신이 WSLg(그래픽 지원이 있는 WSL2)를 사용 중이라면, Hermes는 먼저 PowerShell 경로를 시도하고, 실패하면 wl-paste로 대체합니다. WSLg의 클립보드 브리지에서는 이미지에 대해 BMP 형식만 지원하며 — Hermes는 BMP를 Pillow(설치된 경우) 또는 ImageMagick의 convert 명령을 사용하여 자동으로 PNG로 변환합니다.
WSL2 클립보드 접근 확인
# 1. Check WSL detection
grep -i microsoft /proc/version
# 2. Check PowerShell is accessible
which powershell.exe
# 3. Copy an image, then check
powershell.exe -NoProfile -Command "Add-Type -AssemblyName System.Windows.Forms; [System.Windows.Forms.Clipboard]::ContainsImage()"
# Should print "True"
SSH 및 원격 세션
클립보드 이미지 붙여넣기는 SSH를 통해 완전히 작동하지 않습니다. 원격 머신에 SSH로 접속하면, Hermes CLI는 원격 호스트에서 실행됩니다. 클립보드 도구(xclip, wl-paste, powershell.exe, osascript)는 자신이 실행되는 머신의 클립보드를 읽습니다 — 즉 원격 서버의 클립보드를 읽으며, 사용자의 로컬 머신 클립보드는 읽지 않습니다. 따라서 로컬 클립보드 이미지는 원격 측에서 접근할 수 없습니다.
텍스트는 때때로 터미널 붙여넣기나 OSC52를 통해 여전히 전달될 수 있지만, 이미지 클립보드 액세스와 로컬 스크린샷 임시 경로는 여전히 Hermes를 실행하는 기기에 연결되어 있습니다.
SSH에 대한 우회 방법
-
이미지 파일 업로드 — 이미지를 로컬에 저장한 후,
scp, VSCode의 파일 탐색기(드래그 앤 드롭) 또는 어떤 파일 전송 방법을 통해 원격 서버에 업로드하세요. 그런 다음 경로로 참조합니다. (향후 릴리스에서 사용할/attach <filepath>명령이 계획되어 있습니다.) -
URL 사용 — 이미지가 온라인에서 접근 가능하다면, 메시지에 URL을 붙여넣기만 하면 됩니다. 에이전트는
vision_analyze를 사용하여 모든 이미지 URL을 직접 확인할 수 있습니다. -
X11 포워딩 — X11을 포워딩하려면
ssh -X에 연결하세요. 이렇게 하면 원격 머신의xclip가 로컬 X11 클립보드에 접근할 수 있습니다. 로컬에서 X 서버가 실행 중이어야 합니다(맥OS에서는 XQuartz, Linux X11 데스크톱에서는 기본 제공). 큰 이미지는 느릴 수 있습니다. -
메시징 플랫폼 사용 — 이미지를 Telegram, Discord, Slack 또는 WhatsApp을 통해 Hermes로 전송하세요. 이러한 플랫폼은 이미지 업로드를 기본적으로 지원하며 클립보드/터미널 제한의 영향을 받지 않습니다.
터미널이 이미지를 붙여넣을 수 없는 이유
이것은 흔한 혼란의 원인이므로, 여기 기술적인 설명이 있습니다:
터미널은 텍스트 기반 인터페이스입니다. Ctrl+V(또는 Cmd+V)를 누르면 터미널 에뮬레이터는:
- 클립보드에서 텍스트 내용을 읽습니다
- 괄호로 묶인 붙여넣기 이스케이프 시퀀스로 감싼다
- 터미널의 텍스트 스트림을 통해 애플리케이션으로 전송한다
클립보드에 이미지(텍스트 없음)만 있는 경우, 터미널은 보낼 것이 없습니다. 이진 이미지 데이터를 위한 표준 터미널 이스케이프 시퀀스는 없습니다. 터미널은 단순히 아무것도 하지 않습니다.
이것이 Hermes가 별도의 클립보드 체크를 사용하는 이유입니다 — 터미널 붙여넣기 이벤트를 통해 이미지 데이터를 받는 대신, 클립보드를 독립적으로 읽기 위해 OS 수준 도구(osascript, powershell.exe, xclip, wl-paste)를 서브프로세스를 통해 직접 호출합니다.
지원되는 모델
이미지 붙여넣기는 비전을 지원하는 모든 모델에서 작동합니다. 이미지는 OpenAI 비전 콘텐츠 형식의 base64로 인코딩된 데이터 URL로 전송됩니다:
{
"type": "image_url",
"image_url": {
"url": "data:image/png;base64,..."
}
}
대부분의 최신 모델은 GPT-4 Vision, Claude(비전 포함), Gemini, 그리고 OpenRouter를 통해 제공되는 오픈 소스 멀티모달 모델을 포함하여 이 형식을 지원합니다.
이미지 라우팅 (비전 가능 모델 vs 텍스트 전용 모델)
사용자가 이미지를 첨부하면 — CLI 클립보드, 게이트웨이(Telegram/Discord 사진), 또는 다른 진입점을 통해 — Hermes는 현재 모델이 실제로 비전을 지원하는지 여부에 따라 이를 라우팅합니다:
| 당신의 모델 | 이미지에 무슨 일이 생기나요 |
|---|---|
| 비전 가능 (GPT-, 비전을 지원하는 Claude, Gemini, Qwen-VL, MiMo-VL 등) | 위 제공자의 네이티브 이미지 콘텐츠 형식을 사용하여 실제 픽셀로 전송되었습니다. 텍스트 요약 레이어는 없습니다. |
| 텍스트 전용 (DeepSeek V3, 더 작은 오픈소스 모델, 이전 채팅 전용 엔드포인트) | vision_analyze 보조 도구를 통해 경로가 설정됨 — 보조 비전 모델이 이미지를 설명하고, 텍스트 설명이 대화에 주입됩니다. |
이를 구성할 필요가 없습니다 — Hermes는 공급자 메타데이터에서 현재 모델의 기능을 조회하고 자동으로 올바른 경로를 선택합니다. 실제 효과는 다음과 같습니다: 세션 중간에 비전 모델과 비비전 모델을 전환할 수 있으며 이미지 처리가 워크플로를 변경하지 않고 '그냥 작동'합니다. 텍스트 전용 모델은 거부해야 하는 불완전한 멀티모달 페이로드 대신 이미지에 대한 일관된 컨텍스트를 얻습니다.
어떤 보조 모델이 텍스트-설명 경로를 처리하는지는 auxiliary.vision 아래에서 구성할 수 있습니다 — 보조 모델을 참조하세요.