--- title: "Hermes Agent 从中级到高级进阶指南" source: "https://x.com/BTCqzy1/status/2044259795499450414" author: - "[[@BTCqzy1]]" published: 2026-04-15 created: 2026-04-24 description: "本指南默认你已完成 Hermes 的基础安装与配置,正文不再重复安装步骤。我们将直接进入进阶核心内容:记忆系统、技能自进化、多 Agent 协作、生产化部署与高级调试。目录一、记忆系统进阶 1 Hermes 记忆系统的整体架构详解 2 Agent-curated memory..." tags: - "clippings" --- ![图像](https://pbs.twimg.com/media/HF6qqtKasAIjmaS?format=jpg&name=large) 本指南默认你已完成 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**。 ![图像](https://pbs.twimg.com/media/HF6maF2asAIswJ6?format=jpg&name=large) 这样更容易让 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 模板(直接复制到你的项目根目录) ```text # 项目规范: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,找到或添加类似配置: ```text 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 的核心优势是自动提取与同步长期记忆,适合不想手动设计太多记忆流程的用户。 ```text # 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 往往是一个更偏本地化的选择。 ```text # 激活 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: 请整理你的记忆,删除过时条目,合并相关条目,腾出空间。 手动清理也可以直接编辑文件: ```text nano ~/.hermes/memories/MEMORY.md ``` nano ~/.hermes/memories/MEMORY.md 如果你的版本支持相关记忆维护命令,也可以优先使用官方提供的清理或压缩方式。 **8 记忆与技能的联动机制** 当 Agent 在 MEMORY.md 中多次记录了类似工作流,例如“每次部署前都要执行 A、B、C 三步”,这往往意味着:这个流程更适合沉淀为一个 Skill,而不是继续零散地塞在记忆里。 你可以主动引导: **我注意到你已经记住了我们的部署流程。请把这个流程创建为一个可复用的 Skill,名字叫 deploy-workflow,这样以后可以直接复用。** 动手实践:构建你的专属记忆系统 任务目标: 配置好基础的记忆文件,并测试 Agent 的记忆能力。 操作步骤: 1. 复制本章的 SOUL.md 模板到 ~/.hermes/SOUL.md,并根据你的实际情况修改。 2. 在你的常用项目目录下创建一个 AGENTS.md。 3. 修改 config.yaml,先将 nudge\_interval 设置为 5 进行测试。 4. 开启一个新的对话,告诉 Agent 一条特定偏好,例如:“以后所有的 Python 脚本都保存在 /tmp/scripts 目录下。” 5. 进行 5 轮以上的对话,观察是否触发记忆整理。 预期效果: - 运行 cat ~/.hermes/memories/MEMORY.md,能看到你刚才告诉它的偏好已经被记录下来。 - 开启一个全新的会话,让 Agent 写一个 Python 脚本,它更有可能自动遵循先前记录的偏好。 ![图像](https://pbs.twimg.com/media/HF6nSTZbsAAugQu?format=jpg&name=large) ## 二、技能自进化 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 的触发条件与流程** 1. 常见触发条件通常包括以下场景: 2. 完成了一个相对复杂的任务 3. 遇到了错误或死路,后来找到了正确路径 4. 用户纠正了它的做法 5. 发现了一个值得复用的非平凡工作流 主动引导 Agent 创建 Skill: **我们刚才完成的这个数据处理流程很有价值,请把它保存为一个 Skill,名字叫 data-pipeline,放在 devops 分类下,确保包含触发条件、操作步骤、注意事项和验证方法。** 3 技能质量控制与优化方法 1. 判断一个 Skill 质量好不好的标准: 2. 触发条件清晰:Agent 能准确判断什么时候该用它 3. 步骤可执行:每一步都有明确操作,而不是空泛描述 4. 有验证方法:执行完后能判断是否成功 5. 有注意事项:记录了踩过的坑 手动优化 Skill 时,通常建议让 Agent 做定点修改,而不是整篇重写。例如: **请更新 stock-daily-report 这个 Skill,在注意事项里补充一条:“周五收盘后数据可能延迟到周六早上才完整。”** 4 技能退化与重复问题的解决思路 技能退化的表现通常包括: - 描述越来越模糊,触发条件越来越宽泛 - 多个 Skill 做的是同一件事,但写法不同 **解决方案:让 Agent 做技能审计。** 1. 请审查你所有的 Skills,找出: 2. 功能重复的技能(合并它们) 3. 描述模糊、触发条件不清晰的技能(重写它们) 给我一份审计报告,然后等我确认后再执行修改。步骤已经过时的技能(更新它们) **5 Skill 与记忆系统的联动机制** 在 SKILL.md 中,你可以引导 Agent 在执行技能前先查看记忆: ```text ## 操作流程 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 学习并固化一个你常用的工作流。 **操作步骤**: 1. 找一个你经常做的重复性任务,例如:检查系统磁盘空间、清理 Docker 悬空镜像,并输出一份简报。 2. 在对话中,一步步指导 Agent 完成这个任务,纠正它的错误,直到执行稳定。 3. 发送指令:“请把刚才的清理流程保存为一个 Skill,命名为 docker-cleanup,包含触发条件、具体执行命令和验证步骤。” 4. 运行 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): 这个任务可以并行处理: 1. 子任务 A:抓取 A 股今日涨停板数据 2. 子任务 B:分析北向资金流向 3. 子任务 C:生成市场情绪指数 请派生 3 个子 Agent 并行完成这三个子任务,然后汇总结果。 **子 Agent 的关键限制(必读)** 子 Agent 往往从一个新的会话上下文开始,它并不会天然继承主 Agent 的完整历史。因此,你必须在 context 里把子 Agent 所需的背景信息传完整: ```text 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// 这类路径。 创建 Profile 的三种常见方式: ```text # 方式一:全新 Profile(空白) hermes profile create mybot # 方式二:克隆配置(复用 API Key 和模型,但记忆和会话独立) hermes profile create work --clone # 方式三:完整克隆(包含记忆、会话、技能等更多状态) hermes profile create backup --clone-all ``` 运行多个独立 Agent: ```text # 终端 1:运行编码助手 coder chat # 终端 2:运行投研助手(独立的记忆和技能) research chat ``` **3 子 Agent 的独立记忆与技能隔离** 每个 Profile 的 memories/、skills/、sessions/ 和 logs/ 目录通常都是独立的,不会互相读写。 如果你希望多个 Profile 共享同一套技能,可以考虑使用外部技能目录;但具体字段名和配置方式,最好以你当前版本的配置参考为准。一个常见思路如下: ```text skills: external_dirs: - ~/.hermes/shared-skills ``` **4 主 Agent 协调多个子 Agent 的技巧** 明确角色分工,通常是最有效的方法。你可以在 SOUL.md 或 AGENTS.md 中定义: ```text ## 多 Agent 协作规范 - Planner Agent:负责任务分解和进度追踪,不直接执行 - Executor Agent:负责具体的数据获取和处理,不做决策 - Reviewer Agent:负责质量检查和结果验证,不做修改 ``` **5 多 Agent 资源分配与冲突避免** Bot Token 冲突保护 如果两个 Profile 意外使用了同一个 Bot Token,运行中的 Gateway 往往会产生冲突。因此,最好在各自的 .env 中配置不同的 Token。 端口冲突 如果你在本地运行多个 Hermes 实例,最好让它们使用不同端口。例如: ```text # Profile A GATEWAY_PORT=8080 # Profile B GATEWAY_PORT=8081 ``` 动手实践:配置双 Agent 协作工作流 任务目标: 创建两个独立的 Profile,分别承担不同角色,互不干扰。 操作步骤: 1. 运行 hermes profile create coder --clone 创建一个专门写代码的 Agent。 2. 运行 hermes profile create reviewer --clone 创建一个专门做代码审查的 Agent。 3. 分别编辑它们的 SOUL.md,赋予不同角色设定。 4. 让 coder 写一段有 Bug 的代码并保存到文件。 5. 切换到 reviewer,让它读取该文件并提出修改建议。 预期效果: - 两个 Agent 能独立运行,且 reviewer 的记忆中不会混入 coder 的工作流。 ## 四、生产化部署 **1 Gateway 长期后台运行的多种方式** 方式一:Systemd(Linux 生产环境首选) ```text # 安装为 Systemd 服务 hermes gateway install # 查看服务状态 systemctl status hermes-gateway # 如果你使用命名 Profile,服务名可能 会带上 profile 后缀,以实际安装输出为准 journalctl -u hermes-gateway -f ``` 方式二:Docker Compose 方式(更适合多 Profile 部署) ```text 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 机制(防止静默失败) ```text # 在 ~/.hermes/.env 中添加 echo "GATEWAY_HEARTBEAT=true" >> ~/.hermes/.env ``` 定时任务(Cron) ```text # 示例:工作日早上 8:30 生成日报 hermes cron add "30 8 * * 1-5" " 生成今日 A 股市场日报并发送到 Telegram" ``` 时区是最容易踩的坑之一。 Hermes 的 Cron 通常使用服务器系统时区。如果你的服务器时区与预期不一致,定时任务就会在错误时间运行。 ```text # 先确认服务器系统时区 timedatectl # 如果时区不对,再修改 sudo timedatectl set-timezone Asia/Shanghai ``` 创建任务后,最好先手动运行一次验证逻辑: ```text hermes cron list hermes cron run 任务名称 ``` **3 日志监控与调试方法** 日志目录会跟随当前 profile 的 HERMES\_HOME 变化;默认 profile 下通常位于 ~/.hermes/logs/,并可结合 hermes logs 等方式查看 6。 当你需要向社区或官方反馈问题时,也可以考虑: ```text hermes debug share ``` **4 Tirith 安全模块的使用与处理** Tirith 是 Hermes 的预执行安全扫描模块。 ```text approvals: mode: manual # manual | smart | off ``` 这三种模式可以直接这样理解: - manual:所有高风险命令都需要人工确认。 - smart:由辅助判断做一层风险分级,低风险场景会更顺滑一些。 - off:关闭安全检查,仅适合可信环境。 如果你所在版本支持命令白名单,且某些高频命令被误拦截,可以考虑把它们加入 allowlist;但具体字段名与位置,请以你当前版本的配置参考为准。 **5 多平台接入进阶配置** Telegram 接入 ```text # 基础配置 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。 操作步骤: 1. 在 .env 中配置好 Telegram 或 Discord 的 Token 和你的 User ID。 2. 使用 hermes gateway install 将其注册为 Systemd 服务,或采用 Docker Compose。 3. 启动服务:systemctl start hermes-gateway 4. 在手机上打开 Telegram/Discord,向你的 Bot 发送消息测试。 5. 配置一个简单的 Cron 任务,测试定时触发是否正常。 预期效果: - 即使关闭 SSH 终端,Bot 依然能在 Telegram/Discord 上正常回复消息。 - Cron 任务能在指定时间附近准确触发。 ## 五、高级扩展与调试 **1 MCP 外部工具链集成实战** MCP(Model Context Protocol)允许你为 Hermes 接入外部工具,例如本地文件系统、数据库、自定义 API 等。 实战:接入本地文件系统(MCP Filesystem Server) ```text # 安装 MCP Filesystem Server npm install -g @modelcontextprotocol/server-filesystem ``` 在 [$HERMES](https://x.com/search?q=%24HERMES&src=cashtag_click)\_HOME/mcp.json 中配置: ```text { "mcpServers": { "filesystem": { "command": "npx", "args": [ "-y", "@modelcontextprotocol/server-filesystem", "/home/ubuntu/projects", "/home/ubuntu/data" ] } } } ``` 配置后,Agent 就更有机会直接通过 MCP 工具读写指定目录,而不必每次都依赖终端命令。 **2 调试高级技巧 + 中高级常见报错快速定位** 常用调试工具箱: ```text hermes doctor # 全面健康检查,优先运行 hermes memory status # 检查记忆系统 hermes mcp status # 检查 MCP 连接 hermes debug share # 生成脱敏调试报告 ``` 动手实践:接入本地文件系统或数据库 任务目标: 通过 MCP 协议,让 Agent 获得直接操作本地文件或数据库的能力。 操作步骤: 1. 按照本章教程,安装 [@modelcontextprotocol/server-filesystem](https://x.com/@modelcontextprotocol/server-filesystem)。 2. 配置 mcp.json,将一个安全的测试目录暴露给 Agent。 3. 运行 hermes mcp status 确认连接成功。 4. 在对话中,让 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 为准。 ```text agent: max_turns: 90 memory: nudge_interval: 10 provider: mem0 # 或 holographic / honcho / supermemory 等 approvals: mode: smart terminal: backend: docker timeout: 60 ``` 生产环境参考 .env ```text # 核心 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 路径实际结果为准。