Hermes Agent 入門：安裝、第一次對話與自訂 OpenAI 相容端點

從 Hermes Agent 0.21.3 開始，完成安裝、最小對話與自訂 OpenAI 相容端點設定，並用實際模型 ID 連接 BazaarLink。

Hermes Agent 入門：安裝、第一次對話與自訂 OpenAI 相容端點

Hermes Agent 是 NousResearch 開源的 AI agent。它不只回答單次問題，也能把對話、工具、記憶、skills 與子任務串成較長的工作流程。對第一次接觸 agent 的人來說，可以先把它理解成「有工作目錄與工具的聊天介面」：先讓它完成一個可驗證的小任務，再逐步加入長期記憶、排程或訊息平台。

本文依官方文件與官方版本頁查核至 2026-09-21，版本以 Hermes Agent 0.21.3 為準。為了讓範例可以換端點，下面不依賴特定模型服務的登入流程，而是使用公開模型清單中已查到的 gemini-3.8-flash。

1. Hermes Agent 是什麼，解決什麼問題？

一般聊天工具把重點放在一問一答；agent 則會在一次工作中反覆讀取檔案、使用終端機工具、整理上下文，再決定下一步。Hermes Agent 的定位就是這種可長時間工作的 agent：它有 CLI、TUI、Gateway、持久化 session、記憶與 skills，也能把較大的任務分派給子 agent。

這種設計適合三類工作：

• 需要讀寫專案檔案、執行命令並回報結果的開發工作。
• 需要跨多輪保留上下文的研究或整理工作。
• 想先在本機使用，再視需要接到訊息平台或常駐 Gateway 的工作流。

但它仍需要一個可用的模型端點。安裝成功不等於模型已經連通；最小驗證應該是讓它完成一個短而容易核對的任務。

2. 安裝與最小可跑範例

官方安裝器會處理 Hermes 所需的 Python、Node.js、ripgrep 與 ffmpeg 等相依項目。Linux、macOS、WSL2 或 Android/Termux 可使用 shell 安裝器；Windows 原生環境使用 PowerShell 安裝器：

# Linux / macOS / WSL2 / Android (Termux)
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

# Windows PowerShell
iex (irm https://hermes-agent.nousresearch.com/install.ps1)

安裝完成後重新載入 shell，先啟動 TUI：

source ~/.bashrc   # zsh 使用 source ~/.zshrc
hermes --tui

若你只想先跑經典 CLI，直接執行 hermes 即可。第一個提示可以用「檢查目前目錄，列出三個最重要的檔案，並說明判斷理由」；這比開一個很大的任務更容易確認模型、終端機工具與回覆流程都正常。官方 quickstart 也建議先讓普通聊天成功，再加入 Gateway、cron、skills 或 delegation。

Hermes Agent 目前要求模型至少有 64K context。若自訂端點的 context 不足，長對話或工具迴圈可能在啟動或壓縮上下文時失敗。

3. 主要設定：指向自訂 OpenAI 相容端點

Hermes 把非機密設定放在 ~/.hermes/config.yaml，把金鑰放在 ~/.hermes/.env。自訂端點的主模型可以用 provider: custom、default、base_url 與 api_mode 四個欄位：

# ~/.hermes/.env
OPENAI_API_KEY=<BAZAARLINK_API_KEY>

# ~/.hermes/config.yaml
model:
  provider: custom
  default: gemini-3.8-flash
  base_url: https://api.bazaarlink.ai/v1
  api_mode: chat_completions

這裡的 gemini-3.8-flash 是 2026-09-21 從 BazaarLink 公開模型清單查到的實際 ID；不要把顯示名稱自行改寫成另一個名稱。api_mode: chat_completions 是給 OpenAI 相容 Chat Completions 介面的明確設定。若你不想手動編輯 YAML，也可以先執行 hermes model，選擇 custom endpoint，再把模型 ID 填成同一個值。

修改後可用下列命令查看 Hermes 實際讀到的設定，然後開一個新 session：

hermes config get model --json
hermes status
hermes --tui

其他欄位仍可先維持預設值。等主模型能完成一輪對話，再考慮為 compression、vision 或 delegation 設定 auxiliary model；這些欄位各自也接受 provider、model 與 base_url，不需要一開始全部改動。

2026-09-21 實測（最小重放）： Hermes 的 custom chat_completions 形狀以 Authorization: Bearer 呼叫 POST https://api.bazaarlink.ai/v1/chat/completions。純文字對話回 200、finish_reason=stop，有正常文字；帶 tools 與 tool_choice: auto 的請求也回 200，finish_reason=tool_calls，並回傳 get_weather 與 {"city":"Taipei"}。這次已確認 tool call 的標準結束原因。

stream: true 回 200，SSE 共 5 個 chunk，最後以 [DONE] 收尾。加入標準 top-level reasoning_effort: "low" 回 200，但這次回應只有 role 與 content，沒有結構化 reasoning 欄位；因此只能說請求欄位被接受，不能宣稱 reasoning 輸出已完整互通。image_url data URI 圖片輸入也回 200，模型確實讀到圖片並回答顏色；這個圖片輸入形狀已於 2026-09-21 查核。

GET https://api.bazaarlink.ai/v1/models 回 200，清單含 gemini-3.8-flash。固定 default 的生成請求不需要依賴清單才能帶出這個已知 model ID；但 Hermes 的 model picker、能力探索或不帶模型名的 /model custom 仍可能查詢端點的 /models，官方設定也提供 discover_models 控制這件事。另以 Anthropic Messages 形狀用 x-api-key 呼叫 /v1/messages 回 200，回應 type=message；這是明確切換 api_mode 後的另一條路徑，Anthropic 格式的工具與串流互通仍未驗證。

4. 常見問題

hermes 找不到

先重新載入 shell；官方的 per-user 安裝通常把 launcher 放在 ~/.local/bin/hermes。若仍找不到，檢查該目錄是否在 PATH，不要直接用原始碼目錄裡的 Python 檔取代 launcher。

401、模型不存在或回應很快失敗

先確認 OPENAI_API_KEY 是佔位符替換後的真實金鑰，再確認 default 與公開模型清單的 id 完全一致。也要確認目前的 config.yaml 沒有被另一個 profile 或環境變數覆蓋。

為什麼剛改設定，正在開的聊天沒有變？

Hermes 對已經啟動的 session 會保留原本的模型；設定檔通常在下一個 session 生效。要切換目前對話，可以在聊天中使用 /model，或關閉後重新開啟 TUI。

工具工作流仍然不穩定

先把任務縮小，確認模型能正常回覆工具呼叫，再檢查 context 是否至少 64K。若自訂端點對工具欄位、串流或 reasoning 有自己的限制，應以該端點的實際回應為準；這部分不要只從模型名稱推測。

回應幾乎是空的，而且 finish_reason 是 length，怎麼辦？

這個模型預設會思考；如果 max_tokens 太小，推理 token 可能先把額度用完，留下很少或沒有可見文字。把 max_tokens 調高即可；實測從 16 調到 400 後才正常輸出。

5. 接到 BazaarLink

如果你要把這個設定換成 BazaarLink，使用 base_url: https://api.bazaarlink.ai/v1，並把金鑰填入 <BAZAARLINK_API_KEY>；模型 ID 先從公開模型清單確認。純文字、tool call（finish_reason=tool_calls）、5 chunk SSE 串流與圖片輸入（模型能讀到圖片並回答顏色）的最小 request shape 已在 2026-09-21 驗證；Anthropic 格式的工具與串流，以及 Hermes 完整 session／channel／skill 流程仍未驗證。需要更多端點設定時，可參考SDK 文件。

台幣計費・統一發票・主流 AI 模型・OpenAI 相容 API