1. 从「会用」到「看懂」Hermes Agent 源码结构到底解决什么问题Hermes Agent 是一个开源 AI Agent 框架能聊天、能调工具、能记忆、能接 Telegram、能跑定时任务。但当你用了九期之后大概率会遇到一个瓶颈功能都会用了可一旦想改点什么——加个自定义工具、调一下 prompt 顺序、让 Cron 任务复用某个 skill——就不知道从哪下手。这就是源码结构和整体架构要解决的问题。这篇笔记面向的是想读懂开源 AI Agent 框架的开发者。不逐行读源码而是先建立一张「架构地图」用户输入一句话之后Hermes 内部到底发生了什么CLI、Gateway、Cron 为什么能复用同一个 Agent 核心Memory 和 Skills 在哪个环节进入上下文Tools 是怎么被模型选中并执行的MCP 工具和内置工具最终在哪里汇合把这些问题搞清楚后面再读任何 Agent 框架的源码你都能快速定位到关键链路。Hermes 的整体架构可以概括成一句话多入口 一个 Agent 核心 多种能力层 长期状态管理。入口可以很多但 Agent 核心尽量统一这是它最核心的设计取舍。2. 前置准备本地跑通 Hermes Agent 并拿到模型调用凭证在开始追源码之前得先让 Hermes 在本地跑起来否则你只能静态看代码没法验证调用链。Hermes 支持多种模型 provider配置方式是通过环境变量或配置文件指定 Base URL、API Key 和 Model ID。这里我用 TaoToken 作为模型接入层来演示因为它兼容 OpenAI 风格的接口配置简单适合边读源码边验证请求。第一步拿到 API Key。打开 https://taotoken.net/api-keys 注册后创建一个 Key复制保存。注意这个 Key 只在创建时显示一次丢了就得重新生成。第二步确认你要用的模型 ID。在 https://taotoken.net/models 可以看到当前支持的模型列表选一个你熟悉的比如 claude-sonnet 系列或 gpt 系列。记下准确的 Model ID后面配置要用。第三步配置 Hermes 的模型接入。Hermes 读取模型配置的方式通常是环境变量或项目级配置文件。以环境变量为例你需要在 shell 里设置export HERMES_PROVIDERopenai-compatible export HERMES_BASE_URLhttps://taotoken.net/api export HERMES_API_KEYsk-你的Key export HERMES_MODELclaude-sonnet-4-20250514如果你用的是 Hermes 的配置文件方式可以在项目根目录创建.hermes/config.toml[provider] name openai-compatible base_url https://taotoken.net/api api_key sk-你的Key model claude-sonnet-4-20250514 api_mode chat_completions这里api_mode是关键参数。Hermes 的 Provider Resolution 层会根据这个字段决定用哪种请求格式。OpenAI 兼容接口一般用chat_completionsAnthropic 原生接口用anthropic_messages。配错了会在调用时报 400 或 404。第四步验证配置是否生效。运行hermes --version hermes config showconfig show会打印当前解析到的 provider、base_url、model。确认 base_url 是https://taotoken.net/apimodel 是你选的那个。如果这里显示的还是默认值说明环境变量没被读到检查 shell 是否 source 了配置文件。3. 可复制配置把 Agent Loop 主链路拆成可验证的模块配置好模型接入之后下一步是理解 Hermes 的目录结构和核心模块调用关系。我建议先抓住几个关键文件和目录不要一上来就横向扫所有文件。Hermes 的源码目录大致是这样的hermes/ ├── run_agent.py # AIAgent 核心Agent Loop 主入口 ├── cli.py # CLI/TUI 入口 ├── model_tools.py # 工具 schema 收集与模型调用桥接 ├── agent/ │ ├── prompt_builder.py # 系统提示词分层构建 │ ├── system_prompt.py # stable 层身份与行为规范 │ ├── context_compressor.py # 上下文压缩 │ ├── prompt_caching.py # prompt 缓存 │ └── auxiliary_client.py # 辅助模型调用 ├── tools/ │ ├── registry.py # 工具注册表 │ └── *.py # 各内置工具实现 ├── gateway/ │ ├── run.py # Gateway 主循环 │ ├── session.py # 会话管理 │ ├── delivery.py # 结果投递 │ ├── pairing.py # 用户鉴权配对 │ ├── hooks.py # 生命周期钩子 │ └── platforms/ # Telegram/Slack/Discord 适配器 ├── cron/ │ ├── jobs.py # 任务定义 │ └── scheduler.py # 调度器 ├── plugins/ │ ├── memory/ # memory provider 插件 │ └── context_engine/ # context engine 插件 ├── skills/ # 内置 skills ├── optional-skills/ # 可选 skills └── tests/读源码的顺序我建议这样先看run_agent.py里的AIAgent.run_conversation()这是整个 Agent Loop 的主函数。然后看agent/prompt_builder.py理解系统提示词是怎么分层的。接着看model_tools.py和tools/registry.py搞清楚工具是怎么注册和暴露给模型的。最后再看gateway/run.py和cron/scheduler.py理解不同入口是怎么把任务交给 AIAgent 的。如果你想在本地验证这条链路可以在run_agent.py的run_conversation()入口加一行日志import logging logging.basicConfig(levellogging.DEBUG) # 在 run_conversation 开头 logger.debug(Agent Loop start: session%s, model%s, session_id, self.model)然后跑一次 CLI 对话观察日志输出。你会看到 prompt 构建、provider 解析、模型调用、工具执行、结果写回这几个阶段的顺序。这比静态读代码直观得多。4. 验证请求一次对话请求的完整生命周期与成功结果配置和目录都清楚了现在跑一次完整的请求验证 Agent Loop 的每个环节。启动 Hermes CLIhermes chat输入一句需要调用工具的话比如「帮我看看当前目录下有哪些 Python 文件」。观察终端输出和日志。一次完整的 Hermes 对话请求会经历这些步骤用户在 CLI 输入消息cli.py接收输入。Hermes 把消息加入 conversation history。prompt_builder.py构建系统提示词分 stable、context、volatile 三层。Provider Resolver 根据配置确定模型和 API 模式。Hermes 组装 API messages调用模型。模型返回tool_calls请求调用文件列表工具。model_tools.py根据工具名找到 handler 并执行。工具结果写回 conversation history。继续调用模型模型生成最终回答。输出结果到终端保存 session。必要时刷新 memory上下文过长时触发压缩。简化成一条链路就是User → Prompt → Model → Tool Call? → Tool Result → Model → Final Response → Persistence验证成功的标志是终端先显示工具调用过程比如「正在执行 list_files...」然后显示模型基于工具结果生成的回答。日志里能看到tool_calls的解析和handle_function_call的执行记录。如果你在model_tools.py里加一行日志logger.debug(Tool call received: %s, args: %s, tool_name, tool_args)就能清楚看到模型请求了哪个工具、传了什么参数。这一步验证通过说明你的模型接入配置和 Agent Loop 主链路都是通的。5. 常见报错排查401、local proxy failed、reading choices、OAuth跑通之后你可能会在改配置或换模型时遇到一些报错。这里整理几个高频问题和排查方法。401 Unauthorized最常见的原因是 API Key 没配好或过期。检查HERMES_API_KEY是否设置正确Key 有没有多余空格。如果用的是配置文件确认api_key字段没有引号包裹问题。另外TaoToken 的 Key 是绑定账号的如果账号欠费或 Key 被删除也会返回 401。去 https://taotoken.net/api-keys 重新生成一个 Key 试试。local proxy failed / connection refused这个报错通常出现在 base_url 配置错误时。确认HERMES_BASE_URL是https://taotoken.net/api不要多加/v1或漏掉/api。Hermes 的 Provider Resolution 层会根据api_mode拼接具体路径手动加路径反而会导致 404。另外检查本地网络是否能正常访问该地址可以用curl https://taotoken.net/api/models测试连通性。reading choices / index out of range这个报错一般出现在模型返回格式和 Hermes 预期不一致时。比如你用了anthropic_messages模式但实际接口返回的是 OpenAI 格式。检查api_mode是否和模型匹配。OpenAI 兼容接口统一用chat_completions。如果换了模型 ID 但没改api_mode也会出现这个错。OAuth / credential pool 相关报错Hermes 支持 OAuth 和 credential pool 做多凭证轮换。如果你没配置 OAuth 但代码走了 OAuth 分支会报缺少 token。检查配置文件里是否误开了oauth true。如果用的是 credential pool确认池里至少有一个有效凭证。对于 TaoToken 这种 API Key 接入方式不需要 OAuth把oauth设为false即可。排查时建议打开 DEBUG 日志观察 Provider Resolution 阶段解析出的 base_url、api_mode、model 三个值是否符合预期。大部分报错都源于这三个值和实际接口不匹配。6. 从架构地图到改造 Hermes下一步怎么走把 Agent Loop 主链路跑通、报错排查清楚之后你对 Hermes 的整体架构应该有了具体认知。回到开头那张架构地图入口层有 CLI、Gateway、Cron、ACP、Batch Runner、API Server核心层是 AIAgent负责 prompt 构建、provider 解析、工具调度、会话历史、上下文压缩、memory 刷新、session 持久化能力层有内置工具、MCP 工具、Skills、Memory Providers、Plugins、Context Engines外部环境层是文件系统、Shell、GitHub、数据库、消息平台、LLM Provider。这张图里最重要的不是某个模块而是中间的 AIAgent。无论用户从 CLI 发消息、从 Telegram 发消息还是 Cron 定时触发最终都会进入AIAgent.run_conversation()。这就是「平台无关核心」的设计思想入口可以很多但 Agent 核心尽量统一。理解了这条主线Gateway 和 Cron 就只是不同的触发入口MCP 只是扩展了工具来源Skills 只是在 prompt 阶段按需加载的能力文档。Memory、Session、Compression 分别解决长期事实、会话轨迹、上下文长度三个不同层次的状态问题。下一步如果你想改造 Hermes可以从这几个方向入手给tools/目录加一个自定义工具文件按 registry 规范注册写一个自己的 Skill放在skills/目录下配置一个 MCP server观察它如何转换成 Hermes tool schema用 Cron Gateway 做一个定时任务机器人。这些改造的前提都是你已经清楚 Agent Loop 的主链路和各个模块的职责边界。如果你在配置模型接入或排查报错时需要更详细的接口说明可以查 https://taotoken.net/doc 。想直接验证模型对话效果去 https://taotoken.net/chat 。长期跑编码类 Agent 任务的话 https://taotoken.net/coding-plan 有更合适的方案。