快速上手 Hermes Agent

快速上手的目標不是把 Hermes Agent 的所有功能開啟，而是得到一個穩定、可恢復、可排障的基礎對話。只有這個基礎閉環穩定，後面的工具、記憶、skills（技能）、Gateway（訊息閘道器）、cron（定時）、MCP（模型上下文協議）和自動化才有意義。

官方資料：Quickstart、Configuration、Providers、Slash Commands Reference、GitHub README。

先給結論：第一次只做四件事：① 安裝；② 配置一個 provider（推理服務商）；③ 完成一次普通對話；④ 用 hermes --continue 恢復 session（會話）。任何 Gateway、cron、skills、MCP 都放到這四步之後——基礎不穩就開擴充套件，故障會疊加成「哪都可能錯」。

最短路徑

下面五步是 Hermes 第一次能跑起來必須按順序透過的檢查點。任何一步失敗都停在當前層排障，不要跳著走：

flowchart LR
    A[1 安裝 install.sh] --> B[2 過載 shell<br/>驗證 PATH]
    B --> C[3 hermes model<br/>配 provider]
    C --> D[4 hermes<br/>第一次對話]
    D --> E[5 hermes --continue<br/>恢復 session]
    E -.穩定後才開擴充套件.-> F[Gateway / cron / skills / MCP / 自動化]
    style F fill:#fde2e2,stroke:#c43d3d

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
source ~/.bashrc   # zsh 用户改用 source ~/.zshrc；原生 Windows 关掉 PowerShell 重开即可
hermes model       # 进入 provider 交互配置
hermes             # 第一次对话
hermes --continue  # 恢复刚才的 session

這五步分別驗證：① 命令安裝、② shell PATH 生效、③ 模型 provider 可用、④ 普通對話能完成、⑤ session 持久化。任何一步失敗就停在當前層排障，不要繼續新增新能力——把鍋留小，比把鍋留大易修。

按目標挑路徑

與官方 The fastest path 表對照——挑一行最貼合你當前目標的執行：

目標	先做這一步	再做這一步
我只想讓 Hermes 在本機能跑	`hermes setup`（嚮導式裝機）	跑一次真實對話驗證它會回
我已經知道用哪家 provider	`hermes model`（直接配）	存好配置，開始聊天
我想做 bot 或 always-on（常駐）服務	先把 CLI 跑穩，再 `hermes gateway setup`	接 Telegram / Discord / Slack 等平臺
我要用本地或自建模型	`hermes model` → 選 custom endpoint	驗證 endpoint URL、模型名、上下文長度
我要多 provider fallback（備用切換）	`hermes model` 先把主路徑跑穩	基礎對話穩定後再加 routing 和 fallback

判斷準則：如果 Hermes 連一次普通對話都跑不通，不要繼續新增任何功能——先讓一次乾淨的對話工作起來，再分層疊加 Gateway、cron、skills、voice、routing。

選擇 provider

Provider 是第一次配置裡最關鍵的部分。Hermes 支援的 provider 陣容很廣（截至本文核驗日，按官方 Providers 頁當前列表為準）：

國際訂閱 / API：Nous Portal、OpenAI Codex、Anthropic Claude、OpenRouter、AWS Bedrock、NVIDIA NIM、Hugging Face、Vercel AI Gateway、GitHub Copilot（含 ACP）。
中國區主流：Z.AI（GLM / 智譜）、Kimi / Moonshot（含中國區端點）、MiniMax（OAuth / 國際 / 中國區）、Alibaba Cloud Qwen（通義千問 DashScope）、DeepSeek。
小眾與試驗：Arcee AI、GMI Cloud、Kilo Code、OpenCode Zen / Go 等。
自定義 endpoint：vLLM、SGLang、Ollama、llama.cpp 或任何 OpenAI 相容 API。

進入互動配置：

hermes model

第一次選擇 provider 時按這三個標準：

你最容易拿到穩定憑據——OAuth 比 API key 更不容易出 typo；國際卡有困難就走中國區 provider。
該 provider 在你當前網路下延遲和可用性穩定——能複用現有梯子的優先國際，沒梯子優先中國區直連。
模型上下文視窗不低於官方要求——下一段細說。

最小上下文 64K tokens：Hermes 啟動時會拒絕上下文視窗 < 64,000 tokens 的模型——長會話、工具呼叫、檔案閱讀和 session 恢復都需要足夠工作記憶。多數託管模型（Claude / GPT / Gemini / Qwen / DeepSeek）預設滿足；本地模型需要顯式設：llama.cpp 用 --ctx-size 65536，Ollama 用 -c 65536。

選錯了不會被鎖死——任何時候都可以 hermes model 切換 provider，配置和 session 都不丟。

配置寫在哪裡

Hermes 把金鑰和普通配置分開放：

~/.hermes/.env         API keys、tokens、secrets（敏感数据，不进 git）
~/.hermes/config.yaml  model、backend、toolsets 等非密钥配置（可进 git）

優先用 CLI 寫非金鑰配置（直接編輯 yaml 容易破壞縮排）：

# 模型（注意：具体模型名按官方推荐为准，不要在教程里写死版本号）
hermes config set model openrouter/anthropic/claude-sonnet-4
hermes config set terminal.backend docker

API key 優先在 hermes model 互動裡貼上或寫到 ~/.hermes/.env（KEY=value 一行一條）。不要手動把金鑰複製到教程、README、GitHub issue、公開 gist 或團隊聊天記錄裡——一旦進了 git 歷史或聊天截圖，撤回成本極高。

第一次對話

啟動經典 CLI：

hermes

或啟動現代 TUI（帶滑鼠支援的終端 UI，富介面）：

hermes --tui

執行後你會看到 Hermes 的歡迎資訊（含當前 provider 和 model 名），下面會出現一個輸入提示符——直接打字、Enter，就是和 Hermes 對話。退出按 Ctrl+C 兩次（或輸入 /exit / 按 Ctrl+D）。

第一次任務要小、明確、可驗證。不要一上來讓 Hermes 重構專案、部署服務或接管資料庫——出錯時你分不清問題是模型、prompt、工具還是配置。

推薦第一條 prompt（複製貼上到提示符後Enter）：

请检查当前目录，说明这是什么项目，并列出你会先查看的 3 个文件。不要修改任何文件。

成功標準（任一不滿足就停在這層排障）：

✅ 歡迎資訊裡能看到當前 provider 和 model 名。
✅ Hermes 能正常回復，回覆內容緊扣你的提問。
✅ 沒有 API key、網路、context 或 provider 報錯。
✅ 如果呼叫了工具，你能看懂它為什麼呼叫（read 哪個檔案、跑了什麼命令）。
✅ 它沒有在未授權情況下修改檔案。

驗證 session 恢復

完成第一次對話後立刻測試恢復：

hermes --continue
# 短参数等价：
hermes -c

如果無法恢復上一輪上下文，先修 session。Hermes 的長期使用全部依賴 session 管理——Gateway、多平臺對話、memory、skills 和自動化都需要穩定的會話基礎；session 不穩，上層全部白搭。

試三個基礎能力

① 只讀理解（最安全的能力，確認模型在做事）：

总结当前目录结构，指出最可能的入口文件。不要修改文件。

② 斜槓命令（slash commands，CLI 的快捷指令）——輸入：

應該能看到命令補全，常見有 /help（幫助）、/tools（檢視工具）、/model（檢視 / 切換模型）、/usage（用量）、/insights（行為洞察）、/history（歷史 session 列表）、/clear（清空當前對話）、/exit（退出）（完整清單按官方 Slash Commands Reference 當前列表為準；實際清單跟 toolset 和已裝 skill 聯動，每裝一個 skill 會自動多一條 /<skill-name> 命令）。

③ 中斷——能中斷才能繼續試更長任務：

如果任务运行太久，发送一条新消息或按 Ctrl+C 中断。

能中斷，才適合繼續試更長任務；中斷不響應說明 TUI 或 session 狀態有問題。

安裝後沒有過載 shell → hermes: command not found。POSIX 跑 source ~/.bashrc / ~/.zshrc；原生 Windows 關掉 PowerShell 重開。
provider key 寫錯或寫到錯位置 → 401/403/拒絕呼叫。重跑 hermes model 走互動配置。
本地模型 context 低於 64K → 啟動時直接被拒。給 llama.cpp 加 --ctx-size 65536，Ollama 加 -c 65536。
第一次任務太大 → 出錯時無法判斷是 provider、工具、prompt 還是 backend 報錯。換小任務回測。
沒驗證 --continue 就接 Gateway → Gateway 收到訊息但回覆丟失。先把單機 session 跑穩。
工具許可權開太多 → 基礎對話報錯被 terminal、browser、MCP 的層層報錯淹沒。臨時把 toolset 降到最小再排障。

Recovery Toolkit · 排障工具集

與官方 Recovery Toolkit 段對應——常見故障的恢復命令速查：

hermes doctor              # Hermes 自查：版本、依赖、配置、权限
hermes config check        # 配置文件语法和必填字段校验
hermes config show         # 打印当前生效配置（注意密钥会脱敏）
hermes model               # 重新走 provider 交互配置
hermes sessions list       # 看历史 session 列表
hermes sessions browse           # 交互浏览历史 session（也可 hermes sessions list 看清单）
# 跨 session 全文搜索由 agent 自己调用 session_search 工具完成（在对话里让它"搜下 X"即可）

不到迫不得已不要 rm -rf ~/.hermes/——它會一併刪掉所有 session、memory、已配 skill 和金鑰。

最小驗收

你應該能完成這條鏈路（任一步失敗就停下排障）：

hermes --help     # PATH 生效
hermes model      # 能进 provider 配置
hermes            # 能完成一次普通对话
hermes --continue # 能恢复 session

並能回答四個問題：

當前使用哪個 provider 和 model？
金鑰寫在哪個檔案？（應該是 ~/.hermes/.env，不是 config.yaml）
config.yaml 在哪裡？裡面有什麼欄位？
session 能不能恢復？最近一次 session 的 ID 你能找到嗎？

回答不了，就繼續停在 quickstart，不要進入工具系統、記憶、技能、Gateway 或自動化。

快速上手 Hermes Agent

最短路徑

按目標挑路徑

選擇 provider

配置寫在哪裡

第一次對話

驗證 session 恢復

試三個基礎能力

只在基礎閉環穩定後加下一層

工具系統

記憶系統

技能系統

訊息閘道器

常見失敗模式

Recovery Toolkit · 排障工具集

最小驗收

下一步

規劃學習路徑

第一個穩定閉環

官方資料

本頁目錄