--- # System prepended metadata title: '[AI] Agents / Hermes Agent - 安裝與設定步驟(A版)' tags: [AI / Tools / Agents / Hermes Agent /, tools, AI, Hermes Agent, Hermes, agents, 愛馬仕] --- [AI] Agents / Hermes Agent - 安裝與設定步驟(A版) === ###### tags: `AI / Tools / Agents / Hermes Agent /` ###### tags: `AI`, `tools`, `agents`, `Hermes Agent`, `Hermes`, `愛馬仕`
> [!Note] > - 整理自 **Hermes Agent 官方文件 / GitHub README 文件** > - **解說**：**自架 OpenAI-compatible model server** 放進實作流程。
**目錄** - [\[AI\] Agent / Hermes Agent - 安裝詳解](#AI-Agent--Hermes-Agent---安裝詳解) - [Hermes 快速安裝與設定流程](#Hermes-快速安裝與設定流程) - [1. 官方推薦安裝方式](#1-官方推薦安裝方式) - [2. 先檢查安裝狀態](#2-先檢查安裝狀態) - [3. 設定模型供應商：你的情境選 Custom endpoint](#3-設定模型供應商：你的情境選-Custom-endpoint) - [4. 先用 curl 驗證你的 OpenAI-compatible endpoint](#4-先用-curl-驗證你的-OpenAI-compatible-endpoint) - [4.1 查模型列表](#41-查模型列表) - [4.2 測 chat completions](#42-測-chat-completions) - [5. 官方設定檔位置與優先順序](#5-官方設定檔位置與優先順序) - [6. 手動設定 `~/.hermes/config.yaml`](#6-手動設定-hermesconfigyaml) - [單一自架 endpoint](#單一自架-endpoint) - [多個自架 endpoint](#多個自架-endpoint) - [7. 很重要：`hermes model` vs `/model`](#7-很重要：hermes-model-vs-model) - [8. 關於 context length：官方文件有一點需要注意](#8-關於-context-length：官方文件有一點需要注意) - [9. vLLM 自架模型建議設定](#9-vLLM-自架模型建議設定) - [10. 設定完成後測試](#10-設定完成後測試) - [11. 常見錯誤對照](#11-常見錯誤對照) - [12. 最推薦給你的完整流程](#12-最推薦給你的完整流程) > Date: 2026-04-29 12:34:40 GMT+8
> [!Note] > **官方文件**：https://hermes-agent.nousresearch.com/docs/
## Hermes 快速安裝與設定流程 - ### 1. 安裝 Hermes ```bash curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash ``` 重新載入 shell： ```bash source ~/.bashrc # 或 source ~/.zshrc ``` 檢查： ```bash hermes doctor ``` --- - ### 2. 先確認你的自架 OpenAI-compatible endpoint 查模型名稱： ```bash curl -s http://YOUR_HOST:8000/v1/models | jq ``` 測試 chat completions： ```bash curl -s http://YOUR_HOST:8000/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "YOUR_MODEL_NAME", "messages": [ {"role": "user", "content": "hi"} ] }' | jq ``` 如果有 API key： ```bash -H "Authorization: Bearer YOUR_API_KEY" ``` --- - ### 3. 設定 Hermes 使用自架模型 執行： ```bash hermes model ``` 選： ```text Custom endpoint (enter URL manually) ``` 依序輸入： ```text Base URL: http://YOUR_HOST:8000/v1 API Key: 沒有就留空 Model Name: YOUR_MODEL_NAME Context Length: 65536 ``` --- - ### 4. 確認設定檔 ```bash cat ~/.hermes/config.yaml ``` 大致會像這樣： ```yaml model: provider: custom default: "YOUR_MODEL_NAME" base_url: "http://YOUR_HOST:8000/v1" api_key: "" context_length: 65536 ``` --- - ### 5. 啟動 Hermes ```bash hermes ``` 或： ```bash hermes --tui ``` --- - ### 6. 常見錯誤 | 問題 | 解法 | | --- | --- | | `No inference provider configured` | 離開 Hermes chat，回 shell 執行 `hermes model` | | 在 Hermes 裡打 `hermes model` 沒用 | Hermes 裡要用 `/model`；設定 provider 要在外層 shell 跑 `hermes model` | | endpoint 連不上 | 確認 URL 有 `/v1`，例如 `http://host:8000/v1` | | model name 錯 | 用 `/v1/models` 回傳的 `id` | | tool calling 不正常 | vLLM 啟動時加 `--enable-auto-tool-choice --tool-call-parser ...` | --- - ### 快速版本 ```bash # 安裝 curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash source ~/.bashrc # 檢查 hermes doctor # 查自架模型名稱 curl -s http://YOUR_HOST:8000/v1/models | jq # 設定模型 hermes model # 選 Custom endpoint # URL: http://YOUR_HOST:8000/v1 # Model: /v1/models 回傳的 id # 啟動 hermes ```
---
## 1. 官方推薦安裝方式 官方 Quickstart / Installation / GitHub README 都指向同一個一行安裝指令： ```bash id="zf6pmb" curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash ``` 官方說明支援 **Linux / macOS / WSL2 / Android Termux**；Windows 原生不支援，Windows 使用者需要先安裝 WSL2，再在 WSL2 terminal 裡執行安裝。([Hermes Agent][20260429-A-1]) 官方也說安裝器會自動處理 Python、Node.js、ripgrep、ffmpeg、virtualenv、全域 `hermes` 指令與 LLM provider 設定；唯一明確前置需求是 `git`。([Hermes Agent][20260429-A-1]) 安裝完成後： ```bash id="ec6efq" source ~/.bashrc # 或 source ~/.zshrc hermes ``` 官方安裝頁也列出後續常用設定指令：`hermes model` 設定模型、`hermes tools` 設定工具、`hermes gateway setup` 設定訊息平台、`hermes setup` 重新跑完整設定精靈。([Hermes Agent][20260429-A-1]) --- ## 2. 先檢查安裝狀態 安裝後建議先跑： ```bash id="ebkuqb" hermes doctor ``` 官方 troubleshooting 建議遇到問題時使用 `hermes doctor`，它會檢查缺少什麼並提示修正方式。([Hermes Agent][20260429-A-1]) 常見檢查： ```bash id="ugeuft" which hermes hermes --help hermes doctor ``` 若出現： ```text id="i1ckzq" hermes: command not found ``` 通常是 shell 還沒重新載入： ```bash id="vtwqm2" source ~/.bashrc # 或 source ~/.zshrc ``` --- ## 3. 設定模型供應商：你的情境選 Custom endpoint 官方 AI Providers 頁面說，Hermes 需要至少一個 inference provider；可以用 `hermes model` 互動式切換 provider/model。對於自架模型，只要 server 實作 OpenAI-compatible `/v1/chat/completions`，Hermes 就能指向它。([Hermes Agent][20260429-A-2]) 執行： ```bash id="egbqk9" hermes model ``` 選： ```text id="rl3ya2" Custom endpoint (enter URL manually) ``` 或官方文件中的名稱： ```text id="8a4zql" Custom endpoint (self-hosted / VLLM / etc.) ``` 然後填： ```text id="r14f0i" API base URL: http://你的-model-server:8000/v1 API key: 有就填，沒有就留空 Model name: 你的模型 ID Context length: 建議填 65536 或你的 server 實際支援值 ``` 官方 Custom endpoint 一般設定流程就是：`hermes model` → 選 Custom endpoint → 輸入 API base URL、API key、Model name。([Hermes Agent][20260429-A-2]) --- ## 4. 先用 curl 驗證你的 OpenAI-compatible endpoint 在設定 Hermes 前，先確認你的 server 真的有 OpenAI-compatible API。 ### 4.1 查模型列表 ```bash id="eqfwqv" curl -s http://YOUR_HOST:8000/v1/models | jq ``` 如果有 API key： ```bash id="fim8ma" curl -s http://YOUR_HOST:8000/v1/models \ -H "Authorization: Bearer YOUR_API_KEY" | jq ``` 看回傳的 `id`，例如： ```json id="fi3cnb" { "data": [ { "id": "Qwen/Qwen2.5-Coder-32B-Instruct" } ] } ``` 這個 `id` 就是 Hermes 裡要填的 `Model name`。 ### 4.2 測 chat completions ```bash id="52f7rd" curl -s http://YOUR_HOST:8000/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "Qwen/Qwen2.5-Coder-32B-Instruct", "messages": [ {"role": "user", "content": "hi"} ] }' | jq ``` 有 API key 則加： ```bash id="tp4312" -H "Authorization: Bearer YOUR_API_KEY" ``` 只要這個能回應，Hermes 才比較可能正常接上。 --- ## 5. 官方設定檔位置與優先順序 官方 Configuration 說設定解析順序是： | 優先順序 | 來源 | 用途 | | ---: | ----------------------- | ------------------------- | | 1 | CLI arguments | 單次執行覆蓋 | | 2 | `~/.hermes/config.yaml` | 主要非機密設定 | | 3 | `~/.hermes/.env` | API keys、tokens、passwords | | 4 | 內建預設值 | fallback | 官方原則是：**secrets 放 `.env`，其他模型/provider/terminal/tool 設定放 `config.yaml`**。([Hermes Agent][20260429-A-3]) 所以你的自架模型，核心應該落在： ```bash id="x15bnx" ~/.hermes/config.yaml ``` API key 這類秘密值才放： ```bash id="7r4a6w" ~/.hermes/.env ``` --- ## 6. 手動設定 `~/.hermes/config.yaml` 互動式設定失敗時，可以直接手動改。 ### 單一自架 endpoint ```yaml id="o30uhf" model: default: "Qwen/Qwen2.5-Coder-32B-Instruct" provider: "custom" base_url: "http://YOUR_HOST:8000/v1" api_key: "" context_length: 65536 ``` 官方 Custom endpoint 手動設定範例就是在 `~/.hermes/config.yaml` 設 `model.default`、`provider: custom`、`base_url`、`api_key`。([Hermes Agent][20260429-A-2]) ### 多個自架 endpoint 如果你有本機、GPU server、公司內部 proxy，可以用 named custom providers： ```yaml id="sgylu7" custom_providers: - name: local base_url: "http://localhost:8000/v1" models: Qwen/Qwen2.5-Coder-32B-Instruct: context_length: 65536 - name: work base_url: "http://gpu-server.internal:8000/v1" key_env: CORP_API_KEY models: deepseek-ai/DeepSeek-V3: context_length: 65536 ``` 官方文件也支援 `custom_providers`，可設定多個 named custom endpoints，並用 `/model custom:local:qwen-2.5` 這種三段式語法切換。([Hermes Agent][20260429-A-2]) --- ## 7. 很重要：`hermes model` vs `/model` 你前面遇到的狀況就是這個差異。 | 指令 | 在哪裡執行 | 用途 | | -------------- | ------------------- | ----------------------------------------- | | `hermes model` | 外層 shell / terminal | 新增 provider、輸入 API key、設定 custom endpoint | | `/model` | Hermes chat 裡面 | 只切換已經設定好的 provider/model | 官方明確說：`hermes model` 要在 chat session 外執行，是完整 provider setup wizard；`/model` 只能在已啟動的 Hermes chat 裡切換已設定好的模型，不能新增 provider、不能跑 OAuth、不能要求輸入 API key。([Hermes Agent][20260429-A-2]) 所以正確流程是： ```bash id="7ez7ys" # 在 Hermes chat 裡 /quit # 回到 shell hermes model # 設定完後再進入 hermes ``` --- ## 8. 關於 context length：官方文件有一點需要注意 官方 Quickstart 目前寫：Hermes Agent 需要至少 **64,000 tokens context**，小於這個視窗的模型可能無法維持多步驟 tool-calling 工作，甚至啟動時被拒絕。([Hermes Agent][20260429-A-4]) 但 FAQ / Local model 範例中仍出現 `32768` 的範例值。([Hermes Agent][20260429-A-5]) 我的建議是： **以目前 Quickstart 的 64K 要求為準**，你的自架模型盡量設定： ```yaml id="j2q1mc" context_length: 65536 ``` vLLM server 端也對應： ```bash id="f1ikrb" --max-model-len 65536 ``` --- ## 9. vLLM 自架模型建議設定 官方 vLLM 範例： ```bash id="z9jvtq" pip install vllm vllm serve meta-llama/Llama-3.1-70B-Instruct \ --port 8000 \ --max-model-len 65536 \ --tensor-parallel-size 2 \ --enable-auto-tool-choice \ --tool-call-parser hermes ``` 官方說 vLLM 適合 production GPU inference；tool calling 需要 `--enable-auto-tool-choice`，並依模型格式指定 `--tool-call-parser`，否則工具呼叫可能只會被模型輸出成普通文字。([Hermes Agent][20260429-A-2]) 常見 parser 對照： | 模型類型 | 建議 parser | | --------------------- | ------------------------------ | | Qwen 2.5 / Hermes 2/3 | `hermes` | | Llama 3.x | `llama3_json` | | Mistral | `mistral` | | DeepSeek V3 | `deepseek_v3` 或 `deepseek_v31` | 官方列出的 supported parsers 包含 `hermes`、`llama3_json`、`mistral`、`deepseek_v3`、`deepseek_v31`、`xlam`、`pythonic`。([Hermes Agent][20260429-A-2]) --- ## 10. 設定完成後測試 ```bash id="v9i4bd" hermes ``` 或： ```bash id="h9zw95" hermes --tui ``` 官方說 `hermes` 是 classic CLI，`hermes --tui` 是較新的 TUI；兩者共用 sessions、slash commands 與 config。([Hermes Agent][20260429-A-4]) 進入後測： ```text id="akf8uv" hi ``` 或更實用： ```text id="24tg5e" Check my current directory and tell me what looks like the main project file. ``` 官方 Quickstart 說成功狀態應該包含：banner 顯示選定的 model/provider、Hermes 能正常回應、必要時能使用 tool、對話能持續多輪。([Hermes Agent][20260429-A-4]) --- ## 11. 常見錯誤對照 | 錯誤 | 原因 | 解法 | | ---------------------------------- | ------------------------------- | --------------------------------------------------------- | | `No inference provider configured` | 沒有設定 provider/model | 在外層 shell 執行 `hermes model` | | 在 Hermes 裡打 `hermes model` 無效 | 你在 chat session 內，不是在 shell | `/quit` 後再跑 `hermes model` | | `/model` 找不到 custom endpoint | `/model` 只能切換已設定項目 | 先用 `hermes model` 新增 | | `hermes: command not found` | PATH 尚未更新 | `source ~/.bashrc` 或 `source ~/.zshrc` | | endpoint 連不上 | base URL 錯、少 `/v1`、防火牆、port 不通 | 先用 `curl /v1/models` 測 | | model name 不對 | Hermes 填的 model id 跟 server 不一致 | 用 `/v1/models` 回傳的 `id` | | tool calling 失效 | vLLM/SGLang 沒開 tool parser | vLLM 加 `--enable-auto-tool-choice --tool-call-parser ...` | | context 不足 | local model context 太小 | server 端設 64K，Hermes `context_length: 65536` | --- ## 12. 最推薦給你的完整流程 ```bash id="zh4rxq" # 1. 安裝 curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash # 2. 重新載入 shell source ~/.bashrc # 3. 檢查 hermes doctor # 4. 先確認自架 endpoint curl -s http://YOUR_HOST:8000/v1/models | jq # 5. 設定 Hermes model hermes model # 選 Custom endpoint # URL: http://YOUR_HOST:8000/v1 # API key: 沒有就留空 # Model name: 用 /v1/models 回傳的 id # Context length: 65536 # 6. 確認設定 cat ~/.hermes/config.yaml # 7. 啟動 hermes ``` 以你現在的需求，**不要選 OpenAI Codex、Nous Portal、OpenRouter**。 你要選的是： ```text id="visbgg" Custom endpoint (enter URL manually) ``` 然後填你的 OpenAI-compatible URL，例如： ```text id="p3mmfc" http://10.78.26.123:8000/v1 ``` [20260429-A-1]: https://hermes-agent.nousresearch.com/docs/getting-started/installation "Installation | Hermes Agent" [20260429-A-2]: https://hermes-agent.nousresearch.com/docs/integrations/providers "AI Providers | Hermes Agent" [20260429-A-3]: https://hermes-agent.nousresearch.com/docs/user-guide/configuration "Configuration | Hermes Agent" [20260429-A-4]: https://hermes-agent.nousresearch.com/docs/getting-started/quickstart "Quickstart | Hermes Agent" [20260429-A-5]: https://hermes-agent.nousresearch.com/docs/reference/faq "FAQ & Troubleshooting | Hermes Agent"
{%hackmd vaaMgNRPS4KGJDSFG0ZE0w %}