---
title: "使用手冊"
description: "Hermes Agent 配置、工具系統、記憶、技能和訊息閘道器的中文使用入口，按問題定位能力邊界。"
verifiedAt: "2026-05-09"
---

Hermes 的使用手冊可以先壓成五個入口：**配置、工具、記憶、技能、訊息閘道器**。它們分別回答「在哪裡配置」「能做什麼」「記住什麼」「如何複用流程」「從哪裡遠端接入」。

> [!NOTE]
> **先給結論**：排障從 provider（推理服務商）、session（會話）、配置開始，**不從** Gateway（訊息閘道器）、cron（定時任務）、MCP（模型上下文協議）或 skill（技能）開始。基礎閉環穩定後，再逐層啟用工具、記憶、技能和遠端入口——能力越多，錯位越容易擴散。

## 官方手冊覆蓋什麼

Hermes 官方 `llms.txt` 把 user guide（使用指南）拆成約 30 個子頁，可以分成五大類（先看下面的總覽，每項細節會在後續文章展開，不必現在記）：

- **基礎對話與配置**：CLI（命令列）、TUI（終端 UI）、configuration（配置）、models（模型）、sessions（會話）、profiles（配置檔）、git worktrees（git 工作區）、Docker backend（Docker 後端）、security（安全）、checkpoints（檢查點）。
- **能力擴充套件**：tools（工具）、skills（技能）、memory（記憶）、context files（上下文檔案）、SOUL.md（人格檔案）、context references（上下文引用）、plugins（外掛）。
- **自動化**：cron（定時任務）、delegation（子代理委派）、kanban（看板）、goals（持久目標）、code execution（程式碼執行）、hooks（生命週期鉤子）、batch processing（批次處理）。
- **多模態**：voice（語音）、browser（瀏覽器）、vision（視覺）、image generation（影像生成）、TTS（語音合成）。
- **訊息平臺**：15+ 平臺的接入指南。

中文教程不把這些頁面平鋪成選單，而是按**真實排障順序**壓成 5 組：

| 組 | 包含頁面 | 先解決的問題 |
| --- | --- | --- |
| 基礎執行 | CLI、TUI、configuration、models、sessions、profiles | Hermes 能不能穩定說話、恢復對話和切換模型 |
| 執行環境 | tools、toolsets、terminal backends、Docker、SSH、worktrees | 工具和命令在哪裡執行，是否可回復 |
| 長期上下文 | memory、memory providers、context files、SOUL.md、context references | 哪些事實進長期 prompt（系統提示），哪些按需引用 |
| 可複用能力 | skills、curator、plugins、MCP、ACP（代理上下文協議）、API server | 如何擴充套件能力且不汙染基礎環境 |
| 遠端與自動化 | messaging、cron、delegation、kanban、goals、hooks、batch | 遠端入口和後臺任務如何授權、審計和停止 |

這樣讀的好處是遇到問題能**快速定位責任層**，不會把「模型回答差」「命令執行錯」「訊息平臺沒授權」「memory 寫錯」混成一個含糊問題——四個問題的修復路徑完全不同。

## 五個入口

<Cards>
  <Card title="配置 Hermes Agent" description="讀懂 ~/.hermes/ 下 config.yaml、.env、auth.json、SOUL.md 各自管什麼，以及 provider 和 terminal backend 怎麼切換。" href="/zh-Hant/docs/hermes/official/01-user-guide/configuration" />
  <Card title="工具系統與終端後端" description="判斷要開哪些 toolsets（工具集），以及命令應該在本機、容器、遠端還是雲端執行——兩件事必須分開決策。" href="/zh-Hant/docs/hermes/official/01-user-guide/tools" />
  <Card title="記憶系統" description="MEMORY.md、USER.md、凍結快照、session_search 和外部 memory provider 各自解決不同時間尺度的記憶問題——跨 session、跨任務、跨次對話。" href="/zh-Hant/docs/hermes/official/01-user-guide/memory" />
  <Card title="技能系統" description="判斷什麼任務值得做成 skill，以及安裝外部 skill 前必須審查的金鑰與指令碼風險。" href="/zh-Hant/docs/hermes/official/01-user-guide/skills" />
  <Card title="訊息閘道器與平臺接入" description="把 Hermes 接到 Telegram / Discord / Slack / Email 前，先理解 allowlist（允許名單）、DM pairing（私聊配對）和 chat session（聊天會話）。" href="/zh-Hant/docs/hermes/official/01-user-guide/messaging" />
</Cards>

## 按問題定位

不同症狀對應不同的「先去哪查」。把症狀和入口對上號，比從頭翻文件省時間得多：

```mermaid
flowchart LR
    S1["啟動失敗 / 模型不回<br/>key 不生效"] --> E1["📁 配置"]
    S2["命令不知道在哪跑<br/>工具許可權不清"] --> E2["🔧 工具系統"]
    S3["希望記住偏好<br/>專案規則 / 歷史任務"] --> E3["🧠 記憶系統"]
    S4["同一流程反覆做<br/>想做成可呼叫能力"] --> E4["📚 技能系統"]
    S5["接聊天平臺<br/>遠端入口 / 後臺"] --> E5["💬 訊息閘道器"]
    S6["MCP / ACP / API server<br/>provider routing"] --> CHK1{"基礎會話<br/>和 toolsets<br/>已穩定?"}
    S7["voice / browser<br/>vision / TTS"] --> CHK2{"當前工作流<br/>真需要媒體?"}
    CHK1 -- 否 --> E1
    CHK1 -- 是 --> EXT["✅ 擴充套件入口"]
    CHK2 -- 否 --> SKIP["⛔ 先不開"]
    CHK2 -- 是 --> EXT
    style EXT fill:#fde7c2,stroke:#d4761a
    style SKIP fill:#fde2e2,stroke:#c43d3d
```

文字版（圖載入失敗時看這個）：

- **啟動失敗、模型不回、key 不生效** → 先查**配置**。
- **命令不知道在哪裡執行、工具許可權不清楚** → 先查**工具系統**。
- **希望 Hermes 記住偏好、專案規則或歷史任務** → 先查**記憶系統**。
- **同一套流程反覆做，想變成可呼叫能力** → 先查**技能系統**。
- **想把 Hermes 接到聊天平臺、遠端入口或後臺任務** → 先查**訊息閘道器**。
- **需要 MCP、ACP、API server（API 伺服器）或 provider routing（推理服務商路由）** → 先確認基礎會話和 toolsets 已經穩定。它們是**擴充套件入口，不是排障入口**——基礎不穩就開擴充套件，等於在裂縫上加壓。
- **需要 voice（語音）、browser（瀏覽器）、vision（視覺）、image generation（影像生成）或 TTS（語音合成）** → 先確認這些媒體能力真的屬於當前工作流。多數編碼任務並不需要一開始啟用媒體工具。

## 推薦排障順序

不要從最複雜的入口開始排查。穩定順序是：

1. Provider 能不能完成普通對話。
2. Session 能不能恢復。
3. 配置檔案和金鑰是否分開。
4. Toolset 是否只開了當前任務需要的能力。
5. Terminal backend 是否符合風險邊界。
6. Memory 是否只存穩定事實。
7. Skill 是否來自可信來源並已 `hermes skills inspect`（檢查命令）透過審查。
8. Gateway、cron、background（後臺會話）、MCP 再逐項啟用。

> [!IMPORTANT]
> Hermes 的複雜問題大多會退回三個基礎點：**provider 是否穩定、session 是否可恢復、工具是否越權**。先把這三點修對，再回頭看上層報錯——很多上層故障會自己消失。

## 啟用順序

把 Hermes 放進真實專案時，推薦按下面的順序做，**每一步都要有可觀察結果**（不只是"配完了"，而是"配完後我能看到什麼變化、出錯怎麼知道"）：

1. **Provider**（推理服務商）：普通對話、模型切換和 token 計費路徑都能解釋清楚。
2. **Session**（會話）：新建、繼續、搜尋、命名和清理 session 都能工作。
3. **Config**（配置）：`config.yaml`、`.env`、`auth.json`、profile（配置檔）與專案 context 檔案（如 `AGENTS.md`、`SOUL.md`）分工清楚。
4. **Tools**（工具）：只開當前任務需要的 toolset，並記錄高風險命令的批准方式（哪些命令需要按 Y 才執行，哪些走自動放行）。
5. **Backend**（後端）：local、Docker、SSH、Daytona、Modal、Singularity、Vercel Sandbox 共 7 個選項只選**一個主路徑**先跑通；想加第二個之前先確認第一個穩定。
6. **Memory**（記憶）：只儲存偏好、環境、約定和已驗證結論，不存日誌、金鑰或臨時細節——記憶是越用越髒的，寫入門檻要高。
7. **Skills**（技能）：先使用內建或自建小 skill，跑穩了再考慮 Skills Hub 和外部 skill；任何外部 skill 安裝前都跑 `hermes skills inspect` 看指令碼和金鑰需求。
8. **Gateway**（訊息閘道器）：從一個平臺開始（例如 Telegram 或 Slack），先用 allowlist 限定使用者；跑穩一個再加第二個。
9. **Automation**（自動化）：cron、delegation、hooks、kanban、goals 最後啟用，並**保留暫停入口**——後臺任務必須能被一條命令停掉。

這不是保守，而是減少排障變數。Hermes 的優勢在組合能力，組合能力只有在基礎層穩定後才有價值；基礎不穩就堆功能，等於把噪聲放大。

## 最小健康狀態

一個可繼續擴充套件的 Hermes 設定應該滿足下面 8 條。可以用來對照自己當前裝機：

- `hermes --help` 正常輸出。
- `hermes model` 能列出和切換 provider。
- `hermes` 能完成一次普通對話（輸入問題、收到合理回覆）。
- `hermes --continue` 能恢復上一次 session。
- `~/.hermes/.env`（金鑰）和 `config.yaml`（配置）分工清楚，互不混寫。
- `terminal.backend` 明確指定（local / docker / ssh / ...），不是預設值矇混。
- toolsets 是按任務**最小開啟**——比如做編碼任務不開 browser 工具集。
- **Gateway 沒有在未配置 allowlist 的情況下上線**（這條最容易踩坑：先開 Gateway 再設 allowlist = 在裸跑期間任何人都能命令你的機器）。

## 驗收清單

完成本節後，你應該能做一次最小驗收。把下面 10 條逐項確認（**任何一項說不清，就別繼續疊加 MCP、cron、delegation 或多平臺閘道器**）：

```text
 1. hermes 能进入 CLI 或 TUI
 2. provider 能完成一次普通对话
 3. hermes --continue 能恢复上一轮
 4. 配置文件和密钥文件没有混写（密钥不出现在 config.yaml 里）
 5. 能解释当前 toolset 清单（开了哪几组工具集、为什么）
 6. 能解释 backend 的实际执行位置（命令到底在本机/容器/远端跑）
 7. memory 里没有临时日志、token 或敏感信息
 8. 能解释每个已安装 skill 的来源和作用范围
 9. messaging 入口有 allowlist 或等效访问限制
10. 自动化任务（cron / hooks / goals）有暂停命令、日志和失败告警
```

## 下一步

<Cards>
  <Card title="配置優先" description="新手先從配置頁開始，確認本機閉環能穩定執行——這是後面所有功能的地基。" href="/zh-Hant/docs/hermes/official/01-user-guide/configuration" />
  <Card title="回到原理篇" description="如果你還分不清這些能力之間的關係，先回到原理篇建立心智模型——花 30 分鐘比直接開幹省一整天排障。" href="/zh-Hant/docs/hermes/understanding/01-what-is-hermes-agent" />
</Cards>

## 官方資料

- 官方文件首頁：[https://hermes-agent.nousresearch.com/docs](https://hermes-agent.nousresearch.com/docs)
- 官方 `llms.txt`（機器可讀全文索引）：[https://hermes-agent.nousresearch.com/docs/llms.txt](https://hermes-agent.nousresearch.com/docs/llms.txt)
- 上游原始碼：[https://github.com/NousResearch/hermes-agent](https://github.com/NousResearch/hermes-agent)
- 命令速查：[Reference / CLI Commands](https://hermes-agent.nousresearch.com/docs/reference/cli-commands)
- 工具與後端列表：[User Guide / Features / Tools](https://hermes-agent.nousresearch.com/docs/user-guide/features/tools)
