AI 编程教程中文版
官方教程中文版使用手册

使用手册

Hermes Agent 配置、工具系统、记忆、技能和消息网关的中文使用入口，按问题定位能力边界。

Hermes 的使用手册可以先压成五个入口：配置、工具、记忆、技能、消息网关。它们分别回答「在哪里配置」「能做什么」「记住什么」「如何复用流程」「从哪里远程接入」。

先给结论：排障从 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、profilesHermes 能不能稳定说话、恢复对话和切换模型
执行环境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 写错」混成一个含糊问题——四个问题的修复路径完全不同。

五个入口

配置 Hermes Agent

读懂 ~/.hermes/ 下 config.yaml、.env、auth.json、SOUL.md 各自管什么，以及 provider 和 terminal backend 怎么切换。

工具系统与终端后端

判断要开哪些 toolsets（工具集），以及命令应该在本机、容器、远端还是云端执行——两件事必须分开决策。

记忆系统

MEMORY.md、USER.md、冻结快照、session_search 和外部 memory provider 各自解决不同时间尺度的记忆问题——跨 session、跨任务、跨次对话。

技能系统

判断什么任务值得做成 skill，以及安装外部 skill 前必须审查的密钥与脚本风险。

消息网关与平台接入

把 Hermes 接到 Telegram / Discord / Slack / Email 前，先理解 allowlist（允许名单）、DM pairing（私聊配对）和 chat session（聊天会话）。

按问题定位

不同症状对应不同的「先去哪查」。把症状和入口对上号，比从头翻文档省时间得多：

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 再逐项启用。

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 或多平台网关）：

 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）有暂停命令、日志和失败告警

下一步

配置优先

新手先从配置页开始，确认本机闭环能稳定运行——这是后面所有功能的地基。

回到原理篇

如果你还分不清这些能力之间的关系，先回到原理篇建立心智模型——花 30 分钟比直接开干省一整天排障。

官方资料

规划 Hermes Agent 学习路径

按经验等级和使用场景选择 Hermes Agent 文档阅读顺序，先跑通基础闭环，再进入工具、记忆、消息网关和自动化。

配置 Hermes Agent

理解 Hermes 的 ~/.hermes 目录、config.yaml、.env、OAuth、配置优先级、环境变量替换和七类 terminal backend。

本页目录

官方手册覆盖什么五个入口按问题定位推荐排障顺序启用顺序最小健康状态验收清单下一步官方资料