---
# System prepended metadata

title: '[AI] Agent / Hermes Agent - 安裝與設定步驟(B版)'
tags: [AI / Tools / Agent /, tools, AI, Hermes Agent, Hermes, agent, 愛馬仕]

---

[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 %}