[AI] Agent / Hermes Agent - 安裝與設定步驟(B版)

[AI] Agent / Hermes Agent - 安裝與設定步驟(B版) === ###### tags: `AI / Tools / Agent / Hermes 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 %}

Syntax	Example	Reference
# Header	Header	基本排版
- Unordered List	Unordered List
1. Ordered List	Ordered List
- [ ] Todo List	Todo List
> Blockquote	Blockquote
Bold font	Bold font
Italics font	Italics font
~~Strikethrough~~	~~Strikethrough~~
19^th^	19^th
H~2~O	H₂O
++Inserted text++	Inserted text
==Marked text==	Marked text
[link text](https:// "title")	Link
![image alt](https:// "title")	Image
`Code`	`Code`	在筆記中貼入程式碼
```javascript var i = 0; ```	`var i = 0;`
:smile:		Emoji list
{%youtube youtube_id %}	Externals
$L^aT_eX$	L^aT_eX
:::info This is a alert area. :::	This is a alert area.