1. Hermes Agent 技术架构拆解从 run_agent.py 到 ProCode 模式到底解决了什么问题Hermes Agent 是一个会自我进化的开源 AI 智能体能通过多平台网关接入消息、自动沉淀技能、按 cron 调度任务适合想把重复工作交给一个越用越顺手的助手的开发者。我第一次读它源码时最直观的感受是代码组织非常克制每个模块只干一件事没有为了“架构感”而堆抽象层。下面按真实文件结构拆开讲读完你能判断它适不适合你的场景。1.1 核心文件结构与职责边界hermes-agent/ ├── run_agent.py # 核心 AIAgent主对话循环、工具调用、消息历史 ├── model_tools.py # 工具发现与分发层统一 registry ├── hermes_state.py # 状态管理SQLite WAL FTS5 ├── gateway/ # 多平台消息网关12 个平台统一接入 ├── tools/ │ ├── terminal_tool.py # 终端执行支持多执行后端 │ ├── mcp_tool.py # MCP 协议接入把外部系统注册为原生工具 │ ├── browser_tool.py # 浏览器自动化 │ └── file_tool.py # 文件操作 ├── memory/ │ ├── MEMORY.md # 常驻提示记忆上限 3575 字符 │ ├── USER.md # 用户画像 │ └── skills/ # 自动生成的技能库 └── scheduler/ # 定时任务调度cron 式run_agent.py是主循环负责把用户输入、记忆、工具结果拼成模型可消费的消息序列model_tools.py是工具注册与分发的中枢hermes_state.py用 SQLite 加 WAL 模式保证并发写入不锁死FTS5 让历史消息可全文检索。这个分层的好处是换模型只动 provider 层加工具只动 tools 目录改记忆策略只动 memory 目录互不牵连。1.2 工具注册机制装饰器即插即用Hermes 的工具不是硬编码在核心逻辑里的而是在模块导入时自动注册到统一 registry# 伪代码示意工具注册原理 register_tool(web_search) def web_search(query: str) - str: ... # Agent 按 toolset 动态组装当前可用能力 agent AIAgent(toolset[web_search, terminal, file])这意味着三件事新增工具只需写一个文件加装饰器不用改核心不同场景可以组装不同工具集轻量运行MCP 协议接入的外部工具与内置工具对 Agent 完全透明。我试过把内部工单系统通过 MCP 注册进去Agent 调用它和调用file_tool没有任何区别这种一致性是很多 Agent 框架没做到的。1.3 ProCode 模式把几十轮交互压成个位数这是 Hermes 降低 API 成本的关键设计。普通模式下Agent 调用工具 A、等结果、调用工具 B、再等结果复杂任务轻松跑出几十轮ProCode 模式下Agent 直接生成一个 Python 脚本脚本通过 RPC 批量调用多个工具一次性返回结果。# ProCode 模式示意Agent 生成的脚本批量处理日志 import rpc files rpc.call(file_tool, {action: glob, pattern: ~/logs/*.log}) results [] for f in files: content rpc.call(file_tool, {action: read, path: f}) errors rpc.call(terminal_tool, {cmd: fgrep -c ERROR {f}}) results.append({file: f, errors: errors}) rpc.call(file_tool, {action: write, path: report.md, content: str(results)})对于“分析这 50 个日志文件并生成报告”这类任务交互轮数从几十轮压缩到个位数token 消耗和延迟都明显下降。代价是生成的脚本偶尔会有边界错误需要你在验证环节多看一眼。1.4 记忆系统四层结构各管什么Hermes 的记忆分四层MEMORY.md是常驻提示记忆上限 3575 字符每次对话都注入USER.md是用户画像记录你的偏好和背景skills/是自动生成的技能库从任务执行轨迹中提炼SQLite 里的历史消息则通过 FTS5 支持检索。四层各司其职常驻记忆保证“它记得你是谁”技能库保证“它记得怎么做”历史检索保证“它能翻旧账”。理解这套架构后你就能判断如果你的任务需要长期记忆和跨会话积累Hermes 的设计是对路的如果你只要单次问答这套记忆反而是负担。2. TaoToken 前置统一 Key 与 API 通道配置让 Hermes 不绑死单一模型Hermes 支持 18 模型提供商但逐个配置 API Key 很烦而且不同提供商的 Base URL、鉴权头、模型 ID 命名规则都不一样。TaoToken 的价值在于提供一个统一的 Key 和 API 通道你只配一次就能在 Hermes 里切换多家模型。官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 。2.1 为什么 Hermes 场景下需要统一通道Hermes 的模型配置是写在config.toml里的每个 provider 一段。如果你要对比 Claude、GPT、Gemini 在同一个 Agent 任务上的表现逐个申请 Key、逐个填 Base URL光配置就能耗掉半小时。统一通道把这件事变成改一个model字段。另外 Hermes 的 ProCode 模式会产生大量工具调用请求统一通道在计费和限流上更好管理。2.2 获取 Key 与确认可用模型登录后在控制台创建 API Key地址是 https://taotoken.net/console 。创建时建议按用途命名比如hermes-agent-dev方便后续排查。模型 ID 以文档为准接入文档在 https://taotoken.net/doc 。拿到 Key 后先别急着写进 Hermes用 curl 验证一次curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: claude-3-5-sonnet, messages: [{role: user, content: ping}], max_tokens: 16 }返回里有choices字段就说明通道通了。这一步能提前排掉 401 和模型 ID 写错的问题比在 Hermes 里报错再回头查省事得多。2.3 环境变量与安全存放不要把 Key 硬编码进config.toml提交到 git。推荐写进 shell 配置# ~/.bashrc 或 ~/.zshrc export TAOTOKEN_API_KEYsk-你的key然后source ~/.bashrc重载。Hermes 的配置支持读取环境变量这样 Key 和配置文件分离换机器时只改环境变量。2.4 与 Hermes 模型层的对接位置Hermes 的 provider 配置在config.toml的[model]段统一通道本质上是一个 OpenAI 兼容的 endpoint所以填base_url和api_key两个字段即可。下一节给出完整可复制的配置骨架。3. 可复制配置config.toml 骨架与 TaoToken 通道接入这一节给出一份可以直接抄的config.toml骨架路径是~/.hermes/config.toml。如果你用的是 Claude Code 或 Cline MCP 这类工具配置逻辑类似核心三件套都是 Base URL、Key、Model ID。3.1 完整 config.toml 骨架# ~/.hermes/config.toml [model] # 统一通道TaoToken provider openai-compatible base_url https://taotoken.net/api api_key ${TAOTOKEN_API_KEY} model claude-3-5-sonnet max_tokens 8192 temperature 0.7 [agent] toolset [web_search, terminal, file, mcp] max_turns 30 procode true [memory] memory_file ~/hermes/MEMORY.md user_file ~/hermes/USER.md skills_dir ~/hermes/skills max_memory_chars 3575 [gateway.telegram] enabled true bot_token ${TELEGRAM_BOT_TOKEN} [scheduler] enabled true timezone Asia/Shanghai关键字段说明base_url填https://taotoken.net/api不要带 UTM 参数api_key用${TAOTOKEN_API_KEY}引用环境变量model填你要用的模型 ID以文档为准procode true开启脚本批量调用模式。3.2 如果你用 Claude Code 或 Cline MCPClaude Code 的配置在~/.claude/settings.jsonCline MCP 在扩展设置里三件套对应关系如下工具Base URLKey 字段Model ID 字段Hermesbase_urlapi_keymodelClaude CodeANTHROPIC_BASE_URLANTHROPIC_API_KEYANTHROPIC_MODELCline MCPbaseUrlapiKeymodelIdClaude Code 的环境变量写法export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEY$TAOTOKEN_API_KEY export ANTHROPIC_MODELclaude-3-5-sonnetCline MCP 的settings.json片段{ mcpServers: { taotoken: { baseUrl: https://taotoken.net/api, apiKey: ${TAOTOKEN_API_KEY}, modelId: claude-3-5-sonnet } } }Codex 的auth.json写法{ openai: { base_url: https://taotoken.net/api, api_key: ${TAOTOKEN_API_KEY}, model: claude-3-5-sonnet } }三件套配齐后这些工具都能走同一条通道切换模型只改 Model ID。3.3 配置校验与重载改完配置后执行hermes config check hermes config reloadconfig check会校验 TOML 语法和必填字段config reload让运行中的 Agent 重新读取配置不用重启进程。如果config check报missing required field: base_url说明字段名拼错了对照上面的骨架检查。4. 部署验证从 ping 到第一个自动化任务的完整动作配置写完不算完得跑通验证链路。这一节给出从最小请求到真实任务的验证步骤每一步都有预期结果。4.1 最小验证单轮对话hermes run --prompt 用一句话说明你当前使用的模型和工具集预期输出里会包含模型 ID 和可用工具列表。如果返回空或报错先看下一节的排障表。4.2 工具调用验证让 Agent 执行终端命令hermes run --prompt 执行 uname -a 并把结果告诉我预期 Agent 会调用terminal_tool返回系统信息。这一步验证的是工具注册和分发链路是否正常。如果 Agent 说“我无法执行命令”检查toolset里有没有terminal。4.3 ProCode 模式验证批量文件处理mkdir -p ~/test-logs for i in $(seq 1 10); do echo ERROR line $i ~/test-logs/app-$i.log; done hermes run --prompt 统计 ~/test-logs 下每个文件的 ERROR 行数生成 report.md预期 Agent 生成一个 Python 脚本批量读取 10 个文件并写出报告。查看report.md确认内容正确。这一步验证 ProCode 模式是否生效如果交互轮数很多检查procode true有没有写对。4.4 定时任务验证cron 调度hermes run --prompt 每天早上 8:30 搜索今天 AI 领域三条重要新闻中文总结后通过 Telegram 发给我预期 Agent 自动生成SKILL.md并写入调度器。用hermes scheduler list查看任务是否注册成功。这一步验证的是闭环学习链路一次对话沉淀技能后续自动执行。4.5 记忆验证跨会话保持hermes run --prompt 记住我的项目目录是 ~/projects/myapp # 退出后重新进入 hermes run --prompt 我的项目目录在哪预期第二次能答出~/projects/myapp。如果答不出检查MEMORY.md是否可写以及max_memory_chars是否被占满。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth 对照表配置和部署过程中最容易撞上四类报错下面按真实报错信息给出原因和修法。5.1 401 UnauthorizedError: 401 Unauthorized - invalid api key原因通常是 Key 没读到或写错。检查echo $TAOTOKEN_API_KEY是否有值检查config.toml里是不是写成了${TAOTOKEN_API_KEY}而不是直接粘贴 Key检查 Key 是否被控制台删除或过期。如果用的是 Claude Code检查ANTHROPIC_API_KEY是否指向了正确的变量。5.2 local proxy failedError: local proxy failed to connect to upstream这个报错通常出现在本地网络环境有额外转发层时。检查base_url是否写成了https://taotoken.net/api而不是带路径的完整 endpoint检查系统代理设置是否干扰了直连用curl -v https://taotoken.net/api/v1/models确认网络层可达。如果 curl 通但 Hermes 不通检查 Hermes 是否读取了系统代理环境变量。5.3 reading choices 相关报错Error: reading choices field: unexpected response format这说明返回体不是标准的 OpenAI 兼容格式。常见原因是base_url多写了/v1或少了/v1导致请求打到了错误路径。正确写法是https://taotoken.net/api由客户端自动拼接/v1/chat/completions。另外检查model字段是否填了不存在的模型 ID有些提供商会返回错误页而不是 JSON。5.4 OAuth 相关报错Error: OAuth token expired or invalid如果你用的是需要 OAuth 的 provider检查 token 刷新逻辑。Hermes 的 provider 层支持 OAuth但统一通道走的是 API Key 鉴权不涉及 OAuth。如果报这个错说明配置里还残留了旧的 OAuth provider 段删掉或注释掉即可。5.5 排障速查表报错关键词最可能原因修法401 UnauthorizedKey 未读到或写错检查环境变量和${}引用local proxy failedbase_url 路径错误或代理干扰改为https://taotoken.net/apireading choices返回体非标准格式检查/v1拼接和模型 IDOAuth expired残留 OAuth provider 配置删除旧 provider 段排障时优先用 curl 验证通道再查 Hermes 配置最后查工具层。这个顺序能避免在错误的地方浪费时间。6. 与主流 Agent 深度 PKHermes、OpenClaw、Claude Code、Gemini CLI 怎么选横向对比不能只看功能列表得看你的真实场景。下面按维度拆开最后给选型建议。6.1 Hermes vs OpenClawOpenClaw 定位也是个人 AI 助手但架构模式是多 Agent 协同编排技能靠人工编写记忆是静态配置文件。Hermes 是单一自进化 Agent技能从经验中自动生成记忆四层自动管理。一句话总结OpenClaw 是你定义它能做什么它就精准执行Hermes 是你用它做事它自己学会做得更好。追求稳定可控选 OpenClaw追求越用越强选 Hermes。6.2 Hermes vs Claude CodeClaude Code 是编码专用 Agent与开发流程深度集成但无状态、会话结束即清空消息平台支持有限模型主要绑定 Claude。Hermes 是通用 Agent四层持久化记忆12 个消息平台原生支持18 模型提供商。如果你只要编程助手Claude Code 更顺手如果你要一个跨平台、有长期记忆的通用助手Hermes 更合适。6.3 Hermes vs Gemini CLI / Codex CLIGemini CLI 和 Codex CLI 本质是增强版命令行工具。Gemini CLI 完全锁定 Google Gemini 模型无自学习能力Codex CLI 沙箱安全做得好但偏向 OpenAI 生态CLI only。Hermes 是唯一具备闭环学习、多平台接入、无厂商锁定三者组合的。6.4 能力雷达对比维度HermesOpenClawClaude CodeGemini CLI自学习5211多平台接入5421模型自由度5421定时任务5311稳定可控3554易用性34556.5 选型建议需要越用越懂你、多平台接入、大量重复任务自动化、不绑死单一厂商选 Hermes。只需要编程助手选 Claude Code 或 aider。任务对稳定性要求极高选 OpenClaw。Windows 用户不想折腾 WSL2暂时等官方支持。需要零配置快速上手选 Gemini CLI。6.6 局限性与注意事项Hermes 的自学习有不确定性自动生成的SKILL.md偶尔会把特殊情况误归纳为通用技能建议定期检查~/hermes/skills/目录。常驻记忆 3575 字符上限意味着你得主动告诉它哪些信息值得记住。目前不支持原生 Windows需要 WSL2。最重要的是它适合作为巡检、观察、汇报和半自动处置层不建议直接用于控制生产数据库或关键业务系统。7. 进阶技巧与长期编码场景的通道选择7.1 手动优化记忆文件nano ~/hermes/MEMORY.md推荐写入格式## 工作偏好 - 代码风格Black 格式化类型注解必须 - 报告格式Markdown带目录 - 语言默认中文回复 ## 常用路径 - 项目目录~/projects/ - 笔记库~/obsidian/vault/7.2 预置高质量初始技能不要等 Agent 自己摸索直接写好一个SKILL.md作为种子# SKILL: 每日任务汇报 ## 触发条件 用户要求生成工作日报、周报 ## 执行步骤 1. 查询今日/本周 git commit 记录 2. 查询 Jira/飞书任务完成情况 3. 按完成事项 / 进行中 / 明日计划三段式输出 4. 字数控制在 300 字以内 ## 注意事项 - 不要包含具体代码只写业务描述 - 输出语言中文7.3 MCP 接入扩展能力hermes mcp add notion --token YOUR_NOTION_TOKEN接入后 Notion 的读写能力就变成 Hermes 的原生工具。常用 MCP 接入推荐Notion 做知识管理GitHub 做代码仓库操作Slack/飞书做企业通讯PostgreSQL/MySQL 做数据库查询Google Calendar 做日程管理。7.4 长期编码与 Agent 场景的通道选择如果你把 Hermes 当作长期编码助手或 Agent 底座建议走 Coding Plan 通道地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。这个通道针对高频工具调用做了优化ProCode 模式下批量 RPC 请求的延迟更稳。如果只是验证模型能力用模型对话入口 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 快速试。需要管理多个 Key 时去 API Keys 页面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。接入细节查文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。7.5 一个真实踩坑记录我试过在 ProCode 模式下让 Agent 处理 200 个日志文件生成的脚本用了同步 RPC 逐个调用结果跑了 8 分钟。后来在SKILL.md里加了一条“批量操作优先用并发”Agent 下次生成的脚本就改用了线程池时间降到 40 秒。这说明技能库的质量直接决定长期效率值得花时间打磨种子技能。Hermes 的价值不在于单次调用有多强而在于持续使用后能积累多少。从调用 AI 到拥有 AI这套记忆加技能加调度的组合是目前开源 Agent 里比较完整的实现。项目迭代很快现在入场配置好通道和技能库后面就是让它自己跑。