[AI] Agents / Hermes Agent - 安裝與設定步驟(A版)
===
###### tags: `AI / Tools / Agents / Hermes Agent /`
###### tags: `AI`, `tools`, `agents`, `Hermes Agent`, `Hermes`, `愛馬仕`

<br>

> [!Note]
> - 整理自 **Hermes Agent 官方文件 / GitHub README 文件**
> - **解說**：**自架 OpenAI-compatible model server** 放進實作流程。

<br>

**目錄**
- [\[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

<br>

> [!Note]
> **官方文件**：https://hermes-agent.nousresearch.com/docs/

<br>

## Hermes 快速安裝與設定流程

- ### 1. 安裝 Hermes

    curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

重新載入 shell：

    source ~/.bashrc
    # 或
    source ~/.zshrc

檢查：

    hermes doctor

---

- ### 2. 先確認你的自架 OpenAI-compatible endpoint

查模型名稱：

    curl -s http://YOUR_HOST:8000/v1/models | jq

測試 chat completions：

    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：

    -H "Authorization: Bearer YOUR_API_KEY"

---

- ### 3. 設定 Hermes 使用自架模型

執行：

    hermes model

選：

    Custom endpoint (enter URL manually)

依序輸入：

    Base URL: http://YOUR_HOST:8000/v1
    API Key: 沒有就留空
    Model Name: YOUR_MODEL_NAME
    Context Length: 65536

---

- ### 4. 確認設定檔

    cat ~/.hermes/config.yaml

大致會像這樣：

    model:
      provider: custom
      default: "YOUR_MODEL_NAME"
      base_url: "http://YOUR_HOST:8000/v1"
      api_key: ""
      context_length: 65536

---

- ### 5. 啟動 Hermes

    hermes

或：

    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 ...` |

---

- ### 快速版本

    # 安裝
    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

<br>

---

<br>

## 1. 官方推薦安裝方式

官方 Quickstart / Installation / GitHub README 都指向同一個一行安裝指令：

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])

安裝完成後：

source ~/.bashrc
# 或
source ~/.zshrc

hermes

官方安裝頁也列出後續常用設定指令：`hermes model` 設定模型、`hermes tools` 設定工具、`hermes gateway setup` 設定訊息平台、`hermes setup` 重新跑完整設定精靈。([Hermes Agent][20260429-A-1])

---

## 2. 先檢查安裝狀態

安裝後建議先跑：

hermes doctor

官方 troubleshooting 建議遇到問題時使用 `hermes doctor`，它會檢查缺少什麼並提示修正方式。([Hermes Agent][20260429-A-1])

常見檢查：

which hermes
hermes --help
hermes doctor

若出現：

hermes: command not found

通常是 shell 還沒重新載入：

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])

執行：

hermes model

選：

Custom endpoint (enter URL manually)

或官方文件中的名稱：

Custom endpoint (self-hosted / VLLM / etc.)

然後填：

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 查模型列表

curl -s http://YOUR_HOST:8000/v1/models | jq

如果有 API key：

curl -s http://YOUR_HOST:8000/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY" | jq

看回傳的 `id`，例如：

{
  "data": [
    {
      "id": "Qwen/Qwen2.5-Coder-32B-Instruct"
    }
  ]
}

這個 `id` 就是 Hermes 裡要填的 `Model name`。

### 4.2 測 chat completions

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 則加：

-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])

所以你的自架模型，核心應該落在：

~/.hermes/config.yaml

API key 這類秘密值才放：

~/.hermes/.env

---

## 6. 手動設定 `~/.hermes/config.yaml`

互動式設定失敗時，可以直接手動改。

### 單一自架 endpoint

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：

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])

所以正確流程是：

# 在 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 要求為準**，你的自架模型盡量設定：

context_length: 65536

vLLM server 端也對應：

--max-model-len 65536

---

## 9. vLLM 自架模型建議設定

官方 vLLM 範例：

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. 設定完成後測試

hermes

或：

hermes --tui

官方說 `hermes` 是 classic CLI，`hermes --tui` 是較新的 TUI；兩者共用 sessions、slash commands 與 config。([Hermes Agent][20260429-A-4])

進入後測：

hi

或更實用：

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. 最推薦給你的完整流程

# 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**。
你要選的是：

Custom endpoint (enter URL manually)

然後填你的 OpenAI-compatible URL，例如：

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"

<br>

{%hackmd vaaMgNRPS4KGJDSFG0ZE0w %}