<?xml version="1.0" encoding="utf-8" standalone="yes"?><rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom"><channel><title>Hermes Agent on 记录点滴 - 分享</title><link>https://www.iminling.com/tags/hermes-agent/</link><description>Recent content in Hermes Agent on 记录点滴 - 分享</description><generator>Hugo -- gohugo.io</generator><language>zh-cn</language><copyright>iminling.com</copyright><lastBuildDate>Thu, 19 Nov 2026 00:00:00 +0000</lastBuildDate><atom:link href="https://www.iminling.com/tags/hermes-agent/index.xml" rel="self" type="application/rss+xml"/><item><title>Hermes Agent 扩展篇：Skills 管理、插件开发与 Cron 脚本任务</title><link>https://www.iminling.com/ai/hermes/hermes-agent-skills-plugins-cron/</link><pubDate>Thu, 19 Nov 2026 00:00:00 +0000</pubDate><guid>https://www.iminling.com/ai/hermes/hermes-agent-skills-plugins-cron/</guid><description>&lt;img src="https://images.iminling.com/i/2026/11/19/2cd64f51a7cd1acdd8398b4a226ed87c.webp" alt="Featured image of post Hermes Agent 扩展篇：Skills 管理、插件开发与 Cron 脚本任务" /&gt;&lt;h2 id="写在前面"&gt;写在前面&#10;&lt;/h2&gt;&lt;p&gt;这是 Hermes Agent 架构系列的第五篇，讲能力层。整体分层见 &lt;a class="link" href="https://www.iminling.com/ai/hermes/hermes-agent-architecture-overview/" &gt;Hermes Agent 自托管架构总览&lt;/a&gt;。&lt;/p&gt;&#10;&lt;p&gt;Hermes 有三种扩展方式，解决的问题完全不同：&lt;/p&gt;&#10;&lt;table&gt;&#10;&#9;&lt;thead&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;方式&lt;/th&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;本质&lt;/th&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;适合做什么&lt;/th&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&lt;/thead&gt;&#10;&#9;&lt;tbody&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;Skills&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;给模型看的说明书&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;教 Agent 怎么完成某类任务&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;Plugins&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;运行在网关进程里的 Python 代码&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;修改或补充 Hermes 自身的行为&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;Cron&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;定时触发器&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;定时让 Agent 干活，或定时跑脚本&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&lt;/tbody&gt;&#10;&lt;/table&gt;&#10;&lt;p&gt;一个简单的判断：&lt;strong&gt;需要模型理解和决策的，写 Skill；需要改变 Hermes 程序行为的，写插件；需要按时间触发的，用 Cron。&lt;/strong&gt;&lt;/p&gt;&#10;&lt;h2 id="skills给-agent-的操作手册"&gt;Skills：给 Agent 的操作手册&#10;&lt;/h2&gt;&lt;h3 id="技能的格式"&gt;技能的格式&#10;&lt;/h3&gt;&lt;p&gt;一个技能就是一个目录，核心是 &lt;code&gt;SKILL.md&lt;/code&gt;，开头是 YAML 元数据，后面是给模型读的正文。以内置的 &lt;code&gt;sdlc-review&lt;/code&gt; 为例：&lt;/p&gt;&#10;&lt;div class="highlight"&gt;&lt;div class="chroma"&gt;&#10;&lt;table class="lntable"&gt;&lt;tr&gt;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code&gt;&lt;span class="lnt"&gt; 1&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 2&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 3&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 4&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 5&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 6&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 7&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 8&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 9&#10;&lt;/span&gt;&lt;span class="lnt"&gt;10&#10;&lt;/span&gt;&lt;span class="lnt"&gt;11&#10;&lt;/span&gt;&lt;span class="lnt"&gt;12&#10;&lt;/span&gt;&lt;span class="lnt"&gt;13&#10;&lt;/span&gt;&lt;span class="lnt"&gt;14&#10;&lt;/span&gt;&lt;span class="lnt"&gt;15&#10;&lt;/span&gt;&lt;span class="lnt"&gt;16&#10;&lt;/span&gt;&lt;span class="lnt"&gt;17&#10;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&#10;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-markdown" data-lang="markdown"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nn"&gt;---&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nt"&gt;name&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;sdlc-review&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nt"&gt;description&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;Review Kanban handoffs and route verified outcomes.&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nt"&gt;version&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="m"&gt;1.1.0&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nt"&gt;license&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;MIT&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nt"&gt;platforms&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="l"&gt;linux, macos, windows]&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nt"&gt;metadata&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;hermes&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;tags&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="l"&gt;kanban, review, quality, verification]&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;category&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;devops&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;requires_toolsets&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="l"&gt;kanban]&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nn"&gt;---&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="gh"&gt;# SDLC Review Skill&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="gu"&gt;## When to Use&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;...&#10;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/table&gt;&#10;&lt;/div&gt;&#10;&lt;/div&gt;&lt;p&gt;&lt;code&gt;description&lt;/code&gt; 最关键：Agent 根据它判断什么时候该加载这个技能。正文只有在被使用时才会读入，所以写在正文里的细节不占日常上下文，写在 &lt;code&gt;description&lt;/code&gt; 里的每个字每轮都会带上。&lt;/p&gt;&#10;&lt;p&gt;技能按分类目录存放，比如 &lt;code&gt;skills/devops/&lt;/code&gt;、&lt;code&gt;skills/productivity/&lt;/code&gt;，分类目录下可以放一个 &lt;code&gt;DESCRIPTION.md&lt;/code&gt; 说明这一类技能的用途。&lt;/p&gt;&#10;&lt;h3 id="禁用用不到的内置技能"&gt;禁用用不到的内置技能&#10;&lt;/h3&gt;&lt;p&gt;Hermes 自带大量技能：Notion、Obsidian、PPT、Excel、各种 GitHub 工作流、音视频生成等等。全部开着有两个问题：每个技能的描述都会进入系统提示词，消耗上下文；技能越多，Agent 越容易在不该用的时候误用。&lt;/p&gt;&#10;&lt;p&gt;我的做法是把用不到的全部禁用：&lt;/p&gt;&#10;&lt;div class="highlight"&gt;&lt;div class="chroma"&gt;&#10;&lt;table class="lntable"&gt;&lt;tr&gt;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code&gt;&lt;span class="lnt"&gt;1&#10;&lt;/span&gt;&lt;span class="lnt"&gt;2&#10;&lt;/span&gt;&lt;span class="lnt"&gt;3&#10;&lt;/span&gt;&lt;span class="lnt"&gt;4&#10;&lt;/span&gt;&lt;span class="lnt"&gt;5&#10;&lt;/span&gt;&lt;span class="lnt"&gt;6&#10;&lt;/span&gt;&lt;span class="lnt"&gt;7&#10;&lt;/span&gt;&lt;span class="lnt"&gt;8&#10;&lt;/span&gt;&lt;span class="lnt"&gt;9&#10;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&#10;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-yaml" data-lang="yaml"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nt"&gt;skills&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;disabled&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;- &lt;span class="l"&gt;airtable&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;- &lt;span class="l"&gt;apple-notes&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;- &lt;span class="l"&gt;notion&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;- &lt;span class="l"&gt;obsidian&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;- &lt;span class="l"&gt;powerpoint&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;- &lt;span class="l"&gt;xlsx&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="c"&gt;# ……共禁用了 89 个&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/table&gt;&#10;&lt;/div&gt;&#10;&lt;/div&gt;&lt;p&gt;被禁用的技能文件还在，随时可以从列表里删掉重新启用。上一篇提到的 Profile 也各有自己的 &lt;code&gt;skills/&lt;/code&gt; 目录，所以还能做到&amp;quot;同一个技能只给 &lt;code&gt;dev&lt;/code&gt; 用，不给 &lt;code&gt;home&lt;/code&gt; 用&amp;quot;。&lt;/p&gt;&#10;&lt;p&gt;技能的安装和管理使用 &lt;code&gt;hermes skills&lt;/code&gt;，例如 &lt;code&gt;hermes skills search&lt;/code&gt;、&lt;code&gt;hermes skills install&lt;/code&gt;、&lt;code&gt;hermes skills list&lt;/code&gt;。Hermes 对技能的每次修改都会记录在 &lt;code&gt;.curator_backups/&lt;/code&gt; 中，改坏了可以找回。&lt;/p&gt;&#10;&lt;h2 id="plugins修改-hermes-自己的行为"&gt;Plugins：修改 Hermes 自己的行为&#10;&lt;/h2&gt;&lt;p&gt;技能只能影响模型怎么想，影响不了 Hermes 程序本身怎么运行。比如&amp;quot;每天自动切换会话&amp;quot;&amp;ldquo;某个平台发送失败时换一种方式重试&amp;rdquo;，这些只能写插件。&lt;/p&gt;&#10;&lt;h3 id="插件的结构"&gt;插件的结构&#10;&lt;/h3&gt;&lt;p&gt;插件放在数据目录的 &lt;code&gt;plugins/&lt;/code&gt; 下，一个插件一个目录：&lt;/p&gt;&#10;&lt;div class="highlight"&gt;&lt;div class="chroma"&gt;&#10;&lt;table class="lntable"&gt;&lt;tr&gt;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code&gt;&lt;span class="lnt"&gt;1&#10;&lt;/span&gt;&lt;span class="lnt"&gt;2&#10;&lt;/span&gt;&lt;span class="lnt"&gt;3&#10;&lt;/span&gt;&lt;span class="lnt"&gt;4&#10;&lt;/span&gt;&lt;span class="lnt"&gt;5&#10;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&#10;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-text" data-lang="text"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;plugins/hermes-session-reset-policy/&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;├── plugin.yaml # 元数据&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;├── __init__.py # 入口，提供 register(ctx)&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;├── README.md&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;└── tests/&#10;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/table&gt;&#10;&lt;/div&gt;&#10;&lt;/div&gt;&lt;p&gt;&lt;code&gt;plugin.yaml&lt;/code&gt; 声明插件信息和用到的钩子：&lt;/p&gt;&#10;&lt;div class="highlight"&gt;&lt;div class="chroma"&gt;&#10;&lt;table class="lntable"&gt;&lt;tr&gt;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code&gt;&lt;span class="lnt"&gt;1&#10;&lt;/span&gt;&lt;span class="lnt"&gt;2&#10;&lt;/span&gt;&lt;span class="lnt"&gt;3&#10;&lt;/span&gt;&lt;span class="lnt"&gt;4&#10;&lt;/span&gt;&lt;span class="lnt"&gt;5&#10;&lt;/span&gt;&lt;span class="lnt"&gt;6&#10;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&#10;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-yaml" data-lang="yaml"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nt"&gt;name&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;hermes-session-reset-policy&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nt"&gt;label&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;Session Reset Policy&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nt"&gt;kind&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;standalone&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nt"&gt;version&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="m"&gt;0.3.0&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nt"&gt;provides_hooks&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;- &lt;span class="l"&gt;pre_gateway_dispatch&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/table&gt;&#10;&lt;/div&gt;&#10;&lt;/div&gt;&lt;p&gt;&lt;code&gt;__init__.py&lt;/code&gt; 中的 &lt;code&gt;register(ctx)&lt;/code&gt; 是入口，在这里注册钩子：&lt;/p&gt;&#10;&lt;div class="highlight"&gt;&lt;div class="chroma"&gt;&#10;&lt;table class="lntable"&gt;&lt;tr&gt;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code&gt;&lt;span class="lnt"&gt;1&#10;&lt;/span&gt;&lt;span class="lnt"&gt;2&#10;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&#10;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-python" data-lang="python"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="k"&gt;def&lt;/span&gt; &lt;span class="nf"&gt;register&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;ctx&lt;/span&gt;&lt;span class="p"&gt;):&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; &lt;span class="n"&gt;ctx&lt;/span&gt;&lt;span class="o"&gt;.&lt;/span&gt;&lt;span class="n"&gt;register_hook&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;&amp;#34;pre_gateway_dispatch&amp;#34;&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;_maybe_reset&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/table&gt;&#10;&lt;/div&gt;&#10;&lt;/div&gt;&lt;p&gt;在 &lt;code&gt;config.yaml&lt;/code&gt; 中启用，然后重启网关：&lt;/p&gt;&#10;&lt;div class="highlight"&gt;&lt;div class="chroma"&gt;&#10;&lt;table class="lntable"&gt;&lt;tr&gt;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code&gt;&lt;span class="lnt"&gt;1&#10;&lt;/span&gt;&lt;span class="lnt"&gt;2&#10;&lt;/span&gt;&lt;span class="lnt"&gt;3&#10;&lt;/span&gt;&lt;span class="lnt"&gt;4&#10;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&#10;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-yaml" data-lang="yaml"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nt"&gt;plugins&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;enabled&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;- &lt;span class="l"&gt;hermes-session-reset-policy&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;- &lt;span class="l"&gt;wecom-media-proactive-fallback&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/table&gt;&#10;&lt;/div&gt;&#10;&lt;/div&gt;&lt;p&gt;我目前用了两个插件，正好代表两种典型写法。&lt;/p&gt;&#10;&lt;h3 id="例一用钩子补回被移除的能力"&gt;例一：用钩子补回被移除的能力&#10;&lt;/h3&gt;&lt;p&gt;上游 &lt;code&gt;v2026.9.11&lt;/code&gt; 移除了按时间自动切换会话的定时器，&lt;code&gt;session_reset&lt;/code&gt; 配置从此不再生效。在聊天软件里用 Agent，没有自动切换意味着会话越积越长。&lt;/p&gt;&#10;&lt;p&gt;社区插件 &lt;a class="link" href="https://github.com/fastfinge/hermes-session-reset-policy" target="_blank" rel="noopener"&#10; &gt;hermes-session-reset-policy&lt;/a&gt; 把这个能力补了回来，安装方式：&lt;/p&gt;&#10;&lt;div class="highlight"&gt;&lt;div class="chroma"&gt;&#10;&lt;table class="lntable"&gt;&lt;tr&gt;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code&gt;&lt;span class="lnt"&gt;1&#10;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&#10;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-bash" data-lang="bash"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;hermes plugins install https://github.com/fastfinge/hermes-session-reset-policy.git&#10;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/table&gt;&#10;&lt;/div&gt;&#10;&lt;/div&gt;&lt;p&gt;它的设计很值得学习：&lt;/p&gt;&#10;&lt;pre class="mermaid" style="visibility:hidden"&gt;flowchart TB&#10; Msg[收到用户消息] --&gt; Hook[pre_gateway_dispatch 钩子]&#10; Hook --&gt; Read[读取所属 Profile 的 session_reset 配置]&#10; Read --&gt; Check{距上次用户消息&lt;br/&gt;超过阈值或跨过每日边界？}&#10; Check --&gt;|否| Dispatch[正常分发]&#10; Check --&gt;|是，且没有进行中的任务| Reset[走 /new 的同一条重置流程]&#10; Reset --&gt; Dispatch&lt;/pre&gt;&lt;ul&gt;&#10;&lt;li&gt;&lt;strong&gt;不用定时器&lt;/strong&gt;：在用户发来新消息、正式分发之前检查要不要重置。没有后台线程，也不会在没人说话时写数据库。&lt;/li&gt;&#10;&lt;li&gt;&lt;strong&gt;复用官方的重置流程&lt;/strong&gt;：不自己删会话，而是调用和手动输入 &lt;code&gt;/new&lt;/code&gt; 完全相同的代码路径，缓存清理、钩子通知、状态库更新都由 Hermes 自己完成，结果和手动重置一致。&lt;/li&gt;&#10;&lt;li&gt;&lt;strong&gt;不打断进行中的任务&lt;/strong&gt;：如果会话正在执行任务，就先不重置。&lt;/li&gt;&#10;&lt;li&gt;&lt;strong&gt;只看用户消息的时间&lt;/strong&gt;：Cron 和后台消息不会让会话&amp;quot;保持活跃&amp;quot;，也不会触发重置。&lt;/li&gt;&#10;&lt;/ul&gt;&#10;&lt;p&gt;这就是插件的理想形态：只在边界上插一个判断，具体的事交给 Hermes 已有的机制去做。&lt;/p&gt;&#10;&lt;h3 id="例二替换内部方法修复平台问题"&gt;例二：替换内部方法修复平台问题&#10;&lt;/h3&gt;&lt;p&gt;第二个插件 &lt;code&gt;wecom-media-proactive-fallback&lt;/code&gt; 是我让 Hermes 自己写的，解决企业微信的一个问题：&lt;/p&gt;&#10;&lt;ul&gt;&#10;&lt;li&gt;企业微信机器人回复消息时，优先使用&amp;quot;被动回复&amp;quot;（带着收到消息时的 &lt;code&gt;req_id&lt;/code&gt; 回复）。&lt;code&gt;req_id&lt;/code&gt; 过期后会报错 &lt;code&gt;846604&lt;/code&gt;。&lt;/li&gt;&#10;&lt;li&gt;Hermes 发送文字时，遇到这个错误会自动改用&amp;quot;主动发送&amp;quot;接口重试；但发送图片和文件时没有这层回退，直接失败。&lt;/li&gt;&#10;&lt;li&gt;结果是 Cron 任务要发送文件时，会被标记为发送失败。&lt;/li&gt;&#10;&lt;/ul&gt;&#10;&lt;p&gt;Hermes 没有提供对应的钩子，平台代码在镜像里也不该直接修改（升级会被覆盖）。插件的做法是在 &lt;code&gt;register&lt;/code&gt; 时替换掉内部方法：&lt;/p&gt;&#10;&lt;div class="highlight"&gt;&lt;div class="chroma"&gt;&#10;&lt;table class="lntable"&gt;&lt;tr&gt;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code&gt;&lt;span class="lnt"&gt;1&#10;&lt;/span&gt;&lt;span class="lnt"&gt;2&#10;&lt;/span&gt;&lt;span class="lnt"&gt;3&#10;&lt;/span&gt;&lt;span class="lnt"&gt;4&#10;&lt;/span&gt;&lt;span class="lnt"&gt;5&#10;&lt;/span&gt;&lt;span class="lnt"&gt;6&#10;&lt;/span&gt;&lt;span class="lnt"&gt;7&#10;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&#10;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-python" data-lang="python"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="k"&gt;def&lt;/span&gt; &lt;span class="nf"&gt;register&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;ctx&lt;/span&gt;&lt;span class="p"&gt;):&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; &lt;span class="kn"&gt;from&lt;/span&gt; &lt;span class="nn"&gt;plugins.platforms.wecom.media&lt;/span&gt; &lt;span class="kn"&gt;import&lt;/span&gt; &lt;span class="n"&gt;WeComMediaMixin&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; &lt;span class="n"&gt;current&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;WeComMediaMixin&lt;/span&gt;&lt;span class="o"&gt;.&lt;/span&gt;&lt;span class="n"&gt;_send_media_source&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="nb"&gt;getattr&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;current&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;&amp;#34;_wecom_proactive_media_fallback&amp;#34;&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="kc"&gt;False&lt;/span&gt;&lt;span class="p"&gt;):&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="c1"&gt;# 已经替换过，避免重复安装&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; &lt;span class="n"&gt;WeComMediaMixin&lt;/span&gt;&lt;span class="o"&gt;.&lt;/span&gt;&lt;span class="n"&gt;_send_media_source&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;_send_media_source_with_fallback&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/table&gt;&#10;&lt;/div&gt;&#10;&lt;/div&gt;&lt;p&gt;新方法的逻辑和文字发送保持一致：被动回复失败时，回退到主动发送接口。&lt;/p&gt;&#10;&lt;p&gt;这种写法（monkey patch）很直接，但要清楚代价：它依赖 Hermes 的内部方法名和参数，&lt;strong&gt;上游一改就可能失效甚至出错&lt;/strong&gt;。插件目录里带了测试 &lt;code&gt;tests/test_fallback.py&lt;/code&gt;，升级 Hermes 后应该先跑一遍；等上游修复了，就应该删掉这个插件。&lt;/p&gt;&#10;&lt;p&gt;截至 &lt;code&gt;v0.23.0&lt;/code&gt;，上游做了部分缓解：已知某个会话的流式回复正在进行或已经过期时，发送媒体会直接改走主动接口。但缓存的 &lt;code&gt;req_id&lt;/code&gt; 本身过期、被动回复返回 &lt;code&gt;846604&lt;/code&gt; 时，媒体发送仍然只报错不回退，所以这个插件暂时还需要保留。&lt;/p&gt;&#10;&lt;h2 id="cron定时任务"&gt;Cron：定时任务&#10;&lt;/h2&gt;&lt;p&gt;Hermes 内置的 Cron 有两种用法：&lt;/p&gt;&#10;&lt;ul&gt;&#10;&lt;li&gt;&lt;strong&gt;Agent 模式&lt;/strong&gt;：定时给 Agent 发一段提示词，可以附带技能，让它去完成任务并把结果发到指定渠道。&lt;/li&gt;&#10;&lt;li&gt;&lt;strong&gt;脚本模式&lt;/strong&gt;：定时运行 &lt;code&gt;scripts/&lt;/code&gt; 下的脚本，加上 &lt;code&gt;--no-agent&lt;/code&gt; 就完全不经过模型。&lt;/li&gt;&#10;&lt;/ul&gt;&#10;&lt;p&gt;我现在的定时任务基本都是脚本模式。以每日磁盘检查为例：&lt;/p&gt;&#10;&lt;div class="highlight"&gt;&lt;div class="chroma"&gt;&#10;&lt;table class="lntable"&gt;&lt;tr&gt;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code&gt;&lt;span class="lnt"&gt;1&#10;&lt;/span&gt;&lt;span class="lnt"&gt;2&#10;&lt;/span&gt;&lt;span class="lnt"&gt;3&#10;&lt;/span&gt;&lt;span class="lnt"&gt;4&#10;&lt;/span&gt;&lt;span class="lnt"&gt;5&#10;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&#10;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-bash" data-lang="bash"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;hermes cron create &lt;span class="s1"&gt;&amp;#39;30 9 * * *&amp;#39;&lt;/span&gt; &lt;span class="se"&gt;\&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; --name &lt;span class="s1"&gt;&amp;#39;host disk usage daily alert&amp;#39;&lt;/span&gt; &lt;span class="se"&gt;\&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; --script disk_usage_alert.py &lt;span class="se"&gt;\&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; --no-agent &lt;span class="se"&gt;\&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; --deliver &lt;span class="nb"&gt;local&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/table&gt;&#10;&lt;/div&gt;&#10;&lt;/div&gt;&lt;p&gt;保存在 &lt;code&gt;cron/jobs.json&lt;/code&gt; 里的关键字段：&lt;/p&gt;&#10;&lt;div class="highlight"&gt;&lt;div class="chroma"&gt;&#10;&lt;table class="lntable"&gt;&lt;tr&gt;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code&gt;&lt;span class="lnt"&gt;1&#10;&lt;/span&gt;&lt;span class="lnt"&gt;2&#10;&lt;/span&gt;&lt;span class="lnt"&gt;3&#10;&lt;/span&gt;&lt;span class="lnt"&gt;4&#10;&lt;/span&gt;&lt;span class="lnt"&gt;5&#10;&lt;/span&gt;&lt;span class="lnt"&gt;6&#10;&lt;/span&gt;&lt;span class="lnt"&gt;7&#10;&lt;/span&gt;&lt;span class="lnt"&gt;8&#10;&lt;/span&gt;&lt;span class="lnt"&gt;9&#10;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&#10;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-json" data-lang="json"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="p"&gt;{&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; &lt;span class="nt"&gt;&amp;#34;name&amp;#34;&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;&amp;#34;host disk usage daily alert&amp;#34;&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; &lt;span class="nt"&gt;&amp;#34;script&amp;#34;&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;&amp;#34;disk_usage_alert.py&amp;#34;&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; &lt;span class="nt"&gt;&amp;#34;no_agent&amp;#34;&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; &lt;span class="nt"&gt;&amp;#34;schedule&amp;#34;&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nt"&gt;&amp;#34;kind&amp;#34;&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;&amp;#34;cron&amp;#34;&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nt"&gt;&amp;#34;expr&amp;#34;&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;&amp;#34;30 9 * * *&amp;#34;&lt;/span&gt; &lt;span class="p"&gt;},&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; &lt;span class="nt"&gt;&amp;#34;deliver&amp;#34;&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;&amp;#34;local&amp;#34;&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; &lt;span class="nt"&gt;&amp;#34;last_status&amp;#34;&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;&amp;#34;ok&amp;#34;&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; &lt;span class="nt"&gt;&amp;#34;failure_streak&amp;#34;&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="p"&gt;}&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/table&gt;&#10;&lt;/div&gt;&#10;&lt;/div&gt;&lt;h3 id="为什么用脚本模式"&gt;为什么用脚本模式&#10;&lt;/h3&gt;&lt;p&gt;磁盘检查这种事，规则完全确定：超过 90% 就告警，没超过就安静。让模型来做反而更慢、更贵，还可能不稳定。脚本模式的约定也很简单：&lt;/p&gt;&#10;&lt;ul&gt;&#10;&lt;li&gt;脚本输出为空，就什么都不发。&lt;/li&gt;&#10;&lt;li&gt;脚本自己负责告警（我的脚本直接调用企业微信群机器人的 Webhook），所以 &lt;code&gt;deliver&lt;/code&gt; 设为 &lt;code&gt;local&lt;/code&gt;，结果只留在本地记录中。&lt;/li&gt;&#10;&lt;li&gt;脚本退出码非 0，Cron 会记录失败，&lt;code&gt;failure_streak&lt;/code&gt; 计数加一，可以用 &lt;code&gt;hermes cron runs&lt;/code&gt; 和 &lt;code&gt;hermes cron incidents&lt;/code&gt; 查看。&lt;/li&gt;&#10;&lt;/ul&gt;&#10;&lt;h3 id="踩坑脚本里的-path-不会展开"&gt;踩坑：脚本里的 PATH 不会展开&#10;&lt;/h3&gt;&lt;p&gt;这个任务上线后第一次就失败了，&lt;code&gt;hermes cron runs&lt;/code&gt; 里记录的错误是找不到 &lt;code&gt;df&lt;/code&gt; 命令：&lt;/p&gt;&#10;&lt;div class="highlight"&gt;&lt;div class="chroma"&gt;&#10;&lt;table class="lntable"&gt;&lt;tr&gt;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code&gt;&lt;span class="lnt"&gt;1&#10;&lt;/span&gt;&lt;span class="lnt"&gt;2&#10;&lt;/span&gt;&lt;span class="lnt"&gt;3&#10;&lt;/span&gt;&lt;span class="lnt"&gt;4&#10;&lt;/span&gt;&lt;span class="lnt"&gt;5&#10;&lt;/span&gt;&lt;span class="lnt"&gt;6&#10;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&#10;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-text" data-lang="text"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;Script exited with code 1&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;...&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; File &amp;#34;/opt/data/scripts/disk_usage_alert.py&amp;#34;, line 58, in parse_df&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; out = subprocess.check_output([&amp;#34;df&amp;#34;, &amp;#34;-PTk&amp;#34;], text=True)&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;...&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;FileNotFoundError: [Errno 2] No such file or directory: &amp;#39;df&amp;#39;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/table&gt;&#10;&lt;/div&gt;&#10;&lt;/div&gt;&lt;p&gt;原因是 Cron 运行脚本时会把 Profile 的 &lt;code&gt;.env&lt;/code&gt; 叠加到环境变量上。我在 &lt;code&gt;.env&lt;/code&gt; 里写了类似 &lt;code&gt;PATH=/some/bin:${PATH}&lt;/code&gt; 的配置，而 &lt;code&gt;.env&lt;/code&gt; 中的 &lt;code&gt;${PATH}&lt;/code&gt; 是&lt;strong&gt;按字面量&lt;/strong&gt;处理的，不会展开。结果 &lt;code&gt;PATH&lt;/code&gt; 变成了一个无效值，系统命令全部找不到。&lt;/p&gt;&#10;&lt;p&gt;解决方法是在脚本中调用系统命令时写绝对路径：&lt;/p&gt;&#10;&lt;div class="highlight"&gt;&lt;div class="chroma"&gt;&#10;&lt;table class="lntable"&gt;&lt;tr&gt;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code&gt;&lt;span class="lnt"&gt;1&#10;&lt;/span&gt;&lt;span class="lnt"&gt;2&#10;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&#10;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-python" data-lang="python"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="c1"&gt;# Cron 会把 Profile .env 中的 PATH 原样叠加，${PATH} 不会展开&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="n"&gt;out&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;subprocess&lt;/span&gt;&lt;span class="o"&gt;.&lt;/span&gt;&lt;span class="n"&gt;check_output&lt;/span&gt;&lt;span class="p"&gt;([&lt;/span&gt;&lt;span class="s2"&gt;&amp;#34;/usr/bin/df&amp;#34;&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;&amp;#34;-PTk&amp;#34;&lt;/span&gt;&lt;span class="p"&gt;],&lt;/span&gt; &lt;span class="n"&gt;text&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="kc"&gt;True&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/table&gt;&#10;&lt;/div&gt;&#10;&lt;/div&gt;&lt;p&gt;更彻底的做法是在 &lt;code&gt;.env&lt;/code&gt; 里写完整的 &lt;code&gt;PATH&lt;/code&gt;，不要依赖变量展开。&lt;/p&gt;&#10;&lt;h2 id="总结"&gt;总结&#10;&lt;/h2&gt;&lt;ul&gt;&#10;&lt;li&gt;&lt;strong&gt;Skills&lt;/strong&gt; 教模型做事：&lt;code&gt;description&lt;/code&gt; 写清楚何时使用，正文写怎么做；用不到的内置技能全部禁用。&lt;/li&gt;&#10;&lt;li&gt;&lt;strong&gt;Plugins&lt;/strong&gt; 改程序行为：优先用钩子并复用 Hermes 已有流程；替换内部方法要配测试，并在上游修复后删除。&lt;/li&gt;&#10;&lt;li&gt;&lt;strong&gt;Cron&lt;/strong&gt; 按时间触发：规则确定的任务用 &lt;code&gt;--no-agent&lt;/code&gt; 脚本模式，注意 &lt;code&gt;.env&lt;/code&gt; 中 &lt;code&gt;PATH&lt;/code&gt; 不展开的问题。&lt;/li&gt;&#10;&lt;/ul&gt;&#10;&lt;p&gt;到这里，Hermes 的部署、模型、接入、角色和扩展都讲完了。回到&lt;a class="link" href="https://www.iminling.com/ai/hermes/hermes-agent-architecture-overview/" &gt;总览&lt;/a&gt;，可以再对照一遍各层之间的关系。&lt;/p&gt;&#10;</description></item><item><title>Hermes Agent 接入与 Profile 篇：一个网关服务多个平台和角色</title><link>https://www.iminling.com/ai/hermes/hermes-agent-gateway-profiles/</link><pubDate>Thu, 19 Nov 2026 00:00:00 +0000</pubDate><guid>https://www.iminling.com/ai/hermes/hermes-agent-gateway-profiles/</guid><description>&lt;img src="https://images.iminling.com/i/2026/11/19/6b1baa5dd7d81d1a1f5f9529ceea41b8.webp" alt="Featured image of post Hermes Agent 接入与 Profile 篇：一个网关服务多个平台和角色" /&gt;&lt;h2 id="写在前面"&gt;写在前面&#10;&lt;/h2&gt;&lt;p&gt;这是 Hermes Agent 架构系列的第四篇，讲接入层和角色层。整体分层见 &lt;a class="link" href="https://www.iminling.com/ai/hermes/hermes-agent-architecture-overview/" &gt;Hermes Agent 自托管架构总览&lt;/a&gt;。&lt;/p&gt;&#10;&lt;p&gt;一开始我只有一个 Agent，所有事情都找它。用久了问题就来了：给同事排查问题的技能和家里人用的技能混在一起，记忆互相污染，一个回答风格也满足不了所有人。&lt;/p&gt;&#10;&lt;p&gt;Hermes 的解决方式是 &lt;strong&gt;Profile&lt;/strong&gt;：每个 Profile 是一个独立的 Agent，有自己的人设、技能、记忆和聊天机器人。再配合网关的多路复用，一个容器、一个网关进程就能同时服务所有 Profile。&lt;/p&gt;&#10;&lt;h2 id="整体结构"&gt;整体结构&#10;&lt;/h2&gt;&lt;pre class="mermaid" style="visibility:hidden"&gt;flowchart LR&#10; subgraph Bots["各平台机器人"]&#10; direction TB&#10; B0[飞书 / Telegram 机器人]&#10; B1[企微 / Telegram 机器人]&#10; B2[企微机器人]&#10; B3[微信]&#10; end&#10;&#10; GW[网关进程 multiplex_profiles]&#10;&#10; subgraph Profiles["Profiles"]&#10; direction TB&#10; P0[default 个人助手]&#10; P1[dev / product / tester]&#10; P2[kb 知识库问答]&#10; P3[home 家庭助手]&#10; end&#10;&#10; B0 --&gt; GW --&gt; P0&#10; B1 --&gt; GW --&gt; P1&#10; B2 --&gt; GW --&gt; P2&#10; B3 --&gt; GW --&gt; P3&lt;/pre&gt;&lt;p&gt;核心规则只有一条：&lt;strong&gt;每个 Profile 有自己的机器人凭证，消息从哪个机器人进来，就交给哪个 Profile 处理。&lt;/strong&gt;&lt;/p&gt;&#10;&lt;h2 id="profile-是什么"&gt;Profile 是什么&#10;&lt;/h2&gt;&lt;p&gt;一个 Profile 就是数据目录下 &lt;code&gt;profiles/&amp;lt;name&amp;gt;/&lt;/code&gt; 的一个子目录，结构和根目录（&lt;code&gt;default&lt;/code&gt; Profile）几乎一样：&lt;/p&gt;&#10;&lt;div class="highlight"&gt;&lt;div class="chroma"&gt;&#10;&lt;table class="lntable"&gt;&lt;tr&gt;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code&gt;&lt;span class="lnt"&gt;1&#10;&lt;/span&gt;&lt;span class="lnt"&gt;2&#10;&lt;/span&gt;&lt;span class="lnt"&gt;3&#10;&lt;/span&gt;&lt;span class="lnt"&gt;4&#10;&lt;/span&gt;&lt;span class="lnt"&gt;5&#10;&lt;/span&gt;&lt;span class="lnt"&gt;6&#10;&lt;/span&gt;&lt;span class="lnt"&gt;7&#10;&lt;/span&gt;&lt;span class="lnt"&gt;8&#10;&lt;/span&gt;&lt;span class="lnt"&gt;9&#10;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&#10;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-text" data-lang="text"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;profiles/dev/&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;├── config.yaml # 这个 Profile 自己的配置&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;├── .env # 自己的机器人凭证和密钥&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;├── SOUL.md # 自己的人设&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;├── memories/ # 自己的长期记忆&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;├── skills/ # 自己的技能集合&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;├── cron/ # 自己的定时任务&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;├── sessions/&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;└── state.db # 自己的会话数据库&#10;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/table&gt;&#10;&lt;/div&gt;&#10;&lt;/div&gt;&lt;p&gt;用 &lt;code&gt;hermes profile&lt;/code&gt; 管理：&lt;/p&gt;&#10;&lt;div class="highlight"&gt;&lt;div class="chroma"&gt;&#10;&lt;table class="lntable"&gt;&lt;tr&gt;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code&gt;&lt;span class="lnt"&gt;1&#10;&lt;/span&gt;&lt;span class="lnt"&gt;2&#10;&lt;/span&gt;&lt;span class="lnt"&gt;3&#10;&lt;/span&gt;&lt;span class="lnt"&gt;4&#10;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&#10;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-bash" data-lang="bash"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;hermes profile list &lt;span class="c1"&gt;# 列出所有 Profile&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;hermes profile create &amp;lt;name&amp;gt; &lt;span class="c1"&gt;# 新建&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;hermes profile show &amp;lt;name&amp;gt; &lt;span class="c1"&gt;# 查看详情&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;hermes profile describe &amp;lt;name&amp;gt; &lt;span class="c1"&gt;# 读取或设置描述&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/table&gt;&#10;&lt;/div&gt;&#10;&lt;/div&gt;&lt;p&gt;我按使用者和用途分了六个 Profile：&lt;/p&gt;&#10;&lt;table&gt;&#10;&#9;&lt;thead&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;Profile&lt;/th&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;用途&lt;/th&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;接入平台&lt;/th&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&lt;/thead&gt;&#10;&#9;&lt;tbody&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;default&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;我自己的个人助手&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;飞书、Telegram&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;dev&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;开发排查助手&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;企业微信、Telegram&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;product&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;产品业务问答&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;企业微信、Telegram&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;tester&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;测试问题排查&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;企业微信&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;kb&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;知识库（Knowledge Base）问答&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;企业微信&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;home&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;家里人用的助手&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;微信&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&lt;/tbody&gt;&#10;&lt;/table&gt;&#10;&lt;p&gt;拆分的依据是&lt;strong&gt;谁在用、需要什么能力、能接触什么数据&lt;/strong&gt;。例如 &lt;code&gt;home&lt;/code&gt; 的描述写得很明确：家里人用的中文助手，不访问其他 Profile，也不接线上系统；它的技能也只保留最基础的一套。&lt;/p&gt;&#10;&lt;h2 id="多路复用一个网关服务所有-profile"&gt;多路复用：一个网关服务所有 Profile&#10;&lt;/h2&gt;&lt;div class="highlight"&gt;&lt;div class="chroma"&gt;&#10;&lt;table class="lntable"&gt;&lt;tr&gt;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code&gt;&lt;span class="lnt"&gt;1&#10;&lt;/span&gt;&lt;span class="lnt"&gt;2&#10;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&#10;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-yaml" data-lang="yaml"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nt"&gt;gateway&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;multiplex_profiles&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/table&gt;&#10;&lt;/div&gt;&#10;&lt;/div&gt;&lt;p&gt;开启后，&lt;code&gt;default&lt;/code&gt; Profile 的网关进程会同时服务 &lt;code&gt;profiles/&lt;/code&gt; 下所有可用的 Profile。会话的键会带上 Profile 标识，不同 Profile 的对话不会串在一起。在新版本中，这已经是默认且唯一支持的运行方式，不再推荐每个 Profile 单独跑一个网关。&lt;/p&gt;&#10;&lt;p&gt;消息如何找到对应的 Profile，Hermes 支持几种拓扑。我用的是最简单的一种：&lt;strong&gt;每个 Profile 持有自己的机器人凭证&lt;/strong&gt;。消息由哪个机器人收到，就在哪个 Profile 里处理，回复也从同一个机器人发出。另一种做法是多个 Profile 共用一个机器人，再通过 &lt;code&gt;profile_routes&lt;/code&gt; 配置路由，我没有用。&lt;/p&gt;&#10;&lt;h3 id="凭证隔离"&gt;凭证隔离&#10;&lt;/h3&gt;&lt;p&gt;多路复用时，各 Profile 的 &lt;code&gt;.env&lt;/code&gt; 不会混进进程的全局环境变量：&lt;/p&gt;&#10;&lt;ul&gt;&#10;&lt;li&gt;进程环境变量里只有 &lt;code&gt;default&lt;/code&gt; Profile 的值。&lt;/li&gt;&#10;&lt;li&gt;其他 Profile 的密钥、白名单（如 &lt;code&gt;FEISHU_ALLOWED_USERS&lt;/code&gt;）只在该 Profile 自己的作用域内生效。&lt;/li&gt;&#10;&lt;li&gt;在某个 Profile 里读不到的配置，不会去借用全局环境变量。&lt;/li&gt;&#10;&lt;/ul&gt;&#10;&lt;p&gt;所以每个 Profile 的 &lt;code&gt;.env&lt;/code&gt; 只需要写自己的机器人凭证和权限配置，不用担心互相泄漏。&lt;/p&gt;&#10;&lt;h3 id="克隆-profile-的坑"&gt;克隆 Profile 的坑&#10;&lt;/h3&gt;&lt;p&gt;新建 Profile 时经常从已有的复制一份。Hermes 的克隆默认&lt;strong&gt;不会&lt;/strong&gt;带走机器人凭证、白名单和 home channel，因为两个 Profile 抢同一个机器人会导致消息错乱；除非显式加 &lt;code&gt;--clone-channels&lt;/code&gt;。克隆之后要给新 Profile 单独申请一个机器人。&lt;/p&gt;&#10;&lt;h2 id="平台接入与展示"&gt;平台接入与展示&#10;&lt;/h2&gt;&lt;p&gt;&lt;code&gt;default&lt;/code&gt; Profile 的平台配置：&lt;/p&gt;&#10;&lt;div class="highlight"&gt;&lt;div class="chroma"&gt;&#10;&lt;table class="lntable"&gt;&lt;tr&gt;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code&gt;&lt;span class="lnt"&gt; 1&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 2&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 3&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 4&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 5&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 6&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 7&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 8&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 9&#10;&lt;/span&gt;&lt;span class="lnt"&gt;10&#10;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&#10;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-yaml" data-lang="yaml"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nt"&gt;platforms&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;feishu&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;enabled&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;home_channel&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;platform&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;feishu&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;chat_id&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;&amp;lt;your-chat-id&amp;gt;&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;webhook&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;enabled&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;api_server&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;enabled&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/table&gt;&#10;&lt;/div&gt;&#10;&lt;/div&gt;&lt;p&gt;凭证都放在 &lt;code&gt;.env&lt;/code&gt; 里，例如 &lt;code&gt;FEISHU_APP_ID&lt;/code&gt;、&lt;code&gt;FEISHU_APP_SECRET&lt;/code&gt;、&lt;code&gt;TELEGRAM_BOT_TOKEN&lt;/code&gt;，以及控制谁能使用的 &lt;code&gt;FEISHU_ALLOWED_USERS&lt;/code&gt;、&lt;code&gt;TELEGRAM_ALLOWED_USERS&lt;/code&gt;。&lt;strong&gt;一定要配白名单&lt;/strong&gt;，否则任何人找到机器人都能让它执行命令。&lt;/p&gt;&#10;&lt;p&gt;&lt;code&gt;home_channel&lt;/code&gt; 是这个 Profile 的&amp;quot;主频道&amp;quot;，Cron 任务结果、后台通知默认发到这里。&lt;/p&gt;&#10;&lt;p&gt;不同平台的展示能力差别很大。终端里流式输出、实时显示工具进度很好用，但放到聊天软件里就会刷屏。所以按平台关掉中间过程：&lt;/p&gt;&#10;&lt;div class="highlight"&gt;&lt;div class="chroma"&gt;&#10;&lt;table class="lntable"&gt;&lt;tr&gt;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code&gt;&lt;span class="lnt"&gt; 1&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 2&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 3&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 4&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 5&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 6&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 7&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 8&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 9&#10;&lt;/span&gt;&lt;span class="lnt"&gt;10&#10;&lt;/span&gt;&lt;span class="lnt"&gt;11&#10;&lt;/span&gt;&lt;span class="lnt"&gt;12&#10;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&#10;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-yaml" data-lang="yaml"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nt"&gt;display&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;tool_progress&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;all&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;interim_assistant_messages&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;platforms&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;telegram&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;streaming&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="kc"&gt;false&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;interim_assistant_messages&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="kc"&gt;false&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;wecom&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;interim_assistant_messages&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="kc"&gt;false&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;feishu&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;tool_progress&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="kc"&gt;false&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;interim_assistant_messages&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="kc"&gt;false&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/table&gt;&#10;&lt;/div&gt;&#10;&lt;/div&gt;&lt;p&gt;效果是：聊天软件里只收到最终回复，过程信息留在 Dashboard 和日志中。&lt;/p&gt;&#10;&lt;p&gt;另外，&lt;code&gt;display.busy_input_mode: interrupt&lt;/code&gt; 决定 Agent 正在干活时又收到新消息怎么办：&lt;/p&gt;&#10;&lt;ul&gt;&#10;&lt;li&gt;&lt;code&gt;interrupt&lt;/code&gt;：打断当前任务，处理新消息&lt;/li&gt;&#10;&lt;li&gt;&lt;code&gt;queue&lt;/code&gt;：排队，等当前任务完成后再处理&lt;/li&gt;&#10;&lt;li&gt;&lt;code&gt;steer&lt;/code&gt;：把新消息作为补充指令注入当前任务&lt;/li&gt;&#10;&lt;/ul&gt;&#10;&lt;h2 id="会话怎么划分"&gt;会话怎么划分&#10;&lt;/h2&gt;&lt;h3 id="群聊按人隔离"&gt;群聊按人隔离&#10;&lt;/h3&gt;&lt;div class="highlight"&gt;&lt;div class="chroma"&gt;&#10;&lt;table class="lntable"&gt;&lt;tr&gt;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code&gt;&lt;span class="lnt"&gt;1&#10;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&#10;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-yaml" data-lang="yaml"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nt"&gt;group_sessions_per_user&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/table&gt;&#10;&lt;/div&gt;&#10;&lt;/div&gt;&lt;p&gt;在群里，每个人和机器人的对话是独立的会话，A 问的问题不会混进 B 的上下文。这对多人共用的 &lt;code&gt;dev&lt;/code&gt;、&lt;code&gt;tester&lt;/code&gt; 尤其重要。&lt;/p&gt;&#10;&lt;h3 id="会话自动重置"&gt;会话自动重置&#10;&lt;/h3&gt;&lt;p&gt;聊天软件里的对话没有&amp;quot;新建会话&amp;quot;按钮，一个会话会无限延续，上下文越积越长。我的配置是每天凌晨 4 点切一次新会话：&lt;/p&gt;&#10;&lt;div class="highlight"&gt;&lt;div class="chroma"&gt;&#10;&lt;table class="lntable"&gt;&lt;tr&gt;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code&gt;&lt;span class="lnt"&gt;1&#10;&lt;/span&gt;&lt;span class="lnt"&gt;2&#10;&lt;/span&gt;&lt;span class="lnt"&gt;3&#10;&lt;/span&gt;&lt;span class="lnt"&gt;4&#10;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&#10;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-yaml" data-lang="yaml"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nt"&gt;session_reset&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;mode&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;daily &lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="c"&gt;# idle | daily | both | none&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;idle_minutes&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="m"&gt;1440&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;at_hour&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="m"&gt;4&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/table&gt;&#10;&lt;/div&gt;&#10;&lt;/div&gt;&lt;p&gt;需要注意：上游从 &lt;code&gt;v2026.9.11&lt;/code&gt; 开始移除了按时间自动切换会话的定时器，这段配置在新版本里&lt;strong&gt;单独存在时不再生效&lt;/strong&gt;，只有手动发送 &lt;code&gt;/new&lt;/code&gt; 或 &lt;code&gt;/stop&lt;/code&gt; 才会切换。我用一个社区插件把这个能力补了回来，原理在扩展篇讲。&lt;/p&gt;&#10;&lt;h2 id="不同角色的不同约束"&gt;不同角色的不同约束&#10;&lt;/h2&gt;&lt;p&gt;Profile 的另一个好处是可以给不同角色设置不同的安全边界。比如工具调用循环保护：&lt;/p&gt;&#10;&lt;div class="highlight"&gt;&lt;div class="chroma"&gt;&#10;&lt;table class="lntable"&gt;&lt;tr&gt;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code&gt;&lt;span class="lnt"&gt;1&#10;&lt;/span&gt;&lt;span class="lnt"&gt;2&#10;&lt;/span&gt;&lt;span class="lnt"&gt;3&#10;&lt;/span&gt;&lt;span class="lnt"&gt;4&#10;&lt;/span&gt;&lt;span class="lnt"&gt;5&#10;&lt;/span&gt;&lt;span class="lnt"&gt;6&#10;&lt;/span&gt;&lt;span class="lnt"&gt;7&#10;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&#10;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-yaml" data-lang="yaml"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nt"&gt;tool_loop_guardrails&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;warnings_enabled&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;hard_stop_enabled&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="c"&gt;# dev、tester 开启；default 关闭&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;hard_stop_after&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;exact_failure&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="m"&gt;5&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;same_tool_failure&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="m"&gt;8&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;idempotent_no_progress&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="m"&gt;5&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/table&gt;&#10;&lt;/div&gt;&#10;&lt;/div&gt;&lt;p&gt;&lt;code&gt;default&lt;/code&gt; 是我自己用，遇到工具反复失败时只警告不强停，让我自己判断；&lt;code&gt;dev&lt;/code&gt; 和 &lt;code&gt;tester&lt;/code&gt; 是给别人用的，同一个工具连续失败到阈值就强制停止，避免它在无人看管时空转烧钱。&lt;code&gt;kb&lt;/code&gt; 还通过 &lt;code&gt;disabled_toolsets&lt;/code&gt; 关掉了不需要的工具集，只保留问答所需的能力。&lt;/p&gt;&#10;&lt;h2 id="总结"&gt;总结&#10;&lt;/h2&gt;&lt;ul&gt;&#10;&lt;li&gt;Profile 是独立的 Agent：独立的人设、技能、记忆、会话库和机器人。&lt;/li&gt;&#10;&lt;li&gt;&lt;code&gt;multiplex_profiles&lt;/code&gt; 让一个网关进程服务所有 Profile，凭证按 Profile 隔离。&lt;/li&gt;&#10;&lt;li&gt;每个 Profile 一个机器人，是最简单可靠的路由方式；克隆 Profile 时记得换机器人。&lt;/li&gt;&#10;&lt;li&gt;聊天平台要关掉中间过程消息，群聊按人隔离会话，并配置会话自动重置。&lt;/li&gt;&#10;&lt;li&gt;给别人用的 Profile，约束要比自己用的更严格。&lt;/li&gt;&#10;&lt;/ul&gt;&#10;&lt;p&gt;下一篇讲扩展层：Skills、插件和 Cron。&lt;/p&gt;&#10;</description></item><item><title>Hermes Agent 模型篇：自定义 Provider、主辅模型分工与 MoA</title><link>https://www.iminling.com/ai/hermes/hermes-agent-model-config/</link><pubDate>Thu, 19 Nov 2026 00:00:00 +0000</pubDate><guid>https://www.iminling.com/ai/hermes/hermes-agent-model-config/</guid><description>&lt;img src="https://images.iminling.com/i/2026/11/19/fe531d198cdd4567d3cfd9d9738f98b8.webp" alt="Featured image of post Hermes Agent 模型篇：自定义 Provider、主辅模型分工与 MoA" /&gt;&lt;h2 id="写在前面"&gt;写在前面&#10;&lt;/h2&gt;&lt;p&gt;这是 Hermes Agent 架构系列的第三篇，讲模型层。整体分层见 &lt;a class="link" href="https://www.iminling.com/ai/hermes/hermes-agent-architecture-overview/" &gt;Hermes Agent 自托管架构总览&lt;/a&gt;。&lt;/p&gt;&#10;&lt;p&gt;Agent 和普通聊天最大的区别是调用量：一次任务可能来回几十轮工具调用，再加上上下文压缩、标题生成、审批判断等后台调用。模型层的核心问题就是&lt;strong&gt;哪些调用值得用好模型，哪些用便宜模型就够了&lt;/strong&gt;。&lt;/p&gt;&#10;&lt;h2 id="整体结构"&gt;整体结构&#10;&lt;/h2&gt;&lt;pre class="mermaid" style="visibility:hidden"&gt;flowchart LR&#10; Agent[Agent 对话循环] --&gt;|每轮对话| Main[主模型 grok-4.7]&#10; Agent --&gt;|压缩 / 审批 / 标题 / 技能审查 / 复盘| Aux[辅助模型 glm-5.3-flash]&#10; Agent -.-&gt;|/moa 标记的回合| Refs[参考模型 x3]&#10; Refs -.-&gt; Main&#10; Main --&gt; GW[NewAPI 网关]&#10; Aux --&gt; GW&lt;/pre&gt;&lt;p&gt;所有模型调用最终都经过一个自建的 NewAPI 网关，Hermes 只认识网关地址和密钥，切换上游厂商不需要改 Hermes 配置。&lt;/p&gt;&#10;&lt;h2 id="用-named-provider-接入自建网关"&gt;用 named provider 接入自建网关&#10;&lt;/h2&gt;&lt;p&gt;NewAPI 这类网关对外提供 OpenAI 兼容接口。在 Hermes 中，推荐在 &lt;code&gt;providers:&lt;/code&gt; 下为网关声明&lt;strong&gt;带名字的 provider&lt;/strong&gt;（named provider），并按协议拆开：&lt;/p&gt;&#10;&lt;div class="highlight"&gt;&lt;div class="chroma"&gt;&#10;&lt;table class="lntable"&gt;&lt;tr&gt;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code&gt;&lt;span class="lnt"&gt; 1&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 2&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 3&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 4&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 5&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 6&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 7&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 8&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 9&#10;&lt;/span&gt;&lt;span class="lnt"&gt;10&#10;&lt;/span&gt;&lt;span class="lnt"&gt;11&#10;&lt;/span&gt;&lt;span class="lnt"&gt;12&#10;&lt;/span&gt;&lt;span class="lnt"&gt;13&#10;&lt;/span&gt;&lt;span class="lnt"&gt;14&#10;&lt;/span&gt;&lt;span class="lnt"&gt;15&#10;&lt;/span&gt;&lt;span class="lnt"&gt;16&#10;&lt;/span&gt;&lt;span class="lnt"&gt;17&#10;&lt;/span&gt;&lt;span class="lnt"&gt;18&#10;&lt;/span&gt;&lt;span class="lnt"&gt;19&#10;&lt;/span&gt;&lt;span class="lnt"&gt;20&#10;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&#10;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-yaml" data-lang="yaml"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nt"&gt;providers&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;newapi-grok&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;api&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;https://newapi.example.com/v1&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;key_env&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;HERMES_CUSTOM_NEWAPI_GROK_API_KEY&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;transport&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;codex_responses&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;discover_models&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="kc"&gt;false&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;models&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;grok-4.7&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;context_length&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="m"&gt;500000&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;newapi-glm&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;api&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;https://newapi.example.com/v1&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;key_env&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;HERMES_CUSTOM_NEWAPI_GLM_API_KEY&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;transport&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;chat_completions&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;discover_models&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="kc"&gt;false&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;models&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;glm-5.3-flash&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;context_length&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="m"&gt;1310720&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;glm-5.3&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;context_length&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="m"&gt;1310720&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/table&gt;&#10;&lt;/div&gt;&#10;&lt;/div&gt;&lt;p&gt;几个关键字段：&lt;/p&gt;&#10;&lt;ul&gt;&#10;&lt;li&gt;&lt;code&gt;key_env&lt;/code&gt;：只写环境变量名，真实密钥放在 &lt;code&gt;.env&lt;/code&gt;。配置文件可以放心备份和分享。&lt;/li&gt;&#10;&lt;li&gt;&lt;code&gt;transport&lt;/code&gt;：接口协议，可选 &lt;code&gt;chat_completions&lt;/code&gt;、&lt;code&gt;codex_responses&lt;/code&gt;（OpenAI Responses 风格）和 &lt;code&gt;anthropic_messages&lt;/code&gt;。同一个网关后面的不同模型可以走不同协议，按上游实际支持的选。&lt;/li&gt;&#10;&lt;li&gt;&lt;code&gt;models&lt;/code&gt; + &lt;code&gt;context_length&lt;/code&gt;：手动声明可用模型和上下文长度。上下文压缩的触发点是按这个长度计算的，&lt;strong&gt;写错会导致压缩过早或过晚&lt;/strong&gt;。&lt;/li&gt;&#10;&lt;li&gt;&lt;code&gt;discover_models: false&lt;/code&gt;：不向网关拉取模型列表，只使用 &lt;code&gt;models&lt;/code&gt; 里声明的模型。&lt;/li&gt;&#10;&lt;/ul&gt;&#10;&lt;p&gt;为什么要拆成多个 named provider，而不是只写一个 &lt;code&gt;provider: custom&lt;/code&gt; 再指定 &lt;code&gt;api_mode&lt;/code&gt;？因为 Hermes 对普通 custom 端点很保守：如果域名不是已知的 OpenAI 或 xAI 地址，它会忽略 &lt;code&gt;api_mode: codex_responses&lt;/code&gt; 并回退到 &lt;code&gt;chat_completions&lt;/code&gt;。只有 named provider 上的 &lt;code&gt;transport&lt;/code&gt; 才是 Hermes 认可的明确协议声明。这个细节直接影响提示词缓存能不能命中，单独写了一篇排查文章：&lt;a class="link" href="https://www.iminling.com/ai/hermes/hermes-agent-newapi-prompt-cache/" &gt;Hermes 接入 New API 的提示词缓存排查&lt;/a&gt;。&lt;/p&gt;&#10;&#10; &lt;blockquote&gt;&#10; &lt;p&gt;旧版本使用 &lt;code&gt;custom_providers:&lt;/code&gt; 列表（每项带 &lt;code&gt;name&lt;/code&gt; 和 &lt;code&gt;base_url&lt;/code&gt;），我的配置里至今还是这种写法。当前版本仍然兼容它，但源码中已标注为 legacy，新配置建议直接写 &lt;code&gt;providers:&lt;/code&gt;。&lt;/p&gt;&#10;&#10; &lt;/blockquote&gt;&#10;&lt;p&gt;引用时使用 &lt;code&gt;custom:&amp;lt;name&amp;gt;&lt;/code&gt; 作为 provider：&lt;/p&gt;&#10;&lt;div class="highlight"&gt;&lt;div class="chroma"&gt;&#10;&lt;table class="lntable"&gt;&lt;tr&gt;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code&gt;&lt;span class="lnt"&gt;1&#10;&lt;/span&gt;&lt;span class="lnt"&gt;2&#10;&lt;/span&gt;&lt;span class="lnt"&gt;3&#10;&lt;/span&gt;&lt;span class="lnt"&gt;4&#10;&lt;/span&gt;&lt;span class="lnt"&gt;5&#10;&lt;/span&gt;&lt;span class="lnt"&gt;6&#10;&lt;/span&gt;&lt;span class="lnt"&gt;7&#10;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&#10;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-yaml" data-lang="yaml"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nt"&gt;model&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;default&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;grok-4.7&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;provider&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;custom:newapi-grok&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;aliases&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;grok&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;custom:newapi-grok/grok-4.7&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;flash&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;custom:newapi-glm/glm-5.3-flash&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;glm&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;custom:newapi-glm/glm-5.3&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/table&gt;&#10;&lt;/div&gt;&#10;&lt;/div&gt;&lt;p&gt;&lt;code&gt;aliases&lt;/code&gt; 给常用模型起短名，切换模型时不用输入完整的 &lt;code&gt;provider/model&lt;/code&gt;。&lt;/p&gt;&#10;&lt;h2 id="主辅模型分工"&gt;主辅模型分工&#10;&lt;/h2&gt;&lt;p&gt;主模型负责真正的对话和工具调用，推理强度开到 &lt;code&gt;high&lt;/code&gt;：&lt;/p&gt;&#10;&lt;div class="highlight"&gt;&lt;div class="chroma"&gt;&#10;&lt;table class="lntable"&gt;&lt;tr&gt;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code&gt;&lt;span class="lnt"&gt;1&#10;&lt;/span&gt;&lt;span class="lnt"&gt;2&#10;&lt;/span&gt;&lt;span class="lnt"&gt;3&#10;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&#10;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-yaml" data-lang="yaml"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nt"&gt;agent&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;max_turns&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="m"&gt;150&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;reasoning_effort&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;high&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/table&gt;&#10;&lt;/div&gt;&#10;&lt;/div&gt;&lt;p&gt;除了对话，Hermes 还有很多后台调用。这些任务不需要强推理，全部交给 &lt;code&gt;glm-5.3-flash&lt;/code&gt; 并关闭推理：&lt;/p&gt;&#10;&lt;div class="highlight"&gt;&lt;div class="chroma"&gt;&#10;&lt;table class="lntable"&gt;&lt;tr&gt;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code&gt;&lt;span class="lnt"&gt; 1&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 2&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 3&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 4&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 5&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 6&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 7&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 8&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 9&#10;&lt;/span&gt;&lt;span class="lnt"&gt;10&#10;&lt;/span&gt;&lt;span class="lnt"&gt;11&#10;&lt;/span&gt;&lt;span class="lnt"&gt;12&#10;&lt;/span&gt;&lt;span class="lnt"&gt;13&#10;&lt;/span&gt;&lt;span class="lnt"&gt;14&#10;&lt;/span&gt;&lt;span class="lnt"&gt;15&#10;&lt;/span&gt;&lt;span class="lnt"&gt;16&#10;&lt;/span&gt;&lt;span class="lnt"&gt;17&#10;&lt;/span&gt;&lt;span class="lnt"&gt;18&#10;&lt;/span&gt;&lt;span class="lnt"&gt;19&#10;&lt;/span&gt;&lt;span class="lnt"&gt;20&#10;&lt;/span&gt;&lt;span class="lnt"&gt;21&#10;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&#10;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-yaml" data-lang="yaml"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nt"&gt;auxiliary&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;compression&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="c"&gt;# 上下文压缩时生成摘要&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;provider&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;custom:newapi-glm&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;model&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;glm-5.3-flash&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;reasoning_effort&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;none&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;approval&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="c"&gt;# 判断工具调用是否需要审批&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;provider&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;custom:newapi-glm&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;model&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;glm-5.3-flash&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;reasoning_effort&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;none&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;title_generation&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="c"&gt;# 给会话生成标题&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;provider&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;custom:newapi-glm&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;model&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;glm-5.3-flash&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;reasoning_effort&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;none&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;curator&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="c"&gt;# 审查技能使用情况，技能多时很耗时&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;provider&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;custom:newapi-glm&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;model&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;glm-5.3-flash&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;reasoning_effort&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;none&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;background_review&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="c"&gt;# 后台复盘&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;provider&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;custom:newapi-glm&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;model&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;glm-5.3-flash&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;reasoning_effort&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;none&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/table&gt;&#10;&lt;/div&gt;&#10;&lt;/div&gt;&lt;p&gt;这些任务的 provider 默认是 &lt;code&gt;auto&lt;/code&gt;，也就是继承主模型。主模型越贵，这一步省下的钱越多，响应也更快。&lt;/p&gt;&#10;&lt;p&gt;选择辅助模型时有一个前提：&lt;strong&gt;上下文要足够长&lt;/strong&gt;。压缩任务需要读入整段待压缩的对话，如果辅助模型的窗口比主模型小太多，压缩本身就会失败。这里用的 &lt;code&gt;glm-5.3-flash&lt;/code&gt; 有 1310720 的上下文，比主模型还大。&lt;/p&gt;&#10;&lt;h2 id="上下文压缩"&gt;上下文压缩&#10;&lt;/h2&gt;&lt;p&gt;长任务的对话会越来越长，Hermes 在上下文用到一定比例时自动压缩：保留开头和最近的消息，把中间部分交给辅助模型生成摘要。&lt;/p&gt;&#10;&lt;div class="highlight"&gt;&lt;div class="chroma"&gt;&#10;&lt;table class="lntable"&gt;&lt;tr&gt;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code&gt;&lt;span class="lnt"&gt;1&#10;&lt;/span&gt;&lt;span class="lnt"&gt;2&#10;&lt;/span&gt;&lt;span class="lnt"&gt;3&#10;&lt;/span&gt;&lt;span class="lnt"&gt;4&#10;&lt;/span&gt;&lt;span class="lnt"&gt;5&#10;&lt;/span&gt;&lt;span class="lnt"&gt;6&#10;&lt;/span&gt;&lt;span class="lnt"&gt;7&#10;&lt;/span&gt;&lt;span class="lnt"&gt;8&#10;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&#10;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-yaml" data-lang="yaml"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nt"&gt;compression&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;enabled&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;threshold&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="m"&gt;0.5&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="c"&gt;# 上下文用到 50% 时触发&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;target_ratio&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="m"&gt;0.2&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="c"&gt;# 压缩后保留的近期尾部占阈值的比例&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;protect_first_n&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="m"&gt;3&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="c"&gt;# 开头固定保留的消息数&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;protect_last_n&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="m"&gt;20&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="c"&gt;# 尾部至少保留的消息数&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;min_tail_user_messages&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="m"&gt;1&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;max_attempts&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="m"&gt;3&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/table&gt;&#10;&lt;/div&gt;&#10;&lt;/div&gt;&lt;p&gt;这几个值基本是默认值，我没有调整。几个理解要点：&lt;/p&gt;&#10;&lt;ul&gt;&#10;&lt;li&gt;&lt;code&gt;threshold&lt;/code&gt; 按模型的 &lt;code&gt;context_length&lt;/code&gt; 计算。&lt;code&gt;grok-4.7&lt;/code&gt; 声明了 500000，就是大约 25 万 token 时触发。&lt;/li&gt;&#10;&lt;li&gt;&lt;code&gt;protect_first_n&lt;/code&gt; 保住任务最初的要求，&lt;code&gt;protect_last_n&lt;/code&gt; 保住当前正在做的事，被压缩的是中间的过程。&lt;/li&gt;&#10;&lt;li&gt;压缩是有损的。压缩后 Agent 对早期细节的记忆会变模糊，重要的结论应该写进记忆或文件，而不是指望它一直留在上下文里。&lt;/li&gt;&#10;&lt;/ul&gt;&#10;&lt;h2 id="提示词缓存"&gt;提示词缓存&#10;&lt;/h2&gt;&lt;p&gt;Agent 每轮都会重复发送很长的系统提示词（人设、技能列表、记忆），如果上游能缓存这段固定前缀，费用和延迟都能明显下降。但这里有一个很容易误解的配置：&lt;/p&gt;&#10;&lt;div class="highlight"&gt;&lt;div class="chroma"&gt;&#10;&lt;table class="lntable"&gt;&lt;tr&gt;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code&gt;&lt;span class="lnt"&gt;1&#10;&lt;/span&gt;&lt;span class="lnt"&gt;2&#10;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&#10;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-yaml" data-lang="yaml"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nt"&gt;prompt_caching&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;cache_ttl&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;1h&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/table&gt;&#10;&lt;/div&gt;&#10;&lt;/div&gt;&lt;p&gt;在当前版本中，顶层 &lt;code&gt;prompt_caching&lt;/code&gt; 只控制 &lt;strong&gt;Anthropic 风格&lt;/strong&gt;的缓存（给 Claude 请求加 &lt;code&gt;cache_control&lt;/code&gt; 断点），对 Grok、GLM、GPT 不起作用。这几家的缓存机制各不相同：&lt;/p&gt;&#10;&lt;table&gt;&#10;&#9;&lt;thead&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;模型&lt;/th&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;缓存方式&lt;/th&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;Hermes 侧要做的&lt;/th&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&lt;/thead&gt;&#10;&#9;&lt;tbody&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;Claude&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;显式 &lt;code&gt;cache_control&lt;/code&gt; 断点&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;用 &lt;code&gt;anthropic_messages&lt;/code&gt;，由 &lt;code&gt;prompt_caching&lt;/code&gt; 控制&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;GPT / Grok&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;前缀缓存 + &lt;code&gt;prompt_cache_key&lt;/code&gt; 路由&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;用 &lt;code&gt;codex_responses&lt;/code&gt;，Hermes 自动生成稳定的 key&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;GLM&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;上游自动缓存&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;用 &lt;code&gt;chat_completions&lt;/code&gt;，保持前缀稳定即可&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&lt;/tbody&gt;&#10;&lt;/table&gt;&#10;&lt;p&gt;所以对我这套 Grok + GLM 的组合来说，真正决定缓存的是 provider 的 &lt;code&gt;transport&lt;/code&gt; 选择和网关的渠道路由，而不是 &lt;code&gt;prompt_caching&lt;/code&gt;。完整的原理、取证方法和 New API 侧的坑，见 &lt;a class="link" href="https://www.iminling.com/ai/hermes/hermes-agent-newapi-prompt-cache/" &gt;Hermes 接入 New API 的提示词缓存排查&lt;/a&gt;。&lt;/p&gt;&#10;&lt;h2 id="moa多模型参考"&gt;MoA：多模型参考&#10;&lt;/h2&gt;&lt;p&gt;MoA（Mixture of Agents）让几个不同模型先各自给出意见，再由聚合模型综合后回答。我的配置：&lt;/p&gt;&#10;&lt;div class="highlight"&gt;&lt;div class="chroma"&gt;&#10;&lt;table class="lntable"&gt;&lt;tr&gt;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code&gt;&lt;span class="lnt"&gt; 1&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 2&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 3&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 4&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 5&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 6&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 7&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 8&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 9&#10;&lt;/span&gt;&lt;span class="lnt"&gt;10&#10;&lt;/span&gt;&lt;span class="lnt"&gt;11&#10;&lt;/span&gt;&lt;span class="lnt"&gt;12&#10;&lt;/span&gt;&lt;span class="lnt"&gt;13&#10;&lt;/span&gt;&lt;span class="lnt"&gt;14&#10;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&#10;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-yaml" data-lang="yaml"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nt"&gt;moa&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;enabled&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;reference_models&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;- &lt;span class="nt"&gt;provider&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;openai-codex&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;model&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;gpt-5.5&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;- &lt;span class="nt"&gt;provider&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;openrouter&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;model&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;deepseek/deepseek-v4-pro&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;- &lt;span class="nt"&gt;provider&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;openrouter&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;model&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;anthropic/claude-opus-4.8&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;aggregator&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;provider&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;custom:newapi-grok&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;model&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;grok-4.7&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;fanout&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;user_turn&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;degraded_reference_policy&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;loud&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/table&gt;&#10;&lt;/div&gt;&#10;&lt;/div&gt;&lt;p&gt;理解 MoA 的关键是&lt;strong&gt;它不会自动在每轮生效&lt;/strong&gt;。正常对话只调用主模型；只有用 &lt;code&gt;/moa&lt;/code&gt; 斜杠命令标记的那一轮，才会先把问题发给参考模型，再把它们的回答作为参考交给主模型。工具调用和任务结束仍然由正常的 Agent 循环控制。&lt;/p&gt;&#10;&lt;p&gt;&lt;code&gt;fanout&lt;/code&gt; 控制在被标记的回合里多久向参考模型请求一次：&lt;/p&gt;&#10;&lt;table&gt;&#10;&#9;&lt;thead&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;取值&lt;/th&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;含义&lt;/th&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&lt;/thead&gt;&#10;&#9;&lt;tbody&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;user_turn&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;每个用户回合只请求一次，最省钱（也是无效配置时的回退值）&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;per_iteration&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;每次模型迭代都请求，工具调用多时成本成倍增加&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;every_n:&amp;lt;N&amp;gt;&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;每 N 次迭代请求一次&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&lt;/tbody&gt;&#10;&lt;/table&gt;&#10;&lt;p&gt;&lt;code&gt;degraded_reference_policy: loud&lt;/code&gt; 表示某个参考模型失败时明确提示，而不是静默降级，避免以为用了三家意见实际只用了一家。&lt;/p&gt;&#10;&lt;p&gt;我的用法是：日常对话不开 MoA，遇到方案选择、疑难排查这类需要多个视角的问题时，才手动用 &lt;code&gt;/moa&lt;/code&gt;。&lt;/p&gt;&#10;&lt;h2 id="总结"&gt;总结&#10;&lt;/h2&gt;&lt;ul&gt;&#10;&lt;li&gt;用 &lt;code&gt;providers:&lt;/code&gt; 下的 named provider 接入自建网关，按协议拆分，配置里只写 &lt;code&gt;key_env&lt;/code&gt;，&lt;code&gt;context_length&lt;/code&gt; 要写准。&lt;/li&gt;&#10;&lt;li&gt;主模型干正事，压缩、审批、标题等后台任务交给又快又便宜的辅助模型，并且辅助模型的上下文要够长。&lt;/li&gt;&#10;&lt;li&gt;上下文压缩默认值就够用，但要记住它是有损的。&lt;/li&gt;&#10;&lt;li&gt;&lt;code&gt;prompt_caching&lt;/code&gt; 只管 Claude；GPT、Grok、GLM 的缓存取决于 &lt;code&gt;transport&lt;/code&gt; 和网关路由。&lt;/li&gt;&#10;&lt;li&gt;MoA 是按需工具，用 &lt;code&gt;/moa&lt;/code&gt; 触发，&lt;code&gt;fanout: user_turn&lt;/code&gt; 控制成本。&lt;/li&gt;&#10;&lt;/ul&gt;&#10;&lt;p&gt;下一篇讲接入层和 Profile：一个网关进程如何同时服务多个聊天平台和多个角色。&lt;/p&gt;&#10;</description></item><item><title>Hermes Agent 自托管架构总览：从部署到能力扩展的分层设计</title><link>https://www.iminling.com/ai/hermes/hermes-agent-architecture-overview/</link><pubDate>Thu, 19 Nov 2026 00:00:00 +0000</pubDate><guid>https://www.iminling.com/ai/hermes/hermes-agent-architecture-overview/</guid><description>&lt;img src="https://images.iminling.com/i/2026/11/19/1d4d42b6ab97d0d19a2591bcb284d39a.webp" alt="Featured image of post Hermes Agent 自托管架构总览：从部署到能力扩展的分层设计" /&gt;&lt;h2 id="写在前面"&gt;写在前面&#10;&lt;/h2&gt;&lt;p&gt;Hermes Agent 是 Nous Research 开源的通用 AI Agent。和 Claude Code、Codex 这类主要待在终端里的编程 CLI 不同，它更像一个常驻服务：挂在服务器上，通过飞书、Telegram、企业微信等聊天平台接收消息，按配置调用模型、工具和技能，再把结果送回聊天窗口。&lt;/p&gt;&#10;&lt;p&gt;我在一台内网服务器上跑了几个月 Hermes，配置一路改下来，已经从&amp;quot;能用&amp;quot;变成了一套有明确分层的系统。这个系列把它拆开讲清楚，本篇是总览：先建立整体模型，后续每篇再展开一层。&lt;/p&gt;&#10;&lt;p&gt;本文基于 Hermes Agent &lt;code&gt;v0.23.0&lt;/code&gt;（2026.9.24），使用官方 Docker 镜像部署。涉及账号、渠道 ID、模型网关地址的地方都用占位符替代。&lt;/p&gt;&#10;&lt;h2 id="整体模型"&gt;整体模型&#10;&lt;/h2&gt;&lt;p&gt;先看全貌。Hermes 在这套部署里可以分成六层：消息从最上面的接入层进来，经过角色层和能力层调用模型，记忆与状态贯穿全程，最底下的部署层承载所有进程和数据。&lt;/p&gt;&#10;&lt;pre class="mermaid" style="visibility:hidden"&gt;flowchart TB&#10; subgraph Entry["接入层 Gateway"]&#10; direction LR&#10; Chat[飞书 / Telegram / 企业微信] ~~~ API[api_server / webhook]&#10; end&#10;&#10; subgraph Role["角色层 Profiles"]&#10; Profiles[dev / product / tester / kb / home]&#10; end&#10;&#10; subgraph Agent["能力层"]&#10; direction LR&#10; Skills[Skills] ~~~ Plugins[Plugins / Hooks] ~~~ Cron[Cron]&#10; end&#10;&#10; subgraph Model["模型层"]&#10; direction LR&#10; Main[主模型 grok-4.7] ~~~ Aux[辅助模型 glm-5.3-flash]&#10; end&#10;&#10; subgraph State["记忆与状态层"]&#10; direction LR&#10; Mem[SOUL / MEMORY / USER] ~~~ DB[(state.db)]&#10; end&#10;&#10; subgraph Deploy["部署层"]&#10; direction LR&#10; Docker[Docker Compose + s6] ~~~ Data["数据卷 /opt/data"] ~~~ Dash[Dashboard]&#10; end&#10;&#10; Entry --&gt; Role --&gt; Agent --&gt; Model&#10; Agent &lt;--&gt; State&#10; Model ~~~ Deploy&#10; State ~~~ Deploy&lt;/pre&gt;&lt;p&gt;各层的分工可以用一张表概括：&lt;/p&gt;&#10;&lt;table&gt;&#10;&#9;&lt;thead&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;层&lt;/th&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;负责什么&lt;/th&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;主要配置位置&lt;/th&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&lt;/thead&gt;&#10;&#9;&lt;tbody&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;部署层&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;进程守护、数据持久化、Dashboard&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;docker-compose.yaml&lt;/code&gt;、&lt;code&gt;/opt/data&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;模型层&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;主对话模型、辅助任务模型、多模型协作&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;config.yaml&lt;/code&gt; 的 &lt;code&gt;model&lt;/code&gt;、&lt;code&gt;auxiliary&lt;/code&gt;、&lt;code&gt;moa&lt;/code&gt;、&lt;code&gt;providers&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;接入层&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;聊天平台收发、展示策略、会话切换&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;config.yaml&lt;/code&gt; 的 &lt;code&gt;platforms&lt;/code&gt;、&lt;code&gt;display.platforms&lt;/code&gt;、&lt;code&gt;.env&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;角色层&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;按用途隔离模型、技能和记忆&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;profiles/&amp;lt;name&amp;gt;/&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;能力层&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;技能、插件、定时任务&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;skills/&lt;/code&gt;、&lt;code&gt;plugins/&lt;/code&gt;、&lt;code&gt;cron/&lt;/code&gt;、&lt;code&gt;scripts/&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;记忆与状态层&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;人设、长期记忆、会话与任务状态&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;SOUL.md&lt;/code&gt;、&lt;code&gt;memories/&lt;/code&gt;、&lt;code&gt;state.db&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&lt;/tbody&gt;&#10;&lt;/table&gt;&#10;&lt;h2 id="关键组件"&gt;关键组件&#10;&lt;/h2&gt;&lt;h3 id="部署层一个容器一个数据目录"&gt;部署层：一个容器，一个数据目录&#10;&lt;/h3&gt;&lt;p&gt;整套服务只有一个 &lt;code&gt;hermes&lt;/code&gt; 容器，用 Docker Compose 管理：&lt;/p&gt;&#10;&lt;div class="highlight"&gt;&lt;div class="chroma"&gt;&#10;&lt;table class="lntable"&gt;&lt;tr&gt;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code&gt;&lt;span class="lnt"&gt; 1&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 2&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 3&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 4&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 5&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 6&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 7&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 8&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 9&#10;&lt;/span&gt;&lt;span class="lnt"&gt;10&#10;&lt;/span&gt;&lt;span class="lnt"&gt;11&#10;&lt;/span&gt;&lt;span class="lnt"&gt;12&#10;&lt;/span&gt;&lt;span class="lnt"&gt;13&#10;&lt;/span&gt;&lt;span class="lnt"&gt;14&#10;&lt;/span&gt;&lt;span class="lnt"&gt;15&#10;&lt;/span&gt;&lt;span class="lnt"&gt;16&#10;&lt;/span&gt;&lt;span class="lnt"&gt;17&#10;&lt;/span&gt;&lt;span class="lnt"&gt;18&#10;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&#10;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-yaml" data-lang="yaml"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nt"&gt;services&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;hermes&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;image&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;nousresearch/hermes-agent:latest&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;container_name&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;hermes&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;restart&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;unless-stopped&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;network_mode&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;host&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;volumes&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;- &lt;span class="l"&gt;./data:/opt/data&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;- &lt;span class="l"&gt;/data/work:/data/work:ro&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;environment&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;- &lt;span class="l"&gt;TZ=Asia/Shanghai&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;- &lt;span class="l"&gt;HERMES_DASHBOARD=1&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;- &lt;span class="l"&gt;HERMES_DASHBOARD_HOST=0.0.0.0&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;- &lt;span class="l"&gt;HERMES_DASHBOARD_PORT=9119&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;- &lt;span class="l"&gt;HERMES_DASHBOARD_BASIC_AUTH_USERNAME=&amp;lt;your-username&amp;gt;&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;- &lt;span class="l"&gt;HERMES_DASHBOARD_BASIC_AUTH_PASSWORD=&amp;lt;your-password&amp;gt;&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;- &lt;span class="l"&gt;HERMES_DASHBOARD_BASIC_AUTH_SECRET=&amp;lt;random-secret&amp;gt;&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;command&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;&amp;#34;gateway&amp;#34;&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;&amp;#34;run&amp;#34;&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/table&gt;&#10;&lt;/div&gt;&#10;&lt;/div&gt;&lt;p&gt;几个值得注意的点：&lt;/p&gt;&#10;&lt;ul&gt;&#10;&lt;li&gt;容器内的 &lt;code&gt;HERMES_HOME&lt;/code&gt; 是 &lt;code&gt;/opt/data&lt;/code&gt;。配置、密钥、技能、会话数据库全部落在宿主机的 &lt;code&gt;./data&lt;/code&gt; 里，升级镜像不会丢状态。&lt;/li&gt;&#10;&lt;li&gt;&lt;code&gt;command: [&amp;quot;gateway&amp;quot;, &amp;quot;run&amp;quot;]&lt;/code&gt; 让容器以网关模式常驻；容器内部由 s6 负责守护网关进程。&lt;/li&gt;&#10;&lt;li&gt;工作目录 &lt;code&gt;/data/work&lt;/code&gt; 以只读方式挂载，Agent 能读代码和资料，但不能直接改宿主机文件。&lt;/li&gt;&#10;&lt;li&gt;服务器只在内网，所以使用 &lt;code&gt;network_mode: host&lt;/code&gt;，Dashboard 直接监听 &lt;code&gt;9119&lt;/code&gt; 端口，只配了 Basic Auth。暴露到公网时不应照搬这套配置。&lt;/li&gt;&#10;&lt;/ul&gt;&#10;&lt;p&gt;我早期还自己写过一个 Dockerfile，用来在镜像里装 Chromium，后来发现官方镜像已经通过 &lt;code&gt;PLAYWRIGHT_BROWSERS_PATH&lt;/code&gt; 自带 Playwright 浏览器，这一步完全多余。部署篇会详细说明数据目录结构和这类踩坑点。&lt;/p&gt;&#10;&lt;h3 id="模型层主模型干活小模型打杂"&gt;模型层：主模型干活，小模型打杂&#10;&lt;/h3&gt;&lt;p&gt;模型层最重要的设计是&lt;strong&gt;按任务分配模型&lt;/strong&gt;。&lt;/p&gt;&#10;&lt;ul&gt;&#10;&lt;li&gt;主对话使用 &lt;code&gt;grok-4.7&lt;/code&gt;，推理强度设为 &lt;code&gt;high&lt;/code&gt;。&lt;/li&gt;&#10;&lt;li&gt;上下文压缩、审批判断、标题生成、技能整理（curator）、后台复盘这些辅助任务，统一交给更便宜、更快的 &lt;code&gt;glm-5.3-flash&lt;/code&gt;，并关闭推理。&lt;/li&gt;&#10;&lt;/ul&gt;&#10;&lt;div class="highlight"&gt;&lt;div class="chroma"&gt;&#10;&lt;table class="lntable"&gt;&lt;tr&gt;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code&gt;&lt;span class="lnt"&gt; 1&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 2&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 3&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 4&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 5&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 6&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 7&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 8&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 9&#10;&lt;/span&gt;&lt;span class="lnt"&gt;10&#10;&lt;/span&gt;&lt;span class="lnt"&gt;11&#10;&lt;/span&gt;&lt;span class="lnt"&gt;12&#10;&lt;/span&gt;&lt;span class="lnt"&gt;13&#10;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&#10;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-yaml" data-lang="yaml"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nt"&gt;model&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;default&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;grok-4.7&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;provider&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;custom:newapi-grok&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nt"&gt;auxiliary&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;compression&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;provider&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;custom:newapi-glm&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;model&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;glm-5.3-flash&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;reasoning_effort&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;none&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;title_generation&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;provider&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;custom:newapi-glm&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;model&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;glm-5.3-flash&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;reasoning_effort&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;none&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/table&gt;&#10;&lt;/div&gt;&#10;&lt;/div&gt;&lt;p&gt;所有模型都通过一个自建的 NewAPI 网关接入，按协议拆成几个 named provider 声明，密钥只通过 &lt;code&gt;key_env&lt;/code&gt; 引用环境变量，不写进配置文件。此外还配置了 MoA（Mixture of Agents）：用 &lt;code&gt;/moa&lt;/code&gt; 标记某一轮时，先让几个不同厂商的模型给出参考意见，再由主模型汇总回答。模型篇会讲清楚这些取舍和成本。&lt;/p&gt;&#10;&lt;h3 id="接入层一个网关多个聊天平台"&gt;接入层：一个网关，多个聊天平台&#10;&lt;/h3&gt;&lt;p&gt;Gateway 是 Hermes 和外界的连接点。这套部署启用了：&lt;/p&gt;&#10;&lt;ul&gt;&#10;&lt;li&gt;飞书：日常主要入口，也是 home channel&lt;/li&gt;&#10;&lt;li&gt;Telegram：个人移动端入口&lt;/li&gt;&#10;&lt;li&gt;企业微信、微信：分别给其他 Profile 使用&lt;/li&gt;&#10;&lt;li&gt;&lt;code&gt;api_server&lt;/code&gt; 和 &lt;code&gt;webhook&lt;/code&gt;：供脚本或其他系统调用&lt;/li&gt;&#10;&lt;/ul&gt;&#10;&lt;p&gt;不同平台的展示能力不一样，所以在 &lt;code&gt;display.platforms&lt;/code&gt; 中按平台单独调整，例如飞书和 Telegram 关闭中间过程消息，避免刷屏：&lt;/p&gt;&#10;&lt;div class="highlight"&gt;&lt;div class="chroma"&gt;&#10;&lt;table class="lntable"&gt;&lt;tr&gt;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code&gt;&lt;span class="lnt"&gt;1&#10;&lt;/span&gt;&lt;span class="lnt"&gt;2&#10;&lt;/span&gt;&lt;span class="lnt"&gt;3&#10;&lt;/span&gt;&lt;span class="lnt"&gt;4&#10;&lt;/span&gt;&lt;span class="lnt"&gt;5&#10;&lt;/span&gt;&lt;span class="lnt"&gt;6&#10;&lt;/span&gt;&lt;span class="lnt"&gt;7&#10;&lt;/span&gt;&lt;span class="lnt"&gt;8&#10;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&#10;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-yaml" data-lang="yaml"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nt"&gt;display&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;platforms&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;telegram&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;streaming&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="kc"&gt;false&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;interim_assistant_messages&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="kc"&gt;false&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;feishu&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;tool_progress&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="kc"&gt;false&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;interim_assistant_messages&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="kc"&gt;false&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/table&gt;&#10;&lt;/div&gt;&#10;&lt;/div&gt;&lt;h3 id="角色层用-profile-隔离用途"&gt;角色层：用 Profile 隔离用途&#10;&lt;/h3&gt;&lt;p&gt;一个 Agent 同时承担开发、产品、测试、知识库问答和家庭事务，技能和记忆很容易互相干扰。Hermes 的 Profile 正好解决这个问题：每个 Profile 有自己的配置、技能集合和记忆。&lt;/p&gt;&#10;&lt;p&gt;除了默认的 &lt;code&gt;default&lt;/code&gt;，这里按用途又建了五个 Profile：&lt;code&gt;dev&lt;/code&gt;、&lt;code&gt;product&lt;/code&gt;、&lt;code&gt;tester&lt;/code&gt;、&lt;code&gt;kb&lt;/code&gt;、&lt;code&gt;home&lt;/code&gt;。比如 &lt;code&gt;home&lt;/code&gt; 只挂了最基础的技能，&lt;code&gt;kb&lt;/code&gt; 只保留知识库问答相关的技能。&lt;/p&gt;&#10;&lt;p&gt;配合 &lt;code&gt;gateway.multiplex_profiles: true&lt;/code&gt;，同一个网关进程就能同时服务所有 Profile。路由方式很简单：每个 Profile 持有自己的机器人凭证，消息从哪个机器人进来，就交给哪个 Profile 处理。&lt;/p&gt;&#10;&lt;h3 id="能力层skillsplugins-和-cron"&gt;能力层：Skills、Plugins 和 Cron&#10;&lt;/h3&gt;&lt;p&gt;能力层是 Hermes 可塑性最强的部分：&lt;/p&gt;&#10;&lt;ul&gt;&#10;&lt;li&gt;&lt;strong&gt;Skills&lt;/strong&gt;：以 &lt;code&gt;SKILL.md&lt;/code&gt; 为单位的能力包，按目录分类存放。内置技能很多，我禁用了大部分用不到的，减少提示词占用和误触发。&lt;/li&gt;&#10;&lt;li&gt;&lt;strong&gt;Plugins&lt;/strong&gt;：运行在网关进程里的 Python 扩展。我用了两个插件：一个社区插件在 &lt;code&gt;pre_gateway_dispatch&lt;/code&gt; 钩子里恢复按时间自动重置会话（上游在 &lt;code&gt;v2026.9.11&lt;/code&gt; 移除了这个能力），另一个是让 Hermes 自己写的本地补丁，让企业微信发送文件失败时回退到主动发送。&lt;/li&gt;&#10;&lt;li&gt;&lt;strong&gt;Cron&lt;/strong&gt;：Hermes 内置的定时任务。除了定时让 Agent 执行提示词，也可以直接运行 &lt;code&gt;scripts/&lt;/code&gt; 下的脚本，比如每天检查宿主机磁盘占用并告警。&lt;/li&gt;&#10;&lt;/ul&gt;&#10;&lt;p&gt;扩展篇会以这两个插件为例，讲 Hermes 插件的两种典型写法。&lt;/p&gt;&#10;&lt;h3 id="记忆与状态层让-agent-记住自己是谁"&gt;记忆与状态层：让 Agent 记住自己是谁&#10;&lt;/h3&gt;&lt;ul&gt;&#10;&lt;li&gt;&lt;code&gt;SOUL.md&lt;/code&gt;：Agent 的人设和说话风格，例如要求回答长度与问题分量匹配、不说客套话。&lt;/li&gt;&#10;&lt;li&gt;&lt;code&gt;memories/MEMORY.md&lt;/code&gt; 和 &lt;code&gt;memories/USER.md&lt;/code&gt;：长期记忆和用户画像，分别有 &lt;code&gt;2200&lt;/code&gt; 和 &lt;code&gt;1375&lt;/code&gt; 字符上限，逼着记忆保持精炼。&lt;/li&gt;&#10;&lt;li&gt;&lt;code&gt;state.db&lt;/code&gt;：会话、消息、全文检索等运行状态，启用了 WAL 模式。跑了几个月后已经涨到两百多 MB，需要关注清理和备份。&lt;/li&gt;&#10;&lt;li&gt;&lt;code&gt;session_reset&lt;/code&gt;：每天凌晨 4 点切换新会话，避免上下文无限增长（新版本需要插件配合才生效）。&lt;/li&gt;&#10;&lt;/ul&gt;&#10;&lt;h2 id="一条消息的完整路径"&gt;一条消息的完整路径&#10;&lt;/h2&gt;&lt;p&gt;把各层串起来，一条飞书消息大致经过这些步骤：&lt;/p&gt;&#10;&lt;pre class="mermaid" style="visibility:hidden"&gt;sequenceDiagram&#10; participant U as 用户（飞书）&#10; participant G as Gateway&#10; participant H as 插件钩子&#10; participant A as Agent（Profile）&#10; participant M as 主模型&#10; participant X as 辅助模型&#10;&#10; U-&gt;&gt;G: 发送消息&#10; G-&gt;&gt;H: pre_gateway_dispatch&#10; H--&gt;&gt;G: 必要时重置会话&#10; G-&gt;&gt;A: 路由到对应 Profile 的会话&#10; A-&gt;&gt;M: 携带 SOUL、记忆、技能提示调用模型&#10; M--&gt;&gt;A: 回复或工具调用&#10; A-&gt;&gt;A: 执行工具 / 技能，循环直到完成&#10; A-&gt;&gt;X: 上下文过长时压缩、生成标题&#10; A--&gt;&gt;G: 最终回复&#10; G--&gt;&gt;U: 按平台展示策略发送&lt;/pre&gt;&lt;h2 id="这套架构的边界"&gt;这套架构的边界&#10;&lt;/h2&gt;&lt;ul&gt;&#10;&lt;li&gt;&lt;strong&gt;前提是内网&lt;/strong&gt;：Dashboard 只有 Basic Auth，审批模式也是关闭的（&lt;code&gt;approvals.mode: 'off'&lt;/code&gt;）。这套配置建立在服务器不对外暴露、使用者都可信的前提下。&lt;/li&gt;&#10;&lt;li&gt;&lt;strong&gt;单容器单点&lt;/strong&gt;：所有能力都在一个容器里，容器出问题，所有渠道一起失效。对个人和小团队够用，但要接受这个单点。&lt;/li&gt;&#10;&lt;li&gt;&lt;strong&gt;跟随 &lt;code&gt;latest&lt;/code&gt; 镜像&lt;/strong&gt;：升级方便，但上游行为变化会直接影响现有配置。会话重置能力被移除，就是一个真实例子。&lt;/li&gt;&#10;&lt;/ul&gt;&#10;&lt;h2 id="系列规划"&gt;系列规划&#10;&lt;/h2&gt;&lt;p&gt;后续文章按层展开：&lt;/p&gt;&#10;&lt;ul&gt;&#10;&lt;li&gt;&lt;a class="link" href="https://www.iminling.com/ai/hermes/hermes-agent-docker-deployment/" &gt;部署篇&lt;/a&gt;：Docker Compose、s6 启动链、数据目录结构、Dashboard、升级与备份&lt;/li&gt;&#10;&lt;li&gt;&lt;a class="link" href="https://www.iminling.com/ai/hermes/hermes-agent-model-config/" &gt;模型篇&lt;/a&gt;：自定义 provider、主辅模型分工、上下文压缩与缓存、MoA&lt;/li&gt;&#10;&lt;li&gt;&lt;a class="link" href="https://www.iminling.com/ai/hermes/hermes-agent-gateway-profiles/" &gt;接入与 Profile 篇&lt;/a&gt;：多平台 Gateway、Profile 多路复用、会话划分与重置&lt;/li&gt;&#10;&lt;li&gt;&lt;a class="link" href="https://www.iminling.com/ai/hermes/hermes-agent-skills-plugins-cron/" &gt;扩展篇&lt;/a&gt;：Skills 管理、插件开发、Cron 脚本任务&lt;/li&gt;&#10;&lt;li&gt;&lt;a class="link" href="https://www.iminling.com/ai/hermes/hermes-agent-newapi-prompt-cache/" &gt;番外：提示词缓存排查&lt;/a&gt;：接入 New API 时 GPT、Grok、GLM、Claude 的缓存协议与逐层取证&lt;/li&gt;&#10;&lt;/ul&gt;&#10;&lt;h2 id="总结"&gt;总结&#10;&lt;/h2&gt;&lt;p&gt;Hermes 的配置项很多，按层来看就清晰了：部署层保证常驻和数据持久，模型层决定成本和能力，接入层和角色层决定谁在什么场景下用它，能力层和记忆层决定它能做什么、记得什么。改一个配置之前先想清楚它属于哪一层，就不容易越改越乱。&lt;/p&gt;&#10;</description></item><item><title>Hermes Agent 部署篇：Docker Compose、数据目录与 Dashboard</title><link>https://www.iminling.com/ai/hermes/hermes-agent-docker-deployment/</link><pubDate>Thu, 19 Nov 2026 00:00:00 +0000</pubDate><guid>https://www.iminling.com/ai/hermes/hermes-agent-docker-deployment/</guid><description>&lt;img src="https://images.iminling.com/i/2026/11/19/04f2d7beb05632bf1f5678586439ea85.webp" alt="Featured image of post Hermes Agent 部署篇：Docker Compose、数据目录与 Dashboard" /&gt;&lt;h2 id="写在前面"&gt;写在前面&#10;&lt;/h2&gt;&lt;p&gt;这是 Hermes Agent 架构系列的第二篇，讲最底下的部署层。整体分层见 &lt;a class="link" href="https://www.iminling.com/ai/hermes/hermes-agent-architecture-overview/" &gt;Hermes Agent 自托管架构总览&lt;/a&gt;。&lt;/p&gt;&#10;&lt;p&gt;部署层要解决三件事：进程长期在线、数据不随容器丢失、有一个能看状态的管理界面。Hermes 官方镜像已经把大部分事情做好了，自己要做的主要是挂好数据目录、配好 Dashboard 认证。&lt;/p&gt;&#10;&lt;p&gt;本文环境：Hermes Agent &lt;code&gt;v0.23.0&lt;/code&gt;，官方镜像 &lt;code&gt;nousresearch/hermes-agent:latest&lt;/code&gt;，服务器在内网。&lt;/p&gt;&#10;&lt;h2 id="compose-配置"&gt;Compose 配置&#10;&lt;/h2&gt;&lt;p&gt;我的 &lt;code&gt;docker-compose.yaml&lt;/code&gt; 放在 &lt;code&gt;/usr/local/svc/hermes&lt;/code&gt;：&lt;/p&gt;&#10;&lt;div class="highlight"&gt;&lt;div class="chroma"&gt;&#10;&lt;table class="lntable"&gt;&lt;tr&gt;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code&gt;&lt;span class="lnt"&gt; 1&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 2&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 3&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 4&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 5&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 6&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 7&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 8&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 9&#10;&lt;/span&gt;&lt;span class="lnt"&gt;10&#10;&lt;/span&gt;&lt;span class="lnt"&gt;11&#10;&lt;/span&gt;&lt;span class="lnt"&gt;12&#10;&lt;/span&gt;&lt;span class="lnt"&gt;13&#10;&lt;/span&gt;&lt;span class="lnt"&gt;14&#10;&lt;/span&gt;&lt;span class="lnt"&gt;15&#10;&lt;/span&gt;&lt;span class="lnt"&gt;16&#10;&lt;/span&gt;&lt;span class="lnt"&gt;17&#10;&lt;/span&gt;&lt;span class="lnt"&gt;18&#10;&lt;/span&gt;&lt;span class="lnt"&gt;19&#10;&lt;/span&gt;&lt;span class="lnt"&gt;20&#10;&lt;/span&gt;&lt;span class="lnt"&gt;21&#10;&lt;/span&gt;&lt;span class="lnt"&gt;22&#10;&lt;/span&gt;&lt;span class="lnt"&gt;23&#10;&lt;/span&gt;&lt;span class="lnt"&gt;24&#10;&lt;/span&gt;&lt;span class="lnt"&gt;25&#10;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&#10;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-yaml" data-lang="yaml"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nt"&gt;services&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;hermes&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;image&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;nousresearch/hermes-agent:latest&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;container_name&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;hermes&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;restart&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;unless-stopped&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;network_mode&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;host&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;volumes&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;- &lt;span class="l"&gt;./data:/opt/data&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;- &lt;span class="l"&gt;/data/work:/data/work:ro&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;environment&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;- &lt;span class="l"&gt;TZ=Asia/Shanghai&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="c"&gt;# Dashboard&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;- &lt;span class="l"&gt;HERMES_DASHBOARD=1&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;- &lt;span class="l"&gt;HERMES_DASHBOARD_HOST=0.0.0.0&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;- &lt;span class="l"&gt;HERMES_DASHBOARD_PORT=9119&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="c"&gt;# Dashboard 登录认证&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;- &lt;span class="l"&gt;HERMES_DASHBOARD_BASIC_AUTH_USERNAME=&amp;lt;your-username&amp;gt;&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;- &lt;span class="l"&gt;HERMES_DASHBOARD_BASIC_AUTH_PASSWORD=&amp;lt;your-password&amp;gt;&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;- &lt;span class="l"&gt;HERMES_DASHBOARD_BASIC_AUTH_SECRET=&amp;lt;random-secret&amp;gt;&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;command&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;&amp;#34;gateway&amp;#34;&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;&amp;#34;run&amp;#34;&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/table&gt;&#10;&lt;/div&gt;&#10;&lt;/div&gt;&lt;p&gt;逐项说明：&lt;/p&gt;&#10;&lt;table&gt;&#10;&#9;&lt;thead&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;配置&lt;/th&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;作用&lt;/th&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&lt;/thead&gt;&#10;&#9;&lt;tbody&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;network_mode: host&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;网关、Dashboard、&lt;code&gt;api_server&lt;/code&gt; 直接用宿主机端口，不用逐个映射&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;./data:/opt/data&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;容器内 &lt;code&gt;HERMES_HOME&lt;/code&gt; 就是 &lt;code&gt;/opt/data&lt;/code&gt;，所有状态都落在宿主机&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;/data/work:/data/work:ro&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;只读挂载工作目录，Agent 能读代码和资料，但改不了宿主机文件&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;TZ=Asia/Shanghai&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;Cron 表达式和会话每日重置都按本地时间计算&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;HERMES_DASHBOARD=1&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;在同一个容器里顺带启动 Dashboard&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;command: [&amp;quot;gateway&amp;quot;, &amp;quot;run&amp;quot;]&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;容器以网关模式常驻，接收各聊天平台消息&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&lt;/tbody&gt;&#10;&lt;/table&gt;&#10;&lt;p&gt;和官方仓库里的 &lt;code&gt;docker-compose.yml&lt;/code&gt; 相比，主要区别有三点：&lt;/p&gt;&#10;&lt;ul&gt;&#10;&lt;li&gt;官方示例是本地 &lt;code&gt;build&lt;/code&gt;，并挂载 &lt;code&gt;~/.hermes&lt;/code&gt;；我直接用发布的镜像，数据放在服务目录下，方便和其他服务统一管理。&lt;/li&gt;&#10;&lt;li&gt;官方示例通过 &lt;code&gt;HERMES_UID&lt;/code&gt; / &lt;code&gt;HERMES_GID&lt;/code&gt; 把容器内用户映射成宿主机用户。我没设置，容器内进程使用默认的 &lt;code&gt;10000&lt;/code&gt; 用户，所以宿主机上 &lt;code&gt;data/&lt;/code&gt; 的属主也是 &lt;code&gt;10000&lt;/code&gt;。&lt;/li&gt;&#10;&lt;li&gt;官方建议 Dashboard 只绑定 &lt;code&gt;127.0.0.1&lt;/code&gt;，远程访问走 SSH 隧道或带认证的反向代理。我的服务器只在内网，才直接监听 &lt;code&gt;0.0.0.0&lt;/code&gt; 并只加 Basic Auth。&lt;strong&gt;公网服务器不要照抄这一点。&lt;/strong&gt;&lt;/li&gt;&#10;&lt;/ul&gt;&#10;&lt;h2 id="容器里是怎么启动的"&gt;容器里是怎么启动的&#10;&lt;/h2&gt;&lt;p&gt;镜像的入口是 &lt;code&gt;/opt/hermes/docker/entrypoint-dispatch.sh&lt;/code&gt;。它判断自己是不是 PID 1：正常 Docker 环境下会交给 s6-overlay 的 &lt;code&gt;/init&lt;/code&gt;，由 s6 负责后续的初始化和进程守护。&lt;/p&gt;&#10;&lt;pre class="mermaid" style="visibility:hidden"&gt;flowchart TB&#10; Dispatch[entrypoint-dispatch.sh] --&gt;|PID 1| Init[s6-overlay /init]&#10; Init --&gt; CI[cont-init.d：权限、Profile 校正]&#10; CI --&gt; Wrapper[main-wrapper.sh gateway run]&#10; Wrapper --&gt; Gateway[网关进程]&#10; Wrapper --&gt; Dashboard[Dashboard]&#10; Gateway -.崩溃后由 s6 拉起.-&gt; Gateway&lt;/pre&gt;&lt;p&gt;这条链路带来两个实际影响：&lt;/p&gt;&#10;&lt;ul&gt;&#10;&lt;li&gt;&lt;strong&gt;不要随便覆盖 &lt;code&gt;entrypoint&lt;/code&gt;&lt;/strong&gt;。官方 compose 注释写得很明确：&lt;code&gt;/init&lt;/code&gt; 必须是第一条命令，它负责执行 &lt;code&gt;cont-init.d&lt;/code&gt; 中的权限修正、Profile 校正等初始化脚本。绕过它，网关不能正常工作。&lt;/li&gt;&#10;&lt;li&gt;&lt;strong&gt;进程挂了不用手动重启&lt;/strong&gt;。网关由 s6 守护，异常退出会被重新拉起；&lt;code&gt;restart: unless-stopped&lt;/code&gt; 只负责整个容器层面的重启。&lt;/li&gt;&#10;&lt;/ul&gt;&#10;&lt;p&gt;用 &lt;code&gt;docker exec hermes ps aux&lt;/code&gt; 能看到 &lt;code&gt;s6-supervise&lt;/code&gt; 和以 &lt;code&gt;10000&lt;/code&gt; 用户运行的 Python 网关进程。&lt;/p&gt;&#10;&lt;h2 id="数据目录结构"&gt;数据目录结构&#10;&lt;/h2&gt;&lt;p&gt;&lt;code&gt;/opt/data&lt;/code&gt;（宿主机上的 &lt;code&gt;./data&lt;/code&gt;）就是 Hermes 的全部家当。跑了三个月后，我的数据目录是 7.8G，主要构成如下：&lt;/p&gt;&#10;&lt;table&gt;&#10;&#9;&lt;thead&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;路径&lt;/th&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;体积&lt;/th&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;内容&lt;/th&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&lt;/thead&gt;&#10;&#9;&lt;tbody&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;cache/&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;2.8G&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;各类缓存，可以清理&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;profiles/&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;2.5G&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;每个 Profile 的独立数据，结构和根目录类似&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;skills/&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;689M&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;默认 Profile 的技能&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;lazy-packages/&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;456M&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;按需安装的 Python 依赖，例如语音识别用的 &lt;code&gt;faster_whisper&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;home/&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;407M&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;Agent 执行命令时的家目录&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;tools/&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;267M&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;工具运行时，包括 Playwright 浏览器&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;state.db&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;259M&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;会话、消息、全文检索等核心状态（SQLite）&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;logs/&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;30M&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;网关、Agent、错误日志&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&lt;/tbody&gt;&#10;&lt;/table&gt;&#10;&lt;p&gt;另外几个体积不大但很重要的文件：&lt;/p&gt;&#10;&lt;ul&gt;&#10;&lt;li&gt;&lt;code&gt;config.yaml&lt;/code&gt;：主配置&lt;/li&gt;&#10;&lt;li&gt;&lt;code&gt;.env&lt;/code&gt;：密钥和平台凭证，权限是 &lt;code&gt;600&lt;/code&gt;&lt;/li&gt;&#10;&lt;li&gt;&lt;code&gt;SOUL.md&lt;/code&gt;：默认 Profile 的人设&lt;/li&gt;&#10;&lt;li&gt;&lt;code&gt;memories/&lt;/code&gt;：长期记忆 &lt;code&gt;MEMORY.md&lt;/code&gt; 和用户画像 &lt;code&gt;USER.md&lt;/code&gt;&lt;/li&gt;&#10;&lt;li&gt;&lt;code&gt;cron/jobs.json&lt;/code&gt;：定时任务定义&lt;/li&gt;&#10;&lt;li&gt;&lt;code&gt;plugins/&lt;/code&gt;：插件&lt;/li&gt;&#10;&lt;/ul&gt;&#10;&lt;p&gt;&lt;code&gt;state.db&lt;/code&gt; 使用 WAL 模式（&lt;code&gt;database.journal_mode: wal&lt;/code&gt;），所以旁边总会有 &lt;code&gt;state.db-wal&lt;/code&gt; 和 &lt;code&gt;state.db-shm&lt;/code&gt;。&lt;strong&gt;备份时不要只拷贝 &lt;code&gt;state.db&lt;/code&gt; 一个文件&lt;/strong&gt;，最好停容器后整体备份，或者用 SQLite 的在线备份命令。&lt;/p&gt;&#10;&lt;p&gt;排查问题时最常看的是 &lt;code&gt;logs/&lt;/code&gt; 下的这几个：&lt;/p&gt;&#10;&lt;ul&gt;&#10;&lt;li&gt;&lt;code&gt;gateway.log&lt;/code&gt;：平台连接和消息收发&lt;/li&gt;&#10;&lt;li&gt;&lt;code&gt;agent.log&lt;/code&gt;：对话和工具调用过程&lt;/li&gt;&#10;&lt;li&gt;&lt;code&gt;errors.log&lt;/code&gt;：所有错误汇总&lt;/li&gt;&#10;&lt;/ul&gt;&#10;&lt;h2 id="dashboard"&gt;Dashboard&#10;&lt;/h2&gt;&lt;p&gt;Dashboard 和网关跑在同一个容器里，由 &lt;code&gt;HERMES_DASHBOARD=1&lt;/code&gt; 打开。它能查看会话、模型用量、Cron 任务和配置，日常检查很方便。&lt;/p&gt;&#10;&lt;p&gt;认证使用 Basic Auth，需要三个环境变量：用户名、密码和用于签发登录态的 &lt;code&gt;SECRET&lt;/code&gt;。首次启动后，&lt;code&gt;config.yaml&lt;/code&gt; 的 &lt;code&gt;dashboard.basic_auth&lt;/code&gt; 里只会保存密码哈希，不保存明文。&lt;/p&gt;&#10;&lt;p&gt;Dashboard 能看到所有对话和配置，它的暴露范围要和这些数据的敏感程度相匹配。&lt;/p&gt;&#10;&lt;h2 id="备份与升级"&gt;备份与升级&#10;&lt;/h2&gt;&lt;p&gt;Hermes 在修改配置时会自动留存快照，位置在 &lt;code&gt;backups/config/&lt;/code&gt;，文件名类似 &lt;code&gt;config.yaml.good.20261118-100122&lt;/code&gt;。改坏配置后可以从这里找回上一个能用的版本。&lt;/p&gt;&#10;&lt;p&gt;升级相关配置：&lt;/p&gt;&#10;&lt;div class="highlight"&gt;&lt;div class="chroma"&gt;&#10;&lt;table class="lntable"&gt;&lt;tr&gt;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code&gt;&lt;span class="lnt"&gt;1&#10;&lt;/span&gt;&lt;span class="lnt"&gt;2&#10;&lt;/span&gt;&lt;span class="lnt"&gt;3&#10;&lt;/span&gt;&lt;span class="lnt"&gt;4&#10;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&#10;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-yaml" data-lang="yaml"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nt"&gt;updates&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;pre_update_backup&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="kc"&gt;false&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;backup_keep&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="m"&gt;5&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;non_interactive_local_changes&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;stash&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/table&gt;&#10;&lt;/div&gt;&#10;&lt;/div&gt;&lt;p&gt;用 Docker 部署时，升级就是拉取新镜像后重建容器：&lt;/p&gt;&#10;&lt;div class="highlight"&gt;&lt;div class="chroma"&gt;&#10;&lt;table class="lntable"&gt;&lt;tr&gt;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code&gt;&lt;span class="lnt"&gt;1&#10;&lt;/span&gt;&lt;span class="lnt"&gt;2&#10;&lt;/span&gt;&lt;span class="lnt"&gt;3&#10;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&#10;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-bash" data-lang="bash"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nb"&gt;cd&lt;/span&gt; /usr/local/svc/hermes&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;docker compose pull&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;docker compose up -d&#10;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/table&gt;&#10;&lt;/div&gt;&#10;&lt;/div&gt;&lt;p&gt;我跟的是 &lt;code&gt;latest&lt;/code&gt; 标签，升级方便，但要接受上游行为变化直接生效。比如 &lt;code&gt;v2026.9.11&lt;/code&gt; 移除了按时间自动切换会话的能力，升级后配置还在，功能却没了（后来用插件补回来了，见扩展篇）。重要环境建议固定版本标签，升级前先看更新说明。&lt;/p&gt;&#10;&lt;p&gt;我的做法是手动升级：想升级时执行上面两条命令，升级前不额外备份 &lt;code&gt;data/&lt;/code&gt;。数据目录挂载在宿主机上，重建容器不会删除它；配置改坏了，还可以从 &lt;code&gt;backups/config/&lt;/code&gt; 的快照里找回。&lt;/p&gt;&#10;&lt;h2 id="踩坑不需要自建镜像装浏览器"&gt;踩坑：不需要自建镜像装浏览器&#10;&lt;/h2&gt;&lt;p&gt;最早我以为官方镜像没有浏览器，写了一个 &lt;code&gt;Dockerfile&lt;/code&gt; 基于官方镜像安装 Chromium 和中文字体：&lt;/p&gt;&#10;&lt;div class="highlight"&gt;&lt;div class="chroma"&gt;&#10;&lt;table class="lntable"&gt;&lt;tr&gt;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code&gt;&lt;span class="lnt"&gt;1&#10;&lt;/span&gt;&lt;span class="lnt"&gt;2&#10;&lt;/span&gt;&lt;span class="lnt"&gt;3&#10;&lt;/span&gt;&lt;span class="lnt"&gt;4&#10;&lt;/span&gt;&lt;span class="lnt"&gt;5&#10;&lt;/span&gt;&lt;span class="lnt"&gt;6&#10;&lt;/span&gt;&lt;span class="lnt"&gt;7&#10;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&#10;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-dockerfile" data-lang="dockerfile"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="k"&gt;FROM&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s"&gt;nousresearch/hermes-agent:latest&lt;/span&gt;&lt;span class="err"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="k"&gt;USER&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s"&gt;root&lt;/span&gt;&lt;span class="err"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="k"&gt;RUN&lt;/span&gt; apt-get update &lt;span class="se"&gt;\&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; apt-get install -y --no-install-recommends &lt;span class="se"&gt;\&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; chromium chromium-driver fonts-noto-cjk &lt;span class="se"&gt;\&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; rm -rf /var/lib/apt/lists/*&lt;span class="err"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="k"&gt;USER&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s"&gt;hermes&lt;/span&gt;&lt;span class="err"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/table&gt;&#10;&lt;/div&gt;&#10;&lt;/div&gt;&lt;p&gt;后来发现完全多余：官方镜像已经内置 Playwright，容器里设置了 &lt;code&gt;PLAYWRIGHT_BROWSERS_PATH&lt;/code&gt;，浏览器放在数据目录的 &lt;code&gt;tools/playwright-browsers&lt;/code&gt; 下，Agent 的浏览器工具开箱即用。&lt;/p&gt;&#10;&lt;p&gt;自建镜像的代价也很实在：每次上游更新都要重新构建，&lt;code&gt;docker compose pull&lt;/code&gt; 拉不到新版本。现在 compose 里直接使用官方镜像，那个 Dockerfile 已经弃用。&lt;/p&gt;&#10;&lt;p&gt;&lt;strong&gt;结论：先确认官方镜像里有没有，再决定要不要自己构建。&lt;/strong&gt; 检查方法：&lt;/p&gt;&#10;&lt;div class="highlight"&gt;&lt;div class="chroma"&gt;&#10;&lt;table class="lntable"&gt;&lt;tr&gt;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code&gt;&lt;span class="lnt"&gt;1&#10;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&#10;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-bash" data-lang="bash"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;docker &lt;span class="nb"&gt;exec&lt;/span&gt; hermes sh -c &lt;span class="s1"&gt;&amp;#39;echo $PLAYWRIGHT_BROWSERS_PATH; ls $PLAYWRIGHT_BROWSERS_PATH&amp;#39;&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/table&gt;&#10;&lt;/div&gt;&#10;&lt;/div&gt;&lt;h2 id="总结"&gt;总结&#10;&lt;/h2&gt;&lt;ul&gt;&#10;&lt;li&gt;部署只需要一个容器：官方镜像 + 数据目录挂载 + &lt;code&gt;gateway run&lt;/code&gt;。&lt;/li&gt;&#10;&lt;li&gt;s6 负责初始化和进程守护，不要覆盖入口。&lt;/li&gt;&#10;&lt;li&gt;&lt;code&gt;/opt/data&lt;/code&gt; 就是全部状态，备份它，并注意 &lt;code&gt;state.db&lt;/code&gt; 的 WAL 文件。&lt;/li&gt;&#10;&lt;li&gt;Dashboard 很好用，但认证和暴露范围要自己把关。&lt;/li&gt;&#10;&lt;/ul&gt;&#10;&lt;p&gt;下一篇讲模型层：怎么接入自建的模型网关，以及如何按任务给主模型和辅助模型分工。&lt;/p&gt;&#10;</description></item><item><title>Hermes 接入 New API 的提示词缓存排查：为什么 cached_tokens 总是 0</title><link>https://www.iminling.com/ai/hermes/hermes-agent-newapi-prompt-cache/</link><pubDate>Thu, 19 Nov 2026 00:00:00 +0000</pubDate><guid>https://www.iminling.com/ai/hermes/hermes-agent-newapi-prompt-cache/</guid><description>&lt;img src="https://images.iminling.com/i/2026/11/19/e78b7dc1f3976415b6b20150e7e36433.webp" alt="Featured image of post Hermes 接入 New API 的提示词缓存排查：为什么 cached_tokens 总是 0" /&gt;&lt;h2 id="问题现象"&gt;问题现象&#10;&lt;/h2&gt;&lt;p&gt;这是 Hermes Agent 架构系列的番外排查篇，背景见 &lt;a class="link" href="https://www.iminling.com/ai/hermes/hermes-agent-model-config/" &gt;模型篇&lt;/a&gt;。&lt;/p&gt;&#10;&lt;p&gt;Agent 每轮请求都会带上很长的固定前缀：系统提示词、技能列表、工具定义、记忆。理论上这正是提示词缓存（Prompt Cache）最擅长的场景，命中后输入费用能降一大截。&lt;/p&gt;&#10;&lt;p&gt;我在把 Hermes 接入自建的 New API 网关时，专门排查过一次提示词缓存：New API 消费日志里的 &lt;code&gt;cache_tokens&lt;/code&gt; 显示为 &lt;code&gt;0&lt;/code&gt;，看不出缓存到底有没有生效。&lt;/p&gt;&#10;&lt;p&gt;排查下来的结论是：&lt;strong&gt;不同厂商的提示词缓存根本不是同一种协议&lt;/strong&gt;，Hermes 侧选什么 &lt;code&gt;transport&lt;/code&gt;、New API 怎么路由渠道、网关如何统计 usage，每一层都可能让缓存失效或&amp;quot;看起来失效&amp;quot;。&lt;/p&gt;&#10;&lt;h2 id="环境与前提"&gt;环境与前提&#10;&lt;/h2&gt;&lt;ul&gt;&#10;&lt;li&gt;Hermes Agent 通过自定义 provider 接入 New API，调用 GPT、Grok、GLM，Claude 作为补充说明。&lt;/li&gt;&#10;&lt;li&gt;文中 Hermes 的关键行为已在 &lt;code&gt;v0.23.0&lt;/code&gt; 上核对；源码链接基于排查时的 &lt;code&gt;main@f751a8c&lt;/code&gt;（对应正式版 &lt;code&gt;v0.20.5&lt;/code&gt; 前后）。&lt;/li&gt;&#10;&lt;li&gt;New API 的结论基于 &lt;code&gt;v1.0.0-rc.25&lt;/code&gt;（&lt;code&gt;main@2d8e50b&lt;/code&gt;）。New API 更新较快，&lt;strong&gt;涉及 New API 的缺口请以你实际运行的版本为准&lt;/strong&gt;。&lt;/li&gt;&#10;&lt;li&gt;示例域名统一使用 &lt;code&gt;newapi.example.com&lt;/code&gt;。&lt;/li&gt;&#10;&lt;/ul&gt;&#10;&lt;h2 id="先给结论"&gt;先给结论&#10;&lt;/h2&gt;&lt;table&gt;&#10;&#9;&lt;thead&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;模型家族&lt;/th&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;上游缓存机制&lt;/th&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;Hermes 推荐 &lt;code&gt;transport&lt;/code&gt;&lt;/th&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;缓存亲和字段&lt;/th&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&lt;/thead&gt;&#10;&#9;&lt;tbody&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;Claude&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;显式 &lt;code&gt;cache_control&lt;/code&gt; 断点&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;anthropic_messages&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;cache_control&lt;/code&gt;，必要时用 &lt;code&gt;metadata.user_id&lt;/code&gt; 固定渠道&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;GPT&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;精确前缀缓存，&lt;code&gt;prompt_cache_key&lt;/code&gt; 辅助路由&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;codex_responses&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;prompt_cache_key&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;Grok&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;自动前缀缓存，Chat 和 Responses 用不同亲和字段&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;codex_responses&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;Responses 用 &lt;code&gt;prompt_cache_key&lt;/code&gt;，Chat 用 &lt;code&gt;x-grok-conv-id&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;GLM&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;自动隐式上下文缓存&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;chat_completions&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;无专用字段，保证前缀稳定并固定渠道&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&lt;/tbody&gt;&#10;&lt;/table&gt;&#10;&lt;p&gt;对应的做法：&lt;/p&gt;&#10;&lt;ul&gt;&#10;&lt;li&gt;Claude 走 New API 原生的 &lt;code&gt;/v1/messages&lt;/code&gt;，不要经过 OpenAI Chat 到 Claude Messages 的转换。&lt;/li&gt;&#10;&lt;li&gt;GPT 和 Grok 优先走 &lt;code&gt;/v1/responses&lt;/code&gt;，让 Hermes 自动生成稳定的 &lt;code&gt;prompt_cache_key&lt;/code&gt;。&lt;/li&gt;&#10;&lt;li&gt;GLM 保持 &lt;code&gt;/v1/chat/completions&lt;/code&gt;，依赖上游自动缓存。&lt;/li&gt;&#10;&lt;li&gt;非 Claude 模型不要开 Hermes 的 &lt;code&gt;prompt_caching&lt;/code&gt;，它只用于 Anthropic 风格的 &lt;code&gt;cache_control&lt;/code&gt;。&lt;/li&gt;&#10;&lt;li&gt;New API 有多个候选渠道时，一定要配置渠道亲和。&lt;/li&gt;&#10;&lt;li&gt;&lt;code&gt;cache_tokens = 0&lt;/code&gt; 不一定是上游没缓存，也可能是 New API 统计时丢了字段。&lt;/li&gt;&#10;&lt;/ul&gt;&#10;&lt;h2 id="排查过程"&gt;排查过程&#10;&lt;/h2&gt;&lt;h3 id="先分清是哪一类问题"&gt;先分清是哪一类问题&#10;&lt;/h3&gt;&lt;p&gt;&amp;ldquo;缓存是 0&amp;quot;其实有两种完全不同的情况：&lt;/p&gt;&#10;&lt;p&gt;&lt;strong&gt;第一类：上游真的没命中。&lt;/strong&gt; Hermes 请求的前缀变了、缺少亲和字段、或者被分散到不同渠道，上游响应里的 &lt;code&gt;cached_tokens&lt;/code&gt; 本身就是 0，New API 按普通输入计费。常见原因：&lt;/p&gt;&#10;&lt;ul&gt;&#10;&lt;li&gt;系统提示词、工具定义、消息顺序或模型名发生变化；&lt;/li&gt;&#10;&lt;li&gt;输入没达到模型的最低可缓存长度；&lt;/li&gt;&#10;&lt;li&gt;请求落到了不同的上游 API Key、组织、区域或模型实例；&lt;/li&gt;&#10;&lt;li&gt;两次请求间隔超过了缓存 TTL；&lt;/li&gt;&#10;&lt;li&gt;协议选错，或者缺少 &lt;code&gt;prompt_cache_key&lt;/code&gt;、&lt;code&gt;x-grok-conv-id&lt;/code&gt;，高并发时被路由到没有缓存的机器；&lt;/li&gt;&#10;&lt;li&gt;渠道其实不是官方上游，模型名一样，但缓存能力和计费规则不同。&lt;/li&gt;&#10;&lt;/ul&gt;&#10;&lt;p&gt;&lt;strong&gt;第二类：上游命中了，但 New API 没记下来。&lt;/strong&gt; 上游响应里 &lt;code&gt;cached_tokens &amp;gt; 0&lt;/code&gt;，New API 在协议转换或流式聚合时丢了这部分 usage，日志里显示 0，本地计费和上游真实成本对不上。&lt;/p&gt;&#10;&lt;p&gt;判断属于哪一类，要同时对比三样东西：New API 发往上游的请求、上游原始响应里的 usage、New API 最终消费日志里的 &lt;code&gt;cache_tokens&lt;/code&gt; 和 &lt;code&gt;cache_creation_tokens&lt;/code&gt;。&lt;strong&gt;只看前端那一列 0，下不了结论。&lt;/strong&gt;&lt;/p&gt;&#10;&lt;pre class="mermaid" style="visibility:hidden"&gt;flowchart TB&#10; Start[cache_tokens = 0] --&gt; Q1{Hermes 请求里&lt;br/&gt;有所需的亲和字段吗}&#10; Q1 --&gt;|没有| R1[Hermes provider / transport 配置问题]&#10; Q1 --&gt;|有| Q2{New API 发往上游时&lt;br/&gt;字段还在吗}&#10; Q2 --&gt;|丢了| R2[New API adaptor 或参数覆盖问题]&#10; Q2 --&gt;|在| Q3{上游原始 usage&lt;br/&gt;cached_tokens &gt; 0 ?}&#10; Q3 --&gt;|等于 0| R3[前缀、长度、TTL、模型支持或渠道轮换问题]&#10; Q3 --&gt;|大于 0| R4[New API usage 解析或流式聚合问题]&lt;/pre&gt;&lt;h3 id="hermes-侧provider-名字不会启用缓存"&gt;Hermes 侧：provider 名字不会启用缓存&#10;&lt;/h3&gt;&lt;p&gt;第一个误区是以为把 provider 命名为 &lt;code&gt;newapi-grok&lt;/code&gt;，Hermes 就会按 Grok 处理。实际上这个名字只是 &lt;code&gt;providers&lt;/code&gt; 下的一个引用键，改成 &lt;code&gt;my-router&lt;/code&gt; 效果完全一样，Hermes 不会因为名字里有 &lt;code&gt;grok&lt;/code&gt; 就把它识别成 xAI。&lt;/p&gt;&#10;&lt;p&gt;真正起作用的是这条因果链：&lt;/p&gt;&#10;&lt;div class="highlight"&gt;&lt;div class="chroma"&gt;&#10;&lt;table class="lntable"&gt;&lt;tr&gt;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code&gt;&lt;span class="lnt"&gt;1&#10;&lt;/span&gt;&lt;span class="lnt"&gt;2&#10;&lt;/span&gt;&lt;span class="lnt"&gt;3&#10;&lt;/span&gt;&lt;span class="lnt"&gt;4&#10;&lt;/span&gt;&lt;span class="lnt"&gt;5&#10;&lt;/span&gt;&lt;span class="lnt"&gt;6&#10;&lt;/span&gt;&lt;span class="lnt"&gt;7&#10;&lt;/span&gt;&lt;span class="lnt"&gt;8&#10;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&#10;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-text" data-lang="text"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;providers.&amp;lt;任意名称&amp;gt;.transport = codex_responses&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; → Hermes 明确选择 Responses transport&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; → 根据稳定的 instructions、tools 和会话 lineage 生成 prompt_cache_key&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; → 放进 /v1/responses 请求体&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; → New API 的 Responses 处理和 xAI adaptor 保留该字段&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; → xAI Responses API 正好也支持 prompt_cache_key&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; → xAI 把相关请求路由到同一台缓存服务器&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; → 相同前缀的后续请求才更可能命中&#10;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/table&gt;&#10;&lt;/div&gt;&#10;&lt;/div&gt;&lt;p&gt;生成 key 的代码见 &lt;a class="link" href="https://github.com/NousResearch/hermes-agent/blob/f751a8c5467c41500e505d90cb0eb8b70929080f/agent/transports/codex.py#L600-L623" target="_blank" rel="noopener"&#10; &gt;agent/transports/codex.py&lt;/a&gt;，xAI 对该字段的说明见 &lt;a class="link" href="https://docs.x.ai/developers/advanced-api-usage/prompt-caching/maximizing-cache-hits" target="_blank" rel="noopener"&#10; &gt;官方文档&lt;/a&gt;。&lt;/p&gt;&#10;&lt;h3 id="hermes-侧普通-custom-会悄悄回退到-chat"&gt;Hermes 侧：普通 custom 会悄悄回退到 Chat&#10;&lt;/h3&gt;&lt;p&gt;第二个坑是下面这种写法：&lt;/p&gt;&#10;&lt;div class="highlight"&gt;&lt;div class="chroma"&gt;&#10;&lt;table class="lntable"&gt;&lt;tr&gt;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code&gt;&lt;span class="lnt"&gt;1&#10;&lt;/span&gt;&lt;span class="lnt"&gt;2&#10;&lt;/span&gt;&lt;span class="lnt"&gt;3&#10;&lt;/span&gt;&lt;span class="lnt"&gt;4&#10;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&#10;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-yaml" data-lang="yaml"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nt"&gt;model&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;provider&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;custom&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;base_url&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;https://newapi.example.com/v1&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;api_mode&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;codex_responses&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/table&gt;&#10;&lt;/div&gt;&#10;&lt;/div&gt;&lt;p&gt;看起来已经指定了 Responses，但 Hermes 会把普通 custom 端点当作未知的兼容服务。为了避免把只支持 &lt;code&gt;/chat/completions&lt;/code&gt; 的服务错误地请求成 &lt;code&gt;/responses&lt;/code&gt;，域名不是已知的 OpenAI 或 xAI 地址时，它会&lt;strong&gt;忽略这个 &lt;code&gt;api_mode&lt;/code&gt; 并回退到 &lt;code&gt;chat_completions&lt;/code&gt;&lt;/strong&gt;，日志里只有一行 info：&lt;/p&gt;&#10;&lt;div class="highlight"&gt;&lt;div class="chroma"&gt;&#10;&lt;table class="lntable"&gt;&lt;tr&gt;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code&gt;&lt;span class="lnt"&gt;1&#10;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&#10;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-text" data-lang="text"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;Ignoring persisted custom api_mode=codex_responses for non-OpenAI endpoint&#10;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/table&gt;&#10;&lt;/div&gt;&#10;&lt;/div&gt;&lt;p&gt;回退之后就没有 &lt;code&gt;prompt_cache_key&lt;/code&gt; 了。这个行为在 &lt;code&gt;v0.23.0&lt;/code&gt; 中仍然存在（&lt;code&gt;hermes_cli/runtime_provider.py&lt;/code&gt;）。&lt;/p&gt;&#10;&lt;p&gt;正确做法是按协议拆成 named provider，在 provider 上声明 &lt;code&gt;transport&lt;/code&gt;：&lt;/p&gt;&#10;&lt;div class="highlight"&gt;&lt;div class="chroma"&gt;&#10;&lt;table class="lntable"&gt;&lt;tr&gt;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code&gt;&lt;span class="lnt"&gt; 1&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 2&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 3&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 4&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 5&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 6&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 7&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 8&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 9&#10;&lt;/span&gt;&lt;span class="lnt"&gt;10&#10;&lt;/span&gt;&lt;span class="lnt"&gt;11&#10;&lt;/span&gt;&lt;span class="lnt"&gt;12&#10;&lt;/span&gt;&lt;span class="lnt"&gt;13&#10;&lt;/span&gt;&lt;span class="lnt"&gt;14&#10;&lt;/span&gt;&lt;span class="lnt"&gt;15&#10;&lt;/span&gt;&lt;span class="lnt"&gt;16&#10;&lt;/span&gt;&lt;span class="lnt"&gt;17&#10;&lt;/span&gt;&lt;span class="lnt"&gt;18&#10;&lt;/span&gt;&lt;span class="lnt"&gt;19&#10;&lt;/span&gt;&lt;span class="lnt"&gt;20&#10;&lt;/span&gt;&lt;span class="lnt"&gt;21&#10;&lt;/span&gt;&lt;span class="lnt"&gt;22&#10;&lt;/span&gt;&lt;span class="lnt"&gt;23&#10;&lt;/span&gt;&lt;span class="lnt"&gt;24&#10;&lt;/span&gt;&lt;span class="lnt"&gt;25&#10;&lt;/span&gt;&lt;span class="lnt"&gt;26&#10;&lt;/span&gt;&lt;span class="lnt"&gt;27&#10;&lt;/span&gt;&lt;span class="lnt"&gt;28&#10;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&#10;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-yaml" data-lang="yaml"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nt"&gt;providers&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;newapi-gpt&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;api&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;https://newapi.example.com/v1&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;key_env&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;NEWAPI_API_KEY&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;transport&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;codex_responses&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;discover_models&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="kc"&gt;false&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;models&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;gpt-5.6&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;{}&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;newapi-grok&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;api&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;https://newapi.example.com/v1&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;key_env&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;NEWAPI_API_KEY&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;transport&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;codex_responses&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;discover_models&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="kc"&gt;false&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;models&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;grok-4.7&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;{}&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;newapi-glm&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;api&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;https://newapi.example.com/v1&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;key_env&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;NEWAPI_API_KEY&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;transport&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;chat_completions&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;discover_models&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="kc"&gt;false&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;models&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;glm-5.3&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;{}&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nt"&gt;model&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;provider&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;custom:newapi-grok&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;default&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;grok-4.7&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/table&gt;&#10;&lt;/div&gt;&#10;&lt;/div&gt;&lt;p&gt;会话中切换模型时，也用具体的 named provider：&lt;/p&gt;&#10;&lt;div class="highlight"&gt;&lt;div class="chroma"&gt;&#10;&lt;table class="lntable"&gt;&lt;tr&gt;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code&gt;&lt;span class="lnt"&gt;1&#10;&lt;/span&gt;&lt;span class="lnt"&gt;2&#10;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&#10;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-text" data-lang="text"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;/model custom:newapi-gpt:gpt-5.6&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;/model custom:newapi-glm:glm-5.3&#10;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/table&gt;&#10;&lt;/div&gt;&#10;&lt;/div&gt;&lt;h3 id="hermes-侧能拿到-cache-key不等于完整的-xai-支持"&gt;Hermes 侧：能拿到 cache key，不等于完整的 xAI 支持&#10;&lt;/h3&gt;&lt;p&gt;&lt;code&gt;custom:newapi-grok&lt;/code&gt; 在 Hermes 内部仍然是 custom provider。只有 provider 是 &lt;code&gt;xai&lt;/code&gt; / &lt;code&gt;xai-oauth&lt;/code&gt;，或者主机名是 &lt;code&gt;api.x.ai&lt;/code&gt; 时，Hermes 才会启用 xAI 专用行为（&lt;a class="link" href="https://github.com/NousResearch/hermes-agent/blob/f751a8c5467c41500e505d90cb0eb8b70929080f/agent/chat_completion_helpers.py#L1884-L1903" target="_blank" rel="noopener"&#10; &gt;判断代码&lt;/a&gt;，&lt;code&gt;v0.23.0&lt;/code&gt; 中逻辑未变）。&lt;/p&gt;&#10;&lt;table&gt;&#10;&#9;&lt;thead&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;能力&lt;/th&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;&lt;code&gt;custom:newapi-grok&lt;/code&gt; + &lt;code&gt;codex_responses&lt;/code&gt;&lt;/th&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&lt;/thead&gt;&#10;&#9;&lt;tbody&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;请求 New API 的 &lt;code&gt;/v1/responses&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;可以&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;生成通用的 &lt;code&gt;prompt_cache_key&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;可以&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;New API 把 key 转发给 xAI&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;可以，前提是渠道走 Responses 且没有被参数覆盖删掉&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;xAI 根据 key 做缓存路由&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;可以&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;Hermes 把它完整识别为 xAI&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;不可以&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;自动发送 Chat 专用的 &lt;code&gt;x-grok-conv-id&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;不可以&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;自动套用全部 Grok reasoning 参数规则&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;不可以&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;自动过滤 xAI 不支持的 &lt;code&gt;include&lt;/code&gt;、&lt;code&gt;service_tier&lt;/code&gt; 等字段&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;不保证&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&lt;/tbody&gt;&#10;&lt;/table&gt;&#10;&lt;p&gt;所以会出现&amp;quot;缓存能命中，但某些 Grok 型号报 &lt;code&gt;reasoning.effort&lt;/code&gt;、&lt;code&gt;include&lt;/code&gt; 或 &lt;code&gt;service_tier&lt;/code&gt; 不支持&amp;quot;的情况。这是 xAI transport 兼容性问题，不是缓存问题。&lt;/p&gt;&#10;&lt;h2 id="各模型的具体情况"&gt;各模型的具体情况&#10;&lt;/h2&gt;&lt;h3 id="gpt"&gt;GPT&#10;&lt;/h3&gt;&lt;p&gt;OpenAI 的提示词缓存要求渲染后的完整前缀匹配；GPT-5.6 及以后最低可缓存长度为 1024 tokens，更早的模型通常需要 2048。model、tools、系统指令、历史消息都会影响前缀。&lt;code&gt;prompt_cache_key&lt;/code&gt; 是路由提示，不保证命中，但高并发时能减少请求被分到没有缓存的机器（&lt;a class="link" href="https://developers.openai.com/api/docs/guides/prompt-caching/" target="_blank" rel="noopener"&#10; &gt;官方文档&lt;/a&gt;）。&lt;/p&gt;&#10;&lt;p&gt;推荐链路：Hermes &lt;code&gt;codex_responses&lt;/code&gt; → New API &lt;code&gt;/v1/responses&lt;/code&gt; → OpenAI Responses。New API 的 Responses 处理在流式和非流式下都会记录 &lt;code&gt;usage.input_tokens_details.cached_tokens&lt;/code&gt;。&lt;/p&gt;&#10;&lt;p&gt;如果某个 GPT 上游只支持 Chat Completions，Hermes 不会给自定义域名自动加 &lt;code&gt;prompt_cache_key&lt;/code&gt;。确认上游接受该字段后，可以给 provider 配一个固定的 key：&lt;/p&gt;&#10;&lt;div class="highlight"&gt;&lt;div class="chroma"&gt;&#10;&lt;table class="lntable"&gt;&lt;tr&gt;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code&gt;&lt;span class="lnt"&gt;1&#10;&lt;/span&gt;&lt;span class="lnt"&gt;2&#10;&lt;/span&gt;&lt;span class="lnt"&gt;3&#10;&lt;/span&gt;&lt;span class="lnt"&gt;4&#10;&lt;/span&gt;&lt;span class="lnt"&gt;5&#10;&lt;/span&gt;&lt;span class="lnt"&gt;6&#10;&lt;/span&gt;&lt;span class="lnt"&gt;7&#10;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&#10;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-yaml" data-lang="yaml"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nt"&gt;providers&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;newapi-gpt-chat&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;api&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;https://newapi.example.com/v1&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;key_env&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;NEWAPI_API_KEY&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;transport&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;chat_completions&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;extra_body&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;prompt_cache_key&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;hermes-gpt-workflow-v1&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/table&gt;&#10;&lt;/div&gt;&#10;&lt;/div&gt;&lt;p&gt;这个 key 按系统提示词和工具版本划分，不要带时间戳，也不要每轮随机生成。&lt;/p&gt;&#10;&lt;h3 id="grok"&gt;Grok&#10;&lt;/h3&gt;&lt;p&gt;xAI 的缓存规则：相邻请求开头完全相同时自动复用；Chat Completions 用 &lt;code&gt;x-grok-conv-id&lt;/code&gt; 请求头把同一会话路由到同一台服务器，Responses API 用请求体里的 &lt;code&gt;prompt_cache_key&lt;/code&gt; 达到同样效果。缓存存在具体服务器上，所以&lt;strong&gt;粘性路由对命中率非常关键&lt;/strong&gt;（&lt;a class="link" href="https://docs.x.ai/developers/advanced-api-usage/prompt-caching" target="_blank" rel="noopener"&#10; &gt;官方文档&lt;/a&gt;）。&lt;/p&gt;&#10;&lt;p&gt;走 Chat 很容易丢缓存，原因有两层：&lt;/p&gt;&#10;&lt;ul&gt;&#10;&lt;li&gt;Hermes 不知道 custom provider 背后是 xAI，不会自动发 &lt;code&gt;x-grok-conv-id&lt;/code&gt;；New API 默认也不透传任意请求头，需要显式配置 &lt;code&gt;pass_headers&lt;/code&gt;。&lt;/li&gt;&#10;&lt;li&gt;New API &lt;code&gt;rc.25&lt;/code&gt; 的 &lt;code&gt;xAIStreamHandler&lt;/code&gt; 在流式聚合 usage 时只复制了 &lt;code&gt;PromptTokens&lt;/code&gt;、&lt;code&gt;TotalTokens&lt;/code&gt;、&lt;code&gt;CompletionTokens&lt;/code&gt;，丢了 &lt;code&gt;PromptTokensDetails.CachedTokens&lt;/code&gt;（&lt;a class="link" href="https://github.com/QuantumNous/new-api/blob/f116414284162ad15d8925f7bca494c109b83e93/relay/channel/xai/text.go#L38-L60" target="_blank" rel="noopener"&#10; &gt;源码&lt;/a&gt;）。结果是 xAI 实际命中了缓存，New API 日志和本地计费却显示 0。非流式处理返回完整 usage，可以用 &lt;code&gt;stream: false&lt;/code&gt; 做对照。&lt;/li&gt;&#10;&lt;/ul&gt;&#10;&lt;p&gt;所以 Grok 优先走 Responses：Hermes 生成 key，New API 保留字段并正确记录 &lt;code&gt;cached_tokens&lt;/code&gt;，同时绕开了 Chat 流式统计的缺口。&lt;/p&gt;&#10;&lt;p&gt;如果必须继续用 Chat，需要同时满足三点：Hermes 发出稳定的 &lt;code&gt;x-grok-conv-id&lt;/code&gt;、New API 渠道允许透传这个请求头、New API 修复流式 usage 聚合。&lt;/p&gt;&#10;&lt;h3 id="glm"&gt;GLM&#10;&lt;/h3&gt;&lt;p&gt;智谱 GLM 使用自动上下文缓存，不需要手动加任何缓存字段，重复的系统提示词和多轮历史会被自动识别，命中情况在 &lt;code&gt;usage.prompt_tokens_details.cached_tokens&lt;/code&gt; 中（&lt;a class="link" href="https://docs.z.ai/guides/capabilities/cache.md" target="_blank" rel="noopener"&#10; &gt;官方文档&lt;/a&gt;）。注意小的格式变化也会降低命中。&lt;/p&gt;&#10;&lt;p&gt;所以 GLM 保持 &lt;code&gt;transport: chat_completions&lt;/code&gt;，不要开 &lt;code&gt;prompt_caching&lt;/code&gt;。New API 的智谱适配器会重建请求，但保留消息、工具和顺序；它不保留 &lt;code&gt;prompt_cache_key&lt;/code&gt;，不过 GLM 本来也不依赖这个字段。New API 读取智谱 usage 时会依次尝试 &lt;code&gt;prompt_tokens_details.cached_tokens&lt;/code&gt;、&lt;code&gt;input_tokens_details.cached_tokens&lt;/code&gt;、&lt;code&gt;cached_tokens&lt;/code&gt;、&lt;code&gt;prompt_cache_hit_tokens&lt;/code&gt; 几种格式。&lt;/p&gt;&#10;&lt;p&gt;另外，New API &lt;code&gt;rc.25&lt;/code&gt; 的智谱适配器还没有实现 Responses 转换，所以 GLM 不能和 GPT、Grok 一起统一切到 Responses。&lt;/p&gt;&#10;&lt;h3 id="claude"&gt;Claude&#10;&lt;/h3&gt;&lt;p&gt;Claude 要走原生链路：Hermes &lt;code&gt;anthropic_messages&lt;/code&gt; → New API &lt;code&gt;/v1/messages&lt;/code&gt; → Claude Messages 上游。&lt;/p&gt;&#10;&lt;p&gt;不要让它经过 New API 的 OpenAI Chat → Claude Messages 转换。&lt;code&gt;rc.25&lt;/code&gt; 在这个转换里重建 system 和文本块时没有复制 &lt;code&gt;CacheControl&lt;/code&gt;（&lt;a class="link" href="https://github.com/QuantumNous/new-api/blob/f116414284162ad15d8925f7bca494c109b83e93/relaykit/relayconvert/internal/oai_chat/to_claude_messages_req.go#L255-L269" target="_blank" rel="noopener"&#10; &gt;system&lt;/a&gt;、&lt;a class="link" href="https://github.com/QuantumNous/new-api/blob/f116414284162ad15d8925f7bca494c109b83e93/relaykit/relayconvert/internal/oai_chat/to_claude_messages_req.go#L331-L338" target="_blank" rel="noopener"&#10; &gt;文本块&lt;/a&gt;），缓存断点在半路就丢了。原生 Claude 渠道直接透传原请求，没有这个问题。&lt;/p&gt;&#10;&lt;h2 id="new-api-侧渠道亲和"&gt;New API 侧：渠道亲和&#10;&lt;/h2&gt;&lt;p&gt;New API 一个模型配了多个渠道时，同一会话的请求可能在不同账号、区域或实例之间轮换，每换一次都是一次冷启动。渠道亲和就是让相关请求尽量落到同一个渠道。&lt;/p&gt;&#10;&lt;p&gt;&lt;code&gt;rc.25&lt;/code&gt; 的默认亲和规则只覆盖了这一种情况（&lt;a class="link" href="https://github.com/QuantumNous/new-api/blob/f116414284162ad15d8925f7bca494c109b83e93/setting/operation_setting/channel_affinity_setting.go#L113-L150" target="_blank" rel="noopener"&#10; &gt;源码&lt;/a&gt;）：&lt;/p&gt;&#10;&lt;div class="highlight"&gt;&lt;div class="chroma"&gt;&#10;&lt;table class="lntable"&gt;&lt;tr&gt;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code&gt;&lt;span class="lnt"&gt;1&#10;&lt;/span&gt;&lt;span class="lnt"&gt;2&#10;&lt;/span&gt;&lt;span class="lnt"&gt;3&#10;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&#10;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-text" data-lang="text"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;model: ^gpt-.*$&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;path: /v1/responses&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;key: prompt_cache_key&#10;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/table&gt;&#10;&lt;/div&gt;&#10;&lt;/div&gt;&lt;p&gt;也就是说，GPT Responses 默认能按 Hermes 的 key 固定渠道，但 Grok Responses、GLM Chat，以及 &lt;code&gt;openai/gpt-*&lt;/code&gt; 这类带前缀的模型名都不在范围内。可以增加一条自定义规则：&lt;/p&gt;&#10;&lt;div class="highlight"&gt;&lt;div class="chroma"&gt;&#10;&lt;table class="lntable"&gt;&lt;tr&gt;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code&gt;&lt;span class="lnt"&gt; 1&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 2&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 3&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 4&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 5&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 6&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 7&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 8&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 9&#10;&lt;/span&gt;&lt;span class="lnt"&gt;10&#10;&lt;/span&gt;&lt;span class="lnt"&gt;11&#10;&lt;/span&gt;&lt;span class="lnt"&gt;12&#10;&lt;/span&gt;&lt;span class="lnt"&gt;13&#10;&lt;/span&gt;&lt;span class="lnt"&gt;14&#10;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&#10;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-json" data-lang="json"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="p"&gt;{&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; &lt;span class="nt"&gt;&amp;#34;name&amp;#34;&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;&amp;#34;hermes non-claude cache affinity&amp;#34;&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; &lt;span class="nt"&gt;&amp;#34;model_regex&amp;#34;&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;&amp;#34;^gpt-.*$&amp;#34;&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;&amp;#34;^grok-.*$&amp;#34;&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;&amp;#34;^glm-.*$&amp;#34;&lt;/span&gt;&lt;span class="p"&gt;],&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; &lt;span class="nt"&gt;&amp;#34;path_regex&amp;#34;&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;&amp;#34;^/v1/(responses|chat/completions)$&amp;#34;&lt;/span&gt;&lt;span class="p"&gt;],&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; &lt;span class="nt"&gt;&amp;#34;key_sources&amp;#34;&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nt"&gt;&amp;#34;type&amp;#34;&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;&amp;#34;gjson&amp;#34;&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nt"&gt;&amp;#34;path&amp;#34;&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;&amp;#34;prompt_cache_key&amp;#34;&lt;/span&gt; &lt;span class="p"&gt;},&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nt"&gt;&amp;#34;type&amp;#34;&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;&amp;#34;context_int&amp;#34;&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nt"&gt;&amp;#34;key&amp;#34;&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;&amp;#34;id&amp;#34;&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; &lt;span class="p"&gt;],&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; &lt;span class="nt"&gt;&amp;#34;ttl_seconds&amp;#34;&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;3600&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; &lt;span class="nt"&gt;&amp;#34;skip_retry_on_failure&amp;#34;&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;false&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; &lt;span class="nt"&gt;&amp;#34;include_using_group&amp;#34;&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; &lt;span class="nt"&gt;&amp;#34;include_model_name&amp;#34;&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; &lt;span class="nt"&gt;&amp;#34;include_rule_name&amp;#34;&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="p"&gt;}&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/table&gt;&#10;&lt;/div&gt;&#10;&lt;/div&gt;&lt;p&gt;含义：&lt;/p&gt;&#10;&lt;ul&gt;&#10;&lt;li&gt;GPT、Grok 的 Responses 请求优先按请求体里的 &lt;code&gt;prompt_cache_key&lt;/code&gt; 固定渠道；&lt;/li&gt;&#10;&lt;li&gt;GLM Chat 没有这个字段，退回按 New API 的用户 ID 固定；&lt;/li&gt;&#10;&lt;li&gt;&lt;code&gt;skip_retry_on_failure: false&lt;/code&gt; 偏向可用性，固定的渠道失败后允许换，但换过去的第一次请求会冷启动；改成 &lt;code&gt;true&lt;/code&gt; 亲和更强，但渠道故障时不会自动换路。&lt;/li&gt;&#10;&lt;/ul&gt;&#10;&lt;p&gt;几个注意点：规则按顺序匹配，先命中的生效；&lt;code&gt;model_regex&lt;/code&gt; 匹配的是进入 New API 时的模型名，不是映射后的上游模型名；如果每个模型本来就只有一个渠道，亲和规则就不是必需的。&lt;/p&gt;&#10;&lt;h2 id="验证方法"&gt;验证方法&#10;&lt;/h2&gt;&lt;h3 id="先不用-hermes直接测-new-api"&gt;先不用 Hermes，直接测 New API&#10;&lt;/h3&gt;&lt;p&gt;直接向 New API 连续发两三次请求：模型、系统提示词、工具及其顺序、长历史前缀都相同，只改最后一条用户消息，在缓存 TTL 内完成，验证期间只启用一个渠道。然后检查：&lt;/p&gt;&#10;&lt;div class="highlight"&gt;&lt;div class="chroma"&gt;&#10;&lt;table class="lntable"&gt;&lt;tr&gt;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code&gt;&lt;span class="lnt"&gt;1&#10;&lt;/span&gt;&lt;span class="lnt"&gt;2&#10;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&#10;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-text" data-lang="text"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;GPT / Grok Responses：usage.input_tokens_details.cached_tokens&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;GPT / GLM Chat： usage.prompt_tokens_details.cached_tokens&#10;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/table&gt;&#10;&lt;/div&gt;&#10;&lt;/div&gt;&lt;p&gt;如果直接请求都命中不了，问题和 Hermes 无关，去查上游、模型支持、前缀和渠道路由。&lt;/p&gt;&#10;&lt;h3 id="再验证-hermes"&gt;再验证 Hermes&#10;&lt;/h3&gt;&lt;p&gt;逐项确认：&lt;/p&gt;&#10;&lt;ul&gt;&#10;&lt;li&gt;GPT、Grok 的 provider 确实是 &lt;code&gt;transport: codex_responses&lt;/code&gt;，GLM 是 &lt;code&gt;chat_completions&lt;/code&gt;；&lt;/li&gt;&#10;&lt;li&gt;没有给非 Claude 模型开 &lt;code&gt;prompt_caching&lt;/code&gt;；&lt;/li&gt;&#10;&lt;li&gt;Responses 请求体里有 &lt;code&gt;prompt_cache_key&lt;/code&gt;，并且跨轮稳定；&lt;/li&gt;&#10;&lt;li&gt;连续几轮被 New API 分到了同一个渠道；&lt;/li&gt;&#10;&lt;li&gt;系统提示词、工具和早期消息逐字稳定。&lt;/li&gt;&#10;&lt;/ul&gt;&#10;&lt;h3 id="grok-流式与非流式对照"&gt;Grok 流式与非流式对照&#10;&lt;/h3&gt;&lt;p&gt;对同一个 Grok Chat 渠道，用相同的长前缀和亲和 ID 分别发 &lt;code&gt;stream: false&lt;/code&gt; 和 &lt;code&gt;stream: true&lt;/code&gt; 的请求。如果非流式 &lt;code&gt;cache_tokens &amp;gt; 0&lt;/code&gt;、流式等于 0，基本可以确定是 New API 流式 usage 聚合丢了字段。&lt;/p&gt;&#10;&lt;h3 id="判定标准"&gt;判定标准&#10;&lt;/h3&gt;&lt;p&gt;最终只认这一条：&lt;/p&gt;&#10;&lt;div class="highlight"&gt;&lt;div class="chroma"&gt;&#10;&lt;table class="lntable"&gt;&lt;tr&gt;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code&gt;&lt;span class="lnt"&gt;1&#10;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&#10;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-text" data-lang="text"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;同一真实上游 + 同一稳定前缀 + 后续请求的 cached_tokens &amp;gt; 0&#10;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/table&gt;&#10;&lt;/div&gt;&#10;&lt;/div&gt;&lt;p&gt;并且 New API 日志记录了相同的缓存量。只看到配置名、key 存在或渠道固定，都只能说明链路&lt;strong&gt;可能&lt;/strong&gt;生效，不能证明命中。&lt;/p&gt;&#10;&lt;h2 id="不要这样做"&gt;不要这样做&#10;&lt;/h2&gt;&lt;ul&gt;&#10;&lt;li&gt;&lt;strong&gt;只调 New API 的缓存倍率。&lt;/strong&gt; 如果上游真实 &lt;code&gt;cached_tokens = 0&lt;/code&gt;，调低 &lt;code&gt;cache_ratio&lt;/code&gt; 只是本地少扣费，上游照常收钱，真实成本一分没降。&lt;/li&gt;&#10;&lt;li&gt;&lt;strong&gt;给所有模型开 &lt;code&gt;prompt_caching&lt;/code&gt;。&lt;/strong&gt; 这会把 Anthropic 风格的 &lt;code&gt;cache_control&lt;/code&gt; 注入 GPT、Grok、GLM 请求，轻则被忽略，重则改变消息结构或被严格的上游拒绝。&lt;/li&gt;&#10;&lt;li&gt;&lt;strong&gt;每轮生成不同的 cache key。&lt;/strong&gt; 时间戳、随机 UUID 都会把本可复用的请求打散。key 应该对应稳定的提示词和工具版本，或者稳定的会话。&lt;/li&gt;&#10;&lt;li&gt;&lt;strong&gt;只看第一次请求。&lt;/strong&gt; 第一次通常是冷请求或写入缓存，要看后续相同前缀的请求。&lt;/li&gt;&#10;&lt;li&gt;&lt;strong&gt;把代码推断当成实测结果。&lt;/strong&gt; 读代码只能说明字段可能被发送、丢失或解析，最终要用真实请求验证。&lt;/li&gt;&#10;&lt;/ul&gt;&#10;&lt;h2 id="相关-issue-与-pr"&gt;相关 issue 与 PR&#10;&lt;/h2&gt;&lt;p&gt;Hermes Agent：&lt;/p&gt;&#10;&lt;ul&gt;&#10;&lt;li&gt;&lt;a class="link" href="https://github.com/NousResearch/hermes-agent/issues/84506" target="_blank" rel="noopener"&#10; &gt;LiteLLM OpenAI wire 0 缓存问题 #84506&lt;/a&gt;，修复 &lt;a class="link" href="https://github.com/NousResearch/hermes-agent/pull/87517" target="_blank" rel="noopener"&#10; &gt;#87517&lt;/a&gt;&lt;/li&gt;&#10;&lt;li&gt;&lt;a class="link" href="https://github.com/NousResearch/hermes-agent/pull/85554" target="_blank" rel="noopener"&#10; &gt;Anthropic 自定义模型别名缓存 #85554&lt;/a&gt;&lt;/li&gt;&#10;&lt;li&gt;&lt;a class="link" href="https://github.com/NousResearch/hermes-agent/pull/93321" target="_blank" rel="noopener"&#10; &gt;custom OpenAI Chat provider 的逐模型缓存声明 #93321&lt;/a&gt;&lt;/li&gt;&#10;&lt;li&gt;&lt;a class="link" href="https://github.com/NousResearch/hermes-agent/issues/70382" target="_blank" rel="noopener"&#10; &gt;GPT-5.6 显式 cache breakpoint 讨论 #70382&lt;/a&gt;&lt;/li&gt;&#10;&lt;/ul&gt;&#10;&lt;p&gt;New API：&lt;/p&gt;&#10;&lt;ul&gt;&#10;&lt;li&gt;&lt;a class="link" href="https://github.com/QuantumNous/new-api/issues/1601" target="_blank" rel="noopener"&#10; &gt;OpenAI 格式请求 Claude 渠道的缓存计费问题 #1601&lt;/a&gt;&lt;/li&gt;&#10;&lt;li&gt;&lt;a class="link" href="https://github.com/QuantumNous/new-api/issues/6538" target="_blank" rel="noopener"&#10; &gt;Chat/Claude 转 Responses 丢失 prompt cache key #6538&lt;/a&gt;&lt;/li&gt;&#10;&lt;li&gt;&lt;a class="link" href="https://github.com/QuantumNous/new-api/issues/5982" target="_blank" rel="noopener"&#10; &gt;Claude Messages 转 OpenAI 残留 &lt;code&gt;cache_control&lt;/code&gt; #5982&lt;/a&gt;&lt;/li&gt;&#10;&lt;li&gt;&lt;a class="link" href="https://github.com/QuantumNous/new-api/pull/6691" target="_blank" rel="noopener"&#10; &gt;Claude 转 OpenAI 的 cache control 和 prompt key 相关 PR #6691&lt;/a&gt;&lt;/li&gt;&#10;&lt;/ul&gt;&#10;&lt;h2 id="总结"&gt;总结&#10;&lt;/h2&gt;&lt;p&gt;最终推荐的拓扑（中间都经过 New API，连线上标的是 New API 的入口路径）：&lt;/p&gt;&#10;&lt;pre class="mermaid" style="visibility:hidden"&gt;flowchart LR&#10; H1[newapi-gpt&lt;br/&gt;codex_responses] --&gt;|/v1/responses| U1[GPT 上游&lt;br/&gt;prompt_cache_key + 渠道亲和]&#10; H2[newapi-grok&lt;br/&gt;codex_responses] --&gt;|/v1/responses| U2[xAI 上游&lt;br/&gt;prompt_cache_key + 渠道亲和]&#10; H3[newapi-glm&lt;br/&gt;chat_completions] --&gt;|/v1/chat/completions| U3[Z.AI 上游&lt;br/&gt;自动缓存 + 渠道亲和]&#10; H4[newapi-claude&lt;br/&gt;anthropic_messages] --&gt;|/v1/messages| U4[Claude 上游&lt;br/&gt;原生 cache_control]&lt;/pre&gt;&lt;p&gt;这套拆分的重点不是&amp;quot;给每个模型都打开缓存&amp;rdquo;，而是让每个模型使用它真实上游认可的缓存协议，并让同一个稳定前缀尽量落到同一个缓存命名空间。排查时从 Hermes 请求、New API 转发、上游原始 usage、New API 日志四层逐层取证，不要凭一个 0 下结论。&lt;/p&gt;&#10;</description></item></channel></rss>