---
title: "快速上手 Hermes Agent"
description: "從安裝、provider、第一次對話、session 恢復到下一層能力，跑通 Hermes Agent 的最小穩定閉環。"
verifiedAt: "2026-05-09"
---

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

官方資料：[Quickstart](https://hermes-agent.nousresearch.com/docs/getting-started/quickstart)、[Configuration](https://hermes-agent.nousresearch.com/docs/user-guide/configuration)、[Providers](https://hermes-agent.nousresearch.com/docs/integrations/providers)、[Slash Commands Reference](https://hermes-agent.nousresearch.com/docs/reference/slash-commands)、[GitHub README](https://github.com/NousResearch/hermes-agent)。

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

## 最短路徑

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

```mermaid
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
```

```bash
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 |

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

## 選擇 provider

Provider 是第一次配置裡最關鍵的部分。Hermes 支援的 provider 陣容很廣（截至本文核驗日，按官方 [Providers 頁](https://hermes-agent.nousresearch.com/docs/integrations/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。

進入互動配置：

```bash
hermes model
```

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

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

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

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

## 配置寫在哪裡

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

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

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

```bash
# 模型（注意：具体模型名按官方推荐为准，不要在教程里写死版本号）
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：

```bash
hermes
```

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

```bash
hermes --tui
```

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

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

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

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

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

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

## 驗證 session 恢復

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

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

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

## 試三個基礎能力

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

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

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

```text
/
```

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

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

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

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

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

<Cards>
  <Card title="工具系統" description="配置 web / terminal / file / browser / memory / cron 等 toolsets——按當前任務最小啟用。" href="/zh-Hant/docs/hermes/official/01-user-guide/tools" />
  <Card title="記憶系統" description="MEMORY.md（專案記憶）、USER.md（使用者偏好）、session_search（歷史檢索）的寫入門檻。" href="/zh-Hant/docs/hermes/official/01-user-guide/memory" />
  <Card title="技能系統" description="用 skill 存放可複用工作流和過程性知識——但外部 skill 安裝前必須 inspect。" href="/zh-Hant/docs/hermes/official/01-user-guide/skills" />
  <Card title="訊息閘道器" description="接 Telegram / Discord / Slack / WhatsApp / Signal / Email / DingTalk / Feishu 等平臺前先做 allowlist。" href="/zh-Hant/docs/hermes/official/01-user-guide/messaging" />
</Cards>

Gateway、cron 和後臺自動化都會**擴大許可權面**——基礎對話不穩定時不要接。等於在裂縫上加壓，故障傳導路徑會變長難追。

## 常見失敗模式

按出現頻率從高到低，先看符合自己症狀的那條：

- **安裝後沒有過載 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_ 段對應——常見故障的恢復命令速查：

```bash
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 和金鑰。

## 最小驗收

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

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

並能回答四個問題：

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

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

## 下一步

<Cards>
  <Card title="規劃學習路徑" description="跑通基礎閉環後，按經驗和目標選擇後續文件——挑一條貼近你目標的路徑開幹。" href="/zh-Hant/docs/hermes/official/00-getting-started/learning-path" />
  <Card title="第一個穩定閉環" description="想理解為什麼不要一開始全開功能是教程鐵律，讀原理篇的閉環章節。" href="/zh-Hant/docs/hermes/understanding/02-first-stable-loop" />
</Cards>

## 官方資料

- [Quickstart 完整頁](https://hermes-agent.nousresearch.com/docs/getting-started/quickstart)（含影片版）
- [Configuration](https://hermes-agent.nousresearch.com/docs/user-guide/configuration)
- [Providers 完整目錄](https://hermes-agent.nousresearch.com/docs/integrations/providers)
- [Slash Commands Reference](https://hermes-agent.nousresearch.com/docs/reference/slash-commands)
- [GitHub README](https://github.com/NousResearch/hermes-agent)
