1. 为什么我要把 Hermes Agent 源码翻一遍Hermes Agent 是一个用 Python 写的自我进化型 Agent 框架核心能力是让 Agent 在跑任务的过程中自动沉淀技能、维护记忆、持续变强。它适合谁适合已经用过基础 Agent 框架、想搞清楚“自我进化”到底怎么落地的人也适合需要长期运行自动化任务的开发运维同学。我最初关注它是因为一个很实际的问题大多数 Agent 框架的技能靠人手写写多少会多少用久了也不会变聪明。Hermes 不一样它的技能是 Agent 自己“长”出来的——完成复杂任务后自动创建 SKILL.md发现技能过时了自动 patch。这个闭环到底怎么实现的值得从源码层面拆开看。但源码读得再透最终还是要跑起来。Hermes Agent 在运行时会频繁调用 LLM API如果每个模型都单独配一套 Key 和 Base URL配置文件会变得很难维护。我的做法是用 TaoToken 统一 Key/API 通道把模型调用收敛到一个入口settings.json 和 config.toml 里只保留一套凭证。下面先讲三大核心机制的源码逻辑再给可直接复制的配置骨架和验证步骤。2. 三大核心机制的源码拆解2.1 同步对话循环run_conversation() 的设计取舍AIAgent 类是 Hermes 的核心抽象run_conversation() 实现了一个完全同步的对话循环。很多人第一反应是“为什么不用 async”源码给出的答案很明确Agent 的核心瓶颈在 LLM API 延迟不在 I/O 并发。同步循环让调用栈清晰、断点调试友好出问题时能直接定位到哪一轮工具调用卡住了。循环里有三个关键细节值得注意。第一是迭代预算机制子 Agent 拥有独立预算不会消耗父 Agent 的配额防止单一任务把全局资源吃光。第二是消息格式严格遵循 OpenAI 格式role 只有 system/user/assistant/tool 四种推理内容存在 assistant_msg[reasoning] 里这样切换模型时不需要改消息结构。第三是 coerce_tool_args() 函数它把 LLM 返回的字符串参数和 JSON Schema 比对后自动强转类型避免因为 count: 3 这种小问题导致工具调用失败。2.2 有界策展式记忆2200/1375 字符背后的设计哲学记忆系统在 tools/memory_tool.py 里MemoryStore 的实现非常克制。它维护两个分离文件MEMORY.md 存 Agent 的环境知识USER.md 存用户偏好。容量硬性限制在 2200 和 1375 字符这不是技术限制而是设计哲学——倒逼 Agent 做信息压缩过时的条目自然被挤掉。“超限即失败”策略是精髓。当添加条目超限时add 操作直接返回错误而不是静默丢弃同时返回 current_entries 让模型看到所有现有条目引导它执行 replace 或 remove。这比“悄悄扔掉旧记忆”要聪明得多模型知道自己该做清理了。冻结快照机制则直接关系到成本。每次会话启动时Memory 加载后立即捕获快照注入系统提示词整个会话期间这个快照不变。这意味着前缀缓存Prefix Caching在整个会话期间有效对支持 prompt caching 的提供商来说API 成本会明显下降。2.3 技能自动生成与精确修补技能系统是“自我进化”的核心载体在 tools/skill_manager_tool.py 里。_create_skill 的流程很完整校验 name 格式小写字母、数字、连字符、校验 frontmatter 结构必须含 name 和 description、跨本地和外部目录全量搜索检查同名冲突、创建目录并原子写入 SKILL.md临时文件加 os.replace()、安全扫描、清除系统 Prompt 缓存让新技能立即生效。_patch_skill 则采用精准的 find-and-replace而不是全量替换大幅降低 Token 消耗。它用模糊匹配引擎容忍空白符和缩进差异专门为 LLM 生成内容的不精确性设计。patch 后还会校验 frontmatter 完整性原子写入加安全扫描加回滚机制。触发机制藏在系统 Prompt 的 SKILLS_GUIDANCE 里大意是完成复杂任务5 次以上工具调用、修复棘手错误、发现非平凡工作流后用 skill_manage 把方法存成技能使用技能时发现过时或不完整立即 patch不要等被要求。这段指令是闭环能自动运转的关键。2.4 工具注册层与优雅降级ToolRegistry 单例是整个工具系统的脊柱。每个工具文件在模块导入时调用 registry.register() 声明 Schema、处理器函数、工具集归属和可用性检查函数。优雅降级机制很实用需要 API Key 的工具在 Key 未配置时自动从工具列表中隐藏而不是报错。get_tool_definitions() 还会动态重建某些工具的 Schema比如 execute_code 工具描述里列出的可用工具会随 API Key 配置状态变化避免模型产生“幻觉工具调用”。3. TaoToken 前置统一 Key/API 通道Hermes Agent 运行时需要调用 LLM API如果每个模型单独配 Keysettings.json 和 config.toml 会迅速膨胀。TaoToken 的作用是把模型调用收敛到一个统一入口你只需要维护一套凭证。先到官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册账号然后在控制台创建 API Key。控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite API Key 管理页在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。API 基础地址是 https://taotoken.net/api 注意这个地址不加 UTM 参数。创建好 Key 之后你需要在本地环境变量里设置它。我习惯用 .env 文件管理但 Hermes 的配置读取逻辑同时支持环境变量和配置文件下面两种方式都会给到。4. 可复制配置settings.json 与 config.toml 骨架4.1 settings.json 骨架Hermes Agent 的 settings.json 主要管模型通道和运行时参数。下面这份骨架可以直接复制把 YOUR_TAOTOKEN_API_KEY 替换成你在控制台创建的真实 Key。{ llm: { provider: openai_compatible, base_url: https://taotoken.net/api, api_key: YOUR_TAOTOKEN_API_KEY, model: claude-sonnet-4-20250514, max_tokens: 8192, temperature: 0.3, timeout_seconds: 120 }, agent: { max_iterations: 30, sub_agent_max_depth: 2, sub_agent_parallel: 3, memory_char_limit: 2200, user_char_limit: 1375 }, tools: { enable_code_execution: true, enable_skill_manage: true, enable_memory: true, skill_scan_on_create: true }, logging: { level: INFO, log_dir: ./logs } }几个参数说明。base_url 固定为 https://taotoken.net/api provider 用 openai_compatible 是因为 Hermes 的消息格式严格遵循 OpenAI 格式走兼容通道最省事。model 字段填你实际要用的模型名TaoToken 支持多种模型切换时只改这一个字段。max_iterations 控制单次对话的最大迭代轮数30 对大多数任务够用。sub_agent_max_depth 设为 2 是源码里的默认上限防止递归失控。4.2 config.toml 骨架config.toml 管的是更细粒度的运行时行为包括记忆文件路径、技能目录、安全扫描策略。[llm] base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY default_model claude-sonnet-4-20250514 fallback_model gpt-4o [memory] memory_file ./data/MEMORY.md user_file ./data/USER.md memory_char_limit 2200 user_char_limit 1375 freeze_snapshot true [skills] skill_dir ./skills external_skill_dirs [./community-skills] auto_create true auto_patch true scan_on_create true atomic_write true [security] scan_fail_action rollback max_skill_size_kb 64 [delegate] max_depth 2 max_parallel 3 isolated_context true这里 api_key_env 指向环境变量 TAOTOKEN_API_KEY比把 Key 明文写在文件里安全。freeze_snapshot 设为 true 就是启用前面说的冻结快照机制配合支持 prompt caching 的模型能省不少成本。scan_on_create 和 scan_fail_action 对应源码里的安全扫描加回滚逻辑。4.3 环境变量设置如果你用环境变量方式在 shell 里执行export TAOTOKEN_API_KEY你的真实Key export TAOTOKEN_BASE_URLhttps://taotoken.net/apiWindows PowerShell 用$env:TAOTOKEN_API_KEY你的真实Key $env:TAOTOKEN_BASE_URLhttps://taotoken.net/api5. 验证请求确认通道生效配置写完后先跑一个最小验证脚本确认 TaoToken 通道能正常返回。import os import json import urllib.request api_key os.environ.get(TAOTOKEN_API_KEY) base_url https://taotoken.net/api payload { model: claude-sonnet-4-20250514, messages: [ {role: system, content: You are a helpful assistant.}, {role: user, content: Reply with exactly: channel_ok} ], max_tokens: 32, temperature: 0 } req urllib.request.Request( f{base_url}/v1/chat/completions, datajson.dumps(payload).encode(utf-8), headers{ Content-Type: application/json, Authorization: fBearer {api_key} }, methodPOST ) with urllib.request.urlopen(req, timeout60) as resp: body json.loads(resp.read().decode(utf-8)) print(status:, resp.status) print(content:, body[choices][0][message][content])预期输出是 status: 200 和 content: channel_ok。如果返回 401说明 Key 没读到或写错了返回 404检查 base_url 是不是写成了带路径的地址返回 429说明触发了限流稍等再试。通道验证通过后再启动 Hermes Agent 本体观察日志里第一轮对话是否正常完成。如果 Agent 启动时报“no available tools”大概率是 API Key 没被工具注册层识别检查环境变量名是否和 config.toml 里的 api_key_env 一致。6. 本篇常见错排查6.1 401 Unauthorized最常见的原因是 Key 没读到。先确认环境变量在当前 shell 里生效echo $TAOTOKEN_API_KEYLinux/macOS或echo $env:TAOTOKEN_API_KEYPowerShell。如果为空说明 export 只在一个终端窗口生效换窗口就丢了建议写进 shell 配置文件或 .env 文件。另一个原因是 Key 复制时带了空格或换行。TaoToken 控制台复制出来的 Key 是纯字符串粘贴时注意别把首尾空白带进去。6.2 模型名不匹配Hermes 的 model 字段必须和 TaoToken 支持的模型名完全一致。如果你填了一个不存在的模型名通常会返回 400 或 404。解决办法是到模型对话页 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 确认当前可用的模型列表把 model 字段改成列表里的准确名称。6.3 技能创建后不生效源码里 _create_skill 最后一步是清除系统 Prompt 缓存。如果你自己改了技能目录但没重启 Agent新技能不会出现在工具列表里。另外检查 skill_dir 路径是否存在原子写入需要目录有写权限。如果安全扫描失败技能会被自动回滚删除日志里会有 scan_fail 记录检查 SKILL.md 的 frontmatter 是否包含 name 和 description。6.4 记忆超限报错MemoryStore 的“超限即失败”策略意味着 add 操作在超过 2200/1375 字符时会直接报错。这不是 bug是设计。遇到这个报错时让 Agent 执行 replace 或 remove 清理旧条目而不是去改大限制值。改大限制会破坏前缀缓存的稳定性反而增加成本。6.5 子 Agent 委托失败delegate_task 创建的子 Agent 有独立上下文和受限工具集最大深度 2。如果你在子 Agent 里再调 delegate_task第三层会被拒绝。批量模式下最多 3 个子 Agent 并行超过会排队。检查 config.toml 里的 max_depth 和 max_parallel 是否被改成了不合理的值。7. 接入文档与后续动作配置骨架跑通之后建议把 settings.json 和 config.toml 纳入版本管理但 API Key 走环境变量不要提交到仓库。如果你需要更细的接口参数说明接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有各端点的请求格式和错误码对照。如果你打算长期跑编码类或 Agent 类任务可以看一下 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 它针对高频调用场景做了配额优化。Claude Code 相关的 Anthropic 通道配置在 https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaude-code-anthropicutm_campaignrewrite 如果你用 Claude Code 作为前端可以参考那份配置把 base_url 指过来。最后说一个我踩过的坑Hermes 的同步循环在长任务里会阻塞终端如果你在 Jupyter 里跑记得把 max_iterations 调小一点先验证流程确认没问题再放开。技能目录第一次创建时是空的跑两三个复杂任务后才会看到 SKILL.md 文件长出来别急着以为没生效。