---
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="/docs/hermes/official/01-user-guide/configuration" />
  <Card title="工具系统与终端后端" description="判断要开哪些 toolsets（工具集），以及命令应该在本机、容器、远端还是云端执行——两件事必须分开决策。" href="/docs/hermes/official/01-user-guide/tools" />
  <Card title="记忆系统" description="MEMORY.md、USER.md、冻结快照、session_search 和外部 memory provider 各自解决不同时间尺度的记忆问题——跨 session、跨任务、跨次对话。" href="/docs/hermes/official/01-user-guide/memory" />
  <Card title="技能系统" description="判断什么任务值得做成 skill，以及安装外部 skill 前必须审查的密钥与脚本风险。" href="/docs/hermes/official/01-user-guide/skills" />
  <Card title="消息网关与平台接入" description="把 Hermes 接到 Telegram / Discord / Slack / Email 前，先理解 allowlist（允许名单）、DM pairing（私聊配对）和 chat session（聊天会话）。" href="/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="/docs/hermes/official/01-user-guide/configuration" />
  <Card title="回到原理篇" description="如果你还分不清这些能力之间的关系，先回到原理篇建立心智模型——花 30 分钟比直接开干省一整天排障。" href="/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)
