Hermes Agent 从中级到高级进阶指南

本指南默认你已完成 Hermes 的基础安装与配置，正文不再重复安装步骤。我们将直接进入进阶核心内容：记忆系统、技能自进化、多 Agent 协作、生产化部署与高级调试。

一、记忆系统进阶

1 Hermes 记忆系统的整体架构详解

2 Agent-curated memory 机制原理：为什么它“不记得”？

3 核心记忆文件正确使用方法（附模板）

4 Super Memory 与持久记忆 nudge 配置

5 跨会话与长任务记忆保持方法

6 外部 Memory Providers 实战配置

7 记忆文件管理规则与清理技巧

8 记忆与技能的联动机制

动手实践：构建你的专属记忆系统

二、技能自进化

1 Hermes 自我进化机制详解（Agent-Managed Skills）

2 Agent 自动创建 Skill 的触发条件与流程

3 技能质量控制与优化方法

4 技能退化与重复问题的解决思路

5 Skill 与记忆系统的联动机制

6 Self-optimization 功能使用建议

动手实践：训练你的第一个自动化技能

三、多 Agent 协作

1 Sub-Agent 的 spawn 机制与使用方法

2 Profiles 功能实战：同一台机器运行多个独立 Hermes

3 子 Agent 的独立记忆与技能隔离

4 主 Agent 协调多个子 Agent 的技巧

5 多 Agent 资源分配与冲突避免

动手实践：配置双 Agent 协作工作流

四、生产化部署

1 Gateway 长期后台运行的多种方式

2 定时任务、Heartbeat 与通知机制

3 日志监控与调试方法

4 Tirith 安全模块的使用与处理

5 多平台接入进阶配置

6 生产化部署 Checklist

动手实践：完成生产环境的稳定部署

五、高级扩展与调试

1 MCP 外部工具链集成实战

2 调试高级技巧 + 中高级常见报错快速定位

动手实践：接入本地文件系统或数据库

六、疑难解答（Q&A）

七、配置速查表

一、记忆系统进阶

很多人用了 Hermes 一段时间后，最大的抱怨就是：“它根本记不住东西”。这通常不是 Bug，而是没有搞清楚它的记忆机制。Hermes 的记忆系统有比较明确的设计逻辑，理解它，才能真正让 Agent 越用越聪明。

1 Hermes 记忆系统的整体架构详解

Hermes 的记忆系统更适合理解为内置记忆 + 外部记忆提供商 + 运行时上下文的组合，而不是简单的“只有两层”。其中，内置记忆始终存在；外部 Memory Provider 是叠加能力，不是替代关系。

第一层：内置记忆（始终激活）

内置记忆通常由两个文件组成。默认 profile 下，它们通常存储在 ~/.hermes/memories/ 目录；如果你启用了命名 Profile，则对应路径会跟随当前 HERMES_HOME 变化到该 Profile 的 memories/ 目录。

MEMORY.md 更像 Agent 的工作笔记，主要保存环境事实、项目约定和学到的技巧。针对 MEMORY.md，Hermes 存在 2,200 字符的系统阈值（硬限制）。为避免信息截断，建议日常维持在 1,800 字符（约 1,200 汉字）左右，预留 20% 空间给 Agent 自动追加。
USER.md 更像用户画像，主要保存偏好、沟通风格和工作习惯。针对 USER.md，Hermes 存在 1,375 字符的系统阈值（硬限制）。建议日常维持在 1,100 字符（约 700 汉字）左右，预留空间给 Agent 自动追加，以保持用户画像的精炼。

这两个文件在每次会话开始时，会作为冻结快照（Frozen Snapshot）注入到上下文中。注意“冻结”这个词，它意味着：

会话中途 Agent 新写入的记忆，往往不会立刻改变当前这轮会话的上下文，通常要到后续会话或后续重载时才更明显地体现出来。
这种设计的核心目标之一，是尽量保持前缀稳定，从而提升缓存命中并降低推理成本。

第二层：外部记忆提供商（可选，叠加激活）

外部提供商是对内置记忆的补充，不是替代。启用后，Hermes 通常会在合适的时机从外部提供商提取相关信息，并在会话结束或阶段性反思时同步新的长期信息。不同 provider 的具体行为会略有差异，因此实战中最好以对应 provider 的官方说明为准。

2 Agent-curated memory 机制原理：为什么它“不记得”？

这是最多人踩的坑。Hermes 的内置记忆是Agent 策展（Agent-curated）的，不是全量记录的。

机制原理

Hermes 把记忆写入设计成“冻结快照 + Agent-curated（策展）机制”，主要有两个重要原因：

节省 Token 和提升推理速度：如果每轮对话都实时更新记忆，System Prompt 的头部就会频繁变化，导致模型无法有效利用 KV Cache（前缀缓存），推理成本和响应速度都会明显变差。冻结快照的设计能让 Prompt 头部保持相对稳定，从而大幅降低 Token 消耗。
防止记忆污染，保证质量：Agent 在思考过程中的很多“碎碎念”、临时试错、中间结果，其实并不值得长期保留。只有经过 Agent 自己判断“重要”的内容，才会被策展（curated）后写入长期记忆。这样能让记忆保持干净、高密度，避免低价值信息干扰后续决策。

简单来说：实时写入会贵且乱，策展 + 周期性 nudge 则是性能与质量的平衡点。

Agent 不会把你说的每一句话都写进记忆。通常只有在以下场景里，记忆才更容易被保留下来：

你明确表达了偏好，例如“我喜欢/不喜欢 xxx”
发现了环境事实，例如“这台机器装了 xxx”
纠正了 Agent 的错误做法，例如“不要用 sudo，我在 docker 组里”
完成了一个重要任务里程碑
你明确要求它记住某件事

触发时机

写入通常不是每句话实时发生，而是会结合 nudge_interval 这类节奏控制，在若干轮对话后触发一次“记忆反思”。如果会话太短，或者任务太单一，Agent 可能根本没有足够机会去整理并固化记忆。

解决方案：尽量明确地下达记忆指令

最直接的方法是在对话中明确指令：

记住我的偏好：所有代码统一使用 Python 3.11，不要用 3.12 或 3.13。

这样更容易让 Agent 把这类信息视为值得长期保留的内容

3 核心记忆文件正确使用方法（附模板）

除了 MEMORY.md 和 USER.md，Hermes 还有几个重要的上下文文件，很多人会搞混它们的用途。这里直接按用途来记会更直观；下面默认按默认 profile 的路径写示例，如果你启用了命名 Profile，请把 ~/.hermes 替换成当前 profile 的 HERMES_HOME。

MEMORY.md 位于 ~/.hermes/memories/，主要保存 Agent 的工作笔记、环境事实和学到的技巧，通常主要由 Agent 维护。
USER.md 位于 ~/.hermes/memories/，主要保存用户画像、偏好和沟通风格，通常主要由 Agent 维护。
SOUL.md 位于 ~/.hermes/，主要保存 Agent 的人格、行为准则和固定规则，这部分更适合你自己来写。
AGENTS.md 位于项目根目录，主要保存项目级行为规范和执行约束，这部分也更适合你自己来写。

铁律：不要把应该写在 SOUL.md 里的东西放进 MEMORY.md。

MEMORY.md 更像 Agent 的工作笔记，会被整理、压缩，甚至替换掉过时内容。你的固定规则应该放在 SOUL.md，那里更适合承载稳定、不希望被自动重写的约束。

SOUL.md 模板

（请参考你原教程“零、开始之前”章节中的完整模板，直接复制到 ~/.hermes/SOUL.md）

AGENTS.md 模板（直接复制到你的项目根目录）

# 项目规范：MyAPI Service
## 技术栈
- 语言：Rust 1.75+
- 框架：Axum
- 数据库：PostgreSQL 16（使用 SQLx）
## 编码约定
1 所有数据库查询必须使用 SQLx 的宏进行编译期检查。
2 错误处理统一使用 `anyhow::Result` 和自定义的 `AppError` 枚举。
3 环境变量配置在 `.env` 文件中，不要在代码中硬编码任何凭证。
## 常用命令
- 运行测试：`cargo test --all-features`
- 启动服务：`cargo run --bin server`

4 Super Memory 与持久记忆 nudge 配置

调整 nudge 频率时，打开 ~/.hermes/config.yaml，找到或添加类似配置：

memory:
nudge_interval: 5

数值越小，Agent 越频繁地进行记忆反思，写入的内容通常也会更多，但 token 消耗也会增加。

推荐值更适合按模型能力与任务长度来估算，而不要把某一个数字当成所有环境的绝对标准。可以这样理解：

小模型、较小上下文窗口的场景，通常更适合从 3~5 起步，因为上下文更紧，需要更早固化重要信息。
标准模型和常见上下文窗口的场景，通常适合从 5~10 起步，在成本与记忆质量之间更容易取得平衡。
大上下文模型可以考虑 10~15 左右，因为它们往往可以在更长对话后再做质量更高的总结。

说明：在很多安装环境里，memory.nudge_interval 的默认值常见为 10，但不同版本、旧配置迁移结果和后续调整都可能不同，最终仍以你本机 config.yaml 为准。Hermes 原生不使用 flush 参数，而是通过 nudge 机制在会话间隙进行记忆固化。

注意：这里的“轮”更适合理解为一次完整的用户输入与 Agent 回复，而不是 Agent 内部的 tool call 次数。

5 跨会话与长任务记忆保持方法

方法一：手动插入 Checkpoint（最简单有效）

在长任务进行到一半时，主动告诉 Agent：

当前进度总结：我们已经完成了数据清洗和特征工程，下一步是训练模型。请把这个进度写入你的记忆，确保后续不会忘记。

方法二：用外部文件作为“任务状态文件”

对于超长任务，让 Agent 维护一个专门的状态文件：

请在项目目录下创建 TASK_STATUS.md，记录当前任务的完整状态。每次我们恢复工作时，先读取这个文件。

时间线提醒：记忆插件化并不是 v0.9.0 才新增的能力。更准确地说，自 v0.7.0 起，Hermes 就已经提供了可插拔的 external memory providers。

6 外部 Memory Providers 实战配置

自 v0.7.0 起，Hermes 已支持多种外部 Memory Providers，例如：Honcho、OpenViking、Mem0、Hindsight、Holographic、RetainDB、ByteRover、Supermemory 等。内置 MEMORY.md / USER.md 仍继续工作，并不是被外部 provider 替代；实际支持列表请以你当前版本的官方文档、插件界面或本机可用 provider 为准。

推荐一：Mem0（偏省心、自动化程度较高）

Mem0 的核心优势是自动提取与同步长期记忆，适合不想手动设计太多记忆流程的用户。

# 1. 安装依赖
pip install mem0ai
# 2. 获取 API Key：https://app.mem0.ai/
# 3. 写入环境变量
echo "MEM0_API_KEY=your-key-here" >> $HERMES_HOME/.env
# 4. 激活
hermes config set memory.provider mem0
# 5. 验证
hermes memory status

推荐二：Holographic（偏本地、隐私友好）

如果你不想把数据发给第三方服务，Holographic 往往是一个更偏本地化的选择。

# 激活
hermes config set memory.provider holographic
# 验证
hermes memory status

7 记忆文件管理规则与清理技巧

记忆容量管理的核心逻辑是：记忆不是越多越好，而是越稳定、越高密度越好。

这里不必把容量当成死表去记，理解使用感受就够了：MEMORY.md 的 2,200 字符硬限制通常更适合保存 8 到 15 条高价值事实；USER.md 的 1,375 字符硬限制通常更适合保存 5 到 10 条稳定偏好。

最佳实践通常不是“把容量塞满”，而是尽量让内容保持紧凑、可复用、不过度重复。实战中控制在 70%~80% 左右通常会更舒服，但这属于经验建议，不是硬性规则。

当 MEMORY.md 接近上限时，你可以手动引导 Agent：

请整理你的记忆，删除过时条目，合并相关条目，腾出空间。

手动清理也可以直接编辑文件：

nano ~/.hermes/memories/MEMORY.md

nano ~/.hermes/memories/MEMORY.md

如果你的版本支持相关记忆维护命令，也可以优先使用官方提供的清理或压缩方式。

8 记忆与技能的联动机制

当 Agent 在 MEMORY.md 中多次记录了类似工作流，例如“每次部署前都要执行 A、B、C 三步”，这往往意味着：这个流程更适合沉淀为一个 Skill，而不是继续零散地塞在记忆里。

你可以主动引导：

我注意到你已经记住了我们的部署流程。请把这个流程创建为一个可复用的 Skill，名字叫 deploy-workflow，这样以后可以直接复用。

动手实践：构建你的专属记忆系统

任务目标：配置好基础的记忆文件，并测试 Agent 的记忆能力。

操作步骤：

复制本章的 SOUL.md 模板到 ~/.hermes/SOUL.md，并根据你的实际情况修改。
在你的常用项目目录下创建一个 AGENTS.md。
修改 config.yaml，先将 nudge_interval 设置为 5 进行测试。
开启一个新的对话，告诉 Agent 一条特定偏好，例如：“以后所有的 Python 脚本都保存在 /tmp/scripts 目录下。”
进行 5 轮以上的对话，观察是否触发记忆整理。

预期效果：

运行 cat ~/.hermes/memories/MEMORY.md，能看到你刚才告诉它的偏好已经被记录下来。
开启一个全新的会话，让 Agent 写一个 Python 脚本，它更有可能自动遵循先前记录的偏好。

二、技能自进化

Hermes 最大的差异点不只是“能干活”，而是“越干越会干”。理解技能自生成机制，才能让你的 Agent 真正进化，而不是每次都从零开始。

1 Hermes 自我进化机制详解（Agent-Managed Skills）

Hermes 的自我进化与 skill_manage 工具关系非常密切。这更接近 Agent 的“程序性记忆”：当它摸索出一套非平凡的工作流后，会把这套方法保存为 Skill，供未来复用。

一句话总结：记忆解决“记得住”，技能解决“用得高效且可复用”。Hermes 设计技能自生成机制的核心目的，是把记忆中的重复经验进一步沉淀为可复用的结构化 Skill。记忆更多是“事实和经验的记录”，相对散乱；

而 Skill 是把这些经验提炼成清晰的触发条件 + 操作步骤 + 注意事项 + 验证方法，相当于把“知道怎么做”变成了“标准化 SOP”。这样做的好处是大幅降低 Agent 每次重新推理的负担（不用每次都从头思考流程），同时 Skill 更容易被标准化、复用，甚至跨 Profile 或跨 Agent 分发。

从长期看，这是 Hermes 实现“规模化协作”和“持续自我进化”的重要基础 —— 记忆是私有的、碎片化的，而 Skill 是可共享、可积累的“程序性知识”。

Skill 通常存放在当前 HERMES_HOME 对应的 skills/ 目录下；默认 profile 一般是 ~/.hermes/skills/。它不是可执行代码，而是一份可复用的操作知识——告诉 Agent“遇到这类任务时，应该怎么做”。

2 Agent 自动创建 Skill 的触发条件与流程

常见触发条件通常包括以下场景：
完成了一个相对复杂的任务
遇到了错误或死路，后来找到了正确路径
用户纠正了它的做法
发现了一个值得复用的非平凡工作流

主动引导 Agent 创建 Skill：

我们刚才完成的这个数据处理流程很有价值，请把它保存为一个 Skill，名字叫 data-pipeline，放在 devops 分类下，确保包含触发条件、操作步骤、注意事项和验证方法。

3 技能质量控制与优化方法

判断一个 Skill 质量好不好的标准：
触发条件清晰：Agent 能准确判断什么时候该用它
步骤可执行：每一步都有明确操作，而不是空泛描述
有验证方法：执行完后能判断是否成功
有注意事项：记录了踩过的坑

手动优化 Skill 时，通常建议让 Agent 做定点修改，而不是整篇重写。例如：

请更新 stock-daily-report 这个 Skill，在注意事项里补充一条：“周五收盘后数据可能延迟到周六早上才完整。”

4 技能退化与重复问题的解决思路

技能退化的表现通常包括：

描述越来越模糊，触发条件越来越宽泛
多个 Skill 做的是同一件事，但写法不同

解决方案：让 Agent 做技能审计。

请审查你所有的 Skills，找出：
功能重复的技能（合并它们）
描述模糊、触发条件不清晰的技能（重写它们）

给我一份审计报告，然后等我确认后再执行修改。步骤已经过时的技能（更新它们）

5 Skill 与记忆系统的联动机制

在 SKILL.md 中，你可以引导 Agent 在执行技能前先查看记忆：

## 操作流程
1 先检查 MEMORY.md 中是否有关于该 API 的特殊注意事项。
2 如果有，优先遵循记忆中的约定。
3 执行完成后，将新发现的注意事项写入 MEMORY.md。

6 Self-optimization 功能使用建议

在 v0.8.0 到 v0.9.0 这一轮版本演进里，Hermes 的自我改进体验在 tool-use 优化和失败模式修复上持续增强，使得 Agent 在遇到问题时能更智能地调整其行为策略 6 7。但具体实现细节和配置入口会随版本迭代，建议以官方最新文档为准。

因此，比较稳妥的写法是：

把 Self-optimization 理解为 Hermes 在使用过程中会逐步修补技能和行为策略的能力方向。
如果你要写进教程正文，建议使用“能力说明”而不是“固定配置键模板”。
对于当前版本暂未完全确认的配置项，最好统一写成“请以官方最新配置参考和你本机 config.yaml 为准”。

动手实践：训练你的第一个自动化技能

任务目标：让 Agent 学习并固化一个你常用的工作流。

操作步骤：

找一个你经常做的重复性任务，例如：检查系统磁盘空间、清理 Docker 悬空镜像，并输出一份简报。
在对话中，一步步指导 Agent 完成这个任务，纠正它的错误，直到执行稳定。
发送指令：“请把刚才的清理流程保存为一个 Skill，命名为 docker-cleanup，包含触发条件、具体执行命令和验证步骤。”
运行 hermes skills list 查看是否创建成功。

预期效果：

开启一个新会话，直接发送指令：/docker-cleanup
Agent 能够较稳定地按照之前固化的步骤完成任务

三、多 Agent 协作

1 Sub-Agent 的 spawn 机制与使用方法

Hermes 对子 Agent 并发做了保护性限制，实战中不建议一上来就把并发拉得太高。对大多数在线模型场景，更稳妥的起点仍然是 2~3 个子 Agent，再根据额度、限流情况和结果质量逐步调整。

专家建议：在实际使用中，并发数不建议超过 3 个。特别是当使用官方 API 时，建议从 2 个起步，以防止触发 API 平台的 Rate Limit 或被封禁 IP，从而影响正常任务的执行。在实战中，追求理论最大并发往往不如控制成本与上下文质量重要。对于大多数在线模型场景，建议从 2~3 个并发子任务起步，再根据额度、限流情况和结果质量逐步调整。并发数越高，API 消耗通常增长越快。

Hermes 支持主 Agent 通过 delegate_task 等方式派生子 Agent 执行拆分后的任务。

基本用法（在对话中引导主 Agent）：

这个任务可以并行处理：

子任务 A：抓取 A 股今日涨停板数据
子任务 B：分析北向资金流向
子任务 C：生成市场情绪指数

请派生 3 个子 Agent 并行完成这三个子任务，然后汇总结果。

子 Agent 的关键限制（必读）

子 Agent 往往从一个新的会话上下文开始，它并不会天然继承主 Agent 的完整历史。因此，你必须在 context 里把子 Agent 所需的背景信息传完整：

delegate_task(
goal="修复 api/handlers.py 中的 TypeError",
context="""
文件路径：/home/user/myproject/api/handlers.py
错误信息：第 47 行 TypeError: 'NoneType' object has no attribute
'get'
原因：parse_body() 在 Content-Type 缺失时返回 None
项目使用 Python 3.11 + Flask
"""
)

最重要的经验是：不要假设子 Agent 知道“这个错误”“刚才那个文件”“上一步那个思路”是什么。

2 Profiles 功能实战：同一台机器运行多个独立 Hermes

Profile 是一个完全隔离的 Hermes 环境。每个 Profile 都有自己独立的配置、记忆、会话和技能；底层通常是通过单独的 HERMES_HOME 路径来实现目录级隔离 5。但要注意，默认 profile 仍然就是 ~/.hermes；只有你显式创建并切换到命名 Profile 时，相关配置、记忆、技能、会话和日志等才会跟随当前 HERMES_HOME 切到 ~/.hermes/profiles/<name>/ 这类路径。

创建 Profile 的三种常见方式：

# 方式一：全新 Profile（空白）
hermes profile create mybot
# 方式二：克隆配置（复用 API Key 和模型，但记忆和会话独立）
hermes profile create work --clone
# 方式三：完整克隆（包含记忆、会话、技能等更多状态）
hermes profile create backup --clone-all

运行多个独立 Agent：

# 终端 1：运行编码助手
coder chat
# 终端 2：运行投研助手（独立的记忆和技能）
research chat

3 子 Agent 的独立记忆与技能隔离

每个 Profile 的 memories/、skills/、sessions/ 和 logs/ 目录通常都是独立的，不会互相读写。

如果你希望多个 Profile 共享同一套技能，可以考虑使用外部技能目录；但具体字段名和配置方式，最好以你当前版本的配置参考为准。一个常见思路如下：

skills:
external_dirs:
- ~/.hermes/shared-skills

4 主 Agent 协调多个子 Agent 的技巧

明确角色分工，通常是最有效的方法。你可以在 SOUL.md 或 AGENTS.md 中定义：

## 多 Agent 协作规范
- Planner Agent：负责任务分解和进度追踪，不直接执行
- Executor Agent：负责具体的数据获取和处理，不做决策
- Reviewer Agent：负责质量检查和结果验证，不做修改

5 多 Agent 资源分配与冲突避免

Bot Token 冲突保护

如果两个 Profile 意外使用了同一个 Bot Token，运行中的 Gateway 往往会产生冲突。因此，最好在各自的 .env 中配置不同的 Token。

端口冲突

如果你在本地运行多个 Hermes 实例，最好让它们使用不同端口。例如：

# Profile A
GATEWAY_PORT=8080
# Profile B
GATEWAY_PORT=8081

动手实践：配置双 Agent 协作工作流

任务目标：创建两个独立的 Profile，分别承担不同角色，互不干扰。

操作步骤：

运行 hermes profile create coder –clone 创建一个专门写代码的 Agent。
运行 hermes profile create reviewer –clone 创建一个专门做代码审查的 Agent。
分别编辑它们的 SOUL.md，赋予不同角色设定。
让 coder 写一段有 Bug 的代码并保存到文件。
切换到 reviewer，让它读取该文件并提出修改建议。

预期效果：

两个 Agent 能独立运行，且 reviewer 的记忆中不会混入 coder 的工作流。

四、生产化部署

1 Gateway 长期后台运行的多种方式

方式一：Systemd（Linux 生产环境首选）

# 安装为 Systemd 服务
hermes gateway install
# 查看服务状态
systemctl status hermes-gateway # 如果你使用命名 Profile，服务名可能
会带上 profile 后缀，以实际安装输出为准
journalctl -u hermes-gateway -f

方式二：Docker Compose 方式（更适合多 Profile 部署）

version: "3.8"
services:
hermes-default:
image: nousresearch/hermes-agent:latest
container_name: hermes-default
restart: unless-stopped
command: gateway run
volumes:
- ~/.hermes:/opt/data
hermes-coder:
image: nousresearch/hermes-agent:latest
container_name: hermes-coder
restart: unless-stopped
command: gateway run
volumes:
- ~/.hermes/profiles/coder:/opt/data

重要提醒：不要同时运行两个容器挂载同一个数据目录，否则共享状态文件可能出问题。

2 定时任务、Heartbeat 与通知机制

❗ 专家级警告：严禁盲目复制模板时区！

Hermes 的 Cron 任务严格依赖服务器系统时区。配置前必须运行 timedatectl 确认。

国内服务器：应显示 Asia/Shanghai。

海外服务器：若显示 UTC，请手动执行 sudo timedatectl set-timezone Asia/Shanghai 修正，否则你的定时任务会在半夜“惊喜上线”。

Heartbeat 机制（防止静默失败）

# 在 ~/.hermes/.env 中添加
echo "GATEWAY_HEARTBEAT=true" >> ~/.hermes/.env

定时任务（Cron）

# 示例：工作日早上 8:30 生成日报
hermes cron add "30 8 * * 1-5" " 生成今日 A 股市场日报并发送到
Telegram"

时区是最容易踩的坑之一。 Hermes 的 Cron 通常使用服务器系统时区。如果你的服务器时区与预期不一致，定时任务就会在错误时间运行。

# 先确认服务器系统时区
timedatectl
# 如果时区不对，再修改
sudo timedatectl set-timezone Asia/Shanghai

创建任务后，最好先手动运行一次验证逻辑：

hermes cron list
hermes cron run 任务名称

3 日志监控与调试方法

日志目录会跟随当前 profile 的 HERMES_HOME 变化；默认 profile 下通常位于 ~/.hermes/logs/，并可结合 hermes logs 等方式查看 6。

当你需要向社区或官方反馈问题时，也可以考虑：

hermes debug share

4 Tirith 安全模块的使用与处理

Tirith 是 Hermes 的预执行安全扫描模块。

approvals:
mode: manual # manual | smart | off

这三种模式可以直接这样理解：

manual：所有高风险命令都需要人工确认。
smart：由辅助判断做一层风险分级，低风险场景会更顺滑一些。
off：关闭安全检查，仅适合可信环境。

如果你所在版本支持命令白名单，且某些高频命令被误拦截，可以考虑把它们加入 allowlist；但具体字段名与位置，请以你当前版本的配置参考为准。

5 多平台接入进阶配置

Telegram 接入

# 基础配置
echo "TELEGRAM_BOT_TOKEN=your-bot-token" >> ~/.hermes/.env
echo "TELEGRAM_ALLOWED_USERS=your-telegram-user-id" >>
~/.hermes/.env

提醒：如果没有配置允许访问的用户范围，Bot 通常不会处于你预期的安全状态，因此上线前一定要做访问控制。

6 生产化部署 Checklist

在将 Hermes 部署到生产环境之前，建议逐项检查：

hermes doctor 无明显报错
API Key 已配置在 .env 文件中，而不是 config.yaml
已按需设置 GATEWAY_HEARTBEAT=true
已配置用户白名单（例如 TELEGRAM_ALLOWED_USERS）
审批模式已根据需求设置（approvals.mode）
已安装为 Systemd 服务，或容器设置了自动重启

动手实践：完成生产环境的稳定部署

任务目标：将 Hermes 部署为后台长期运行的服务，并接入 Telegram/Discord。

操作步骤：

在 .env 中配置好 Telegram 或 Discord 的 Token 和你的 User ID。
使用 hermes gateway install 将其注册为 Systemd 服务，或采用 Docker Compose。
启动服务：systemctl start hermes-gateway
在手机上打开 Telegram/Discord，向你的 Bot 发送消息测试。
配置一个简单的 Cron 任务，测试定时触发是否正常。

预期效果：

即使关闭 SSH 终端，Bot 依然能在 Telegram/Discord 上正常回复消息。
Cron 任务能在指定时间附近准确触发。

五、高级扩展与调试

1 MCP 外部工具链集成实战

MCP（Model Context Protocol）允许你为 Hermes 接入外部工具，例如本地文件系统、数据库、自定义 API 等。

实战：接入本地文件系统（MCP Filesystem Server）

# 安装 MCP Filesystem Server
npm install -g @modelcontextprotocol/server-filesystem

在

$HERMES

_HOME/mcp.json 中配置：

{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"/home/ubuntu/projects",
"/home/ubuntu/data"
]
}
}
}

配置后，Agent 就更有机会直接通过 MCP 工具读写指定目录，而不必每次都依赖终端命令。

2 调试高级技巧 + 中高级常见报错快速定位

常用调试工具箱：

hermes doctor # 全面健康检查，优先运行
hermes memory status # 检查记忆系统
hermes mcp status # 检查 MCP 连接
hermes debug share # 生成脱敏调试报告

动手实践：接入本地文件系统或数据库

任务目标：通过 MCP 协议，让 Agent 获得直接操作本地文件或数据库的能力。

操作步骤：

按照本章教程，安装

@modelcontextprotocol/server-filesystem

。
配置 mcp.json，将一个安全的测试目录暴露给 Agent。
运行 hermes mcp status 确认连接成功。
在对话中，让 Agent 列出该目录下的文件内容。

预期效果：

Agent 能够在不直接执行普通 shell 命令的前提下，通过 MCP 工具读取并修改指定目录下的文件。

六、疑难解答（Q&A）

Q1：为什么我告诉了 Agent 一件事，它下次还是不记得？

A：常见原因包括：会话太短，没有触发记忆整理；或者 Agent 认为这件事不值得长期保存。最直接的做法，是明确说“请把这件事写入你的长期记忆”。

Q2：Cron 定时任务没有按时触发怎么办？

A：按以下顺序排查：

运行 hermes cron list，确认任务状态是否正常。

检查 Gateway 是否在后台运行，因为定时能力通常依赖运行中的服务。

运行 timedatectl 检查服务器系统时区。

手动运行 hermes cron run 任务名，确认任务逻辑本身没有问题。

Q3：Tirith 总是拦截我正常的 bash 命令，很烦怎么办？

A：可以从三个方向处理：

临时切到更宽松的工作模式。

调整 approvals.mode，例如从 manual 变成更灵活的策略。

如果你的版本支持命令白名单，再把高频安全命令加入 allowlist。

Q4：多个 Profile 可以共享同一个 Telegram Bot 吗？

A：通常不建议。多个运行中的 Gateway 最好使用独立 Token，避免冲突。

Q5：日志文件太大了，怎么清理？

A：先看你当前版本是否已经提供轮转或管理机制；如果没有，再手动清理旧日志文件，并在清理前确认重要问题已经留档。

Q6：多个子 Agent 并发运行时，API 消耗急剧增长，怎么控制成本？

A：四个办法最有效：第一，不要一上来就开太多并发，先从 2~3 个子任务试起。第二，让子任务尽量短、上下文尽量清晰，避免反复试错。第三，如果你的版本支持对子 Agent 单独设定模型或轮次上限，可以优先让子任务使用更便宜的模型，并控制最大轮次。第四，如果你在同一 provider 下配置了 Credential Pools，可以利用多 API Key 自动轮转来缓解 429 限流，并提升并发场景下的韧性；这通常比手工换 Key 更稳。

Q7：子 Agent 为什么总是说不知道任务背景？

A：因为子 Agent 往往不是从主会话里“复制脑子”过去的，而是从新上下文开始。你必须在 context 字段中把它需要的文件路径、报错信息、项目结构、依赖版本等都明确写出来。

七、配置速查表

路径提醒：下面的示例默认按默认 profile 编写；如果你正在使用命名 Profile，请把所有 ~/.hermes 路径替换成当前 profile 的 HERMES_HOME。

生产环境参考 config.yaml

这是一份偏保守的参考写法。其中明确写出的字段，尽量只保留已在截至 v0.9.0 的官方文档或当前默认配置中可见的内容；其他随版本变化较快的项，请以你本机 config.yaml 为准。

agent:
max_turns: 90
memory:
nudge_interval: 10
provider: mem0 # 或 holographic / honcho / supermemory 等
approvals:
mode: smart
terminal:
backend: docker
timeout: 60

生产环境参考 .env

# 核心 API Key
OPENAI_API_KEY=sk-xxx
ANTHROPIC_API_KEY=sk-ant-xxx
# Gateway 配置
GATEWAY_PORT=8080
GATEWAY_HEARTBEAT=true
# 平台接入与白名单
TELEGRAM_BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
TELEGRAM_ALLOWED_USERS=123456789,987654321
# 外部记忆提供商（按需启用）
MEM0_API_KEY=m0-xxx

说明：approvals.mode: smart 在这里是面向生产使用的推荐策略示例，不代表它一定是官方默认值；如果你的环境更强调稳妥与审计，也可以继续使用 manual。如果你准备启用同 provider 的 Credential Pools，请优先按当前版本官方文档填写对应字段，不要直接照搬别人的旧配置。

本文保留了原稿的主体结构，并已按官方截至 v0.9.0 的文档与发布说明完成一轮复核修订。若你本机的实际命令输出、配置键名或插件列表与本文存在差异，请优先以当前版本官方文档、release note 和你本机 hermes doctor / config.yaml / profile 路径实际结果为准。

本文收集自网络，本文观点不代表发现AI立场，如若转载，请联系原作者；如有侵权，请联系编辑删除。