H繁中版
文件user-guidevision
<!-- Source: https://hermesbible.com/docs/user-guide/features/vision -->

Section: Core Features · URL: https://hermesbible.com/docs/user-guide/features/vision

視覺與圖片貼上

Hermes Agent 支援多模態視覺功能——你可以直接從剪貼簿將圖片貼到 CLI 中，並要求 agent 分析、描述或處理這些圖片。圖片會以 base64 編碼的內容區塊傳送給模型，因此任何支援視覺的模型都能處理它們。

TIP

Portal 訂閱者可以直接在目錄中使用支援視覺的模型（Claude、GPT-5、Gemini），無需額外設定憑證。詳見 Nous Portal。

運作方式

  1. 將圖片複製到剪貼簿（截圖、瀏覽器圖片等）
  2. 使用以下其中一種方式附加圖片
  3. 輸入你的問題並按下 Enter
  4. 圖片會以 [📎 Image #1] 標記出現在輸入欄上方
  5. 送出後，圖片會作為視覺內容區塊傳送給模型

你可以在送出前附加多張圖片——每張都會有自己的標記。按下 Ctrl+C 可清除所有已附加的圖片。

圖片會以帶有時間戳檔名的 PNG 格式儲存至 ~/.hermes/images/。

貼上方式

你附加圖片的方式取決於你的終端環境。並非所有方法都適用於所有環境——以下是完整說明：

/paste 指令

最可靠的明確圖片附加備用方案。

/paste

輸入 /paste 並按下 Enter。Hermes 會檢查你的剪貼簿中是否有圖片並將其附加。當你的終端機改寫了 Cmd+V/Ctrl+V，或者你只複製了圖片而沒有可檢查的括號貼上文字時，這是最安全的選項。

Ctrl+V / Cmd+V

Hermes 現在將貼上視為多層流程：

  • 先處理一般文字貼上
  • 如果終端機未正常傳遞文字，則使用原生剪貼簿 / OSC52 文字備用方案
  • 當剪貼簿或貼上的內容解析為圖片或圖片路徑時，自動附加圖片

這意味著貼上 macOS 截圖的暫存路徑和 file://... 圖片 URI 可以立即附加，而不是作為原始文字留在編輯器中。

WARNING

如果你的剪貼簿中只有圖片（沒有文字），終端機仍然無法直接傳送二進位圖片資料。請使用 /paste 作為明確的圖片附加備用方案。

/terminal-setup（適用於 VS Code / Cursor / Windsurf）

如果你在 macOS 上的 VS Code 系列整合終端中運行 TUI，Hermes 可以安裝建議的 workbench.action.terminal.sendSequence 按鍵綁定，以獲得更好的多行編輯和復原/重做支援：

/terminal-setup

當 Cmd+Enter、Cmd+Z 或 Shift+Cmd+Z 被 IDE 攔截時，這特別有用。請只在本機執行——不要在 SSH 工作階段中執行。

平台相容性

環境/pasteCmd/Ctrl+V/terminal-setup備註
macOS Terminal / iTerm2✅✅n/a最佳體驗——原生剪貼簿 + 截圖路徑復原
Apple Terminal✅✅n/a若 Cmd+←/→/⌫ 被改寫，可使用 Ctrl+A / Ctrl+E / Ctrl+U 備用按鍵
Linux X11 桌面✅✅n/a需要安裝 xclip（apt install xclip）
Linux Wayland 桌面✅✅n/a需要安裝 wl-paste（apt install wl-clipboard）
WSL2（Windows Terminal）✅✅n/a使用 powershell.exe——無需額外安裝
VS Code / Cursor / Windsurf（本機）✅✅✅建議使用，以獲得更好的 Cmd+Enter / 復原 / 重做支援
VS Code / Cursor / Windsurf（SSH）❌²❌²❌³請改在本機執行 /terminal-setup
SSH 終端（任何）❌²❌²n/a無法存取遠端剪貼簿

² 請參閱下方 SSH 與遠端工作階段 ³ 此指令寫入的是本機 IDE 按鍵綁定，不應在遠端主機上執行

各平台設定

macOS

無需設定。 Hermes 使用 macOS 內建的 osascript 讀取剪貼簿。若想提升效能，可選擇安裝 pngpaste：

brew install pngpaste

Linux（X11）

安裝 xclip：

# Ubuntu/Debian
sudo apt install xclip

# Fedora
sudo dnf install xclip

# Arch
sudo pacman -S xclip

Linux（Wayland）

現代 Linux 桌面（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

TIP — 如何檢查你是否使用 Wayland

echo $XDG_SESSION_TYPE
# "wayland" = Wayland，"x11" = X11，"tty" = 無顯示伺服器

WSL2

無需額外設定。 Hermes 會自動偵測 WSL2（透過 /proc/version），並使用 powershell.exe 透過 .NET 的 System.Windows.Forms.Clipboard 存取 Windows 剪貼簿。這是 WSL2 Windows 互通功能的內建功能——powershell.exe 預設即可使用。

剪貼簿資料以 base64 編碼的 PNG 格式透過 stdout 傳輸，因此不需要路徑轉換或暫存檔。

INFO — WSLg 說明

如果你使用 WSLg（具備 GUI 支援的 WSL2），Hermes 會先嘗試 PowerShell 路徑，然後退回至 wl-paste。WSLg 的剪貼簿橋接器僅支援 BMP 格式的圖片——Hermes 會自動使用 Pillow（如已安裝）或 ImageMagick 的 convert 指令將 BMP 轉換為 PNG。

驗證 WSL2 剪貼簿存取

# 1. 檢查 WSL 偵測
grep -i microsoft /proc/version

# 2. 檢查 PowerShell 是否可存取
which powershell.exe

# 3. 複製一張圖片，然後檢查
powershell.exe -NoProfile -Command "Add-Type -AssemblyName System.Windows.Forms; [System.Windows.Forms.Clipboard]::ContainsImage()"
# 應該會輸出 "True"

SSH 與遠端工作階段

透過 SSH 時，剪貼簿圖片貼上無法完整運作。 當你透過 SSH 連線到遠端機器時，Hermes CLI 運行在遠端主機上。剪貼簿工具（xclip、wl-paste、powershell.exe、osascript）讀取的是它們運行所在機器的剪貼簿——也就是遠端伺服器，而非你的本機。因此，你本機剪貼簿中的圖片無法從遠端存取。

文字通常仍可透過終端貼上或 OSC52 傳遞，但圖片剪貼簿存取和本機截圖暫存路徑仍與運行 Hermes 的機器綁定。

SSH 的替代方案

  1. 上傳圖片檔案 — 在本機儲存圖片，透過 scp、VS Code 的檔案總管（拖放）或任何檔案傳輸方式上傳至遠端伺服器。然後透過路徑引用它。（未來版本計劃推出 /attach <filepath> 指令。）

  2. 使用 URL — 如果圖片可線上存取，只需在訊息中貼上 URL。agent 可以使用 vision_analyze 直接查看任何圖片 URL。

  3. X11 轉發 — 使用 ssh -X 連線以轉發 X11。這讓遠端機器上的 xclip 能存取你本機的 X11 剪貼簿。需要在本機運行 X 伺服器（macOS 上的 XQuartz，Linux X11 桌面則內建）。大型圖片時速度較慢。

  4. 使用通訊平台 — 透過 Telegram、Discord、Slack 或 WhatsApp 傳送圖片給 Hermes。這些平台原生支援圖片上傳，不受剪貼簿/終端限制影響。

為什麼終端機無法貼上圖片

這是一個常見的困惑，以下是技術解釋：

終端機是文字介面。當你按下 Ctrl+V（或 Cmd+V）時，終端模擬器：

  1. 從剪貼簿讀取文字內容
  2. 將其包裹在括號貼上逸出序列中
  3. 透過終端的文字串流傳送給應用程式

如果剪貼簿中只有圖片（沒有文字），終端機就沒有東西可以傳送。沒有標準的終端機逸出序列可用於二進位圖片資料。終端機只會什麼都不做。

這就是為什麼 Hermes 使用獨立的剪貼簿檢查機制——它不是透過終端貼上事件接收圖片資料，而是透過子行程直接呼叫作業系統層級的工具（osascript、powershell.exe、xclip、wl-paste）來獨立讀取剪貼簿。

支援的模型

圖片貼上適用於任何支援視覺的模型。圖片以 base64 編碼的 data URL 格式傳送，使用 OpenAI 視覺內容格式：

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

大多數現代模型都支援此格式，包括 GPT-4 Vision、Claude（具備視覺能力）、Gemini，以及透過 OpenRouter 提供的開源多模態模型。

圖片路由（支援視覺 vs 純文字模型）

當使用者附加圖片時——從 CLI 剪貼簿、閘道器（Telegram/Discord 照片），或任何其他入口——Hermes 會根據你目前的模型是否實際支援視覺來進行路由：

你的模型圖片的處理方式
支援視覺（GPT-4V、Claude 視覺版、Gemini、Qwen-VL、MiMo-VL 等）使用上述提供者的原生圖片內容格式，作為真實像素傳送。無文字摘要層。
純文字（DeepSeek V3、較小型的開源模型、舊版僅文字端點）透過 vision_analyze 輔助工具路由——輔助視覺模型描述圖片，然後將文字描述注入對話中。

你無需手動設定——Hermes 會在提供者中繼資料中查詢你目前模型的能力，並自動選擇正確的路徑。實際效果是：你可以在工作階段中隨時切換視覺和非視覺模型，圖片處理會自動運作，無需更改你的工作流程。純文字模型會收到關於圖片的連貫上下文，而非無法處理的多模態資料。

哪個輔助模型負責文字描述路徑，可在 auxiliary.vision 下設定——詳見輔助模型。

vision_analyze 具有相同的雙重行為

vision_analyze 工具本身也遵循相同的路由邏輯。當主要模型支援視覺且其提供者支援在工具結果中攜帶圖片內容時（目前包括 Anthropic、OpenAI、Azure-OpenAI 和 Gemini 3.x 系列），vision_analyze 會跳過輔助描述器，直接將原始圖片像素作為多模態工具結果封裝傳回。主要模型在下一次回應中可以原生存取圖片——無需輔助呼叫、無文字摘要導致的資訊損失、無額外延遲。

對於純文字的主要模型（或工具結果通道不攜帶圖片的提供者），vision_analyze 會退回至舊版路徑：要求已設定的輔助視覺模型描述圖片，並以純文字形式傳回描述。無論哪種方式，呼叫端的工具介面都是相同的——工具會在執行時根據主要模型決定採用哪條路徑。

圖片生成

ttsvoice mode