Hermes Agent 功能详解与最佳实践

一份纯功能视角的深度解读。不讲代码实现,只讲每个系统做什么、为什么这样设计、怎么用好它。面向想成为 Hermes Agent 最佳使用者的你。


0. Hermes Agent 是什么

Hermes Agent 是由 Nous Research 构建的开源自托管 AI Agent。它和 Claude Code、Cursor、Codex 的根本区别在于:那些是”会话式编程助手”,Hermes 是一个”长期运行的自主助手”。

Hermes 不锁定在任何 IDE 里,也不绑定你的笔记本电脑。你可以把它跑在 $5 的 VPS 上、Docker 容器里、甚至云端 Serverless 环境(Modal / Daytona / Vercel Sandbox)——它持续运行,并从 Telegram、Discord、Slack、微信、飞书、钉钉、WhatsApp、Signal 等 20+ 平台接收你的消息。

但 Hermes 的核心竞争力不只在”多平台”。它有四个 Claude Code 不具备的关键能力:

一、闭环学习系统。 Hermes 在每次完成复杂任务后,能自动判断”这个流程值得记住吗?“,如果值得,就把它沉淀为一个可复用的 Skill。下次遇到类似任务,Skill 自动激活。过程中如果发现更好的做法,Skill 会自我更新。这是 Hermes 和所有其他 Agent 最大的区别——它不只是”会做”,它是”会越做越好”。

二、跨会话持久记忆。 Hermes 不仅记住你说过什么(MEMORY.md),还通过 Honcho 辩证式用户建模构建对”你是谁”的深度理解。FTS5 全文搜索让它能找到几周前的对话细节。记忆系统和会话搜索是两个互补的机制:记忆是”当前上下文里总是有的关键事实”,会话搜索是”需要查一下我们三周前讨论过什么”。

三、自主沉淀技能。 其他 Agent 靠人手动写 Skill 或从市场下载。Hermes 的 Agent 自己做这件事——skill_manage 工具让 Agent 在完成任务后自行判断是否有可复用的流程、创建 Skill、并在后续使用中改进。这形成了一个”做 → 学 → 下次做得更好”的正反馈循环。

四、长期运行与定时自动化。 Hermes 可以在后台运行数月。内置 Cron 调度器让你用自然语言安排定时任务——“每天早上 9 点检查 CI 流水线”、“每周五下午生成进度报告”。任务结果可以通过消息推送到任何已连接的平台。

Nous Research 官方文档的定位很准确:

“The self-improving AI agent. It’s the only agent with a built-in learning loop — it creates skills from experience, improves them during use, nudges itself to persist knowledge, searches its own past conversations, and builds a deepening model of who you are across sessions.”

会自我改进的 AI 智能体。它是唯一内置了学习闭环的智能体——能从经验中提炼技能、在使用过程中持续改进这些技能、主动把知识沉淀下来、检索自己过去的对话,并在一次次会话中建立起对你这个人不断深入的理解。


1. 核心架构:Hermes 的”内脏”长什么样

Hermes 的架构遵循一个明确的设计原则:平台无关的核心 + 平台特定的入口。

1.1 总体布局

入口层(多个可互换的入口)
├── CLI (hermes)                        ← 你的终端
├── Gateway (Telegram/Discord/微信...)   ← 消息平台
├── ACP Adapter (VS Code/Zed/JetBrains) ← 编辑器内
├── Batch Runner                        ← 批量轨迹生成
└── API Server                          ← HTTP API

        ↓ 全部汇聚到同一个核心 ↓

AIAgent (run_agent.py)                  ← 唯一的 Agent 引擎
    ├── Prompt Builder     ← 组装系统提示词
    ├── Provider Resolver  ← 选择模型和 API
    ├── Tool Dispatch      ← 70+ 工具的分发和执行
    ├── Context Engine     ← 上下文压缩和缓存
    └── Session Storage    ← SQLite + FTS5 持久化

关键点:CLI 对话和 Telegram 消息经过的是完全相同的 Agent 核心。 区别仅在入口层——CLI 给你一个终端界面,Gateway 把消息从平台接进来再推回去。Agent 本身不关心消息从哪来。

1.2 数据流(以一次对话为例)

CLI 会话:用户输入 → Agent Loop 启动 → Prompt Builder 组装系统提示词(注入 SOUL.md 人格 + MEMORY.md 记忆 + Skills 目录 + 项目上下文) → Provider Resolver 选择模型 → API 调用 → 模型返回 tool_use 或文本 → 如果需要工具,Tool Dispatch 执行 → 结果返回给模型 → 循环 → 最终响应 → 显示 → 存入 SessionDB。

Gateway 消息:平台事件(如 Telegram 消息) → 平台适配器 → GatewayRunner 验证用户 → 解析会话 → 创建 AIAgent → 对话 → 结果通过适配器推送回平台。

Cron 作业:调度器到点触发 → 创建全新 AIAgent(无历史会话) → 注入作业描述和附带的 Skill → 运行 → 结果推送到目标平台 → 更新作业状态。

1.3 设计原则(直接影响你的使用体验)

理解这些原则能帮你更好地判断 Hermes 为什么在某些时候表现得”和预期不同”:

  • 提示词稳定性:系统提示词在会话中途不会改变。你在会话中改了 MEMORY.md,变化在下一次会话才生效。这是故意的——为了不破坏 LLM 的前缀缓存。
  • 可观测执行:每个工具调用你都能看到(CLI 有 spinner,Gateway 有状态消息)。不存在 Claude Code 那种”背后跑了个子代理你完全不知道”的情况。
  • 可中断:API 调用和工具执行可以中途取消。
  • 松耦合:MCP、插件、外部记忆提供者都是可选的——不配置就不加载,零开销。

2. Agent Loop:最小的那个循环

Hermes 的 Agent Loop 和 learn-claude-code教程 里教的循环本质上一样——都是 while stop_reason == "tool_use"。但 Hermes 的实现有几个自己的特点:

支持三种 API 模式。 不同模型提供商用不同的 API 格式。Hermes 的 runtime_provider.py 统一抽象了三种:OpenAI 的 chat_completions、OpenAI 的新 codex_responses、Anthropic 的 messages。这让你能在 Claude、GPT、GLM、Kimi、MiniMax、DeepSeek 之间自由切换——对 Agent 来说,下层是透明的。

自动重试和 fallback。 如果一个 API 调用失败(网络超时、模型不可用),Hermes 会自动重试,并且在重试耗尽后可能降级到备用模型。这是 s11 Error Recovery 的生产级实现。

压缩不丢关键信息。 当上下文接近模型的有效注意力上限,Hermes 的 Context Compressor 会对中间的对话轮次做摘要压缩。和 learn-claude-code s08 的四层压缩理念一致。

会话血统追踪。 每次压缩后产生的”子会话”和原”父会话”保持关联。你可以在会话列表中看到完整的”谁从谁衍生”关系链。


3. 工具系统:70+ 工具、28 个工具集、7 个终端后端

Hermes 的工具系统是它和所有其他 Agent 拉开差距的地方之一。不是因为它工具多——而是因为它的工具组织方式和可配置粒度。

3.1 工具集(Toolsets):按需启用的模块化

70+ 个工具被组织成 28 个工具集(Toolset)。你可以按平台、按场景启用不同的工具组合。比如:

  • Telegram 上只用 web, terminal, file, memory——不给浏览器和代码执行权限
  • CLI 上用全功能——terminal, file, web, browser, vision, image_gen, tts, code_execution
  • Cron 定时任务只给 terminal, web, send_message

这是通过 hermes tools 交互式配置完成的,不需要编辑配置文件。

3.2 工具分类一览

类别代表工具说明
Webweb_search, web_extract搜索网页并提取正文内容
X (Twitter) 搜索x_search搜索 X 上的帖子和线程,需要 xAI 凭证
终端与文件terminal, read_file, patch执行命令、操作文件。patch 是 Hermes 的 diff 编辑工具
浏览器browser_navigate, browser_snapshot, browser_vision自动化浏览器操作——导航、截图、视觉分析
多媒体vision_analyze, image_generate, video_generate, video_analyze, text_to_speech图像理解、AI 生图、视频生成和分析、文字转语音
Agent 编排todo, clarify, execute_code, delegate_task任务规划、主动澄清、代码执行、子代理委派
记忆与召回memory, session_search持久记忆管理和跨会话搜索
自动化与投递cronjob, send_message定时任务管理和消息推送
集成ha_* (Home Assistant), MCP 服务器工具智能家居控制、外部 MCP 工具

3.3 七个终端后端:你的 Agent 跑在哪

这是 Hermes 作为一个”长期运行的自主助手”的关键基础设施。terminal 工具不一定要在本地执行命令——它支持七种后端:

后端执行位置典型用途
local(默认)你的机器开发、受信任任务
docker隔离容器,一个持续生命周期安全沙箱,pip install 后整个会话有效
ssh远程服务器推荐安全方案——Agent 改不了自己的代码
singularityHPC 集群容器科研计算、集群环境
modal云端 Serverless弹性扩展,近乎零空闲成本
daytona云端持久工作区远程开发环境,空闲休眠按需唤醒
vercel_sandboxVercel 云端微 VM快照文件系统持久化

SSH 后端是最安全的选择。 Agent 在远程服务器上执行一切——它物理上无法修改运行在本地机器上的 Hermes 代码。即使它想”升级自己”,也只能在远端操作。

Docker 后端的持久化是一个容易被忽略的特性。 默认配置下,Docker 容器是持续运行的——pip install 装过的包、cd 切过的目录、创建过的文件,在整个 Hermes 进程生命周期内都存在。这意味着 Agent 可以在多次对话中积累环境状态,而不需要每轮重新配置。

3.4 后台进程管理

terminal 工具支持 background=true 参数。Agent 可以启动一个进程(比如 pytest -v tests/),拿到一个 session_id,然后通过 process 工具查询状态、等待完成、读取输出、发送输入或杀掉进程。PTY 模式(pty=true)让 Agent 可以和交互式 CLI 工具(如 Codex、Claude Code)协作——Hermes 控制着终端,Codex 在里面运行。

3.5 Sudo 支持

如果命令需要 sudo,Hermes 会提示你输入密码(会话内缓存),或者你可以提前在 ~/.hermes/.env 里设置 SUDO_PASSWORD。


4. Skill 系统:Hermes 的”肌肉记忆”

这是 Hermes 最独特的功能,没有之一。它是 Hermes 和其他所有 Agent 之间最根本的差异。

4.1 Skill 是什么

Skill 是一份 Markdown 文档(SKILL.md),存在 ~/.hermes/skills/ 下。它告诉 Agent:什么场景下该触发这个技能、该怎么做、要注意什么坑、怎么验证做对了。Skill 兼容 agentskills.io 开放标准——你写的 Skill 可以跨 Agent 产品复用。

4.2 渐进式公开:token 高效的核心设计

Skill 采用三层加载模式:

  • Level 0:Agent 启动时,只加载”技能目录”——列出所有可用 Skill 的名字和一句话描述。约 3K token。
  • Level 1:Agent 判断”我需要用某个 Skill”,Harness 才把该 Skill 的完整内容加载进来。token 按需消费。
  • Level 2:如果 Skill 引用了外部参考文件,Agent 可以进一步按路径加载特定文件。

这意味着你装 50 个 Skill,不会在每次对话开头浪费 50 个 Skill 的 token。这和 MCP 形成鲜明对比——一个 Playwright MCP server 的工具定义占 13K-18K token,不管你用不用都加载。

4.3 Agent 自主创建、更新、删除 Skill

这是 Hermes 闭环学习的核心。skill_manage 工具让 Agent 拥有”过程记忆”——完成一个非平凡的工作流后,Agent 自主把这个流程保存为一个 Skill。

关键机制:

  • 创建:Agent 在任务完成后评估”这个流程是新的吗?可复用吗?“,如果是,自动创建 Skill
  • 更新(patch):下次执行同一 Skill 时,如果发现更好的做法,更新 Skill 内容
  • 删除:如果一个 Skill 长期没用或已被更好的替代,Agent 清理它

这意味着你不需要手动维护 Skill。Agent 自己在用、自己在改、自己在淘汰。你用得越多,Hermes 越懂你的工作流。

4.4 条件激活(Fallback Skills)

Skill 可以根据当前工具集的状态自动显示或隐藏自己:

  • fallback_for_toolsets: [web]:当 web 工具集不可用时,这个 Skill 才出现。内置的 DuckDuckGo 搜索 Skill 就用这个——你有 Firecrawl API key 时它不出现(Agent 直接用它内置的 web_search),没 key 时才作为降级方案露出
  • requires_toolsets: [terminal]:这个 Skill 只在 terminal 工具集可用时才出现

这意味着 Skill 不只是”写了就有”——它们是上下文感知的。

4.5 Skill Bundle:一次加载多个 Skill

如果你发现某个任务类型总是需要同时用三个 Skill(比如”后端特性开发”总是需要代码审查 + TDD + PR 工作流),你可以创建一个 Bundle YAML:

name: backend-dev
description: 后端特性开发:审查、测试、PR
skills:
  - github-code-review
  - test-driven-development
  - github-pr-workflow

然后 /backend-dev 一条命令,三个 Skill 全部加载。Bundle 只是一个 YAML 别名——不安装 Skill 本身,Skill 必须已经存在。

4.6 外部 Skill 目录

如果你有一组多个 AI 工具共用的 Skill(比如放在 ~/.agents/skills/ 下),Hermes 可以直接扫描。在 config.yaml 里配置 skills.external_dirs,外部 Skill 就和本地 Skill 一样出现在索引、命令补全和 Agent 感知中。本地的同名 Skill 优先级更高(shadow)。

4.7 Skill 的安全设计

Skill 声明缺失的环境变量时,Hermes 在 CLI 中安全地提示你输入,消息平台永远不会在聊天中要求密钥——它让你本地用 hermes setup 配置。

required_environment_variables 声明的变量在 Skill 执行时自动传递给 execute_code 和 terminal 沙箱。Skill 的脚本可以直接读 $API_KEY,不需要你手动 export。


5. Memory 系统:Hermes 的”长期记忆”

Hermes 的记忆系统不是简单的”把所有对话存下来”——它是一个有精心设计的容量限制、自动管理和跨会话持久化的双层系统。

5.1 两层记忆文件

文件用途容量限制
MEMORY.mdAgent 自己的笔记——环境事实、项目约定、学会的东西2,200 字符(~800 token)
USER.md你的画像——偏好、沟通风格、身份信息1,375 字符(~500 token)

两者都存储在 ~/.hermes/memories/,在每次会话开始时作为冻结快照被注入到系统提示词中。

5.2 为什么是”冻结快照”

会话开始时系统提示词被固化为一个前缀。在会话中途你对 MEMORY.md 的修改不会在当前会话中生效——这是故意的。原因:LLM 的前缀缓存机制——如果系统提示词在中途变了,缓存作废,后续每次 LLM 调用都要重新计算整个提示词,成本翻倍。

5.3 Agent 如何管理记忆

Agent 使用 memory 工具有三个操作:

  • add:添加新记忆。如果已经存在完全相同的条目,自动跳过(防重复)。
  • replace:替换某条记忆。使用”最少文本匹配”——你不需要给完整的旧文本,给一段能唯一定位到目标条目的子串即可。
  • remove:删除不再相关的条目。同样用最少文本匹配。

Agent 会在”值得记住”的时刻自动操作——不需要你告诉它。触发条件包括:用户表达了偏好、发现了环境配置的”坑”、完成了一个项目约定、被你纠正了某个错误。

5.4 容量管理:当记忆满了怎么办

Agent 被设计成主动管理容量。当记忆超过 80% 容量(系统提示词里会显示百分比),Agent 应该先合并再添加——把三条”项目用 X”的散落条目合并成一条综合描述,然后用 replace 替代旧条目。如果满了还尝试添加,工具会返回错误让 Agent 重新规划。

5.5 记忆安全扫描

记忆条目在被写入前会经过注入和泄露模式扫描。匹配到提示词注入、凭证泄露、SSH 后门、隐形 Unicode 字符的内容会被拦截。

5.6 会话搜索(补充机制)

记忆是”总是需要知道的关键事实”,但有些内容不需要一直在上下文里——你需要的时候能找到就行。这就是 session_search 工具的价值:

  • 所有 CLI 和 Gateway 会话存在 SQLite 数据库中,带 FTS5 全文搜索
  • Agent 可以直接搜索几周前的对话细节
  • 不需要 LLM 摘要——直接返回数据库中的原始消息
  • 零 token 成本(直到你发起搜索)

记忆 ~1,300 token 固定成本,每次会话都加载。会话搜索零固定成本,按需消耗。 哪个该放记忆?——“我需要在每次对话中都被提醒”的。哪个该靠搜索?——“我知道存在但不需要每次看到”的。

5.7 外部记忆提供者

MEMORY.md / USER.md 是最基础的内置记忆。对于更深度、更持久的需求,Hermes 内置了 8 个外部记忆提供者插件——包括 Honcho(辩证式用户建模,构建对你的深度理解画像)、Mem0、Holographic 等。外部提供者和内置记忆并行运行(不会替代),增加语义搜索、知识图谱、自动事实提取等能力。


6. 消息网关:20+ 平台,统一路由

6.1 它是怎么工作的

Gateway 是一个长期运行的进程(hermes gateway start),接受来自 20+ 个平台的消息,通过一个统一的消息循环分发给 AIAgent 处理,然后将结果通过对应的平台适配器推送回去。

每个平台适配器只做一件事:把自己平台的格式翻译成 Hermes 内部的 MessageEvent 格式。Telegram 的文本消息、Discord 的斜杠命令、微信的语音转录——在进入 AIAgent 之前都变成了同一个内部格式。Agent 不关心消息从哪来。

6.2 跨平台连续性

同一个用户可以同时从多个平台和同一个 Hermes 实例对话——会话是跨平台连续的。你在 Telegram 上发的消息,切换到 Discord 继续,Agent 看到的是同一个会话历史。

6.3 支持的平台

Telegram、Discord、Slack、WhatsApp、Signal、飞书、企业微信、微信(个人号)、钉钉、QQ、Matrix、Mattermost、Email、SMS、Home Assistant、Webhook 等。中文社区特别关注微信、飞书、企业微信、钉钉和 QQ 的支持——这在 Global-first 的 Agent 产品中是比较少见的。


7. Cron 自动化:Agent 自己安排自己的事

7.1 不是 shell 任务——是 Agent 任务

Hermes 的 Cron 的独特之处在于:你安排的不是 shell 命令,而是一个完整的 Agent 任务。到达触发时间后,Hermes 创建一个全新的 AIAgent 实例(不带任何对话历史),注入你写的任务描述,Agent 自主完成,然后把结果推送给你。

这意味着你可以用自然语言安排:“每天早上 9 点检查 GitHub Issues 的更新,汇总成一个日报发到 Telegram。“

7.2 支持什么

  • 多种调度格式(cron 表达式 + 自然语言解析)
  • 创建/列出/更新/暂停/恢复/运行/删除作业
  • 作业可以附带 Skill——比如”这个作业应该用 github-issue-summary 这个 Skill”
  • 结果可以投递到任何平台

8. 安全模型:信任但隔离

8.1 容器隔离

Docker、Singularity、Modal、Daytona、Vercel Sandbox 五个容器后端都启了安全加固——只读根文件系统、capability 全部丢弃、no new privileges、PID 限制、完整 namespace 隔离。Agent 在容器里想搞破坏的难度大幅提高。

8.2 命令审批

危险命令(rm -rf /、sudo、mkfs 等)在被执行前触发审批。CLI 上弹提示,消息平台上会暂停等待你的 y/n。

8.3 DM 配对

消息平台的 Gateway 支持”DM 配对”机制——你的账号和你 Agent 的账号绑定。Agent 只回复已配对的用户。对于多用户场景(如团队共用),可以配置白名单。

8.4 SSH 后端:物理隔离

如果你把 terminal.backend 设为 ssh,Agent 所有的终端操作都在远程服务器上执行。它物理上无法修改本地机器上 Hermes 自己的代码。这是最彻底的安全方案——Agent 自己跑在自己改造不了的环境里。


9. 人格与上下文:让 Agent 成为”你的人”

9.1 SOUL.md:Agent 的人格文件

Hermes 支持通过 SOUL.md 定义 Agent 的基调和行为风格。它被注入到每次会话的系统提示词中,在 Personality 部分。你可以定义它的口吻、专业领域、做事风格、边界。

9.2 上下文文件

两个层级:

  • 全局上下文:~/.hermes/CLAUDE.md(或者 AGENTS.md)——所有项目通用的背景知识
  • 项目上下文:当前工作目录下的 .hermes.md 或 AGENTS.md——特定项目的约定、架构概述

这些文件在 Prompt Builder 组装系统提示词时自动注入。你会发现这个设计和 Claude Code 的 CLAUDE.md 机制几乎一样——事实上它们共享同一个约定。

9.3 /personality 命令

你可以随时切换人格:/personality [name]。CLI 和消息平台都支持。


10. 与 OpenClaw 的关系:迁移只需一条命令

如果你之前用的是 OpenClaw(小龙虾),Hermes 官方提供了完整的迁移路径。hermes claw migrate 自动检测 ~/.openclaw 并导入:

  • SOUL.md、MEMORY.md、USER.md
  • 用户创建的 Skill
  • 命令审批规则
  • 消息平台配置
  • API 密钥(仅限白名单内的安全密钥)
  • TTS 资产

首次运行 hermes setup 时也会自动检测并提示迁移。这意味着你不需要”重头开始”——旧的经验和配置可以直接带到 Hermes。

关于两者的核心差异,见你 wiki 里的早期对比资料 Hermes Agent 和 OpenClaw。总结:Hermes 在 Skill 自主沉淀、安全性设计、安装门槛、Token 消耗优化上都有明显改进。


11. 成为最好的 Hermes 使用者:22 条实践建议

以下是基于官方文档、架构设计和社区经验的总结。

安装与配置

  1. 用 WSL2(Windows 用户)或 Linux。原生 Windows 支持尚在早期阶段。
  2. 安装后第一件事:hermes setup 完成交互式配置。
  3. 如果你不想分别申请模型、搜索、生图、TTS 的多个 API key,考虑 Nous Portal——一条 hermes setup --portal 覆盖全部。
  4. 国产模型用户:Hermes 原生支持 GLM、Kimi、MiniMax、DeepSeek、Qwen、小米 MiMo。用 hermes model 切换。

工具与安全

  1. 最重要的安全配置:把 terminal.backend 从 local 改成 ssh。Agent 在远端执行,无法改自己的代码。
  2. 按平台定制工具集:CLI 上用全功能,Telegram 上只给 web + terminal + file + memory。
  3. container_persistent: true 保持 Docker 容器的状态跨会话——你装过的包下次还在。

Skill 管理

  1. 不需要手动写太多 Skill。用好几个内置的高质量 Skill(plan、github-pr-workflow、axolotl),让 Agent 在工作中自己创建剩下的。
  2. 定期检查 ~/.hermes/skills/——Agent 创建的 Skill 可能比你手写的更好,因为它是从实际执行中沉淀的。
  3. 如果你在多个 AI 工具之间共享 Skill,配置 skills.external_dirs。
  4. 用 Bundle 组织高频 Skill 组合——/backend-dev 比三个 /skill 快得多。

记忆管理

  1. 让 Agent 自己管理记忆——不主动告诉它”记住这个”,只是当它犯错时纠正它,它会记下来。
  2. 当 Agent 在任务中表现好时,明确告诉它”这个方法很好”——这会被它记入 MEMORY.md。
  3. 如果记忆开始膨胀,Agent 会自动合并。你不需要手动编辑 ~/.hermes/memories/MEMORY.md。
  4. 区分什么该放记忆 vs 什么该靠会话搜索:每次对话都需要知道的 → 记忆;偶尔需要回顾的 → 搜索。

自动化

  1. 从最简单的 Cron 开始——“每天早上 9 点检查 GitHub”。跑通一个,再复杂化。
  2. Cron 作业可以附带 Skill——让定时任务利用你已经沉淀好的工作流。

多平台

  1. 不要在所有平台上给相同的权限。Telegram 是移动端快速交互,少给工具。CLI 是深度工作,给全量。
  2. 跨平台会话的连续性意味着你可以在手机上开始一个任务,回到电脑上继续。

日常使用

  1. /compress 在长会话中是一个有用的命令——主动压缩上下文,帮助 Agent 保持清醒。
  2. /retry 和 /undo 允许你纠正 Agent 的错误,这是高频使用的命令。
  3. /insights 查看 Agent 的使用统计——多少 token、哪种工具用得最多、什么时候启动的。

参考来源

来源说明
Nous Research Hermes Agent GitHub官方 README + 完整代码库
hermes-agent.nousresearch.com官方文档(Skills、Memory、Tools、Architecture)
hermesagent.org.cn中文社区文档与安装指南
wiki 已有内容早期 B 站视频的 Hermes 讲解 vs OpenClaw 对比