[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
```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
```
<br>
---
<br>
## 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"
<br>
{%hackmd vaaMgNRPS4KGJDSFG0ZE0w %}
Sign in via Google
Sign in via Facebook
Sign in via X(Twitter)
Sign in via GitHub
Sign in via Dropbox
Sign in with Wallet
Connect another wallet