Hermes Agent Loop 执行流程拆解：回调机制、工具注册与跨平台部署实践

1. 从一次回调超时说起：Hermes Agent Loop 到底在循环什么

第一次接触 Hermes Agent 的人，十有八九会被它的执行流程绕晕。你给它一个任务，它没有立刻返回结果，而是先思考、再调用工具、拿到工具结果、继续思考、再调用工具……整个过程像一条不断自我延伸的链条。很多人第一次调试时都会遇到同一个现象：明明工具函数已经执行完了，日志里却迟迟等不到下一步动作，最后抛出一个回调超时。

这个现象背后，就是Agent Loop（智能体执行循环）在起作用。Hermes Agent 不是"一问一答"式的模型调用，而是一个带状态、带工具、带回调的执行引擎。它的核心循环可以粗略概括为：接收任务 → 规划下一步 → 选择并调用工具 → 观察工具返回 → 更新上下文 → 判断是否结束 → 未结束则回到规划。这个循环会一直转，直到模型认为任务完成，或者触发终止条件。

理解这个循环，对三类人特别重要。第一类是应用开发者，你要把 Hermes Agent 接进自己的产品，就必须知道每一步的钩子在哪里、回调什么时候触发、状态存在哪里。第二类是运维和部署人员，你要在 Windows、Ubuntu 或者桌面版上把它跑起来，就得明白它依赖哪些运行时、日志打在哪、卡住时该看什么。第三类是做集成的人，比如把 Hermes 接入企业微信 Bot、接入 Obsidian、接入自己的业务系统，这时候回调函数、会话用户 ID、消息解析这些细节会直接决定你能不能跑通。

我见过太多人把 Hermes Agent 当成一个"更聪明的 API"来用，结果在回调、状态、工具注册这几个环节反复踩坑。所以这篇不打算写成官方文档的复述，而是按一个真正调过它、部署过它、被它坑过的人的视角，把 Agent Loop 的执行流程一层层拆开。你会看到循环的每个阶段在做什么、为什么这么设计、回调为什么容易出问题、以及在不同平台上部署时那些文档里不会写的细节。

提示：本文讨论的是 Hermes Agent 的通用执行模型与工程实践，涉及具体版本行为时以你实际安装的版本为准，不同版本在回调时机和工具注册方式上可能有差异。

2. Agent Loop 的四个阶段：规划、行动、观察、收敛

要拆解执行流程，先得把循环切成可辨认的阶段。Hermes Agent 的一轮完整循环，我习惯把它分成四个阶段：规划（Plan）、行动（Act）、观察（Observe）、收敛（Converge）。这四个阶段不是官方术语，而是我在调试日志时总结出来的划分方式，因为它刚好对应日志里四类不同的输出，方便定位问题卡在哪一环。

2.1 规划阶段：模型决定"下一步做什么"

规划阶段是整个循环的起点。Agent 拿到当前上下文——包括原始任务、历史对话、之前所有工具调用的结果——然后让模型输出下一步的意图。这个意图通常表现为两种形式：要么是"我要调用某个工具，参数是这些"，要么是"我认为任务已经完成，最终答案是这些"。

这里有个容易被忽略的点：规划阶段的输入是不断增长的。第一轮循环时上下文很短，可能只有任务描述；到了第五轮，上下文里已经塞进了四次工具调用的完整返回。如果工具返回的内容很大（比如读了一个长文件、查了一次数据库），上下文会迅速膨胀。这就是为什么很多人在长任务里会遇到响应变慢甚至超限——不是模型不行，是循环把上下文喂得太满了。

我的经验是，在规划阶段之前做一层上下文裁剪非常有必要。具体做法是：保留最近 N 轮的工具调用原文，更早的调用只保留摘要。Hermes 本身不强制你做这件事，但如果你不做，长任务跑到后面基本会崩。裁剪的阈值没有标准答案，我一般按 token 预算倒推，给规划阶段留出至少一半的窗口。

2.2 行动阶段：工具调用的真正执行

规划阶段输出"要调用工具"之后，就进入行动阶段。这一步 Hermes 会去解析模型给出的工具名和参数，找到注册过的对应工具函数，然后执行它。执行可能是同步的，也可能是异步的——这取决于你的工具是怎么注册的。

行动阶段最容易出问题的地方是参数解析。模型输出的参数是文本，需要被解析成工具函数能接受的类型。如果模型给了一个格式不对的 JSON，或者参数名和工具定义对不上，这一步就会失败。失败之后有两种处理：一种是直接把错误信息塞回上下文，让模型下一轮自己修正；另一种是直接终止循环报错。Hermes 默认倾向于前者，也就是"让模型自己看着办"，这在多数情况下是好事，但也意味着一个参数错误可能让循环多转好几轮。

注意：如果你发现 Agent 在同一个工具上反复失败，先别怀疑模型，去检查工具的参数 schema 是不是写得太宽松或者太严格。schema 和模型输出之间的"翻译层"是 bug 高发区。

2.3 观察阶段：把工具结果喂回上下文

工具执行完，返回值需要被格式化后塞回上下文，这就是观察阶段。听起来简单，但这里藏着 Agent Loop 最核心的设计哲学：模型不直接"看到"工具的真实返回，它看到的是被序列化后的文本。所以工具返回什么格式，直接决定了模型下一轮能不能正确理解。

举个实际例子。你写了一个查询订单的工具，返回一个 Python 字典。如果你直接把这个字典str()一下塞回去，模型看到的是带单引号的、不规范的表示；如果你json.dumps()一下，模型看到的是标准 JSON。后者明显更好解析。我踩过的坑就是早期图省事直接返回对象，结果模型经常把字段名理解错，因为它看到的格式太随意了。

观察阶段还有一个隐藏职责：判断工具调用是否"有效"。有些工具会返回空结果、错误码或者超时标记，这些信息需要被明确标注出来，否则模型可能把"没查到"当成"查到了空值"，继续往下走。我一般会在工具返回里加一个显式的status字段，让模型一眼能看出这次调用是成功还是失败。

2.4 收敛阶段：循环什么时候停

收敛阶段决定这一轮循环之后是继续还是结束。判断依据通常有几条：模型明确输出了最终答案、达到了最大循环轮数、触发了某个终止工具、或者外部主动中断。这几条里，最大循环轮数是最重要的安全阀。

为什么需要安全阀？因为 Agent Loop 理论上可以无限转下去。模型可能陷入"调用工具→结果不满意→再调用→还不满意"的死循环。我见过一个案例，Agent 在反复尝试读取一个不存在的文件，每次失败都换个路径再试，转了二十多轮才被轮数上限拦住。如果没有这个上限，它会一直烧 token。

轮数上限设多少合适？这取决于任务复杂度。简单任务 5 到 8 轮足够，复杂任务可能需要 20 轮以上。我的建议是按任务类型动态设置，而不是全局写死一个值。另外，收敛阶段最好能记录"为什么停"——是正常完成还是被强制中断，这个信息对后续排查非常关键。

3. 回调机制：为什么你的回调总是慢半拍

回调是 Hermes Agent 里被问得最多的部分，也是坑最密集的地方。热词里"回调函数""支付宝回调""网页授权回调域名""flutter future 的 then 回调"这些词频繁出现，说明大量使用者的困惑都集中在"回调什么时候触发、在哪个线程触发、为什么没触发"这三个问题上。

3.1 回调在循环中的位置决定了它的时机

先建立一个基本认知：Hermes 的回调不是独立于循环存在的，它是循环各阶段的钩子。也就是说，回调的触发时机完全由循环走到哪一步决定。常见的回调点包括：循环开始前、规划完成后、工具调用前、工具调用后、循环结束后。

理解了这一点，很多"回调慢半拍"的现象就解释得通了。比如你在"工具调用后"注册了一个回调，期望它立刻执行，但如果工具本身是异步的，回调可能要等异步任务真正完成才触发。再比如你在"循环结束后"注册回调，那它当然要等整个 Agent Loop 收敛之后才跑，前面所有轮次都跑完了才轮得到它。

我遇到过一个典型场景：有人把结果处理逻辑放在"工具调用后"的回调里，结果发现同一个回调被触发了多次——因为循环里调用了多次工具。这就是没搞清楚回调位置导致的。回调注册在哪个阶段，就要预期它可能被触发几次。

3.2 同步回调与异步回调的取舍

Hermes 支持的回调既有同步的也有异步的，选哪种直接影响执行流程。同步回调会阻塞循环，也就是说回调不返回，循环就不往下走。异步回调则不阻塞，循环继续，回调在后台跑。

什么时候用同步？当你需要回调的结果影响下一步决策时。比如工具调用后的回调要校验返回数据，校验不通过就要中断循环，这种必须同步。什么时候用异步？当日志上报、埋点统计、通知推送这类"做了就行、不影响主流程"的操作，用异步更合适，避免拖慢循环。

这里有个反直觉的点：异步回调不等于"更快"。如果异步回调里做了重活，它只是把阻塞从主循环挪到了别的地方，整体耗时没变，反而增加了调试难度。我一般的原则是：影响决策的用同步，纯副作用的用异步，异步回调里绝不做重计算。

3.3 回调超时的完整排查链路

回到开头那个"回调超时"的问题。我把排查过程完整走一遍，你可以照着复现。

第一步，确认超时发生在哪个回调。日志里通常会标注回调名称和触发阶段，先定位是规划后、工具后还是循环后。

第二步，看这个回调是同步还是异步。如果是同步，超时基本意味着回调函数内部卡住了；如果是异步，可能是回调根本没被调度，或者调度了但没执行完。

第三步，检查回调函数内部有没有阻塞操作。常见的阻塞源包括：网络请求没设超时、数据库查询慢、文件读写卡在大文件上、死锁。我遇到过一次是回调里发了一个 HTTP 请求，对端服务挂了，请求一直挂着，把整个回调拖死了。

第四步，确认回调的注册时机。如果回调是在循环开始后才注册的，而循环已经跑过了那个阶段，回调就永远不会触发——表现出来也像"超时"。

第五步，看是不是回调被触发了多次，其中某一次卡住。这种情况在循环里很常见，因为同一个回调点会被多轮循环命中。

提示：给所有回调里的外部调用都加上显式超时，这是最省事的预防措施。宁可回调快速失败，也不要让它无限等待拖垮整个循环。

3.4 回调里拿到的数据为什么和预期不一样

还有一个高频困惑：回调里拿到的数据，和工具实际返回的不一样。这通常是因为回调拿到的不是原始返回，而是经过观察阶段格式化后的版本。如果你在"工具调用后"的回调里期望拿到原始对象，结果拿到的是序列化后的字符串，就会觉得"数据被改了"。

解决办法是分清两个概念：原始返回和上下文表示。原始返回是工具函数真正 return 的东西，上下文表示是喂给模型看的文本。如果你需要原始数据，应该在工具函数内部就把它存下来，或者用专门的钩子去取，而不是依赖回调参数。这个区分在调试时特别重要，很多人对着回调里的字符串反复找 bug，其实数据本身没问题，只是被格式化过了。

4. 工具注册与状态管理：循环能转起来的地基

Agent Loop 能转，靠的是两样东西：注册好的工具和可维护的状态。这两块没搭好，循环要么转不动，要么转着转着就乱了。

4.1 工具注册的三种常见方式与选择依据

Hermes 里注册工具的方式不止一种，选哪种取决于你的工具是本地函数、远程服务还是动态生成的。

第一种是装饰器注册，最直观，适合本地 Python 函数。你写一个函数，加个装饰器，Hermes 启动时自动扫描并注册。优点是简单，缺点是工具和代码耦合，改工具要改代码。

第二种是配置文件注册，把工具的名称、描述、参数 schema 写在配置里，运行时加载。优点是工具定义和实现分离，适合工具经常变的场景。缺点是配置和实现容易不同步，改了实现忘了改配置就会出问题。

第三种是动态注册，运行时根据条件注册工具。适合多租户或者按任务类型加载不同工具集的场景。灵活但难调试，因为工具集不是固定的。

我的选择依据很简单：工具集稳定就用装饰器，工具集多变就用配置，工具集按场景切换才用动态。大部分项目其实用装饰器就够了，别一上来就上动态注册，那是给自己找麻烦。

4.2 工具描述写得好不好，直接决定循环转几轮

这是我最想强调的一点：工具的描述文本，是模型决定要不要调用它的唯一依据。描述写得含糊，模型就会犹豫、乱试、反复调用，循环轮数飙升。描述写得清楚，模型一次就能选对工具、给对参数。

什么叫写得好？我总结三条。第一，说清楚这个工具"做什么"和"不做什么"。比如"查询订单状态"要明确说明它只查状态，不修改订单，避免模型拿它去干别的。第二，参数说明要带例子。模型对示例的敏感度远高于抽象描述，给一个正确的参数示例，比写三段说明都管用。第三，说明返回值的结构。模型知道返回什么字段，下一轮规划才能用对。

我做过对比测试：同一套工具，描述写得粗糙时平均要 12 轮才完成任务，描述优化后降到 5 轮。轮数减半，token 消耗和响应时间都跟着降。所以别把工具描述当注释随便写，它是循环效率的直接杠杆。

4.3 状态存在哪里：内存、文件还是外部存储

Agent Loop 是有状态的，每一轮都要读写状态。状态存哪里，决定了你的 Agent 能不能持久化、能不能并发、能不能恢复。

内存状态最简单，进程活着状态就在，进程一挂全丢。适合短任务和本地调试。文件状态能持久化，重启后能恢复，但并发写会有冲突，需要加锁。外部存储（数据库、缓存）适合生产环境，能并发、能恢复、能跨进程共享，但引入额外依赖和延迟。

我的建议是按阶段选。开发调试用内存，快速迭代；单机部署用文件，够用且简单；多实例或者需要断点续跑的场景，必须上外部存储。这里有个坑：很多人一开始用内存，上线后想换外部存储，发现状态结构没设计好，迁移成本极高。所以哪怕先用内存，也把状态结构设计成可序列化的，给未来留条路。

4.4 循环中断后如何恢复

长任务跑到一半中断了怎么办？如果状态是持久化的，理论上可以从断点恢复。但恢复不是简单地"读回状态继续跑"，因为循环的上下文里包含了历史工具调用，这些调用可能有副作用——比如已经发出去的请求、已经写进去的数据。恢复时如果重放这些调用，就会重复执行。

我的做法是给每个工具调用打上幂等标记。有副作用的工具，调用前先检查这个操作是否已经做过；没有副作用的工具（纯查询），重放无所谓。这样恢复时只重放安全的调用，有副作用的跳过。这个机制不复杂，但能避免很多"恢复后数据翻倍"的事故。

5. 跨平台部署：Windows、Ubuntu 与桌面版的差异

热词里"hermes 安装 windows""ubuntu 安装 hermes""hermes 桌面版无法更新""windows hermes agent 桌面版 配置"这些词扎堆出现，说明部署是另一大痛点。同一套 Agent Loop，在不同平台上跑起来的表现确实不一样。

5.1 Windows 部署：路径、权限与后台进程

Windows 上部署 Hermes，第一个坎是路径。很多工具和配置默认用正斜杠，Windows 用反斜杠，路径拼接稍不注意就出错。我的习惯是全程用pathlib或者统一的路径处理函数，绝不手写字符串拼接。

第二个坎是权限。Windows 的权限模型和 Linux 不同，某些目录写入需要管理员权限。如果你把状态文件或者日志写到系统目录，可能静默失败。建议把工作目录放在用户目录下，避开权限问题。

第三个坎是后台进程。Windows 上没有 Linux 那样的守护进程概念，想让 Hermes 常驻，要么用服务方式注册，要么用任务计划程序。桌面版通常自带托盘常驻，但如果你跑的是命令行版，就得自己解决常驻问题。

5.2 Ubuntu 部署：依赖、服务与日志

Ubuntu 上部署相对顺畅，但有几个细节要注意。依赖版本是第一个坑，Hermes 依赖的某些库对版本敏感，系统自带的版本可能太旧。建议用虚拟环境隔离，别直接装在系统 Python 里。

服务化是第二个点。生产环境一般用 systemd 管理，写好 service 文件，配好重启策略。这里要注意工作目录和环境变量，systemd 启动的进程环境和你手动跑的不一样，环境变量没配好会导致找不到配置。

日志是第三个点。systemd 的日志走 journald，和 Hermes 自己的日志文件是两套。排查问题时两边都要看，Hermes 日志看业务逻辑，journald 看进程是否正常启动、有没有崩溃重启。

5.3 桌面版更新失败的常见原因

"桌面版无法更新"是个高频问题。常见原因有几个：网络问题导致下载中断、旧版本进程没退干净导致文件被占用、更新包校验失败、权限不足无法写入安装目录。

排查顺序我一般这样走：先确认旧进程是否完全退出，任务管理器里看有没有残留；再确认安装目录是否可写；然后看更新日志里的具体报错。多数情况下是进程占用或者权限问题，真正网络原因的反而少。

注意：更新前先备份配置和状态文件。桌面版更新有时会重置配置，没备份的话之前调好的参数全没了。

5.4 指定安装目录的正确姿势

"hermes 怎么安装并且指定安装目录"这个问题，关键在于安装器和运行时对目录的处理方式不同。安装器可能只负责放文件，运行时的工作目录、配置目录、数据目录是分开的。你指定了安装目录，不代表数据也存那里。

我的做法是：安装目录按安装器的指引指定，数据目录和配置目录通过环境变量或者配置文件单独指定。这样升级时只动安装目录，数据不受影响。很多人把数据和安装混在一起，升级一次数据丢一次，就是没分开。

6. 集成实战：企微 Bot、Obsidian 与外部系统对接

Agent Loop 跑通之后，下一步就是把它接进实际业务。热词里"hermes 接入企微 bot""hermes agent obsidian""hermes 配合什么开发工具使用"这些，都是集成层面的问题。

6.1 企微 Bot 接入：会话用户 ID 加密怎么解

接入企业微信 Bot 时，一个绕不开的问题是拿到的会话用户 ID 是加密的。这不是 Hermes 的问题，而是平台侧为了保护用户隐私做的处理。你要拿到可读的用户标识，得走官方提供的解析接口，用加密 ID 去换真实 ID。

具体流程是：Bot 收到消息时拿到加密 ID，调用官方接口解析，拿到真实用户标识，再和你的业务系统关联。这里要注意接口的调用频率限制和缓存策略，别每条消息都去解析一次，那样既慢又容易触发限流。我一般会做一个本地缓存，加密 ID 到真实 ID 的映射缓存一段时间，减少接口调用。

还有一个细节：解析接口的权限。不是所有应用都有权限调用解析接口，需要在平台侧配置好权限范围。权限没配好，接口会直接拒绝，表现出来就是"解析失败"，但实际是权限问题。

6.2 Obsidian 集成：把 Agent 变成知识库助手

把 Hermes 接进 Obsidian，本质是让 Agent 能读写你的笔记库。这里的关键是文件访问的边界。Agent 不应该有权限读写整个磁盘，只应该访问指定的笔记目录。这个边界要在工具层面限制死，不能靠模型自觉。

实现上，我会写一组专门的文件工具：读笔记、写笔记、搜索笔记、列出目录。每个工具都限定在笔记库根目录下，路径做规范化校验，防止../之类的越界访问。工具描述里明确写清楚"只能访问笔记库内的文件"，模型就不会乱试。

另一个细节是笔记格式。Obsidian 用 Markdown，Agent 写入时要保持格式规范，否则会破坏笔记的渲染。我一般让写入工具做一层格式校验，不合规的内容先修正再写。

6.3 外部系统对接的通用模式

不管是接企微、接 Obsidian 还是接自己的业务系统，对接模式其实就几种：拉模式（Agent 主动查询外部系统）、推模式（外部系统主动通知 Agent）、双向模式（两者都有）。

拉模式最简单，把外部系统的查询封装成工具就行。推模式需要 Agent 暴露一个接收端点，外部系统调用它来触发任务。双向模式最复杂，要处理状态同步和冲突。

我的建议是从拉模式开始，跑通了再考虑推。因为拉模式的时序是可控的，推模式涉及异步通知，调试难度高一个量级。很多项目一上来就搞双向，结果状态对不齐，排查起来非常痛苦。

7. 那些文档不会写的调试经验

最后分享几条我在实际调 Hermes Agent Loop 时攒下的经验，都是踩过坑才明白的。

第一条，日志要打全，但别打爆。循环每一轮的输入输出都值得记录，但工具返回的大对象别整个打进去，打摘要加长度就行。我见过日志文件一天涨几十 G 的，就是因为把完整返回都打进去了。

第二条，给循环加一个"心跳"输出。长任务跑起来后，如果没有任何中间输出，你根本不知道它是在正常跑还是卡死了。每轮循环打一行简短的心跳，包含轮数和当前阶段，排查时一眼就能看出卡在哪。

第三条，工具要能"干跑"。也就是提供一个不产生副作用的模式，只返回"如果执行会做什么"。调试循环逻辑时用干跑模式，避免误操作真实数据。这个模式实现成本很低，但价值极高。

第四条，别迷信最大轮数。轮数上限是安全阀，不是目标。如果一个任务经常跑到接近上限，说明工具描述或者任务拆分有问题，该优化的是流程，不是把上限调高。

第五条，状态结构要版本化。状态里加一个版本号字段，将来结构变了能识别旧状态并做迁移。这个习惯在早期看起来多余，等你要升级时就知道有多香了。

第六条，回调里别做重活。回调应该轻量、快速、可预测。重活放到工具里或者异步任务里。回调卡住会直接拖垮循环，而工具卡住至少还能被超时机制兜住。

第七条，测试要覆盖"模型犯错"的场景。正常路径谁都能跑通，真正考验系统的是模型给错参数、选错工具、陷入循环的时候。故意构造这些场景做测试，比只测正常路径有价值得多。

第八条，把循环的每一轮当成一次独立的事务。每轮开始前记录状态快照，结束后对比变化。这样出问题时能精确定位是哪一轮改坏了什么，而不是对着整个执行历史大海捞针。

这些经验没有一条是官方文档会重点讲的，但每一条都能在实际调试里帮你省下大量时间。Agent Loop 这东西，跑通不难，跑稳很难，而"稳"恰恰藏在这些细节里。