[AI] Agent / Hermes Agent - 安裝與設定步驟(B版)
===
###### tags: `AI / Tools / Agent /`
###### tags: `AI`, `tools`, `agent`, `Hermes Agent`, `Hermes`, `愛馬仕`
<br>
**目錄**
- [\[AI\] Agent / Hermes Agent - 安裝詳解(B版)](#AI-Agent--Hermes-Agent---安裝詳解B版)
- [Hermes Agent 安裝與設定步驟](#Hermes-Agent-安裝與設定步驟)
- [一、安裝](#一、安裝)
- [一鍵安裝](#一鍵安裝)
- [二、基本命令](#二、基本命令)
- [三、設定精靈](#三、設定精靈)
- [四、模型與提供者設定](#四、模型與提供者設定)
- [`hermes model` vs `/model`](#hermes-model-vs-model)
- [五、常見 Provider 設定方式](#五、常見-Provider-設定方式)
- [六、自架 OpenAI-compatible Model 設定流程](#六、自架-OpenAI-compatible-Model-設定流程)
- [1. 先確認 endpoint 可用](#1-先確認-endpoint-可用)
- [2. 測試 chat completions](#2-測試-chat-completions)
- [3. 設定 Hermes](#3-設定-Hermes)
- [七、組態檔管理](#七、組態檔管理)
- [八、常見組態區段](#八、常見組態區段)
- [九、工具管理](#九、工具管理)
- [十、Skills 管理](#十、Skills-管理)
- [十一、通訊平台 Gateway](#十一、通訊平台-Gateway)
- [十二、Profiles：多配置](#十二、Profiles：多配置)
- [十三、常見問題](#十三、常見問題)
- [十四、更新與解除安裝](#十四、更新與解除安裝)
- [十五、最短可操作流程：自架 OpenAI-compatible Model](#十五、最短可操作流程：自架-OpenAI-compatible-Model)
> Date: 2026-04-29 12:59:19 GMT+8
<br>
> [!Note]
> **官方文件**：https://hermes-agent.nousresearch.com/docs/
<br>
## 一、安裝
### 一鍵安裝
```bash
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
```
安裝完成後重新載入 shell：
```bash
source ~/.bashrc
# 或
source ~/.zshrc
```
啟動 Hermes：
```bash
hermes
```
Windows 原生不支援，Windows 使用者建議在 WSL2 內安裝與執行。官方 README 也列出安裝後可用 `source ~/.bashrc` 或 `source ~/.zshrc` 後執行 `hermes`。([GitHub][20260429-A-2])
---
## 二、基本命令
```bash
hermes # 啟動互動式對話
hermes chat -q "問題" # 單次查詢 / one-shot prompt
hermes model # 選擇或設定模型 / provider
hermes setup # 完整互動式設定精靈
hermes tools # 設定工具啟用狀態
hermes tools --summary # 顯示目前工具啟用摘要
hermes doctor # 檢查健康狀態與相依性
hermes status # 查看目前狀態
hermes dump # 輸出可分享的診斷摘要
```
`hermes chat -q` 是官方 CLI reference 中的 one-shot 查詢用法；`hermes tools` 目前官方穩定文件寫法是 `hermes tools [--summary]`，不建議把 `hermes tools list/enable/disable` 當成主要流程。([Hermes Agent][20260429-A-3]) ([Hermes Agent][20260429-A-3])
---
## 三、設定精靈
```bash
hermes setup
```
也可以只設定其中一個區段：
```bash
hermes setup model
hermes setup tts
hermes setup terminal
hermes setup gateway
hermes setup tools
hermes setup agent
```
官方格式是：
```bash
hermes setup [model|tts|terminal|gateway|tools|agent]
```
主要區段：
| 區段 | 說明 |
| ---------- | ------------------------------ |
| `model` | 模型與 provider 設定 |
| `tts` | 語音 / 文字轉語音設定 |
| `terminal` | Terminal backend 與 sandbox 設定 |
| `gateway` | Telegram、Discord、Slack 等通訊平台設定 |
| `tools` | 各平台可用工具啟用 / 停用 |
| `agent` | Agent 行為設定 |
官方 CLI reference 明確列出 `model|tts|terminal|gateway|tools|agent`，所以原本少了 `tts`。([Hermes Agent][20260429-A-3])
---
## 四、模型與提供者設定
```bash
hermes model
```
`hermes model` 要在 **外層 terminal** 執行，不是在 Hermes 對話中執行。
用途：
| 用途 | 說明 |
| ------------- | ------------------------------------------------ |
| 新增 provider | 例如 OpenRouter、Anthropic、DeepSeek、Custom endpoint |
| 設定 API key | 互動式輸入或更新 key |
| 執行 OAuth | 例如 Codex、Copilot、Nous Portal 等 |
| 設定自架 endpoint | vLLM、SGLang、Ollama 或任何 OpenAI-compatible API |
| 儲存預設模型 | 寫入 Hermes 設定檔 |
### `hermes model` vs `/model`
| 指令 | 執行位置 | 用途 |
| -------------- | ------------------- | ----------------------------------------------- |
| `hermes model` | 外層 shell / terminal | 新增 provider、輸入 API key、OAuth、設定 custom endpoint |
| `/model` | Hermes chat 裡面 | 只切換已經設定好的模型 |
如果要新增 provider 或設定自架 endpoint，要先離開 Hermes：
```text
/quit
```
然後在 shell 執行：
```bash
hermes model
```
官方明確說 `hermes model` 是完整 provider setup wizard；`/model` 只能切換已設定的模型，不能新增 provider、不能跑 OAuth、不能要求輸入 API key。([Hermes Agent][20260429-A-3])
---
## 五、常見 Provider 設定方式
| Provider / 情境 | 設定方式 | 備註 |
| --------------- | -------------------------------- | --------------------------------------------- |
| Nous Portal | `hermes model` | Nous Research subscription / OAuth |
| OpenRouter | `hermes model` 或 API key | 常用環境變數：`OPENROUTER_API_KEY` |
| Anthropic | `hermes model` 或 API key / OAuth | 可用 Claude Code auth 或 Anthropic API key |
| OpenAI Codex | `hermes model` | 走 ChatGPT OAuth / Codex models |
| 一般 OpenAI API | `Custom endpoint` | Base URL 可填 OpenAI-compatible `/v1` endpoint |
| Google Gemini | `hermes model` 或 API key / OAuth | 視你選的 Gemini provider 而定 |
| DeepSeek | `hermes model` 或 API key | 常用環境變數：`DEEPSEEK_API_KEY` |
| NVIDIA NIM | `hermes model` | 可用雲端 NIM 或 local NIM |
| GitHub Copilot | `hermes model` | OAuth 或 GitHub token |
| Custom endpoint | `hermes model` → Custom endpoint | 適合自架 vLLM、SGLang、Ollama、OpenAI-compatible API |
注意：不要把「OpenAI」一概寫成 `OAuth / hermes auth`。官方目前 provider 表中比較明確的是 **OpenAI Codex**，而一般 OpenAI-compatible API 或自架模型應走 **Custom Endpoint**。官方 Quickstart 也列出 Custom Endpoint 適用於 vLLM、SGLang、Ollama 或任何 OpenAI-compatible API。([Hermes Agent][20260429-A-1])
---
## 六、自架 OpenAI-compatible Model 設定流程
你的情境是「自己架設 model 與 URL，API 格式是 OpenAI-compatible」，建議照這個流程。
### 1. 先確認 endpoint 可用
查模型列表：
```bash
curl -s http://YOUR_HOST:8000/v1/models | jq
```
如果有 API key：
```bash
curl -s http://YOUR_HOST:8000/v1/models \
-H "Authorization: Bearer YOUR_API_KEY" | jq
```
看回傳的 model id，例如：
```json
{
"data": [
{
"id": "Qwen/Qwen2.5-Coder-32B-Instruct"
}
]
}
```
這個 `id` 就是 Hermes 裡要填的 model name。
### 2. 測試 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
curl -s http://YOUR_HOST:8000/v1/chat/completions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "YOUR_MODEL_NAME",
"messages": [
{"role": "user", "content": "hi"}
]
}' | jq
```
### 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
```
官方 Quickstart 提到 Hermes Agent 需要至少 64,000 tokens context；自架模型建議把 context 設到至少 64K，例如 `65536`。([Hermes Agent][20260429-A-1])
---
## 七、組態檔管理
```bash
hermes config # 查看目前組態
hermes config show # 顯示目前組態
hermes config edit # 用 $EDITOR 開啟 config.yaml
hermes config set KEY VAL # 設定單一值
hermes config path # 顯示 config.yaml 路徑
hermes config env-path # 顯示 .env 路徑
hermes config check # 檢查遺漏 / 過時設定
hermes config migrate # 互動式補齊新設定
```
主要設定檔位置：
```text
~/.hermes/config.yaml # 主要組態：model、terminal、TTS、compression 等
~/.hermes/.env # API keys、tokens、passwords
~/.hermes/auth.json # OAuth provider credentials
~/.hermes/memories/ # 持久化記憶
~/.hermes/skills/ # Skills
~/.hermes/cron/ # 排程任務
~/.hermes/sessions/ # 對話 / Gateway sessions
~/.hermes/logs/ # 日誌
```
官方原則是：**secrets 放 `.env`，其他非機密設定放 `config.yaml`**。`hermes config set` 會自動把 API key 類資料導到 `.env`，其他設定寫入 `config.yaml`。([Hermes Agent][20260429-A-4])
---
## 八、常見組態區段
常見設定區段：
| 區段 | 說明 |
| ------------------ | ----------------------------------------- |
| `model` | 預設模型與 provider |
| `providers` | provider timeout、model-specific timeout 等 |
| `custom_providers` | 多組自架 OpenAI-compatible endpoint |
| `agent` | Agent 行為，例如 `max_turns` |
| `terminal` | terminal backend、cwd、timeout |
| `compression` | 上下文壓縮設定 |
| `memory` | 記憶 / memory provider |
| `delegation` | 子代理或委派模型設定 |
| `display` | 顯示、主題、streaming、成本顯示 |
| `skills` | skills 設定 |
| `quick_commands` | 自訂 slash command / 快速命令 |
---
## 九、工具管理
```bash
hermes tools # 互動式設定工具啟用狀態
hermes tools --summary # 顯示目前工具啟用摘要
```
目前官方 CLI reference 的穩定寫法是：
```bash
hermes tools [--summary]
```
不加 `--summary` 會進入互動式工具設定 UI；加 `--summary` 則只列出目前啟用摘要。([Hermes Agent][20260429-A-3])
常見工具集概念：
| 工具集 | 說明 |
| ---------------- | ---------------------- |
| `web` | 網頁搜尋與擷取 |
| `browser` | 瀏覽器自動化 |
| `terminal` | Shell 命令 |
| `file` | 檔案讀寫搜尋 |
| `code_execution` | 程式碼執行 / Python sandbox |
| `vision` | 圖片分析 |
| `memory` | 持久化記憶 |
| `delegation` | 子代理委派 |
| `cronjob` | 排程任務 |
在 Hermes 對話中可用：
```text
/tools
```
`/tools` 會列出目前 session 可用工具。官方 CLI guide 也列出 `/tools` 是常見 slash command。([Hermes Agent][20260429-A-5])
---
## 十、Skills 管理
```bash
hermes skills browse # 瀏覽 skills registry
hermes skills search QUERY # 搜尋 skills
hermes skills install ID # 安裝 skill
hermes skills inspect ID # 安裝前預覽 skill
hermes skills list # 列出已安裝 skills
hermes skills check # 檢查更新
hermes skills update # 更新 skills
hermes skills audit # 重新掃描已安裝 skills
hermes skills uninstall ID # 移除 skill
hermes skills config # 互動式設定 skill 啟用狀態
```
官方 CLI reference 的 Skills 子指令包含 `browse/search/install/inspect/list/check/update/audit/uninstall/publish/snapshot/tap/config`。([Hermes Agent][20260429-A-3])
---
## 十一、通訊平台 Gateway
如果要讓 Hermes 跑在 Telegram、Discord、Slack、WhatsApp、Signal、Email 等平台：
```bash
hermes gateway setup # 互動式設定通訊平台
hermes gateway run # 前台執行 Gateway
hermes gateway install # 安裝成 systemd / launchd 背景服務
hermes gateway start # 啟動背景服務
hermes gateway stop # 停止服務
hermes gateway restart # 重啟服務
hermes gateway status # 查看狀態
hermes gateway uninstall # 移除背景服務
```
官方 Gateway 子指令包含 `run/start/stop/restart/status/install/uninstall/setup`；在 WSL、Docker、Termux 裡，官方建議用 `hermes gateway run`，不要優先用 `gateway start`。([Hermes Agent][20260429-A-3])
---
## 十二、Profiles：多配置
```bash
hermes profile list
hermes profile create work
hermes profile create work --clone
hermes profile use work
hermes profile show work
hermes profile delete work
hermes profile rename old-name new-name
hermes profile export work -o work-backup.tar.gz
hermes profile import work-backup.tar.gz --name restored
```
每個 profile 都是獨立 Hermes instance，包含自己的 config、sessions、skills 與 home directory。官方 CLI reference 也支援 `--profile` / `-p` 指定 profile。([Hermes Agent][20260429-A-3])
例如：
```bash
hermes -p work chat -q "Hello from work profile"
```
---
## 十三、常見問題
| 問題 | 解法 |
| ---------------------------------- | -------------------------------------------------------------------- |
| `No inference provider configured` | 離開 Hermes chat，回 shell 執行 `hermes model` |
| 在 Hermes 裡打 `hermes model` 沒用 | Hermes 裡只能用 `/model` 切換已設定模型；新增 provider 要在外層 shell 跑 `hermes model` |
| Custom endpoint 連不上 | 確認 URL 有 `/v1`，例如 `http://host:8000/v1` |
| Model name 錯 | 用 `/v1/models` 回傳的 `id` |
| context length 不足 | 自架模型建議至少 64K，例如 `65536` |
| 工具不可用 | 先跑 `hermes tools` 或進 Hermes 後用 `/tools` 檢查 |
| Gateway 在 WSL 不穩 | 優先用 `hermes gateway run`；需要長駐可搭配 `tmux` |
| 設定檔異常 | `hermes config check`、`hermes config migrate` |
| 需要支援資訊 | `hermes doctor`、`hermes status`、`hermes dump` |
---
## 十四、更新與解除安裝
```bash
hermes update
hermes uninstall
hermes uninstall --full --yes
```
官方 maintenance commands 說明：`hermes update` 會拉最新程式並重新安裝相依套件；`hermes uninstall [--full] [--yes]` 可解除安裝，並可選擇刪除全部 config/data。([Hermes Agent][20260429-A-3])
---
## 十五、最短可操作流程：自架 OpenAI-compatible Model
```bash
# 1. 安裝
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
source ~/.bashrc
# 2. 檢查
hermes doctor
# 3. 查自架模型名稱
curl -s http://YOUR_HOST:8000/v1/models | jq
# 4. 測試 OpenAI-compatible 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
# 5. 設定 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
# 6. 啟動
hermes
```
重點：你的自架模型不要選 `OpenAI Codex`，要選：
```text
Custom endpoint (enter URL manually)
```
[20260429-A-1]: https://hermes-agent.nousresearch.com/docs/getting-started/quickstart "Quickstart | Hermes Agent"
[20260429-A-2]: https://github.com/nousresearch/hermes-agent "GitHub - NousResearch/hermes-agent: The agent that grows with you · GitHub"
[20260429-A-3]: https://hermes-agent.nousresearch.com/docs/reference/cli-commands "CLI Commands Reference | Hermes Agent"
[20260429-A-4]: https://hermes-agent.nousresearch.com/docs/user-guide/configuration "Configuration | Hermes Agent"
[20260429-A-5]: https://hermes-agent.nousresearch.com/docs/user-guide/cli "CLI Interface | 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