Hermes Agent：实践者参考指南（2026）

简而言之： Hermes Agent 是 Nous Research 推出的开源自我改进型 AI 智能体。它既能作为 CLI 运行，也能充当多平台消息 gateway；可在磁盘上存储持久身份与长期记忆，汇集随使用不断改进的 skill，并支持任何兼容 OpenAI 的 LLM 提供商——Nous Portal、OpenRouter、Anthropic、GitHub Copilot、z.ai、Kimi、MiniMax、DeepSeek、Qwen Cloud、Hugging Face、Google、xAI/SuperGrok，以及您自行托管的端点。¹²¹⁹ 当前版本为 v0.21.5（标签 v2026.9.24，发布于2026年9月24日），是 v0.21 系列的汇总补丁版本；v0.21.5 的新增内容介绍了具体变更，其后的版本章节按从新到旧的顺序排列。⁵² 对大多数新用户而言，最难的部分是提供商身份验证：在标签 v2026.9.24 中，Hermes 的静态选择器列表内置了39个提供商，并通过38个捆绑的提供商插件自动扩展该列表，此外还支持自定义端点；身份验证则分为3条不同路径（.env 中的 API 密钥、通过 hermes model 使用 OAuth，或在 config.yaml 中配置自定义端点）。⁵³ 首先需要掌握的是身份验证模型——后续一切都取决于最终解析出的提供商。

Hermes Agent 是完整的智能体运行时，而非聊天工具的简单封装。它能够读取文件系统、在沙箱后端执行命令、抓取网页、生成子智能体、运行预定的 cron 任务，通过单一 gateway 进程与 Telegram/Discord/Slack/WhatsApp/Signal/Email 通信，还能从实践经验中创建自己的 skill。¹ CLI 是构建在 run_agent.py 对话循环之上的终端 UI；gateway 则是一个长期运行的进程，负责将各消息平台的消息路由至同一对话循环。³

Hermes 的普通用法与专家级用法之间，差别归结为5个系统。 掌握它们，Hermes 就能成为事半功倍的利器：

1. 提供商解析：身份验证流程如何映射到 API 调用
2. 配置层级：config.yaml + .env + auth.json + SOUL.md + AGENTS.md
3. Tool + toolset 系统：智能体能够执行哪些操作，以及各平台如何加以限制
4. Skills 系统：由智能体创建并持续演进的程序性记忆
5. Gateway + cron + profiles：让 Hermes 在您的常用平台上运行，而不局限于您当前所在的环境

核心要点

• 提供商身份验证有3条路径，而非只有1条。 .env 中的 API 密钥、通过 hermes model/hermes auth 使用 OAuth，或在 config.yaml 中配置自定义端点。应选择与提供商匹配的路径，而不是仅凭熟悉程度选择。
• 切换提供商只需一条命令。 hermes model 会以交互方式引导您完成每个受支持提供商的配置，包括 OAuth 登录；/model provider:model 则可在会话中途切换模型，同时保留历史记录。²
• 用户可编辑的配置界面由2个文件组成。 ~/.hermes/config.yaml 存放设置，~/.hermes/.env 存放密钥。auth.json、SOUL.md、MEMORY.md 和 skills/ 由 Hermes 直接管理——您可以手动编辑 SOUL.md，其余内容则由智能体自行修改。⁴
• Hermes 是 OpenClaw 的后继者。 如果您正在迁移，hermes claw migrate 可自动导入30多个类别的状态。⁵
• 默认情况下，辅助任务使用您的主模型。 视觉处理、批准分类、压缩和会话标题会作为独立的“辅助” LLM 调用运行；在该标签版本中，auto 会将这些任务全部路由至主聊天模型——无需额外配置，但若使用昂贵的推理模型，这些附带任务会带来不可忽视的成本。必要时，可将各个 auxiliary.<task> 槽位分别指向低成本的快速模型。⁴³⁴

以下各节均以 hermes-agent.nousresearch.com/docs 的上游文档和 github.com/NousResearch/hermes-agent 的源代码树为依据。每项事实性陈述均附有脚注，指向其来源所在的具体上游页面。

选择适合您的路径

Hermes 的工作原理：心智模型

Hermes 围绕一个可由任意入口调用的单一对话循环构建。这些入口包括 CLI（cli.py）、消息 gateway（gateway/run.py）、用于编辑器集成的 ACP 适配器、批处理运行器，以及一个 API 服务器。³它们最终都会调用 run_agent.py 中的 AIAgent.run_conversation()，该方法会：

1. 通过 agent/prompt_builder.py，根据 SOUL.md、MEMORY.md、USER.md、skill、上下文文件和工具指南构建系统提示词（2026年9月的拆分将其移入了新的 agent/ 包）³
2. 通过 runtime_provider.py 解析运行时提供商——此步骤会选择身份验证方式、基础 URL 和 API 模式³
3. 使用以下3种 API 模式之一调用提供商：chat_completions、codex_responses 或 anthropic_messages³
4. 通过 model_tools.py 和中央工具注册表（tools/registry.py）分派返回的所有工具调用³
5. 持续循环，直至模型生成最终响应，然后将会话持久化到支持 FTS5 的 SQLite 中³

理解这一循环至关重要，因为所有功能——个性、记忆、skill、压缩、回退——都依附于其中某个阶段。当您查看某个配置键并想知道它有何作用时，答案通常是：“它是用于调节上述循环第1、2、3或4阶段的参数。”

与平台无关的核心。一个 AIAgent 类同时服务于 CLI、gateway、ACP、批处理和 API 服务器。平台差异存在于入口层，而非 agent 本身。³正因如此，同一组斜杠命令既可在终端中使用，也可在 Telegram 中使用——这些命令均由 hermes_cli/commands.py 中共享的 COMMAND_REGISTRY 分派。⁶

目录结构就是系统本身。Hermes 将所有内容存储在 ~/.hermes/ 下（非默认 profile 则存储在 $HERMES_HOME 下）：⁴

~/.hermes/
├── config.yaml        # Settings (model, terminal, TTS, compression, etc.)
├── .env               # API keys and secrets
├── auth.json          # OAuth provider credentials (Nous Portal, Codex, Anthropic)
├── SOUL.md            # Primary agent identity (slot #1 in system prompt)
├── memories/          # Persistent memory (MEMORY.md, USER.md)
├── skills/            # Bundled + agent-created + hub-installed skills
├── cron/              # Scheduled jobs
├── sessions/          # Gateway session state
└── logs/              # agent.log, gateway.log, errors.log (secrets auto-redacted)

上述每个文件各司其职，彼此之间并无重叠。如果您想知道“Hermes 将 X 存储在哪里”，答案就在其中。

v0.21.5 的新增内容（9月24日汇总版本）

Hermes Agent v0.21.5（标签 v2026.9.24，发布于2026年9月24日）是当前版本，也是 v0.21.x 系列的第3个小型汇总版本：“此标签将自 v0.21.4 以来合并的约460个 PR 汇总为一个稳定的标签版本，供下游使用者采用”。精选发行说明再次推迟至 v0.22.0 发布。以下是面向运维人员的变更，均已根据该标签下的源代码核实：⁵²⁵³

• Hindsight memory 已移出核心代码树。内置的 Hindsight 提供商和 hermes-agent[hindsight] pip 可选依赖均已移除；Hindsight 现由 Vectorize 维护，并通过插件目录安装；发行说明并未提及此项变更。如果配置中设置了 memory.provider: hindsight，hermes update 会将目录中的插件安装到所有引用它的 profile 主目录中。若仍未安装，首次启动 agent 时也会自动安装，除非 security.allow_lazy_installs 为 false（此时请运行 hermes plugins install hindsight）。设置、.env 键和记忆数据均保持不变。请参阅外部记忆提供商。
• gateway.multiplex_profiles: false 已停用。gateway 会将其原地改写为 true，并显示一次性方框提示。必须保留独立 gateway 的命名 profile，需要在自身的 config.yaml 中设置 gateway.standalone: true；若要让某个由主机服务的 profile 下线，hermes -p <name> gateway stop 现在会将其暂停，而不会停止主机。请参阅消息 Gateway。
• Nous 和 OpenRouter 模型选择器中新增模型：GPT-6 Sol 和 GPT-6 Luna（两者均提供 -pro 变体），以及 Claude Opus 5.5。
• 插件兼容性保持不变：plugins.allow_deprecated_imports: true 仍然有效。

更新方式：运行 hermes update 或安装程序的一行命令；Docker 和 Hermes Cloud 镜像基于 nousresearch/hermes-agent:v2026.9.24 构建。⁵²

v0.21.4 新增内容（第二个汇总补丁）

Hermes Agent v0.21.4（标签 v2026.9.21，2026年9月21日）是 v0.21.x 系列中第二个刻意保持精简的汇总版本。其自身定位是：“补丁版本。此标签将自 v0.21.3 以来合并的约 1,800 个 PR 汇总为稳定的带标签版本，供下游使用者（Docker 镜像、Hermes Cloud、托管部署）使用。”自 v0.21.3 以来的窗口包含“5,071 个非合并提交”，涉及“5,169 个变更文件”“1,812 个已合并 PR”和“2,116 个已关闭问题”。按提交数计算，这是项目历史上标签之间第二大的变更窗口，仅次于 v0.21.1 的 5,139 个提交；按已合并 PR 数计算，则是最大的一次。精选整理工作再次推迟，原文如下：“此窗口的完整精选发布说明将随 v0.22.0 发布，并记录从 v0.21.0 开始的所有内容”，以及“此窗口中的任何内容都不会遗漏。”发布说明确实列出了暂未记录的内容，以下每一项均已在该标签的源代码中核查；若某项变更涉及本指南中的既有章节，则会在行内给出链接。⁵⁰⁵¹

• 每台主机仅运行一个 gateway，Desktop 采用连接方式而非重新启动。 规则是：每台主机上的每个操作系统用户只能运行一个 hermes serve 和一个 hermes gateway run，二者各自对所有 profile 进行多路复用。新的主机级单例层会强制执行此规则：胜出进程在其整个生命周期内持有主机锁，同时通过包含 (pid, createTime) 的会合记录，使第二次调用能够确认所有者仍是同一存活进程，并直接连接，而非绑定第二个端口。系统始终通过证据判定记录是否过期，绝不凭空假设。Desktop 应用也从自身一侧采用相同机制，连接正在运行的主机后端，而不是再启动一个后端。Messaging Gateway介绍了具体机制。⁵¹
• 连接器统一为后端所有的一项操作，并共用一张设置卡片。 一次 manage_connections 工具调用会驱动后端的纯数据连接状态机，而 Desktop、TUI 和 CLI 都将其渲染为同一张设置卡片：每项缺失的凭据对应一个字段；在所有必填字段均有内容之前，卡片的操作按钮都会保持禁用。请参阅 Nous 免费层级小节。⁵¹
• --format stream-json：机器可读的单次运行。 hermes chat -q ... --format stream-json 会为 CI 运行程序和编排器在 stdout 的每一行输出一个 JSON 对象：先是 system/init 事件，随后是 text 增量、tool_use、tool_result 事件，最后是一个终止 result 信封，其中包含退出代码、最终文本和 token 统计信息。诊断信息和会话 ID 保留在 stderr；每个事件中的工具输出上限为 5,000 个字符；该标志隐含启用 --quiet，且必须与 -q 或 --query-file 配合使用（未提供时以代码 2 退出），并且不能与 --tui 组合使用。hermes chat 选项表中列出了此标志。⁵¹
• skills.auto_load 将 skill 固定加载到每个会话中。 config.yaml 中 skills.auto_load 下列出的名称会在每个新会话中完整加载——无论是 CLI、TUI、gateway、cron 还是 API——并在首次构建提示词时统一解析一次。Skills System新增了“固定加载的 Skills”小节。⁵¹
• 为未经授权的私信新增 decline 选项。 unauthorized_dm_behavior 除 pair 和 ignore 外新增第三个值：decline 会发送一次礼貌的拒绝消息，此后在 24 小时内不再回复该发送者。请参阅用户授权与配对。⁵¹
• mcp.discovery_concurrency 限制 MCP 发现连接的并发数。 默认值为 4，0 表示不设限制；所有已配置的服务器仍会建立连接，只是不再同时发起。请参阅 MCP 集成。⁵¹
• session_search 支持时间范围和召回重试。 发现参数新增 after/before 范围（支持 ISO 格式或 7d 之类的相对时长）；多词查询若返回零条结果，系统会改为匹配任意词项并重试，而不再沿用 FTS5 隐含的所有词项 AND 逻辑。请参阅会话搜索。⁵¹
• hermes sessions set-journal-mode delete|wal：离线日志模式转换器。 这是用于修复 state.db 卡在错误 SQLite 日志模式下的自助方案——此前必须手动运行 PRAGMA journal_mode=DELETE。请先停止 gateway、dashboard 和所有 CLI：只要任何其他进程仍持有该数据库，命令就会拒绝执行；它不会等待占用者退出，而是直接失败，并会在转换后核验 SQLite 文件头字节。Windows 不支持占用者扫描，因此在该平台上，您必须自行停止所有 Hermes 进程并传入 --force，否则命令会拒绝执行。hermes doctor 现在会引导使用此命令。顶级命令中的 hermes sessions 行已收录该功能。⁵¹
• Desktop：字体设置、一键更新引擎以及卸载插件。 设置中新增按 profile 持久化到 desktop.font_family 的字体系列字段。它会覆盖聊天和 UI 中主题的无衬线字体；建议列表优先展示无障碍字体（OpenDyslexic、Atkinson Hyperlegible、Lexend）；留空则由主题决定。托管的本地模型运行时会在有可用更新时显示“更新引擎”按钮；更新失败后按钮仍会保留，便于直接重试。此外，Plugins 中心现在支持通过确认对话框卸载插件。⁵¹
• 视频目录：LTX 2.5 和 Kling O3。 FAL 视频插件新增 ltx-2.5（Lightricks 的开源音视频模型：原生音频、最长 20 秒/4K 图生视频、相机运动预设、低价层级——fal 会拒绝分辨率为 1440p/2160p 且时长超过 10 秒的片段）和 kling-o3（Kuaishou 的前沿模型系列，属高价层级：支持原生多镜头叙事、可选音频，时长 3～15 秒）。⁵¹
• 插件目录成为随产品发布的目录和网站。 仓库中的 plugin-catalog/ 目录从 v2026.9.14 时的 9 个条目增至此标签下的 228 个——每个插件对应一个经过审核的 YAML，并固定到精确的提交 SHA。文档网站现在还会为每个插件和每位作者构建单独页面，每个页面均从固定提交中渲染插件的 README。此版本点名的 10 个社区插件在该标签下均已收录于目录中。Plugin System介绍了详细信息。⁵¹
• 此外还有大规模修复，涉及 profile/多路复用隔离、cron、看板、Desktop 和 state.db；发布说明仅将其作为一个类别提及，具体修复的精选记录将由 v0.22.0 补充。⁵⁰

插件兼容性回退在此窗口中仍未落地。 在 v2026.9.21 中，COMPAT_MANIFEST.md、compat_manifest.json 和兼容性垫片仍然存在；此窗口内对 hermes_cli/plugin_compat.py 的改动仅包括进程级扫描缓存（多路复用 gateway 会为每个受服务的 profile 发现一次插件，而在启动路径中重复解析每个插件的源代码会为每个 profile 增加约 0.4 秒开销），以及 Windows 上采用 POSIX 格式的命中路径（#112576）。日期门槛和字面量布尔值逃生通道均未改变，因此 plugins.allow_deprecated_imports: true 仍能让受影响的插件继续加载。Plugin System中的兼容性说明框记录了当前状态。⁴²

更新方式不变：git 安装使用 hermes update，全新安装则使用 shell 安装程序；Docker 和 Hermes Cloud 镜像均基于此标签构建（nousresearch/hermes-agent:v2026.9.21）。⁵⁰

v0.21.3 新增内容（9月14日补丁）

Hermes Agent v0.21.3（标签 v2026.9.14，2026年9月14日）涵盖 main 分支上又 3 天的变更，发布说明仅列出两项内容。之所以发布此版本，是因为 Cloud agent 会自动更新到最新发布标签，而访问这些 agent 需要修复远程 gateway 登录问题。（1）远程 dashboard 会话不再因集中刷新请求而被撤销：gateway 上的两条刷新路径（cookie 门控和 Desktop 的原生 bearer 路由）现在会将携带同一轮换刷新 token 的并发请求合并为单次执行。因此，Desktop 唤醒时的一波请求不再会把已轮换的 token 重放到 Portal 的复用检测机制中，进而撤销整个会话。刷新操作也已移出事件循环，因此缓慢的身份提供商不会再冻结 /api/status。（2）长时间运行的进程不再创建重复的 state.db 写入句柄：gateway、dashboard/Desktop 后端、ACP 和 CLI 读取器均以只读方式连接，而进程内写入器则共享注册表中的句柄。窗口统计数据为：“1,036 个非合并提交”，涉及“2,642 个变更文件”和“338 个已合并 PR”。其余内容均有意延后整理：发布说明明确列出了暂未记录的项目（每个模型选择器上的推理强度选择器、OpenRouter OAuth PKCE、HEIF/HEIC/AVIF 解码、一批 FAL 目录更新、Slack 粘贴表格和 Agent Sessions API、跨虚拟机文件系统上对 state.db WAL 模式的拒绝，以及其他内容），并原文承诺：“此窗口的完整精选发布说明将随 v0.22.0 发布，并记录从 v0.21.0 开始的所有内容”，以及“此窗口中的任何内容都不会遗漏。”⁴⁹

插件兼容性截止日期也如期到来。 v0.21.1 宣布的 2026年9月14日移除计划在已发布代码中以日期门槛生效，而非代码回退：在标签 v2026.9.14 中，hermes_cli/plugin_compat.py 包含 COMPAT_REMOVAL_DATE = 2026-09-14，且 removal_in_effect() 从该日期起返回 true（若清单文件消失，则会更早返回 true），因此受影响的外部插件现在会在加载时被禁用，并显示红色通知。尚未发生的是：真正删除旧导入路径的回退。COMPAT_MANIFEST.md、compat_manifest.json 和兼容性垫片在该标签下仍然存在——截至9月22日，在 v2026.9.21 和 main 上也依然存在——这正是 plugins.allow_deprecated_imports: true 仍能作为逃生通道的原因：只要加载器获准继续执行，旧路径仍可解析。这里有两个容易踩中的问题：该键必须是字面量 YAML 布尔值（代码只接受布尔值 True；根据源代码注释“Literal boolean only”，"true" 或 "false" 之类的带引号字符串会被视为未设置）；而且一旦回退落地，此通道将立即失效，因为路径本身会随之消失。Plugin System中的兼容性说明框记录了当前状态。⁴²⁴⁹

v0.21.2 的新变化（state.db 补丁版本）

Hermes Agent v0.21.2（标签为 v2026.9.11，发布于2026年9月11日）的首要任务，是修复 v0.21.0 引入的问题。发布说明直言不讳：“v0.21.0 对会话存储的连接处理机制进行了大规模重写，但在部分安装环境中，这导致 state.db 变得脆弱：多个写入方会相互取消对方的锁，正常数据库被误报为损坏，一条异常记录就能导致 sessions list 整体失败。此版本彻底解决了这一类问题，同时汇总了 v0.21.1 发布后4天内合入 main 的其他所有改动。”与 v0.21.1 刻意简略的说明不同，此版本记录了自身的重点更新；该时间窗口内共有“947次非合并提交”，涉及“1,869个变更文件”和“312个已合并 PR”，贡献者达“140人”。至于整个 v0.21.x 阶段的精选记录，仍将由 v0.22.0 补全。⁴⁸

• state.db 可靠性专项治理：6个 PR，关闭44个问题。 发布说明首先给出了面向运维人员的建议，您也应照此处理：如果 state.db 在0.21.0或0.21.1中损坏，请运行 hermes doctor——它现在会分别指出结构损坏与全文搜索索引损坏，而不再将所有问题笼统称为“FTS 写入损坏”；如果重建仍不足以解决问题，它还会引导您使用 hermes sessions recover --inspect-only（离线、非破坏性、固定到指定 profile；无需创建输出数据库即可报告规范表的可读性）。根因修复工作消除了存储上的所有第二写入方：profile gateway 过去每5秒就会将托管房间状态写入根 state.db，现在这些协调数据改存于专用的 shared-state.db，因此 profile gateway 再也不会以可写方式打开主会话存储；dashboard 会优先以只读方式打开数据库；cron 的生命周期防护现在通过受跟踪的连接注册表执行，而不会对正在使用的数据库直接调用原始 open()（后者会取消 gateway 的 POSIX 锁，堪称导致 SQLite 损坏的经典操作）；此外，doctor --fix 会拒绝执行无法确认安全的 checkpoint。除写入方问题外：FTS 索引损坏现在只会导致搜索降级，并在稍后重建索引，不再使整个交互回合失败并关闭；一条损坏记录不再拖垮 sessions list、导出或 insights（异常记录会显示为 ?，并通过警告指出对应会话）；会话绝不会绑定或读取其他 profile 的数据库；只读打开也不再获取写锁，因此在繁忙 gateway 后运行一次性 hermes 时，耗时已从卡顿4至20秒后失败缩短至0.01秒。⁴⁸
• 强化多 profile 隔离。 自 v0.19.0 起，本指南一直援引项目方的说法：profile 路由为每个 profile 提供“完全隔离的配置、skills、内存和密钥”。到 v0.21.2，这一承诺中曾存在的漏洞现已补齐：次要 profile 的机器人会继承默认 profile 的允许列表；适配器可能将凭据发送到默认 profile 的主机；stdio MCP 服务器会收到默认 profile 的保险库密钥；MEDIA: 交付可能附带其他 profile 的 .env、auth.json 或 state.db；webhook 和 Feishu 回调可能偏离路由指定的 profile；次要 profile 还可能从进程级备忘缓存中获取同级 profile 的 Nous bearer（#107609-#107630）。如果您在一个多路复用 gateway 下运行多个 profile，那么从此版本开始，隔离承诺才真正名副其实。⁴⁸
• 对密码不可见的凭据保险库。 现在，agent 可以通过 1Password、Bitwarden 或本地 Hermes 保险库在浏览器中登录、付款和填写地址，全程无需查看任何密钥；双因素验证码可以来自已保存的身份验证器密钥（TOTP：base32 种子或 otpauth://totp URI；不接受基于计数器的 HOTP），也可以在您的 UI 中请求输入。所有后端都向 agent 提供相同的数据结构——登录元数据加上不透明的命名空间句柄（本地为 vault_，另有 op:、bw:），密码仅在填写时解析；外部密码管理器在当前会话中解锁前会始终保持锁定，而主密码“绝不会作为工具参数，绝不会出现在 argv 中，也绝不会被持久化”。此功能建立在 v0.19.0 的 SecretSource 工作之上；该机制已将提供商的 API 密钥移出明文 .env，如今保险库也为 agent 的浏览器凭据提供了同等保护。⁴⁸
• 精选且以 SHA 固定版本的插件目录。 hermes plugins browse 会列出“精选插件目录中的每个条目”，hermes plugins search 用于查询目录，而 hermes plugins install 除 Git URL 和 owner/repo 外，也能解析目录名称。hermes plugins pack 则通过“声明式、可共享的插件集合”完善了整套功能：使用一个 hermes-pack.yaml 将一组插件固定到精确的提交 SHA；pack install 将其展开为常规的固定版本安装，同时仍按插件逐一征求能力授权；pack export 为当前安装生成 pack；pack show 则用于试运行。插件系统的命令块已包含这些新子命令。⁴⁸
• Nous 免费层级与引导式首次启动。 全新安装开箱即用，只需一条命令登录，即可获得免费推理和连接器；也可以在聊天中使用 /login，并通过 tool_search 搜索连接器工具（Gmail、Linear、Notion 等）。桌面应用的引导式首次启动由 HERMES_GUEST_ONBOARDING=1 控制，并且只有字面值 1 才会启用：桌面应用自身的测试明确断言，'true'、'0' 和空值都会使其保持关闭；启动决策还会写入新生成后端的环境中，从而杜绝继承值意外渗入。请参阅 Nous Tool Gateway。⁴⁸
• 桌面后端的批量重复启动问题已成过去。 Bot Mode 过去会在启动时以及每次 roster tick 时，针对每个 profile 启动或连接一个后端；鼠标悬停在 Bots roster 上时，会为每一行启动一个后端；切换 profile 还可能重复启动主后端。这些问题均已在此版本窗口内修复。⁴⁸

更新方式保持不变：现有安装运行 hermes update，全新安装则使用 shell 安装程序。⁴⁸

v0.21.1 的新增内容（汇总补丁）

Hermes Agent v0.21.1（标签 v2026.9.7，2026年9月7日）刻意保持精简：这是一个“补丁版本”，“汇总了自 v0.21.0 以来当前 main 分支的内容，供使用标签部署的用户和下游使用者使用”。正文给出了这一时间窗口的统计数据——“4,364 个变更文件中包含 5,139 个非合并提交（+601,014 / -768,419）”以及“632 个已合并 PR”——随后将完整说明留待后续发布：“这一时间窗口经过整理的完整发行说明将随 v0.22.0 发布。”这使其成为项目历史上相邻标签之间规模最大的单次变更窗口（此前没有任何相邻标签窗口超过 v2026.7.20..v2026.7.30 的 2,790 个非合并提交），却配上了最简短的发行说明。在 v0.22.0 给出经过整理的正式记录之前，以下6组变化代表了在此标签版本中操作 Hermes 时需要关注的内容，且每项均已通过源代码验证。⁴¹

• 代码库已经拆分，插件兼容倒计时于9月14日结束。 2026年9月的代码拆分（PR #102117）将仓库中的大型模块拆成了职责明确的文件：新的 agent/ 包承载对话循环的内部实现（包含214个顶层模块和7个子包；prompt_builder.py 现位于 agent/prompt_builder.py，而 run_agent.py 仍是 AIAgent 的所在地）；CLI 的子命令解析器移入 hermes_cli/subcommands/ 包（61个模块）；静态 CANONICAL_PROVIDERS 列表从 hermes_cli/models.py 移至 hermes_cli/models_catalog_static.py（列表本身没有变化：仍为39个静态条目，并继续根据39个内置提供商插件目录自动扩展）；delegate_task 则拆分至约12个 tools/delegate_tool_* 模块。内部导入路径并非稳定的 API，因此仓库根目录新增了 COMPAT_MANIFEST.md，通过旧模块路径重新导出1,148个“moved-lazy”公共名称；解析每个名称时，每个进程仅会为该名称发出一次 HermesPluginCompatWarning。此兼容层只是临时措施，并已按计划于2026年9月14日移除，即标签发布6天后生效——这并非通过代码回滚实现，而是由已随版本交付的代码中的日期门控触发。自该日起，受影响的第三方插件将不会加载：CLI 横幅、hermes doctor 和 hermes update 会显示红色通知，指出被禁用的插件；桌面端会显示一次性模态窗口；hermes plugins list 则会列出具体原因。如果您运行外部插件，请务必检查：hermes plugins compat <path> 会输出每一处仍使用旧路径的位置，格式为 file:line 并附带旧路径 -> 新路径；只要仍有残留，命令就会以状态码1退出（使用 --json 可获得机器可读输出；不带参数运行则会扫描已安装的全部插件）。若插件作者尚未完成适配，可在 config.yaml 中设置 plugins.allow_deprecated_imports: true 作为权宜之计，而且该设置目前仍然有效：截至9月22日，真正删除旧导入路径的回滚尚未合入（已验证至标签 v2026.9.21 及 main 分支），因此只要加载器获准继续运行，旧路径仍可解析。后续详情请参阅上文的 v0.21.2 的新增内容；插件系统一节则包含当前状态说明框。⁴²
• Gateway 对话彻底不再按计时器轮换。 会话生命周期文档现已明确规定：“空闲时间和实际经过时间都不会触发对话轮换。/new 和 /reset 会创建明确的边界；context compression 会继续管理较长的历史记录。旧版计时器配置将被忽略。现有 SessionResetPolicy 数据类型仅作为无实际作用的兼容数据保留，并非运行时策略。”边界必须由用户明确创建；如果您通过 hermes claw migrate 带入了 OpenClaw 时代的会话重置计时器，这些计时器如今只是无实际作用的数据。请参阅消息 Gateway。⁴³
• MCP 授权新增设备代码流程。 hermes mcp login <name> 新增 --flow {browser,device}：browser 是现有的 PKCE 流程；device 是符合 RFC 8628 的设备代码登录流程，适用于难以使用浏览器回调的机器；该标志会覆盖服务器的 oauth.flow 配置。此次更新还强化了 MCP 的其他身份验证环节：在整个 OAuth 会话中强制执行 profile 所有权检查；格式错误的 OAuth 元数据缓存会被忽略，不再导致服务器卡死；桌面端则通过客户端本地回调中继 MCP OAuth。此外，-t/--toolsets 现在也会筛选究竟启动哪些已配置的 MCP 服务器，因此一次性运行 hermes -z -t <toolsets> 时，不会再冷启动不需要的服务器。MCP 集成的命令块现已加入 login 和 reauth [--all]；这两项命令早在本次更新前便已存在，只是此前未在本文档中说明。⁴⁴
• Delegation 对后台工作的处理更加如实可靠。 以下是 delegate_task 的6项可靠性改进，均直接取自该标签版本的 delegate 工具源代码。（1）默认情况下，一个后台批次只会返回一次完整结果；启用 delegation.independent_completions 后，则会将调用拆分成多个完成单元：具有相同 group 值的任务会合并并统一报告，没有分组的任务则会在各自完成时单独报告。采用默认行为是有意为之——源代码指出，逐任务密集返回完成通知会“让没有为此制定计划的编排器支离破碎”。（2）子代理结束时，其后台进程会被终止，除非子代理使用 process_manage(action="handoff") 将进程移交给父代理；未移交的残留进程会在结果中以 orphaned_processes 列出，而已经退出但从未被读取的子进程则会以 unread_completions 呈现，并附带输出末尾内容。根据源代码文档字符串所表达的设计立场，父代理“必须从运行时获知这一情况”，而不能轻信子代理声称的“监视程序正在运行”。（3）delegation.fallback_providers 成为真正可用的配置项：null 会让未固定提供商的子代理继承父代理的回退链；[] 会禁用回退；按提供商、端点或模型固定的子代理不会获得回退，除非此设置明确声明回退项。（4）子代理回退链通过规范化器解析，因此格式错误的条目会被丢弃，而不会导致生成失败。（5）单元执行途中崩溃不再导致已完成的子代理结果丢失：多子代理单元中的每个已完成子代理都会被持久记录在该单元自身的行中，并作为部分结果保留至恢复后的结果里。（6）子代理绝不会继承1小时的提示词缓存层级：委派的子代理会降至5分钟层级，因为1小时层级的定价面向暂时离开的真人用户，而非短时间内并行运行的一批子代理。⁴⁵
• 提供商和模型。 Nous Portal 和 OpenRouter 目录新增 OpenAI 的 GPT-6 Astra 与 Astra Pro，并提供 -fast/-flex 速度层级变体（“价格2倍，优先层级”/“价格0.5倍，弹性层级”）。在 ChatGPT/Codex OAuth 路由中，Astra 受账户权限控制（只有实时、账户范围的发现流程才能公布该模型），并新增可选择启用的 -900k 选择器变体，将标示的272K上下文窗口提升至经实时验证的约900K；该后缀绝不会在线路上传输。同期新增的还有：anthropic/claude-fable-5.1、google/gemini-3.7-flash 和 gemini-3.8-flash、qwen/qwen3.8-max-0902 和 qwen3.8-flash，以及 Meta 的 Muse Spark 1.3 系列（1M上下文，含贡献者变体）和一个 Meta muse-image 图像生成提供商插件。Tavily 作为网页搜索/提取后端加入（TAVILY_API_KEY；通过 hermes tools 选择 Tavily 时无需密钥也能使用）。托管式 llama.cpp 运行时让本地模型成为一等支持路径（官方二进制文件、一个受监管的 llama-server，以及桌面端一键安装），代码树之外的外部进程提供商也获得了专用解析分支。在运维方面，选择器的远程目录现在每20分钟刷新一次（model_catalog.ttl_minutes，默认值为20；旧版 ttl_hours 键仅在用户曾明确设置时才会继续生效）。⁴⁶
• 桌面端：标注页面，掌控会话。 应用内浏览器新增评论模式：点击 Annotate，然后点击实时页面中的任意元素（或拖动框选区域）并输入备注；保存后的评论会保留为带编号的图钉，而且绝不会自行发送对话轮次。完成后，“Add N comments”会将整批评论交给编辑器，并为每个图钉附上裁剪后的屏幕截图；每条元素评论还会携带其 CSS 选择器、标记以及影响布局的计算样式，使代理能够在源代码中准确找到该元素，而不必看图猜测（标记离开页面前，会隐藏密码值、不可见值以及名称形似密钥的属性）。较大的批次会按页面区域分组，因此20多条评论会整理成少量工作项，通常分别涉及不同文件——这正是能够安全地将它们分派给并行 worker 的原因。除此之外，本次更新还带来了：结构化会话控件和会话自动化控件、通过拖动创建会话、用于导入其他编码代理对话记录的会话导入视图、display.resume_last_session（默认为 true：冷启动时重新打开上一次聊天或页面）、首次打开 Browser 窗格且 browser.use_real_profile 处于关闭状态时显示的同意提示（允许用户选择启用该设置）、Capabilities -> Skills 下内置的可选 skill 目录及一键安装功能，以及新的俄语桌面端界面语言（CLI 的17个语言区域目录保持不变）。⁴⁷

更新方式没有变化：现有安装运行 hermes update，全新安装则使用 shell 安装程序。该时间窗口经过整理的正式记录将由 v0.22.0 给出；以上各组内容则是在此标签版本中真正产生变化的部分。⁴¹

v0.21.0（The Pantheon Release）新增内容

Hermes Agent v0.21.0（标签v2026.8.31，2026年8月31日）是当前功能版本，也是整个v0.20.x汇总发布序列一直留待整理的权威记录：“此版本汇总了v0.20.1至v0.20.6基础设施补丁标签中的全部内容——这些发布窗口现已在此处完整记录。”其叙事承接Herald：“v0.20.0让Hermes成为传令者——他开口传讯，并将消息带给其他代理。在v0.21.0中，众神齐聚。”以下是未经改动的统计数据：“自v0.20.0以来：约5,800次提交 · 约2,475个合并的PR · 约5,680个变更文件 · 约869,000行新增 · 约135,000行删除 · 约2,100个问题已关闭 · 760多位贡献者”。³⁵

此版本按功能领域组织，以下摘要亦是如此。若某项功能改变了本指南中的既有章节，相关链接会直接标注在对应内容中。

• Bot Mode：内置功能让您的代理组成一个社会。 Bot Mode从v0.20.3发布窗口中捆绑的hermes-bots插件，升级为桌面应用默认启用的组成部分。每个代理profile都有名称、带随机化和锁定控制的确定性头像，并在共享名册中占有一席之地；您可以创建类似Discord的群聊，让多个机器人与您在同一房间中交流，通过编辑器@提及任意机器人，还能为房间设置名称和图片。其子功能包括标明来源的代理间消息卡片、发送方送达通知、实现即时唤醒的优先绘制hydration、Routines面板，以及基于应用设计系统的重新构建。引用该版本的原话：“过去，‘多代理’意味着一套管道系统；如今，它看起来就像一个坐满同事的聊天应用。”³⁵
• hermes peer：代理之间的机器人私信。 任何Hermes代理都可以通过handle向其他代理发送消息，跨profile、跨gateway皆可；既能从CLI发起，也能在对话中操作——例如让研究机器人将调查结果交给编程机器人，再直接在当前位置查看回复。“回复会进入每个代理的规范Bot Chat，因此代理之间的对话可持久保存且可供检查，而非发出即忘。”hermes peer命令（添加、列出、移除peer以及dm）已收录在顶级命令表中。³⁵
• 能够记忆的Cron任务。 计划任务不再像金鱼般转瞬即忘：cron代理会像其他代理一样加载并更新持久记忆；continuity=true会将每次运行的输出带入下一次运行，让监控程序能够依据已报告的内容去重；每项任务都会获得持久的notepad暂存区；没有变化时，monitor模式任务会完全跳过LLM；可为每项任务固定推理强度；cron输出还可发送到机器人的规范Bot Chat，并由机器人真正作出回应。计划任务（Cron）章节现已记录每项功能在该标签版本中的具体机制。³⁵³⁷
• 实时subagent编排。 delegate_task新增控制操作：列出正在运行的子代理、在执行过程中向某个子代理发送修正指令，或提前停止它并保留部分结果。可以依据JSON schema验证子代理输出；结果中会显示每次委派的成本；默认值也提高至每个subagent 250次迭代和10个并发子代理（即v0.19.0中取代max_async_children的统一上限）。³⁵³⁸
• MCP指挥中心。 MCP服务器和catalog整合到一个桌面页面中，支持通过拖入内容进行“粘贴任何内容”式导入；后台健康检查会及时提醒您重新认证，避免工具调用失败；还提供涵盖整个服务器群的成本和用量叠加层（schema token估算、每台服务器30天用量），以及在明确确认后安装MCP服务器的hermes://深层链接。请参阅MCP集成。³⁵
• 一波CLI增强功能。 按Ctrl+P可打开模糊搜索命令面板（也可通过/palette访问）；/model选择器会随输入实时筛选；/status会显示推理模式、待处理审批和context用量；状态栏可显示实时缓存命中率、延迟和每秒token数，并可分别切换各字段。此外还加入了全局紧急停止、会话固定与取消固定、轮换显示的编辑器占位提示，以及终端宠物。关于命名需特别注意：发布说明将试运行审批检查器称为hermes approval-check；但在该标签版本中，实际命令是hermes approvals test——并不存在approval-check子命令。³⁵⁴⁰
• 代理可以操控桌面应用中的浏览器。 应用内浏览器不再只是一个仅供代理查看的窗口：Hermes能够直接导航、点击和读取页面；页面也可弹出至系统浏览器，并提供完整的链接上下文菜单。³⁵
• 6家新provider与一轮model catalog更新。 Meta Model API（Muse Spark）、CommandCode、Tencent TokenPlan、Nebius Token Factory、Ramp Router和Actual Computer。其中3家（Meta AI、CommandCode、Actual Computer）已在早期汇总发布窗口中加入，并已收录于provider完整矩阵；矩阵现在新增Tencent TokenPlan、Nebius Token Factory和Ramp Router，以及文档中新加入的Alibaba Token Plan SKU。各catalog新增GLM-5.3-Flash、qwen3.8-max/flash、Gemini 3.7 Flash、MiniMax M3 free、Nemotron 3.5 Lightning和Muse Spark 1.2。此外还包含两项结构性变更：通过config.yaml中的model_overrides，无需等待新版本即可修正任意model的context窗口或定价；provider现在也可以通过pip安装的软件包形式发布，并借助entry point自动发现。统一的选择保护注册表还会在所有选择器界面中发出警告，提示某个model是否会使用您的数据进行训练。³⁵³⁶
• 全方位安全加固。 对受保护代理指令文件（AGENTS.md、skills和memory存储）的写入如今一律需要审批，防止遭受提示注入的代理悄然改写自身的常驻指令；一次深入的脱敏排查修补了终端错误、.env读取、checkpoint和ACP日志中的秘密泄露缺口；审批系统新增对Windows破坏性命令的识别；macOS权限授权现在通过稳定的TCC签名身份（hermes desktop --setup-tcc-identity）跨版本更新保留；上游项目遭入侵后，Blender MCP catalog条目及其skill已被移除。有关该标签版本的具体信息，请参阅安全加固。³⁵³⁹
• Gateway日趋成熟。 Slack新增原生实时卡片（真正的流式回复，以及可选启用的计划/任务卡片）和出站链接预览抑制；Telegram新增内联选择器，可通过@botname搜索所有命令和skill，从而绕过Telegram的命令菜单数量上限；relay通道日趋完善（原生插件初始化、支持草稿流式传输的实时卡片操作、会话跨度分段，并恢复语音消息STT）；gateway控制套接字允许服务器群使用方查询gateway，也让更新程序能够优雅地暂停gateway，而不必终止整个进程树；当watchdog触发时，turn-reaper会捕获卡死worker的堆栈。³⁵
• 一轮skills更新。 包括8项抢救恢复的生产力skills（document-to-action-items、meeting-action-items、email-inbox-triage、github-issue-to-pr、weekly-review-planning、competitor-news-monitor、product-price-monitor、social-media-content-calendar）、基于HAR生成的API客户端（“只需观察网站一次，此后无需浏览器即可直接调用其隐藏的API”）、publish-site、session-librarian、blocked-page-recovery、merge-reconciler、plan-interrogation，以及在创建时运行的建议性SKILL.md linter。³⁵

在此发布窗口中已回退（不会随版本发布）： Model Council模式（/council）和DCP context engine都曾合入，随后被回退；仅支持WS的gateway服务器（#94245）合入后也被回退（#96118），因此FastAPI仍保留在桌面应用启动路径中——但带序列戳的事件重放（#94219）以及通过WebSocket实现的桌面应用无损重连，确实已随版本发布。Electron已回退至40.10.2。如果社区对v0.20.x发布窗口的报道提及其中任何功能，请注意它们并未包含在此版本中。³⁵

更新方式保持不变：已有安装可运行hermes update，全新安装则使用shell安装程序。下文Herald版本下的汇总小节仍按标签记录每个发布窗口加入的具体内容。³⁵

v0.20.0（The Herald Release）新增内容

Hermes Agent v0.20.0（标签 v2026.8.3，2026年8月3日）是 v0.21.0 汇总所有变更之前的功能版本；v0.20.1（8月13日）和 v0.20.2（8月16日）是在此基础上发布的稳定版本，而 v0.20.3（标签 v2026.8.16.2，发布于8月17日）、v0.20.4（标签 v2026.8.18，8月18日）、v0.20.5（标签 v2026.8.19，发布于8月21日）和 v0.20.6（标签 v2026.8.27，8月27日）继续推进汇总发布，并且各自也涵盖了新的功能变更——详见下方小节。自 v0.19.0 以来，此阶段涵盖约 3,650 次提交、1,400 个已合并 PR，以及由 650 多位贡献者关闭的 1,200 个议题。⁵⁵

以下3项变更使本指南早期版本中的操作说明不再适用。 请务必先阅读这些内容：

• 现在要求使用 Node 26。 安装程序固定使用 NODE_VERSION="26"，并会拒绝旧版运行时，提示“Node.js … is too old (Hermes requires Node >=26)”。安装程序、heal 和 upgrade 均会强制执行此要求。请注意，文档站点的安装页面仍标注 Node v22——安装脚本和发行说明更新更及时，应以它们为准。⁵⁵
• pip 和 Homebrew 已停止支持，而不只是弃用。 原文明确写道：“brew + pip/PyPI wheel channels retired (shell installer / Docker / Nix are the supported channels).”如果仍通过 pip 或 brew 安装，该渠道将不再收到新版本。⁵⁵
• 默认工具调用迭代上限已从 90 提高到 500。 长时间自主运行不会再撞上人为设置的限制，下文所有预算压力阈值也都按照新的上限计算。read_file 的默认读取行数也从 500 行增加到 2,000 行。⁵⁵

此版本的其他更新：

• 对话式语音。 支持可随时打断的流式 TTS，以及设备端唤醒词。⁵⁵
• A2A v1.0。 新增智能体间协议插件，解决了议题 #514 中长期存在的需求。⁵⁵
• 已签名的出站 Webhook。 此前 hermes webhook 仅支持入站；v0.20.0 新增使用 HMAC 签名的出站生命周期 Webhook，可用于会话、轮次和工具事件。⁵⁵
• 有依据的引用。 新增带事实核查模式的 skill。⁵⁵
• 面向高级用户的 CLI 功能浪潮。 !command 可立即运行 shell 命令，无需消耗模型轮次；/init 会扫描项目并写入或更新 AGENTS.md；/diff 可从任何界面显示已暂存、全部或当前会话的变更；/context 会分析上下文窗口被哪些内容占用；/focus 提供精简输出视图，并可恢复隐藏行；Ctrl+S 可暂存尚未写完的提示词。hermes import-agent 能通过一条命令迁移 Claude Code 或 Codex CLI 配置。⁵⁵
• 密钥功能扩展。 新增可与所有保险库组合使用的命令辅助密钥源、附带可操作启动错误提示的一键令牌轮换、可选的 Bitwarden 加密紧急访问缓存、按 profile 主目录限定作用域的保险库注入密钥，以及 config.yaml 与 MCP 配置之间的 ${env:VAR} SecretRef 对等支持。下文所述的三路径身份验证模型保持不变。⁵⁵
• 热启动更快。 hermes -w 的冷启动时间从约 14 秒降至 1.8 秒。⁵⁵
• 桌面端正式成为一个平台。 支持带版本卡片和沙箱化实时预览的工件、以 Kanban 为首个桌面插件的 Plugin SDK、快速输入全局快捷键、多个 GUI 窗口、SSH 远程后端模式，以及符合 RFC 8252 的原生登录。⁵⁵

v0.20.3、v0.20.4、v0.20.5 和 v0.20.6 汇总版本（8月17日至27日）

项目在 v0.20.0 之后采用高频标签汇总的发布节奏，而且这些版本并非仅用于稳定性维护。4个版本都以相同方式推迟了精选发行说明——均声明“full curated release notes for this window will ship with v0.21.0”——如今 v0.21.0 已经兑现承诺：上方的 v0.21.0（The Pantheon Release）新增内容 是整个阶段的精选记录（该版本确认这些时间窗口“are fully documented here”）。下列内容仍作为各标签发布时的同期记录保留，用于明确每个标签分别引入了哪些内容；精选发行说明则将它们合并整理。^54233035

v0.20.3（自 v0.20.2 以来约 250 次提交、约 125 个 PR）：

• 迁移至 MCP 2.x SDK，支持 2026-07-28 无状态协议。 Hermes 升级至当前一代 MCP SDK，并支持该协议的无状态修订版。⁵⁴
• Bot Mode 作为捆绑插件发布（hermes-bots），内含核心队友协议。⁵⁴
• 新增 CommandCode 提供商插件，纳入提供商目录。⁵⁴
• 用于计算机操作的 Cua Driver 0.20 运行时契约，并强化子进程 Python 运行时所有权（隔离 PYTHONHOME/PYTHONPATH）。⁵⁴
• 可靠性改进：cron 调度器自我修复（EMFILE 恢复、过期认领协调、卡死作业重新启用）、会话移交数据丢失修复、桌面端远程 gateway 连接自我修复，以及一系列生态系统移植功能（插件安装安全扫描、/worktree、/rollback 保留手动编辑内容、读取 UTF-16 文件）。⁵⁴

v0.20.4（自 v0.20.3 以来约 146 次提交、约 74 个 PR）：

• 桌面端的玻璃质感界面：加入磨砂玻璃与半透明效果，并提供模糊效果选择器和 macOS 预选功能。⁵⁴
• 带 SESSIONS|BOTS 标签页的侧边栏，可分别隐藏或显示各个机器人；此外还修复了 Bot Mode 群聊问题（长时间运行的成员轮次、Markdown 渲染、跨设备路由）。⁵⁴
• 安装 skill 时执行 NVIDIA SkillEvaluator Tier 1 提示性扫描——安装 skill 时会运行许可证与安全检查。⁵⁴
• 强化 cron 媒体发送功能（可配置超时、手动运行附件、显示错过的触发任务），修复 SessionDB 事件循环线程与争用问题，确保 hermes update 如实报告搁置分支状态，并为 Kanban 添加原生操作系统通知。⁵⁴

v0.20.5（自 v0.20.4 以来约 746 次提交、约 323 个 PR）：

• 无密钥 Web 层：全新安装后无需任何 API 密钥即可使用 Web 搜索——支持5家供应商的免费轮换，并具备环形故障转移机制。²³
• CLI 体验优化浪潮：模糊搜索式 /model 选择器、Ctrl+P 命令面板，以及信息更丰富的 /status。²³
• Bot Mode 日趋成熟：支持群组房间线程、可折叠的对话摘要、Blob Face 头像，以及可拖放的 PDF/文件附件。²³
• 机群与 worktree 工具：hermes update 回执、hermes update --plan（发行说明称之为“fleet --plan verification”；该标志属于 hermes update，而非某个 fleet 命令。根据其解析器帮助信息，它会“Show the update plan and exit without changing anything”），以及 hermes worktree list/prune。²³²⁷
• cron 作业获得持久记忆和按作业配置的推理强度；此外还根据 Composio 评测结果增加了执行纪律与运行时停滞防护、多问题澄清功能、无需 opencode 的零身份验证提供商，以及桌面端性能改进（Bot Mode 优先绘制式水合、在两个渲染器中启用 React Compiler）。²³

v0.20.6（标签 v2026.8.27，8月27日——自 v0.20.5 以来约 1,313 次提交、约 525 个 PR）：

该版本直言自己是一个“Patch release. This tag rolls up the ~525 PRs merged since v0.20.5 into a stable tagged release for downstream consumers”。其描述显示，此发布窗口涵盖约 1,313 次提交，涉及约 1,557 个文件（+177,113 / −21,682），合并了约 525 个 PR。³⁰ 根据该描述，主要更新如下：

• 经用户同意后使用真实 profile 浏览——本地浏览可使用默认 Chromium profile，并在 Windows 上提供需经批准的关闭流程。³⁰
• 桌面端 Browser 现在拥有独立的操作系统窗口，另有托管式 SSH 远程更新引擎和机群 profile 栏。³⁰
• 扩充远程 MCP 目录：纳入 50 多个经过实时验证、由供应商托管的服务器，包括 Cloudflare、Grafana Cloud、Better Stack 和 Railway。³⁰
• 可选择使用操作系统钥匙串加密已存储的密钥——无需再在每次启动时响应 macOS 钥匙串提示。³⁰
• 选择器新增多个模型：GLM-5.3-Flash、免费版 MiniMax M3，以及 MiniMax H3 Max 视频模型。³⁰
• 为 web_search/web_extract 添加带 TTL 的结果缓存，并为多查询 tool_search 添加词干提取功能。³⁰
• Lean-tail 压缩现已成为默认方案——下方的上下文压缩章节记录了该标签发布时的配置。³⁰³¹
• 终端后端现已支持插件化——请参阅终端后端。³⁰³²
• 更新程序与机群如实报告状态：更新程序会通过控制套接字暂停 gateway，而非终止整个进程树；由镜像或软件包管理的安装则会拒绝不安全的原地更新。³⁰
• cron 增加持久事故确认机制，并提供更清晰的代码版本偏差故障提示；另有 Slack 链接展开控制和共享的 Docker 容器身份。³⁰

更新方式保持不变：现有安装运行 hermes update，全新安装则使用 shell 安装程序。⁵⁴²³³⁰

v0.19.0 的新增功能（Quicksilver 版本）

Hermes Agent v0.19.0（标签 v2026.7.20，2026年7月20日）以信使之神的神速命名。此版本的核心是极致响应速度：所有平台的首轮首个 token 响应时间均缩短约 80%。围绕这一核心，新增了终端账单管理、密码管理器密钥源、默认启用的智能审批、可观察的 subagent，以及防崩溃的响应交付机制。自 v0.18.0 以来，这是该项目迄今规模最大的一次更新：约 2,245 次提交、约 1,065 个合并的 PR、约 3,300 个已关闭的 issue，以及 450 多名社区贡献者。⁵⁶

• 各平台首个 token 的响应速度均提升约 80%。 CLI、gateway、TUI、桌面端和 cron 的冷启动提交→分派时间从约 4.3 秒降至约 0.9 秒——Discord 功能检测已移出关键路径，已知非 Ollama 提供商将跳过 Ollama 探测，同时从 agent 初始化过程中移除了阻塞任务。感知延迟也得到了专项优化：推理模型现在默认实时流式显示思考过程（display.show_reasoning 已开启），响应框也改为逐 token 而非逐行渲染。⁵⁶
• 桌面端和 TUI 渲染全面提速。 桌面应用通过约 20 个 PR 完成了大规模性能改造：借助增量块词法分析，流式 Markdown 拆分器的 CPU 占用降低至原来的 1/14；审查窗格中的差异采用虚拟化渲染；大型对话记录间的会话切换更加迅捷；侧边栏和工具行也不再随每个 token 重复渲染。TUI 现在会按块增量渲染流式 Markdown。⁵⁶
• pip 和 Homebrew 安装方式已弃用。 这两种方式均被标记为“不受支持的旧版”安装渠道，并计划移除。此移除已在 v0.20.0 中完成——brew 和 pip/PyPI wheel 渠道均已停用，目前受支持的渠道仅包括 shell 安装程序、Docker 和 Nix。⁵⁶⁵⁵
• 密钥可以来自密码管理器。 新增可插拔的 SecretSource 接口，可在加载时从 Bitwarden 和 1Password（op:// 引用）获取密钥。该接口支持同时启用多个保险库、确定性的优先级、冲突警告以及逐变量来源追踪——API 密钥不再必须存放在明文 .env 文件中。未来的保险库提供商可以插件形式接入。⁵⁶
• 智能审批现已默认启用。 当 Hermes 准备运行被标记的命令时，将由独立的 LLM 审查器进行评估，无需每次都提示您——每项裁定仅适用于对应的确切命令。用户定义的拒绝规则即使在 YOLO 模式下也会阻止匹配的命令；/deny <reason> 会转达您的拒绝原因，以便 agent 调整方向；重新引入并支持规则键的插件 pre_tool_call 批准操作，则可将工具调用升级至人工审批。⁵⁶
• 终端账单管理：/subscription 和 /topup。 无需离开终端即可管理 Nous Portal 套餐——查看当前套餐和剩余额度，准确预览升级费用或降级生效时间，并可执行操作及撤销。桌面应用也新增了对应的账单设置选项卡。⁵⁶
• 观察 subagent 工作，不再丢失已完成的答案。 delegate_task 分派任务后会立即返回实时对话记录文件，subagent 一经启动即可使用 tail -f 查看——每个子任务都有一份便于阅读的日志，完整记录所有工具调用、结果和流式回复。后台委派任务的完成结果可跨重启持久保存；gateway 的最终响应则记录在 state.db 的交付义务账本中。如果 gateway 在发送过程中崩溃，响应会在下次启动时重新交付。max_async_children 配置选项已弃用，统一由委派并发上限取代。⁵⁶
• 一个 gateway，多个 profile。 单个多路复用 gateway 可共享一个机器人 token，并将特定服务器、频道或帖子串路由到不同 profile——每个 profile 的配置、skills、memory 和密钥均完全隔离——同时支持 GATEWAY_MULTIPLEX_PROFILES 覆盖设置。路由索引已迁移至 state.db；sessions.json 目前仅作为可选的旧版镜像。⁵⁶
• 提供商和模型集中更新。 Fireworks AI 获得一等支持（包括成本估算，并位列提供商选择器第 2 位），DeepInfra 和 Upstage Solar 也同步加入。模型目录新增 GPT-5.6（Sol/Terra/Luna + Pro，端到端完整接入）、grok-4.5（正式发布）、kimi-k3（kimi-k2.x 已停用），以及完整接入的 Claude Sonnet 5。每个提供商均可设置 enabled: false 标志，excluded_providers 配置则会从 /model 选择器和解析流程中移除未使用的提供商。⁵⁶
• 推理强度变为可调节选项。 所有界面均新增 max 和 ultra 强度级别，同时支持在配置中按模型覆盖、在 MoA 预设中按槽位设置强度（顾问深入思考，综合模型保持快速）、为辅助模型按任务设置强度，以及在 CLI 中通过会话级 /reasoning 进行调整。⁵⁶
• CLI 和 MCP 功能扩展。 hermes sessions export 可导出 Markdown、Quarto、HTML、仅提示词和 Hugging Face 追踪格式，并可选择使用 --redact 清理敏感信息；/model --once 可为单轮对话覆盖模型；斜杠 skill 调用支持叠加（/skill-a /skill-b do XYZ）；--safe-mode 可辅助故障排查；hermes config get/unset 完善了配置管理功能；hermes serve 成为真正的无头后端；MCP 工具则采用 mcp__server__tool 命名约定。⁵⁶

如果您从 v0.18.x 升级，首先需要关注两项变更：通过 pip 或 Homebrew 安装时，现在会出现“不受支持的旧版方式”警告（请迁移至单行安装程序）；max_async_children 也已弃用，改由统一的委派并发上限取代。其余变更均为增量功能——升级的主要理由包括首轮延迟缩短约 80%、智能审批，以及可确保已完成答案不因崩溃而丢失的交付账本。

v0.18.0 的新增功能（Judgment 版本）

Hermes Agent v0.18.0（标签 v2026.7.1，2026年7月1日）以“判断”命名：agent 会验证自身工作，而非直接宣称成功；同时，您还可以实际检查集成推理过程。此版本也清空了全部 P0/P1 待办事项——在 12 天内解决了约 692 个最高优先级项目。²²

• Mixture-of-Agents 成为一等模型。 现在可以像选择其他模型一样，在所有界面中选择 MoA，且集成推理过程清晰可见：每个参考模型的完整输出都会以独立的带标签块呈现，并实时流式显示答案——您可以观察整个集成系统的思考过程，不再只能获得不透明的合并答案。²²
• /goal 的完成契约。 agent 会先运行项目检查来验证自身工作，再报告目标已完成，而非直接宣称成功——将判断应用于自身。²²
• /learn——通过描述将任何内容转化为 skill。 只需描述工作流，即可将其转化为可复用的 skill；生成的 skills 会自动遵循仓库的 CONTRIBUTING.md 约定。²²
• /journey 时间线。 以可视化方式呈现 memory 和 skills 随时间变化的历史记录，支持编辑；桌面端还提供 memory 图谱。²²
• 后台 subagent 扇出。 可委派多个并发运行的任务，且不会阻塞对话——v0.17.0 中单个后台 subagent 现已扩展为一支协作队伍。²²
• 桌面端 Projects。 提供一等的编程 Projects，并采用项目/仓库/工作通道组织模型。²²
• 可缩容至零的 gateway。 gateway 可在空闲时进入休眠状态，并协调任务排空以实现无缝部署——对于将 Hermes 作为常驻服务运行的用户而言，这项改进意义重大。²²
• 支持 Google Vertex AI。 可通过 GCP 服务账号访问 Gemini，并自动刷新 OAuth2 token，现已加入提供商目录。²²
• /prompt 编辑器命令。 打开 $EDITOR 编写多行提示词，无需再受限于单行输入框。²²

如果您从 v0.17.x 升级，此版本不会破坏 CLI。升级的主要理由包括完成契约（能够自行验证的目标）、具有可检查集成过程的一等 MoA，以及用于捕获 skill 的 /learn。

v0.17.0 的新增功能（The Reach Release）

Hermes Agent v0.17.0（标签 v2026.6.19，2026年6月19日）以智能体如今触达范围之广而命名——新增消息渠道、模型提供商，并进一步增强了桌面端和仪表板的控制能力。此版本在 v0.16.x 的基础上增量更新；CLI 界面保持不变。²¹

• 新增消息渠道。 借助 Photon Spectrum，iMessage 现在无需 Mac 中继即可运行（设备代码 OAuth、hermes photon login）；WhatsApp Business Cloud API 是 Meta 官方适配器，不再需要桥接进程；SimpleX 新增群组、原生附件、文本批处理和自动接受功能；Raft 也作为内置平台插件加入，并采用以隐私契约为基础的唤醒通道设计。²¹
• 新增模型和提供商。 模型目录新增 z-ai/glm-5.2（1M 上下文）、anthropic/claude-fable-5、laguna-m.1、nemotron-3-ultra 和 grok-composer-2.5-fast（通过 xAI OAuth 使用的 Cursor 模型，200k 上下文）。xAI 的默认模型已改为 grok-build-0.1，Anthropic 自适应模型现在遵循现代思考契约（绝不会发送 reasoning 字段）。²¹
• 桌面端和仪表板。 桌面端新增后台子智能体，通过实时“监视窗口”流式展示委派活动（delegate_task(background=true)）；还新增 Composer 模型选择器、可重新绑定的键盘快捷键、原生操作系统通知、按线程保存的 Composer 草稿、VS Code Marketplace 主题，以及日语和繁体中文界面。仪表板新增完整的 profile 构建器（无需编辑 config.yaml 即可配置模型、skills 和 MCPs）、全局 profile 切换器、经过重新设计且带安全扫描的 Skills Hub、Automation Blueprints（可通过表单、斜杠命令、对话和文档使用的参数化模板），以及在 OAuth 访问门槛后返回 401 的安全登录机制。²¹
• Skills 和工具。 image_generate 现在不仅能从零创建图像，还能在所有受支持的图像提供商中编辑和转换源图像；memory 工具新增 operations 数组，可在单次调用中以原子方式批量执行添加、替换和删除操作；新的 simplify-code skill 会并行运行由 3 个智能体参与的审查与清理流程，并以 Chesterton’s-Fence 风险等级作为准入条件；布尔值 write_approval 取代了三态 write_mode。²¹
• 架构。 后台子智能体会立即返回句柄，并将结果作为新的轮次重新引入；MCP 引导处理程序支持在工具调用期间进行确认，延迟连接的 MCP 工具则会在轮次之间公开（缓存安全）；cron 改为可插拔的 CronScheduler，并提供 Chronos 托管 cron 提供商；新增 Managed scope（/etc/hermes），允许管理员固定用户无法修改的配置，同时还新增了用于多 gateway 拓扑的 Gateway-Gateway 中继。²¹
• 新增命令。 /version、/billing（交互式终端账单）、hermes photon login（iMessage 身份验证）和 hermes curator run --consolidate——整合现在需要主动启用，因此常规后台整理不会消耗任何 token。²¹
• 安全性。 v0.17.0 修复了 shell 转义拒绝列表绕过问题；当审批模块或自有策略 gateway 适配器缺失时，系统会以失败关闭方式处理；清理 cron 作业脚本子进程的环境；对请求调试转储中的机密信息进行脱敏；检查 MCP stdio 配置中的数据外泄模式；并升级 urllib3 和 PyJWT 以修复 CVE。²¹

如果从 v0.16.x 升级，此版本不会破坏 CLI；它只是在同一智能体周围增加了新的渠道、模型和操作界面。无需中继的 iMessage、官方 WhatsApp 适配器以及面向管理员的 Managed scope，是此次升级最值得关注的理由。

v0.16.0 的新增功能（The Surface Release）

Hermes Agent v0.16.0（标签 v2026.6.5，2026年6月5日）以其为 CLI 优先的智能体带来的新操作界面而命名。最重要的变化是，Hermes 不再只能通过终端使用。²⁰

• 原生桌面应用。 Hermes Desktop 是一款面向 macOS、Linux 和 Windows 的全新 Electron 应用，支持一键安装和应用内自动更新。它提供流式聊天窗口、文件拖放、剪贴板图像粘贴、Cmd+K 命令面板、支持归档与搜索的会话列表，以及状态栏模型选择器。该应用可以通过安全的 WebSocket 连接远程 Hermes gateway，并使用 OAuth 或用户名/密码进行身份验证；它还支持按 profile 配置远程主机，以及通过跨 profile 的 @session 引用关联并发多 profile 会话。桌面界面还通过类型化 i18n 层（display.language；英语仍为默认语言）提供完整的简体中文翻译。²⁰
• 浏览器管理面板。 本地 Web 仪表板已从状态视图升级为完整的管理面板：包括带启用/禁用开关的 MCP 目录、凭据管理、webhook 和 hook 创建、内存配置、gateway 控制，以及支持更新前检查和一键 Debug Share 的 System 页面。新的 Channels 页面可直接在浏览器中配置所有 gateway 消息平台，包括 Telegram、Discord、Slack 等。身份验证现在支持插拔：用户名/密码登录、通用自托管 OIDC 提供商、用于自托管 OAuth 客户端的 hermes dashboard register，以及刷新 token 会话轮换。²⁰
• 新增 CLI 和斜杠命令。 /undo [N] 可回退最近 N 个用户轮次，并支持预填充和软删除；该功能适用于 CLI、TUI 以及各类消息平台。新增可配置的默认界面（cli 或 tui），并提供 --cli 覆盖选项；TUI 新增统一的 /model 命令和 Sessions 浮层。hermes portal 成为 Nous Portal 引导流程便于理解的别名，首次运行时新增 Quick Setup 和 Full Setup 两种路径；同时加入 hermes prompt-size 和 hermes sessions optimize 两项诊断功能。²⁰
• 新增模型和提供商。 选择器新增 deepseek-v4-flash、MiniMax-M3（1M 上下文、原生 MiniMax 提供商）、qwen3.7-plus（Nous + OpenRouter）和 gemini-3.5-flash（Gemini OAuth + API 密钥）。桌面启动器新增一等支持的 xAI Grok OAuth 提供商；模型选择器现在可在所有操作界面中进行模糊搜索；多端点提供商会归入同一行；目录刷新频率也从每天一次提高到每小时一次。²⁰（v0.21.1 此后再次调整了刷新频率：选择器的远程目录每 20 分钟刷新一次，即 model_catalog.ttl_minutes。⁴⁶）
• 更精简的 skills 与渐进式披露。 默认 skill 集移除了重复和失效的 skills（Spotify 已迁移至原生插件，Linear 改用 hermes mcp install linear，另有若干过时条目被删除），将更多 skills 调整为可选项，并新增 environments: 前置元数据相关性门控（kanban/docker/s6），在未被请求时不会将特定上下文的 skills 加入索引。除 OpenAI、Anthropic 和 HuggingFace 外，NVIDIA/skills 现在也成为 Skills Hub 默认信任的 tap。MCP 和插件工具新增渐进式（限定范围的）工具披露机制；此外，还修复了未获得 token 时 MCP 错误报告 OAuth 成功的问题。²⁰
• 安全性。 v0.16.0 固定使用已修复的 Starlette（≥1.0.1），以应对 CVE-2026-48710（BadHost）；在异步路径中将 SSRF URL 检查移出事件循环；从子进程环境中移除 Bedrock 推理 bearer token；将 bws_cache.json 加入文件安全读取防护；将 docker restart/stop/kill 加入危险模式列表；并清理经过审核的 skill 内容中的不可见 Unicode 字符。此版本关闭了 2 个 P0 和 62 个 P1 问题，其中 16 个带有安全标签。²⁰

如果从 v0.15.x 升级，这些变化均不会对 CLI 本身造成破坏性影响；它们只是在同一智能体周围增加了操作界面和提供商。如果希望让非终端用户使用 Hermes，或通过浏览器管理远程 gateway，桌面应用和管理面板便是升级的主要理由。

v0.14.0 的新增功能（The Foundation Release）

与其说 v0.14.0 围绕某项重磅功能展开，不如说它着重降低设置负担，同时扩展 Hermes 的运行范围。¹⁹ 主要运维变化如下：

• 安装和启动更加轻量。 可通过 PyPI 使用 pip install hermes-agent 安装；重量级适配器会在首次使用时按需安装；启动路径则推迟了足够多的工作，使冷启动时间缩短约 19 秒。（v0.19.0 此后已弃用 pip 安装——请参阅安装。）
• 订阅可转化为本地 API 端点。 hermes proxy 可将 Claude Pro、ChatGPT Pro 和 SuperGrok 等基于 OAuth 的提供商转换为兼容 OpenAI 的本地端点，供 Codex、Aider、Cline 和 Continue 等工具使用。
• Gateway 覆盖范围扩大。 LINE 和 SimpleX Chat 加入 gateway（文档中的平台对比表显示，标签 v2026.8.31 共支持 28 个平台；消息 Gateway部分说明了该数字的统计口径），Microsoft Teams 已实现端到端接入，Discord 历史记录回填默认启用，Telegram/Discord 的 clarify 提示现在使用原生按钮。
• 写入时验证得到改进。 完成编辑后，Hermes 可在下一轮开始前显示每轮文件变更摘要和语言服务器语义诊断，使其进一步迈向以证据为依据的智能体工作方式。
• 桌面与媒体工具覆盖面扩大。 computer_use 可通过 cua-driver 与非 Anthropic 提供商配合使用；video_generate 统一至可插拔后端之上；vision_analyze 则会将原始像素发送给真正具备视觉能力的模型。

安装

官方支持的安装方式是使用单行安装程序。它会自动处理Python、uv、Node.js、ripgrep、ffmpeg、仓库克隆、虚拟环境以及全局hermes命令。⁷

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

自v0.19.0起，已弃用pip和Homebrew安装方式。 v0.14.0引入的PyPI软件包（pip install hermes-agent）和Homebrew公式现已被标记为“不受支持的旧版”安装方式——Hermes检测到此类安装时，会在所有界面发出警告（但不会阻止运行），并计划停止通过PyPI/Homebrew发布。如果此前通过pip或brew安装，请迁移到上述安装程序。⁵⁶

支持Linux、macOS、WSL2和Android/Termux（安装程序会自动检测Termux，并切换至经过测试的Android软件包组合）。⁷ 原生Windows现已成为Tier 1平台，不再是v0.14.0发布时的早期测试版——可使用iex (irm https://hermes-agent.nousresearch.com/install.ps1)进行安装。文档明确指出一项限制：macOS仅支持Apple Silicon，不支持Intel Mac。⁵⁵ 从历史上看，v0.14.0曾通过PowerShell安装程序以早期测试版形式加入原生Windows支持；但在Windows安装方案成熟之前，生产环境仍建议优先使用WSL2，以求稳妥。¹⁹

安装完成后：

source ~/.bashrc    # or ~/.zshrc
hermes              # Start chatting

唯一的前置条件是git。安装程序会通过uv自动配置Python 3.11（无需sudo）、Node.js 26（用于浏览器自动化和WhatsApp桥接）、ripgrep以及ffmpeg。自v0.20.0起，Node 26是硬性最低版本——如果检测到更旧的版本，安装程序会拒绝使用，并改为安装由Hermes管理的Node。⁵⁵⁷

验证安装

hermes --version    # Check version (global flag; there is no `version` subcommand)
hermes doctor       # Diagnose config/dependency issues
hermes status       # Show current configuration + auth state
hermes dump         # Copy-pasteable setup summary for debugging

hermes doctor会准确指出缺失的组件及其修复方法。⁷ 寻求帮助时，可将hermes dump的输出粘贴到GitHub议题或Discord讨论串中——该命令会生成整个设置的纯文本摘要，并隐去其中的敏感信息。⁸

手动安装

如果需要完全掌控安装过程——例如自定义Python版本、选择特定扩展功能或集成Nix/NixOS——上游安装指南提供了详尽的分步说明。⁷ 以下是可通过uv pip install -e ".[<extras>]"组合安装的主要可选扩展：

Termux的安装命令有所不同——它使用带约束文件的pip，而不是uv pip：

python -m pip install -e ".[termux]" -c constraints-termux.txt

这是因为在Android上安装.[all]时，voice扩展会引入faster-whisper，而后者依赖尚未针对Android发布的ctranslate2wheel包。⁷

身份验证与提供商

在标签v2026.9.7中，hermes_cli/models_catalog_static.py第311行包含39个静态CANONICAL_PROVIDERS条目（2026年9月的拆分将该列表从hermes_cli/models.py中移出；条目本身保持不变，仍包括v0.21.0的tencent-tokenplan），并会根据plugins/model-providers/自动扩展该列表（共39个捆绑目录；其中9个——actual、alibaba-coding-plan、commandcode、deepinfra、meta-ai、nebius-token-factory、opencode-free、router、upstage——没有静态条目，由于使用默认的api_key身份验证类型，因此会被自动扩展机制纳入）。文档的提供商页面以表格列出45个云端和订阅提供商，以及一行自定义端点；此外还单独介绍了本地和自托管服务器（Ollama、vLLM、SGLang、llama.cpp、LM Studio、LiteLLM、ClawRouter，以及任何与OpenAI兼容的端点）。²⁶ 在标签v2026.9.24中，静态列表仍包含39个条目，但plugins/model-providers/只剩38个目录：无需密钥的opencode-free提供商已于9月18日移除，因为OpenCode的免费层现已拒绝来自其自有客户端之外的匿名流量。⁵³ 在此基础上，还有自定义端点和3种不同的身份验证路径。下面按照路径完整梳理身份验证方式，便于您找到与现有条件相匹配的方案。

3种身份验证路径

Hermes中的每个提供商均采用以下3种身份验证模式之一：

路径1——.env中的API密钥。 将密钥写入~/.hermes/.env，Hermes会在启动时读取。OpenRouter、AI Gateway、z.ai/GLM、Kimi/Moonshot、MiniMax（以及MiniMax中国区）、Alibaba Cloud/DashScope、Kilo Code、OpenCode Zen、OpenCode Go、DeepSeek、Hugging Face、Google/Gemini及大多数第三方提供商均采用此方式。² 自v0.19.0起，密钥不再必须存放于明文文件中：可插拔的SecretSource接口能够在加载时从Bitwarden或1Password（op://引用）获取密钥，并支持同时启用多个密码库、确定性的优先级、冲突警告和逐变量来源追踪；.env仍作为后备方案。（这与v0.15.0的Bitwarden Secrets Manager引导令牌有所不同，后者通过单个令牌集中管理提供商密钥；SecretSource则取代明文文件本身，未来的密码库提供商也可作为插件接入。）⁵⁶

路径2——通过hermes model或hermes auth使用OAuth。 此方式会启动设备代码流程、打开浏览器，并将凭据存储在~/.hermes/auth.json中（也可从Claude Code或Codex CLI等工具导入现有凭据）。Nous Portal、OpenAI Codex（ChatGPT账户）、GitHub Copilot和Anthropic（Claude Pro/Max）均采用此方式。²

路径3——config.yaml中的自定义端点。 适用于任何与OpenAI兼容的API，包括Ollama、vLLM、SGLang、llama.cpp、LM Studio、LiteLLM代理、Together AI、Groq、Azure OpenAI或您自行托管的服务器。通过hermes model → Custom endpoint配置一次后，设置会持久化到config.yaml中。²

完整提供商矩阵

此矩阵涵盖文档页面表格中列出的提供商，并给出每个提供商的准确设置流程；该标签版本的选择器所列项目比文档更多（请参阅上方数量），而任何与OpenAI兼容的服务都可通过自定义端点行接入。²²⁶

Anthropic：3 种身份验证方式

Anthropic 单独成节，是因为 Hermes 提供了 3 种不同的 Claude 接入方式，选择合适的方式至关重要。根据上游文档：²

# Method 1: API key (pay-per-token)
export ANTHROPIC_API_KEY=***
hermes chat --provider anthropic --model claude-sonnet-4-6

# Method 2: OAuth through hermes model (preferred)
# Uses Claude Code's credential store when available
hermes model

# Method 3: Manual setup-token (fallback/legacy)
export ANTHROPIC_TOKEN=***
hermes chat --provider anthropic

# Auto-detect Claude Code credentials
hermes chat --provider anthropic   # reads Claude Code files automatically

通过 hermes model 选择 Anthropic OAuth 时，Hermes 会优先使用 Claude Code 自身的凭据存储，而不是将令牌复制到 ~/.hermes/.env。这样可确保可刷新的 Claude 凭据继续正常刷新。² 如果同一台计算机上已经在使用 Claude Code，这是最简洁的方式。

要在 config.yaml 中永久固定使用 Anthropic：

model:
  provider: "anthropic"
  default: "claude-sonnet-4-6"

--provider claude 和 --provider claude-code 也可作为 --provider anthropic 的简写。²

GitHub Copilot：2 种模式

Copilot 支持 2 种模式：直接调用 Copilot API（推荐），以及 Copilot ACP（将本地 Copilot CLI 作为子进程启动）。²

# Direct Copilot API
hermes chat --provider copilot --model gpt-5.4

# Copilot ACP (requires the Copilot CLI in PATH + an existing copilot login)
hermes chat --provider copilot-acp --model copilot-acp

根据上游文档，身份验证按以下顺序检查：² 1. COPILOT_GITHUB_TOKEN 环境变量 2. GH_TOKEN 环境变量 3. GITHUB_TOKEN 环境变量 4. gh auth token CLI 回退方式 5. 通过 hermes model 进行 OAuth 设备代码登录

令牌类型至关重要。 Copilot API 不支持经典 Personal Access Token（ghp_*）。支持的类型包括 OAuth 令牌（gho_*）、细粒度 PAT（github_pat_*，需具备 Copilot Requests 权限），以及 GitHub App 令牌（ghu_*）。如果 gh auth token 返回 ghp_* 令牌，请改用 hermes model 通过 OAuth 进行身份验证。²

中国 AI provider（原生支持）

Hermes 原生支持 z.ai/GLM、Kimi/Moonshot、MiniMax（全球和中国端点）以及 Alibaba Cloud，并为其提供专用的 provider ID。²

# z.ai / ZhipuAI GLM
hermes chat --provider zai --model glm-5                 # Requires: GLM_API_KEY

# Kimi / Moonshot AI
hermes chat --provider kimi-coding --model kimi-for-coding   # Requires: KIMI_API_KEY

# MiniMax (global)
hermes chat --provider minimax --model MiniMax-M2.7          # Requires: MINIMAX_API_KEY

# MiniMax (China)
hermes chat --provider minimax-cn --model MiniMax-M2.7       # Requires: MINIMAX_CN_API_KEY

# Alibaba Cloud / DashScope (Qwen)
hermes chat --provider alibaba --model qwen3.5-plus          # Requires: DASHSCOPE_API_KEY

可通过 GLM_BASE_URL、KIMI_BASE_URL、MINIMAX_BASE_URL、MINIMAX_CN_BASE_URL 或 DASHSCOPE_BASE_URL 环境变量覆盖基础 URL。²

Z.AI 会自动检测端点。 使用 z.ai/GLM provider 时，Hermes 会探测多个端点（全球、中国和编程版），找出可接受您的 API 密钥的端点。可用端点会自动缓存——大多数用户无需设置 GLM_BASE_URL。²

xAI（Grok）会自动启用提示词缓存。 当基础 URL 包含 x.ai 时，Hermes 会随每个请求发送 x-grok-conv-id 标头，将同一对话会话路由到同一台服务器，从而复用已缓存的系统提示词和历史记录。² 此过程自动完成，无需配置。

hermes auth 命令

hermes auth 是用于管理凭据池和 OAuth 凭据的命令。⁶

hermes auth                              # Interactive wizard
hermes auth list                         # Show all credential pools
hermes auth list openrouter              # Show one provider's pool
hermes auth add openrouter --api-key sk-or-v1-xxx
hermes auth add anthropic --type oauth
hermes auth remove openrouter 2          # Remove by index
hermes auth reset openrouter             # Clear cooldowns

凭据池用于轮换同一 provider 的多个 API 密钥或 OAuth 令牌——这样无需修改代码，即可将速率限制分摊到多个密钥。⁶ 旧版 hermes login / hermes logout 命令已被移除；请改用 hermes auth。⁶

自定义端点与自托管端点

Hermes 可与任何兼容 OpenAI 的 API 端点配合使用。如果服务器实现了 /v1/chat/completions，即可将 Hermes 指向该服务器。²

交互式设置（推荐）：

hermes model
# Select "Custom endpoint (self-hosted / VLLM / etc.)"
# Enter: API base URL, API key, Model name

手动配置 config.yaml：

model:
  default: your-model-name
  provider: custom
  base_url: http://localhost:8000/v1
  api_key: your-key-or-leave-empty-for-local

两种方式都会将配置持久化到 config.yaml。该文件是主模型、provider 和基础 URL 的唯一真实来源。² 旧版环境变量 OPENAI_BASE_URL 和 LLM_MODEL 不再用于读取主模型配置——请使用 hermes model，或直接编辑 config.yaml。²（对于辅助 provider: "main" 路由路径，OPENAI_BASE_URL + OPENAI_API_KEY 仍可作为回退配置，因此如果正在该路径中使用它们，请勿贸然删除。）⁴

在会话期间切换自定义端点：

/model custom:qwen-2.5             # Custom endpoint with explicit model
/model custom                      # Auto-detect the model from the endpoint
/model custom:local:qwen-2.5       # Named custom provider "local"
/model custom:work:llama3          # Named custom provider "work"
/model openrouter:claude-sonnet-4  # Back to a cloud provider

/model custom（不带模型名称）会查询端点的 /v1/models API；如果仅加载了一个模型，则会自动选择该模型。这对于仅运行单个模型的本地服务器非常实用。²

本地 LLM 服务器（设置模板）

上游文档提供了 Ollama、vLLM、SGLang、llama.cpp 和 LM Studio 的完整设置指南。以下是实际需要运行的关键命令。每种方案都旨在提供一个可供 Hermes 连接的可用端点。²

Ollama——最简单的本地方案，无需配置：

ollama pull qwen2.5-coder:32b
OLLAMA_CONTEXT_LENGTH=32768 ollama serve   # Raise from 4k default
hermes model   # Custom endpoint → http://localhost:11434/v1 → qwen2.5-coder:32b

Ollama 的关键注意事项：Ollama 默认使用非常短的上下文长度（VRAM 不足 24GB 时为 4,096 个 token）。必须通过 OLLAMA_CONTEXT_LENGTH 或 Modelfile 提高该值——兼容 OpenAI 的 API 不接受客户端传入的上下文长度，因此 Hermes 无法代为设置。²用于 agent 时，至少应设为 16k–32k。

vLLM——高性能 GPU 服务：

pip install vllm
vllm serve meta-llama/Llama-3.1-70B-Instruct \
  --port 8000 \
  --max-model-len 65536 \
  --tensor-parallel-size 2 \
  --enable-auto-tool-choice \
  --tool-call-parser hermes

工具调用需要使用 --enable-auto-tool-choice 和 --tool-call-parser <name>。支持的解析器包括：hermes（Qwen 2.5、Hermes 2/3）、llama3_json、mistral、deepseek_v3、deepseek_v31、xlam、pythonic。如果缺少这些标志，工具调用将以纯文本形式返回。²

SGLang——利用 RadixAttention 复用 KV 缓存的快速服务方案：

pip install "sglang[all]"
python -m sglang.launch_server \
  --model meta-llama/Llama-3.1-70B-Instruct \
  --port 30000 \
  --context-length 65536 \
  --tp 2 \
  --tool-call-parser qwen

SGLang 的注意事项：默认 max_tokens 为 128。如果响应被截断，请在服务器上设置 --default-max-tokens，或在 config.yaml 中配置 model.max_tokens。²

llama.cpp / llama-server——适用于 CPU 和 Apple Silicon Metal：

./build/bin/llama-server \
  --jinja -fa \
  -c 32768 \
  -ngl 99 \
  -m models/qwen2.5-coder-32b-instruct-Q4_K_M.gguf \
  --port 8080 --host 0.0.0.0

工具调用必须启用 --jinja。如果未启用，llama-server 会完全忽略 tools 参数，模型则会尝试通过在响应文本中写入 JSON 来调用工具——Hermes 无法将其解析为真正的工具调用。²

LM Studio——带 GUI 的桌面应用：

从 LM Studio 应用中启动服务器（Developer 选项卡 → Start Server），也可以通过 CLI 启动：lms server start（在 1234 端口启动）和 lms load qwen2.5-coder --context-length 32768。²然后让 hermes model 指向 http://localhost:1234/v1。

LM Studio 的关键注意事项：LM Studio 会从模型元数据中读取上下文长度，但许多 GGUF 模型报告的默认值为 2048 或 4096。请务必在 LM Studio 的模型设置中明确指定上下文长度——单击模型选择器旁的齿轮图标，将“Context Length”设为至少 16384（最好为 32768），然后重新加载模型。²

命名自定义提供商

如果您使用多个自定义端点（例如本地开发服务器和远程 GPU 服务器），请在 config.yaml 中将它们定义为命名自定义提供商：²

custom_providers:
  - name: local
    base_url: http://localhost:8080/v1
    # api_key omitted — Hermes uses "no-key-required" for keyless local servers
  - name: work
    base_url: https://gpu-server.internal.corp/v1
    api_key: corp-api-key
    api_mode: chat_completions      # optional, auto-detected from URL
  - name: anthropic-proxy
    base_url: https://proxy.example.com/anthropic
    api_key: proxy-key
    api_mode: anthropic_messages    # for Anthropic-compatible proxies

随后即可使用三段式语法在会话期间切换：

/model custom:local:qwen-2.5
/model custom:work:llama3-70b
/model custom:anthropic-proxy:claude-sonnet-4

也可以从交互式 hermes model 菜单中选择命名自定义提供商。²

可插拔提供商架构（v0.13.0+）

v0.13.0 提供了 ProviderProfile ABC 和 plugins/model-providers/ 目录，使第三方推理提供商无需修改核心代码即可接入。¹⁸如果提供商支持兼容 OpenAI、Anthropic 或 Codex 的 API 模式，您可以实现一个 ProviderProfile 子类，用于声明身份验证路径、基础 URL、模型目录和缓存标头；Hermes 会通过内置提供商使用的同一 runtime_provider.py 路径解析它。这正是 v0.13.0 扩展提供商支持背后的架构变革：添加提供商不再需要编辑核心代码，只需发布一个插件。

兼容 OpenAI 的本地代理（v0.14.0+）

hermes proxy 会公开一个兼容 OpenAI 的本地端点，其后端是 Hermes 已登录的 OAuth 提供商——Claude Pro、ChatGPT Pro、SuperGrok 或其他已配置的兼容提供商。¹⁹这意味着，包括 Codex CLI、Aider、Cline、Continue 或自定义脚本在内，需要 OpenAI 风格 API 的工具，都可以复用 Hermes 基于订阅的身份验证，而无需单独的 API 密钥。应将该代理视为本地开发基础设施：有意选择其绑定地址，切勿大范围公开，并留意各提供商的特定条款。

上下文长度检测

根据上游文档，以下两个设置经常被混淆：²

• context_length——上下文窗口总量（输入与输出的 token 预算之和，例如 Claude Opus 4.7 为 1,000,000，Sonnet 4.6 为 200,000）。Hermes 据此决定何时压缩历史记录。
• model.max_tokens——输出上限（模型在单次响应中最多可以生成的 token 数量）。它与历史记录长度无关。

如果自动检测得到的窗口大小不正确，请设置 context_length：

model:
  default: "qwen3.5:9b"
  base_url: "http://localhost:8080/v1"
  context_length: 131072      # tokens

Hermes 通过多来源解析链检测上下文窗口：配置覆盖 → 自定义提供商的单模型设置 → 持久化缓存 → 端点 /models → Anthropic /v1/models → OpenRouter API → Nous Portal → models.dev（由社区维护、收录 3800 多个模型的注册表）→ 回退默认值（128K）。²该系统能够识别提供商，因此同一模型可能因服务提供方不同而具有不同的上下文限制（例如，claude-opus-4.6 通过 Anthropic 直接提供时为 1M，而通过 GitHub Copilot 提供时为 128K）。²

智能模型路由：提供商轮换与回退

Hermes 不会将您限制在单一提供商的单一模型上。智能模型路由由一组 机制组成，用于决定实际由哪个提供商和模型处理特定请求：凭据 池会将负载分散到多个密钥上；主模型失败时，已配置的回退模型会接管；而 下方的辅助槽位可独立于主模型，将附属任务路由到成本更低的模型。²⁶请将这三项一并配置——它们决定了 agent 是因速率限制而停滞不前，还是能够继续工作。

凭据池。如果同一提供商有多个 API 密钥，请通过 hermes auth 配置轮换策略。这样即可将速率限制分散到多个密钥上。⁶

回退模型。配置一个备用 provider:model。当主模型因速率限制、服务器错误或身份验证失败而无法使用时，Hermes 会自动切换到该模型：²

fallback_model:
  provider: openrouter            # required
  model: anthropic/claude-sonnet-4  # required
  # base_url: http://localhost:8000/v1    # optional, for custom endpoints
  # api_key_env: MY_CUSTOM_KEY           # optional, env var name

回退机制会在会话期间切换模型和提供商，同时保留对话内容。每个会话最多触发一次。²支持回退的提供商包括：openrouter、nous、openai-codex、copilot、copilot-acp、anthropic、huggingface、zai、kimi-coding、minimax、minimax-cn、deepseek、ai-gateway、opencode-zen、opencode-go、kilocode、alibaba、custom。²

辅助模型

Hermes 使用“辅助”模型处理附属任务：图像分析（视觉）、危险命令审批分类、上下文压缩、会话标题生成、TTS 音频标签插入、skill 匹配、MCP 工具分派，以及 Kanban 规约器/分解器系列任务。⁴³⁴默认情况下（auxiliary.*.provider: "auto"），所有辅助任务都会在主聊天模型上运行——也就是您在 hermes model 中选择的同一提供商和模型。文档明确指出，这一行为取代了旧版的低成本提供商自动检测机制：“早期版本会将聚合器用户（OpenRouter、Nous Portal）分配到提供商侧的低成本默认模型。这种行为出人意料……现在，auto 会对所有用户使用主模型，而 config.yaml 中针对各项任务的覆盖设置仍然优先。”³⁴开始使用时无需进行任何配置；但需要权衡成本——使用昂贵的推理模型时，辅助任务会产生不容忽视的额外开销。因此，在成本较为重要的场景中，请将各项任务分别指向价格低廉、速度较快的模型。 有两个曾经的辅助任务已完全不再使用LLM：网页提取（“web_extract和浏览器快照会以确定性方式截断过长内容，并存储完整文本，以便通过read_file分页读取——不涉及LLM”）和会话搜索（该单一形态的工具直接返回数据库内容）。它们原有的auxiliary.web_extract.*和auxiliary.session_search.*配置块已从默认配置中移除——现有config.yaml中残留的值“不会造成影响，将被忽略”——在该标签对应的默认配置中，flush_memories槽位同样已不存在。³⁴

您可以配置每个辅助任务使用的模型和提供商。每个辅助槽位使用相同的配置项：provider、model、base_url（以及api_key、timeout、extra_body和各任务独立的reasoning_effort）。⁴³⁴

auxiliary:
  vision:                          # vision_analyze + browser screenshots
    provider: "auto"               # "auto" (= main model), "openrouter", "nous", "main", etc.
    model: ""                      # e.g. "openai/gpt-4o", "google/gemini-2.5-flash"
    base_url: ""                   # Custom OpenAI-compatible endpoint
    api_key: ""                    # Falls back to OPENAI_API_KEY
    timeout: 120
    download_timeout: 30
  approval:                        # dangerous-command approval classifier
    provider: "auto"
    model: ""
    timeout: 30
  compression:                     # summarizer -- legacy compression.summary_* keys migrate here (config v17)
    provider: "auto"
    model: ""
    base_url: ""
    timeout: 120
  title_generation:                # auto-generated session titles after the first exchange
    enabled: true                  # set false to disable auto-titles
    provider: "auto"
    model: ""
    language: ""                   # empty follows the conversation; e.g. "English" pins titles to one language
  tts_audio_tags:    { provider: "auto", model: "" }  # Gemini 3.1 TTS hidden audio-tag insertion
  skills_hub:        { provider: "auto", model: "" }  # skill matching and search
  mcp:               { provider: "auto", model: "" }  # MCP tool dispatch
  triage_specifier:  { provider: "auto", model: "" }  # hermes kanban specify: rough one-liner into a concrete spec, promoted to todo
  kanban_decomposer: { provider: "auto", model: "" }  # hermes kanban decompose: triage task into a graph of child tasks routed to specialist profiles
  profile_describer: { provider: "auto", model: "" }  # hermes profile describe --auto: 1-2 sentence profile descriptions

更多专用槽位也采用相同的结构，包括goal_judge（判断是否满足/goal契约）、curator（用于审查skill使用情况的分支）、background_review（每轮结束后运行的自我改进分支）、review（/review的审查子代理）、moa_reference和moa_aggregator（Mixture-of-Agents）、memory_query_rewrite以及monitor。您完全不必手动编辑YAML：运行hermes model，然后选择“Configure auxiliary models”，即可通过交互式选择器为每项任务单独配置。³⁴

"main"提供商选项表示“使用主代理当前所用的提供商”——它仅可用于auxiliary:、compression:和主回退项（fallback_providers:或旧版fallback_model:）中，不能用于顶层的model.provider设置。如果主模型使用自定义的OpenAI兼容端点，请在model:部分设置provider: custom。⁴

这为何重要：由于auto已经会沿用主模型，以往“必须配置OpenRouter，否则辅助任务会悄然降级”的隐患已不复存在——如今需要权衡的是成本。如果主模型是价格昂贵的推理模型，建议将频繁运行的辅助任务交给价格低廉且速度快的模型：

auxiliary:
  vision:
    provider: "openrouter"
    model: "google/gemini-2.5-flash"
  compression:
    provider: "openrouter"
    model: "google/gemini-2.5-flash"

配置系统

Hermes采用分层配置系统。理解其优先级至关重要，因为较高层级会覆盖较低层级，而且其中一层是您无法在config.yaml中看到的全局提供商注册表。

配置文件结构

根据上游文档，Hermes配置由以下文件组成：⁴

~/.hermes/
├── config.yaml       # All settings (model, terminal, TTS, compression, memory, toolsets, ...)
├── .env              # Secrets (API keys, bot tokens, passwords)
├── auth.json         # OAuth provider credentials (Nous Portal, Codex, Anthropic)
├── SOUL.md           # Primary agent identity (slot #1 in system prompt)
├── memories/         # Persistent memory (MEMORY.md, USER.md)
├── skills/           # Bundled + agent-created + hub-installed skills
├── cron/             # Scheduled jobs
├── sessions/         # Gateway session state
└── logs/             # agent.log, gateway.log, errors.log (secrets auto-redacted)

config.yaml与.env——两者均设置时，非敏感设置以config.yaml为准。⁴具体规则如下： - 敏感信息（API密钥、机器人令牌、密码）→ .env - 其他所有设置（模型、终端后端、压缩设置、内存限制、toolset）→ config.yaml

可以在config.yaml中使用shell风格的插值引用敏感信息：⁴

auxiliary:
  vision:
    api_key: ${GOOGLE_API_KEY}
    base_url: ${CUSTOM_VISION_URL}
  delegation:
    api_key: ${DELEGATION_KEY}

管理配置

hermes config                # View current configuration
hermes config show           # Same as above
hermes config edit           # Open config.yaml in your editor
hermes config set KEY VAL    # Set a specific value
hermes config get KEY        # Print a single value (v0.19.0+)
hermes config unset KEY      # Remove a key so the default applies again (v0.19.0+)
hermes config path           # Print the config file path
hermes config env-path       # Print the .env file path
hermes config check          # Check for missing options (after updates)
hermes config migrate        # Interactively add missing options

示例：⁴

hermes config set model anthropic/claude-opus-4
hermes config set terminal.backend docker
hermes config set OPENROUTER_API_KEY sk-or-...   # Saves to .env

每次执行hermes update后，都应运行hermes config check和hermes config migrate。这些命令可以发现文件中尚未包含的新增配置选项。⁶

配置优先级

Hermes从多个来源加载配置。当多个来源设置了同一个值时，以优先级较高的来源为准：⁴

1. CLI参数——hermes chat --model anthropic/claude-sonnet-4（覆盖单次调用的设置）
2. 环境变量——在进程启动时应用
3. config.yaml——主要设置文件
4. .env——仅用于敏感信息
5. 内置默认值——其他来源均未设置值时应用

对于单次调用，CLI标志始终具有最高优先级。config.yaml则是长期配置的权威来源。

本地化（v0.13.0+）

v0.13.0为CLI和gateway消息新增了7种区域设置：简体中文、日语、德语、西班牙语、法语、乌克兰语和土耳其语。¹⁸v0.14.0实现了所有gateway命令和Web控制面板的本地化，新增8种区域设置，总数达到16种。¹⁹在v2026.8.31标签中，locales/目录树包含17份消息目录——英语加16种翻译（af、ar、de、es、fr、ga、hu、it、ja、ko、pt、ru、tr、uk、zh-hant、zh）。³³目前文档仅提供zh-Hans本地化版本。区域设置根据LC_ALL / LANG环境变量或config.yaml中显式指定的locale:键确定。英语仍是默认语言；对于翻译尚未覆盖的任何字符串，英语也是权威来源。

Profiles——多个相互隔离的Hermes实例

profile允许您创建多个相互隔离的Hermes实例，每个实例都有独立的配置、会话、skill、内存和gateway PID。借助此功能，您可以并行运行“工作Hermes”和“个人Hermes”，同时确保两者无法访问彼此的状态。⁶

hermes profile list
hermes profile create work --clone                  # Clone from current profile
hermes profile use work                             # Set sticky default
hermes profile alias work --name h-work             # Create wrapper script
hermes profile export work -o work-backup.tar.gz
hermes profile import work-backup.tar.gz --name restored
hermes -p work chat -q "Hello from work profile"    # One-off without switching

每个profile都有自己的HERMES_HOME（默认为~/.hermes-<name>/），因此多个profile可以同时运行gateway，互不干扰。⁶³

自v0.21.2起，隔离边界得到更严格的保障：一系列修复解决了多路复用gateway设置中确实存在的跨profile泄漏问题。在这些问题中，次要profile可能继承默认profile的允许列表、将凭据发送到默认profile的主机、把默认profile的保险库敏感信息交给stdio MCP服务器，或将其他profile的.env/auth.json/state.db附加到MEDIA:交付内容中（#107609-#107630）。如果您使用多路复用profile，那么从v0.21.2标签开始，隔离承诺才真正成立——请参阅v0.21.2的新变化。⁴⁸

CLI 命令

本节是面向实践者的顶层CLI命令参考。有关以代码为准的权威参考，请参阅上游的CLI命令参考。⁶

全局选项

hermes [global-options] <command> [subcommand/options]

顶层命令

hermes chat——主要入口

不带参数运行hermes会直接进入交互式聊天。hermes chat是带选项的显式形式：⁶

hermes chat -q "Summarize the latest PRs" --oneshot # Answer and exit (without --oneshot, a TTY seeds an interactive session)
hermes chat --provider openrouter --model anthropic/claude-sonnet-4.6
hermes chat --toolsets web,terminal,skills          # Enable specific toolsets
hermes chat --quiet -q "Return only JSON"           # Programmatic mode
hermes chat --worktree -q "Review repo and open a PR"

主要选项：

hermes setup——完整向导

运行完整设置向导，或直接进入其中某个部分：⁶

hermes setup                 # Full wizard
hermes setup model           # Provider and model only
hermes setup terminal        # Terminal backend only
hermes setup gateway         # Messaging platforms only
hermes setup tools           # Tool enable/disable per platform
hermes setup agent           # Agent behavior only
hermes setup --non-interactive
hermes setup --reset         # Reset config to defaults before setup

hermes logs——结构化日志查询

hermes logs比直接对日志文件运行tail -f更强大，因为它支持同时按级别、session ID和时间范围进行筛选。⁶

hermes logs                          # Last 50 lines of agent.log
hermes logs -f                       # Follow in real time
hermes logs gateway -n 100           # Last 100 lines of gateway.log
hermes logs --level WARNING --since 1h   # Warnings from the last hour
hermes logs --session abc123         # Filter by session ID substring
hermes logs errors --since 30m -f    # Follow errors.log from 30m ago
hermes logs list                     # List all log files with sizes

日志文件位于~/.hermes/logs/：⁶ - agent.log——所有代理活动（API调用、工具调度、session生命周期、INFO及以上级别） - errors.log——仅包含警告和错误（agent.log的筛选子集） - gateway.log——消息gateway活动（平台连接、调度和webhook）

日志通过Python的RotatingFileHandler自动轮换——可查找agent.log.1、agent.log.2等文件。⁶

hermes doctor——诊断

遇到问题时，应首先运行hermes doctor [--fix]。它会检查配置有效性、依赖项是否存在、API密钥是否可用以及服务状态，并可通过--fix尝试自动修复。⁶

如需与他人共享诊断信息，请使用hermes dump——它会生成一份精简的纯文本摘要，其中API密钥已经过脱敏，可直接粘贴到GitHub issue或Discord讨论串中。⁶

Slash 命令

Slash 命令在活跃的聊天会话（CLI或消息平台）中运行。它们由hermes_cli/commands.py中的共享COMMAND_REGISTRY分派，因此大多数命令在不同界面上的工作方式完全相同。⁹

会话控制

配置与模型

/model命令是会话过程中切换提供商的主力工具：⁹

/model                              # Show current model and options
/model claude-sonnet-4              # Switch model (auto-detect provider)
/model zai:glm-5                    # Switch provider:model
/model custom:qwen-2.5              # Use model on custom endpoint
/model custom                       # Auto-detect model from custom endpoint
/model custom:local:qwen-2.5        # Named custom provider
/model openrouter:anthropic/claude-sonnet-4   # Back to cloud

v0.19.0新增/model --once，可临时覆盖单轮使用的模型，并在响应后自动恢复为先前的模型。⁵⁶ 自v0.20.5版本周期起，/model选择器还支持模糊搜索，可随输入实时筛选。²³³⁵

工具、Skills与信息

动态Skill Slash命令

每个已安装的skill都会自动公开为Slash命令：⁹

/gif-search funny cats
/axolotl help me fine-tune Llama 3 on my dataset
/github-pr-workflow create a PR for the auth refactor
/excalidraw       # Just the skill name loads it and lets the agent ask what you need

自v0.19.0起，Slash skill调用支持叠加：/skill-a /skill-b do XYZ可在单轮中按顺序加载两个skill，并为串联名称提供自动补全和幽灵文本。⁵⁶

还可以在config.yaml中定义快捷命令，将短名称映射到更长的提示词：⁹

quick_commands:
  review: "Review my latest git diff and suggest improvements"
  deploy: "Run the deployment script at scripts/deploy.sh and verify the output"
  morning: "Check my calendar, unread emails, and summarize today's priorities"

随后，在CLI中输入/review、/deploy或/morning即可。

前缀匹配

命令支持前缀匹配：输入/h会解析为/help，输入/mod会解析为/model。当前缀存在歧义时，将按注册表顺序选择第一个已注册的命令。完整命令名称和已注册的别名始终优先于前缀匹配。⁹

消息平台专用命令

部分命令仅适用于消息平台（Telegram、Discord、Slack、WhatsApp、Signal、Email、Home Assistant）：⁹

• /status——显示会话信息（已不再仅限消息平台；请参阅会话控制）
• /sethome（别名/set-home）——将当前聊天标记为平台主页
• /approve [session|always]——批准待处理的危险命令
• /deny [reason]——拒绝待处理的危险命令。自v0.19.0起，/deny <reason>会将您的拒绝原因传达给agent，使其调整方案，而不是盲目重试⁵⁶
• /update——将Hermes Agent更新至最新版本
• /commands [page]——分页浏览所有命令和skill

另有一些命令仅适用于CLI：/skin、/tools、/toolsets、/browser、/config、/cron、/skills、/platforms、/paste、/statusbar、/plugins。⁹

工具与 Toolset

Hermes 内置了丰富的工具注册表，涵盖互联网搜索、浏览器自动化、终端执行、文件编辑、内存、委派、RL 训练、消息发送和 Home Assistant 集成等功能。¹⁰ 工具按逻辑划分为不同的 toolset，可针对各个平台分别启用或禁用。

高层分类

常见的 toolset 名称包括 web、terminal、file、browser、vision、image_gen、moa、skills、tts、todo、memory、session_search、cronjob、code_execution、delegation、clarify、homeassistant 和 rl。¹⁰

管理工具

hermes chat --toolsets "web,terminal"       # Use specific toolsets
hermes tools                                # Interactive per-platform tool config
hermes tools --summary                      # Print enabled-tools summary

还可在会话期间通过 /tools disable <name> 和 /tools enable <name> 切换工具状态。执行后会重置会话，以便新的工具集生效。⁹

终端后端

终端工具内置了7种执行后端；自 v0.20.6 起，这套后端也像提供商选择器一样支持通过插件扩展（见下文）：¹⁰²⁴

通过 hermes config set terminal.backend <name> 或在 config.yaml 中切换后端：

terminal:
  backend: docker      # or: local, ssh, singularity, modal, daytona, vercel_sandbox
  cwd: "."             # Working directory
  timeout: 180         # Command timeout in seconds

插件后端（v0.20.6+）。 第三方沙箱供应商无需再将实现并入核心仓库：插件在加载时通过 PluginContext.register_terminal_environment_provider 注册 TerminalEnvironmentProvider，注册名称随后即可像内置后端一样通过 terminal.backend 选择。内置名称属于保留名称——如果提供商名称与仓库内的后端冲突，注册表会拒绝该提供商。注册后的后端会自动接入所有核心功能界面（hermes setup 后端选择器、控制面板探测状态、hermes doctor 检查、容器路径与 cwd 处理、密钥剥离），因为核心会在每个分类点查询注册表，而非依赖硬编码的名称列表。³²

SSH 后端（出于安全考虑，建议使用——Agent 无法修改自身代码）：¹⁰

terminal:
  backend: ssh

# In ~/.hermes/.env
TERMINAL_SSH_HOST=my-server.example.com
TERMINAL_SSH_USER=myuser
TERMINAL_SSH_KEY=~/.ssh/id_rsa

Docker 后端：

terminal:
  backend: docker
  docker_image: python:3.11-slim

容器资源（适用于 docker、singularity、modal、daytona）：¹⁰

terminal:
  container_cpu: 1
  container_memory: 5120          # MB (default 5GB)
  container_disk: 51200           # MB (default 50GB)
  container_persistent: true      # Persist filesystem across sessions

启用 container_persistent: true 后，已安装的软件包、文件和配置可跨会话保留。¹⁰

所有容器后端均经过安全加固：只读根文件系统（Docker）；除 DAC_OVERRIDE、CHOWN 和 FOWNER 外，移除所有 Linux capability；禁止权限提升；限制 PID（256个进程）；提供完整的命名空间隔离，并通过卷实现持久化工作区。¹⁰

后台进程

终端工具支持后台执行，并提供明确的进程管理机制：¹⁰

terminal(command="pytest -v tests/", background=true)
# Returns: {"session_id": "proc_abc123", "pid": 12345}

process(action="list")                            # Show all running processes
process(action="poll", session_id="proc_abc123")  # Check status
process(action="wait", session_id="proc_abc123")  # Block until done
process(action="log", session_id="proc_abc123")   # Full output
process(action="kill", session_id="proc_abc123")  # Terminate
process(action="write", session_id="proc_abc123", data="y")  # Send input

PTY 模式（pty=true）支持 Codex 和 Claude Code 等交互式 CLI 工具。¹⁰

Sudo

如果命令需要 sudo，Hermes 会提示您输入密码（在当前会话中缓存）。也可在 ~/.hermes/.env 中设置 SUDO_PASSWORD。¹⁰

多 Agent Kanban（v0.13.0+）

v0.13.0 将多 Agent 协作提升为一等原语：通过一个持久化 Kanban 看板，跨 Agent、跨重启跟踪任务、状态和工作进程身份。¹⁸ 正是这个看板让 Hermes 工作进程群能够真正完成工作，而不会因失效的交接陷入停滞。

在目标管理方面，Kanban 看板可自然地与 /goal（目标锁定的 Ralph 循环）搭配；在启动语义方面，则可与现有的 delegate_task 工具结合。由此形成的工作进程群模式，使每个 Agent 都能共享唯一可信的信息源，明确下一步该做什么、由谁负责，以及哪些工作陷入停滞。

什么是 Hermes 工作进程群？

工作进程群是指多个 Hermes 工作进程并行使用同一个共享 Kanban 看板。 它并不是需要单独启用的子系统，而是看板所实现的一种工作方式。看板 提供了并行 Agent 自身无法解决的关键能力：针对“下一步应该领取什么任务， 是否已经有人在处理？”给出唯一且权威的答案。

v0.15.0 将这种模式提升为正式支持的拓扑，新增了用于并行工作进程协调的 工作进程群拓扑、将高层目标拆解为子任务的自动分解、 按任务覆盖模型、计划任务以及工作树管理，避免并行 工作进程在同一检出目录中发生冲突。⁵⁹

实际运作方式如下：为工作进程群设定目标，由自动分解将其拆成看板任务， 再由工作进程认领、执行并返回结果。重试预算按任务设置（max_retries）， 因此某个不稳定的子任务不会耗尽整个运行过程的容错额度。由于看板可以 持久保存，工作进程群在重启后仍可继续运行——工作进程会重新连接，并基于相同状态恢复工作。

工作进程群的成效取决于任务分解的质量。 看板负责协调工作进程，但无法 将拆分不当的目标变成合理的目标。共享隐式状态的任务仍会相互冲突， 即使使用工作树也无济于事。

skill 系统

skill 是按需加载的知识文档，agent 可在需要时加载。它采用渐进式披露模式，最大限度减少 token 用量，并兼容 agentskills.io 开放标准。¹¹

所有 skill 均位于 ~/.hermes/skills/——这是主要目录，也是唯一可信来源。全新安装时，捆绑的 skill 会从仓库复制到此处。通过 Hub 安装及 agent 创建的 skill 也会存放于此。¹¹

渐进式披露

Level 0: skills_list()           → [{name, description, category}, ...]   (~3k tokens)
Level 1: skill_view(name)        → Full content + metadata                 (varies)
Level 2: skill_view(name, path)  → Specific reference file                 (varies)

只有在实际需要时，agent 才会加载 skill 的完整内容。¹¹

SKILL.md 格式

---
name: my-skill
description: Brief description of what this skill does
version: 1.0.0
platforms: [macos, linux]      # Optional — restrict to OS platforms
metadata:
  hermes:
    tags: [python, automation]
    category: devops
    fallback_for_toolsets: [web]     # Conditional activation
    requires_toolsets: [terminal]    # Conditional activation
    config:                          # Config.yaml settings
      - key: my.setting
        description: "What this controls"
        default: "value"
        prompt: "Prompt for setup"
---

# Skill Title

## When to Use
Trigger conditions for this skill.

## Procedure
1. Step one
2. Step two

## Pitfalls
- Known failure modes and fixes

## Verification
How to confirm it worked.

条件激活

skill 可根据可用工具决定显示或隐藏。这尤其适用于备用 skill——仅当付费工具不可用时才应显示的免费或本地替代方案：¹¹

示例：内置 duckduckgo-search skill 使用 fallback_for_toolsets: [web]。设置 FIRECRAWL_API_KEY 后，web toolset 即可用，agent 会使用 web_search，而 DuckDuckGo skill 将保持隐藏。若未设置 API 密钥，DuckDuckGo skill 会自动作为备用方案显示。¹¹

由 agent 管理的 skill

agent 可通过 skill_manage 工具创建、更新和删除自己的 skill。这是 agent 的程序性记忆——当它探索出一套复杂的工作流程后，会将方法保存为 skill，以便日后复用。¹¹

agent 创建 skill 的时机：¹¹ - 成功完成复杂任务后（调用工具5次以上） - 遇到错误或走入死胡同，随后找到可行路径时 - 用户纠正其处理方式时 - 发现复杂的工作流程时

操作：¹¹

Skill Hub

从在线注册表中浏览、搜索、安装和管理 skill：⁶¹¹

hermes skills browse                          # Browse all hub skills
hermes skills browse --source official        # Browse official optional skills
hermes skills search kubernetes               # Search all sources
hermes skills search react --source skills-sh # Search skills.sh directory
hermes skills inspect openai/skills/k8s       # Preview before installing
hermes skills install openai/skills/k8s       # Install with security scan
hermes skills install skills-sh/anthropics/skills/pdf --force
hermes skills check                           # Check for upstream updates
hermes skills update                          # Reinstall changed hub skills
hermes skills audit                           # Re-scan installed hub skills
hermes skills uninstall k8s
hermes skills publish skills/my-skill --to github --repo owner/repo
hermes skills tap add myorg/skills-repo       # Add custom GitHub source

已集成的 Hub 来源：¹¹

默认 GitHub tap（无需设置即可浏览）：openai/skills、anthropics/skills、huggingface/skills、NVIDIA/skills、garrytan/gstack。claude-marketplace 来源已在 v0.20.0 中移除；在来源列表中由 browse-sh 取而代之。¹¹⁵⁵

安全扫描

所有通过 Hub 安装的 skill 都会经过安全扫描，检查数据外泄、提示词注入、破坏性命令、供应链风险信号及其他威胁。¹¹

信任级别：¹¹

--force 可覆盖 community skill 的非危险策略拦截，但无法覆盖安全扫描给出的 dangerous 判定。¹¹

外部 skill 目录

可将 Hermes 指向其他 skill 目录，使其与本地目录一同接受扫描：¹¹

skills:
  external_dirs:
    - ~/.agents/skills
    - /home/shared/team-skills
    - ${SKILLS_REPO}/skills

路径支持展开 ~，也支持替换 ${VAR} 环境变量。外部目录为只读——agent 创建或编辑 skill 时，始终写入 ~/.hermes/skills/。若两个位置存在同名 skill，则优先使用本地版本。¹¹

固定加载的 skill：skills.auto_load（v0.21.4 阶段）

在 config.yaml 的 skills.auto_load 下列出的 skill 名称会被固定，并在每个新会话中完整加载——CLI、TUI、gateway、cron 和 API 均不例外：⁵¹

skills:
  auto_load:
    - team-conventions
    - deploy-checklist

该列表只会解析一次，即首次构建 agent 提示词时。若名称不存在或已禁用，系统会发出警告并跳过，而不会导致会话失败。HERMES_IGNORE_RULES（--ignore-rules 背后的机制）会像处理其他自动注入的上下文一样禁用此列表。它是常驻指令对 -s/--skills 的补充；后者仅为单次会话预加载 skill。⁵¹

持久记忆

Hermes 具有容量受限且经过整理的记忆，可跨会话持久保留。代理的记忆由2个文件构成，均存储在~/.hermes/memories/中：¹²

两者都会以会话开始时的冻结快照形式注入系统提示词。代理通过memory工具自行管理记忆，可执行add、replace或remove操作。¹²

冻结快照模式：系统提示词注入的内容只在会话开始时捕获一次，此后不会在会话期间发生变化。这是有意为之，旨在保留LLM的前缀缓存以提升性能。会话期间所做的更改会立即持久化到磁盘，但要到下次会话才会出现在系统提示词中。¹²

应保存的内容

保存以下内容（代理会主动执行）：¹² - 用户偏好：“相比JavaScript，我更喜欢TypeScript”→user - 环境事实：“此服务器运行Debian 12和PostgreSQL 16”→memory - 纠正信息：“执行Docker命令时不要使用sudo，用户已加入docker组”→memory - 约定：“项目使用制表符、120字符行宽和Google风格文档字符串”→memory - 已完成的工作：“已于2026年1月15日将数据库从MySQL迁移至PostgreSQL”→memory

跳过以下内容：¹² - 琐碎或显而易见的信息 - 容易重新发现的事实 - 原始数据转储（对于记忆而言过大） - 仅与当前会话相关的临时信息 - 上下文文件中已有的信息

会话搜索

除了MEMORY.md和USER.md之外，代理还可使用session_search工具搜索过往对话。所有CLI和消息会话均存储在SQLite（~/.hermes/state.db）中，并支持FTS5全文搜索。自v0.15.0重新设计后，该工具完全不再涉及LLM——它会直接返回已存储的对话内容（原文表述为“single-shape tool returns DB content directly”）。因此，搜索速度提升了4,500倍，同时消除了API成本。¹²⁵⁹³⁴

v0.21.4期间新增了2项功能，均已在标签v2026.9.21中验证。第一项是时间边界：发现参数接受after（会话开始时间的包含性下限）和before（排他性上限）。两者都可使用ISO日期/日期时间——仅提供日期时，表示当天UTC零点——也可使用相对时长（7d、24h、2w）。这些参数仅适用于明确指定时间范围的查询；sort仍只是排序偏置，而非边界。第二项是零结果召回重试：FTS5会在词项之间隐式使用AND，因此，经过改述的多词查询可能无法匹配缺少其中任意一个词的已存储句子。当精确查询和子字符串回退均无结果时，搜索会重试索引，匹配任意词项，并在排序时优先展示覆盖更多词项的行。已有命中仍保持精确匹配语义（仅在零结果时触发重试），显式使用OR/NOT的查询、单词查询和路由至CJK的查询则保持不变。⁵¹

外部记忆提供商

为了获得超越MEMORY.md和USER.md的深层持久记忆，Hermes 内置了7个外部记忆提供商插件：Honcho、OpenViking、Mem0、Holographic、RetainDB、ByteRover和Supermemory。Hindsight等更多插件可从插件目录安装。¹²

Hindsight 在v0.21.4及更早版本中随核心代码树提供，并于v0.21.5迁移至插件目录，由Vectorize维护。现有配置会自行迁移：如果设置了memory.provider: hindsight，hermes update会将目录中的插件安装到所有使用该配置的profile主目录；若仍未安装，代理首次启动时也会执行安装。若设置了security.allow_lazy_installs: false，代理启动流程只会记录一条消息，因此需要自行运行hermes plugins install hindsight。该插件将安装至~/.hermes/plugins/hindsight/，并添加到plugins.enabled；memory.provider、memory.hindsight.*、HINDSIGHT_API_KEY以及您的记忆数据均保持不变。可使用hermes memory status和hermes plugins list进行检查。hermes-agent[hindsight] pip extra已移除。⁵³

外部提供商与内置记忆并行运行（绝不会取代它），并可增加知识图谱、语义搜索、自动事实提取和跨会话用户建模等能力：⁶¹²

hermes memory setup         # Pick a provider and configure it
hermes memory status        # Check what's active
hermes memory off           # Disable external provider (built-in only)

同一时间只能启用1个外部提供商。内置记忆始终处于启用状态。⁶

会话自动恢复（v0.13.0+）

v0.13.0使代理中途被中断后仍可继续运行。gateway 会在重启后自动恢复被中断的会话；通过/update重启时，会话状态可在升级期间得到保留；开发过程中重新加载源文件时，活动会话会继续保持，无需强制开启新会话。¹⁸实际效果是：进程重启后，长时间运行的gateway任务和由cron驱动的作业不再重置其上下文窗口。

Checkpoints v2（v0.13.0+）

v0.13.0将状态持久化重写为单一存储设计，具备真正的剪枝、磁盘防护机制，并且不再产生孤立的影子仓库。¹⁸旧版checkpoint系统会在长期运行的profile中不断累积磁盘状态；v2存储为本地checkpoint存储设置了明确上限，并移除了导致存储不断增长的重复记录机制。无需更改任何面向用户的配置；下次写入checkpoint时会自动使用v2路径。

个性与SOUL.md

SOUL.md是Hermes实例的核心身份。它占据系统提示词中的第1个插槽，取代硬编码的默认身份。¹³

Hermes 会自动在~/.hermes/SOUL.md（自定义profile则为$HERMES_HOME/SOUL.md）生成默认SOUL.md。现有用户文件绝不会被覆盖。Hermes 仅从HERMES_HOME加载SOUL.md，不会在当前工作目录中查找。由此可确保不同项目中的个性表现一致且可预测。¹³

SOUL.md中应包含的内容

用它定义持久的表达方式和个性指导：¹³ - 语气 - 沟通风格 - 直接程度 - 默认互动方式 - 在风格上应避免的内容 - Hermes 应如何处理不确定性、分歧和歧义

以下内容不太适合放在其中：¹³ - 一次性的项目指令 - 文件路径 - 仓库约定 - 临时工作流细节

这些内容应放在AGENTS.md中，而非SOUL.md。

SOUL.md与AGENTS.md

这是Hermes身份管理中最重要的区别：¹³

SOUL.md——身份、语气、风格、默认沟通方式和个性层面的行为。

AGENTS.md——项目架构、编码约定、工具偏好、仓库特定工作流、命令、端口、路径和部署说明。

一条实用原则是：如果某项内容应始终伴随您，就应放入SOUL.md；如果它只属于某个项目，则应放入AGENTS.md。¹³

内置个性

Hermes 内置了多种个性，可通过/personality切换：¹³³³

在config.yaml中定义自定义个性：¹³

agent:
  personalities:
    codereviewer: >
      You are a meticulous code reviewer. Identify bugs, security issues,
      performance concerns, and unclear design choices. Be precise and constructive.

然后使用/personality codereviewer切换。

SOUL.md与/personality

SOUL.md是基础表达风格，/personality则是会话级叠加层。¹³建议保持务实的默认SOUL.md，然后在辅导对话中使用/personality teacher，或在集思广益时使用/personality creative。

Nous Tool Gateway（v0.10.0+）

自 Hermes Agent v0.10.0（2026年4月16日）起，付费 Nous Portal 订阅用户可使用现有 Portal 凭据，通过托管方式访问一组精选工具，无需管理额外的 API 密钥。⁶¹ Hermes CLI 本身仍采用 MIT 许可证，并完全开源。变化在于，如今通过 Portal 身份验证不仅可以使用模型推理，还能解锁更多功能。

最快的使用方式是运行 hermes setup --portal。README 将其称为“全新安装后只需一条命令”：它会通过 OAuth 为您登录，将 Nous 设置为提供商，并启用 Tool Gateway。此后，可通过 hermes portal 管理相关设置。hermes portal login（未提供子命令时的默认操作）会执行同样的一站式引导流程；hermes portal info 会输出“Portal 身份验证 + Tool Gateway 路由摘要”；hermes portal open 会在默认浏览器中打开订阅页面；hermes portal tools 会列出 gateway 工具，并标明哪些工具通过 Nous 路由。hermes portal status 仍作为 info 的隐藏向后兼容别名保留，而且该标签下文档的 CLI 参考信息仍将子命令写作 status，因此两者均可使用。²⁸

gateway 中包含哪些工具

工作原理

gateway 通过新增的 use_gateway 配置字段，按工具分别选择启用。如果 hermes auth 中已有 Portal 凭据，并且为某个工具启用了 gateway，该工具的调用就会通过 Portal 路由。否则，将使用您的直接 API 密钥（如果已配置）。

# config.yaml — per-tool gateway opt-in
tools:
  web_search:
    provider: firecrawl
    use_gateway: true          # route via Nous Portal subscription
  image_generation:
    provider: fal
    use_gateway: true

运行时优先级：当 gateway 可用且某个工具设置了 use_gateway: true 时，即使同时配置了直接 API 密钥，Hermes 也会优先使用 gateway。这会影响计费：gateway 调用会消耗 Portal 订阅额度，而不是直接 API 密钥的余额。

启用 gateway

hermes model                      # select Nous Portal (OAuth flow)
hermes tools                      # per-platform tool picker integrates gateway tools
hermes status                     # confirms gateway/subscription detection

系统会根据 hermes auth 中已有的 Portal OAuth 凭据自动检测订阅，无需单独登录。自 v0.19.0 起，还可以直接在会话中管理订阅：/subscription 会显示套餐和剩余额度，准确预览升级费用或降级生效时间，并在显示计划变更横幅及提供撤销功能的情况下应用更改；/topup 可用于充值。桌面应用中也提供了对应的账单设置标签页。⁵⁶

定价与访问权限

价格和套餐名称发布在 Nous Portal 定价页面（https://portal.nousresearch.com/pricing）。本指南不逐一列出套餐，因为这些内容由 Portal 产品负责，而非 Hermes CLI，并且可能独立于 Hermes 版本发生变化。请前往 https://portal.nousresearch.com/ 注册，并查看定价页面了解当前套餐。

Nous 免费套餐与首次启动引导（v0.21.2+）

自 v0.21.2 起，全新安装无需付费套餐或 API 密钥即可获得可正常工作的 agent：开箱即用地提供免费推理和连接器，只需一条命令即可登录；也可在聊天中通过 /login 开始登录。连接器工具（Gmail、Linear、Notion 等）与其他工具一样，可以通过 tool_search 搜索。桌面端还提供由 HERMES_GUEST_ONBOARDING=1 控制的首次启动引导；只有字面值 1 才会启用。桌面端自身的测试明确断言，'true'、'0' 和空值均会保持禁用状态；启动决策还会写入所生成后端进程的环境，确保继承的值不会意外传入。⁴⁸

自 v0.21.4 发布周期起，连接这些连接器已统一为由后端负责的一项操作，不再由各前端分散处理：一次 manage_connections 工具调用会驱动后端的纯数据连接状态机（操作期限固定为 300 秒，特意不设为配置键），Desktop、TUI 和 CLI 都会将其呈现为相同的设置卡片。该卡片会为每项缺失的凭据显示一个字段（名称、提示、是否必填），并在所有必填字段均有内容后才启用操作按钮；后端则会在每个前端强制执行相同的“仅限机密信息”隔离规则。⁵¹

弃用通知

• HERMES_ENABLE_NOUS_MANAGED_TOOLS 环境变量已在 v0.10.0 中移除。现在，托管工具通过各工具的 use_gateway 配置字段启用，并根据您的 Portal 订阅状态决定是否可用。⁶¹

定位：此版本不是什么

Hermes Agent CLI 并未设置订阅门槛。该项目仍采用 MIT 许可证；所有核心功能（CLI、skills、内存、消息 gateway、cron、MCP、本地仪表板，以及所有提供商的 BYOK）均可端到端使用，无需向任何一方付费。v0.10.0 只是为已付费订阅 Nous Portal 的用户增加了一条便捷路径，并未从免费使用路径中移除任何内容。

消息 gateway

Hermes 可作为长期运行的 gateway 进程，通过单个 gateway 进程连接28 个消息平台：Telegram、Discord、Slack、WhatsApp、Signal、短信、电子邮件、Home Assistant、Mattermost、Matrix、DingTalk、Feishu/Lark、WeCom、Weixin（WeChat）、BlueBubbles（iMessage）、QQBot、Microsoft Teams、Tencent Yuanbao、Google Chat、LINE、SimpleX Chat、Photon（iMessage）、WhatsApp Cloud API、WeCom Callback、Raft、IRC、ntfy、Buzz，以及通用 Webhook 适配器。^360171819 这里的 28 来自标签 v2026.8.31 文档中的平台比较表；而在底层，gateway/config.py 定义了 24 个内置 Platform 枚举成员（包括 local、api_server、webhook、msgraph_webhook 和 relay 等非聊天条目），并会按需将其他任何名称解析到 plugins/platforms/ 下捆绑的 22 个适配器目录之一。因此，仅统计枚举成员或目录数量都不会与文档中的数字一致。²⁵ v0.9.0 通过 BlueBubbles 增加了 iMessage 支持（自动注册 Webhook、设置向导和崩溃恢复能力），还通过 iLink Bot API 增加了原生 WeChat 支持，并为企业应用提供 WeCom 回调模式。¹⁶ v0.11.0 增加了 QQBot。⁶⁰ v0.12.0 增加了 Microsoft Teams 和 Tencent Yuanbao。¹⁷ v0.13.0 增加了作为第 20 个平台的 Google Chat，沿用同一套可插拔适配器架构；IRC 和 Microsoft Teams 也迁移到了新的适配器模式，并采用通用的 env_enablement_fn / cron_deliver_env_var 插件钩子。¹⁸ v0.14.0 增加了 LINE 和 SimpleX Chat，并通过 Graph 身份验证、Webhook 监听器、流水线运行时和出站投递，端到端完善了 Microsoft Teams 技术栈。¹⁹ v0.17.0（2026年6月19日）通过 Photon Spectrum 增加了无需中继的 iMessage（使用 hermes photon login 进行设备代码 OAuth，无需 Mac/BlueBubbles 中继）、官方 WhatsApp Business Cloud API 适配器（不再需要桥接进程）、SimpleX 群组和原生附件，以及作为捆绑平台插件的 Raft。²¹ 文档表格中还有两个平台未在发行说明中大张旗鼓地提及：ntfy 是一种轻量级 HTTP 发布-订阅推送渠道（在 ntfy 移动应用中订阅主题，向该主题发送消息即可与 agent 对话，并在手机上收到回复；既可使用公共 ntfy.sh 服务器，也可使用自行托管的实例，无需 SDK 或守护进程）；Buzz 则将 Hermes 连接到 Buzz 社区。Buzz 是 Block 基于 Nostr 协议打造的开源人机协作平台，出站消息通过调用 buzz CLI 发送，入站消息则使用原生 Nostr WebSocket 订阅。这两者均通过 hermes gateway setup 配置。²⁵

设置

hermes gateway setup                # Interactive platform configuration
hermes gateway install              # Install as user service (systemd/launchd)
hermes gateway start                # Start the installed service
hermes gateway stop
hermes gateway restart
hermes gateway status
hermes gateway run                  # Run in foreground (debugging)

交互式设置会引导您连接各个平台，包括配置 API 令牌、机器人 ID、频道映射和允许列表。⁶

消息流转方式

根据上游架构文档：³

Platform event → Adapter.on_message() → MessageEvent
  → GatewayRunner._handle_message()
    → authorize user
    → resolve session key
    → create AIAgent with session history
    → AIAgent.run_conversation()
    → deliver response back through adapter

每个消息平台都使用与 CLI 相同的 AIAgent 对话循环。 因此，斜杠命令在两处的工作方式完全一致；在 Telegram 中安排的 cron 任务也能将输出投递到 Discord，因为平台之间的差异仅存在于边缘接入层。³

v0.19.0 增加了基于 profile 的消息路由和持久化投递。 共享同一机器人令牌的单个多路复用 gateway，可以将特定服务器、频道或线程路由到不同的 profile。每个 profile 的配置、skills、内存和密钥均完全隔离；同时还可通过 GATEWAY_MULTIPLEX_PROFILES 覆盖设置。经过一轮加固后，单个 profile 配置错误也不再会拖垮整个 gateway。在底层，路由索引已迁移到 state.db（sessions.json 现在只是可选的旧版镜像）；最终响应会围绕平台发送操作记录在持久化的投递义务账本中。如果 gateway 在答案生成完毕后崩溃，该答案会在下次启动时重新投递，而不会悄无声息地丢失。⁵⁶ v0.21.2 进一步加强了路由 profile 之间的隔离，修复了这种多路复用设置中的一系列跨 profile 泄漏问题：继承的允许列表、发送到默认 profile 主机的凭据、默认 profile 的保管库密钥传入 stdio MCP 服务器、跨 profile 的 MEDIA: 附件，以及同级 profile 的 Nous bearer 残留在进程级备忘缓存中（#107609-#107630）。⁴⁸

v0.21.1 将对话边界改为只能显式创建。 标签 v2026.9.7 的会话生命周期文档用四句话明确了这一约定：“空闲状态和现实时间流逝永远不会轮换对话。/new 和 /reset 会创建显式边界；上下文压缩会继续管理较长的历史记录。旧版计时器配置将被忽略。现有的 SessionResetPolicy 数据类型只是无运行时作用的兼容性数据，而非运行时策略。”显式暂停仍会在下一次入站消息到来时创建边界；恢复操作会遵循已经最终确定的边界，而不会重新打开对话；仅因资源限制而进行的淘汰仍允许恢复对话。如果 gateway 上的某个会话看起来“永不过期”，这正是当前的设计；请自行使用 /new 轮换会话。⁴³

从 v0.21.4 时期开始，第二个 hermes gateway run 会附加到现有进程或拒绝运行，而不会重复绑定。 规则是：每个主机上的每个操作系统用户只能运行一个 hermes serve 和一个 hermes gateway run，且两者都会多路复用所有 profile。若为运行中的多路复用器已经提供服务的 profile 启动 gateway，该命令只会附加后以状态码 0 退出；如果该多路复用器尚未为这个 profile 提供服务，Hermes 会要求它重新扫描 profiles/，待其开始提供服务后再附加；如果无法使其为该 profile 提供服务，命令将拒绝运行，而不会静默启动第二个 gateway。--replace 现在以该主机进程为目标，无论它由哪个 profile 启动；当所有者进程卡死时，--force 会完全跳过询问。独立 gateway 仍可共存：如果正在运行的 gateway 是另一个 profile 的独立（非多路复用）实例，您的 profile 会像以前一样在其旁边启动自己的实例，直到强制执行该迁移（#109417）。如果两个 gateway 同时启动，未能获得主机锁的进程会以状态码 75 退出，Hermes 生成的所有监督程序都会重试；届时，胜出进程的记录已存在，因此重试进程会按照上述规则附加或拒绝运行。锁和会合记录位于 $HERMES_GATEWAY_LOCK_DIR 下；若未设置，则位于 $XDG_STATE_HOME/hermes/gateway-locks（默认为 ~/.local/state/hermes/gateway-locks），并限定在操作系统用户范围内。如果记录中的 PID 已终止或已被其他进程复用，该记录会被视为过期并忽略，因此 gateway 崩溃不会阻止下一次启动。Desktop 应用遵循同样的规则：它会附加到正在运行的主机后端，而不会生成第二个后端。⁵¹

从 v0.21.5 起，多路复用不再是可选项。 gateway.multiplex_profiles 只有一个有效值：true。未设置该键时，它会解析为启用状态，并写入默认 profile 的 config.yaml；如果显式设置为 false，系统会直接将其改写为 true，并在该 gateway 启动时显示一次带边框的通知，随后在下一次 hermes update 摘要中再次提示。现在由两个控制项取代旧的退出选项。若要在不停止其他所有人机器人的情况下让某个 profile 离线，请运行 hermes -p <name> gateway stop：主机会将其停放（创建 profiles/<name>/gateway.parked 标记），而 hermes -p <name> gateway start 会解除停放；dashboard 和 Desktop 的停止/启动按钮执行相同操作。若命名 profile 仍需自己的 gateway，请在其 config.yaml 中设置 gateway.standalone: true；主机永远不会为它提供服务，其 stop/start 命令会作用于自己的进程。文档将此键称为“临时兼容性垫片”，而非受支持的拓扑；在默认 profile 上设置时，该键会被忽略并触发警告。如果拆分到不同的操作系统用户，或使用默认主目录 profiles/ 之外的 HERMES_HOME，仍需使用 --force。⁵³

用户授权与配对

hermes pairing list                    # Show pending and approved users
hermes pairing approve <platform> <code>
hermes pairing revoke <platform> <user-id>
hermes pairing clear-pending

配对码可防止陌生人随意与您的 gateway 对话。用户从其消息平台发送配对码；您使用 hermes pairing approve 批准后，该用户便获得授权。⁶

unauthorized_dm_behavior 决定陌生人的私信在配对前会得到何种处理：pair 会通过私信发送配对码，ignore 会静默丢弃消息，而在 v0.21.4 时期增加的 decline 会礼貌拒绝一次，随后对该发送者保持静默 24 小时（#88028）。拒绝消息会基于平台和发送者去重，并覆盖别名；其文本来自 unauthorized_dm_decline_message（全局键；留空表示使用内置回复：“您好！我是私人助理，只能与我的主人交流，因此无法直接帮助您。抱歉！”）。可设置全局行为，也可针对设置向导写入配置的各个平台单独设置：

# ~/.hermes/config.yaml
unauthorized_dm_behavior: decline      # global; gateway.unauthorized_dm_behavior also works
unauthorized_dm_decline_message: ""    # empty = built-in reply
platforms:
  telegram:
    unauthorized_dm_behavior: pair     # per-platform value always wins

未设置任何值时，实际默认行为取决于允许列表。如果未配置任何允许列表，则默认值为 pair；一旦设置了任意允许列表（GATEWAY_ALLOWED_USERS，或某个平台的允许用户、群组允许用户或群组允许聊天变量），默认值就会变为 ignore。这是因为允许列表表明 gateway 受到了有意限制，向未知联系人发送配对码既会造成干扰，也可能导致信息泄漏（#9337）。全局 ignore 或 decline 可以覆盖这条规则，但全局 pair 不行，因为它与默认值无法区分；若要在使用允许列表的同时保留配对功能，请针对具体平台设置 pair。（如果平台适配器自身设置了 dm_policy，则会在允许列表规则之前参考该策略。）电子邮件采用收件箱模式，默认值为 ignore，除非通过其平台专属键明确启用；全局值不会应用到电子邮件。使用 hermes gateway setup 配置未设置允许列表的平台时，向导会将拒绝行为作为选项之一。⁵¹

定时任务（Cron）

Hermes提供一套一流的cron系统，其中的作业是agent任务，而非shell命令。每个定时作业都会通过全新的AIAgent运行，使用已配置的提示词和可选的附加skill，并将结果发送到任意平台：³⁶

hermes cron list
hermes cron create --prompt "Check HN for AI news and summarize" --schedule "0 9 * * *" --deliver telegram
hermes cron edit <id>
hermes cron pause <id>
hermes cron resume <id>
hermes cron run <id>         # Trigger now on the next tick
hermes cron remove <id>
hermes cron status           # Check if scheduler is running
hermes cron tick             # Run due jobs once and exit

也可以在消息聊天中通过对话方式创建：

Every morning at 9am, check Hacker News for AI news and send me a summary on Telegram.

agent会通过自身工具设置cron作业。作业会持久保存在JSON中，并可在重启后继续运行。³

v0.21.0赋予定时作业记忆与判断能力。 共有4种机制，均已在标签v2026.8.31中验证：³⁵³⁷

• 连续性。 continuity=true会将作业自身最近一次的输出注入每次运行，使侦察或监控任务“唤醒时能看到上次报告的内容，从而去重并接着此前的进度继续执行”——注入的指引是“避免重复已经报告过的内容”；首次运行不受影响；在内部，该标志以保留的self条目存储在context_from中。可通过hermes cron create ... --continuity以及hermes cron edit <job_id> --continuity／--no-continuity切换此功能。³⁷
• 持久化记事本。 每个作业都会获得一个小型KV暂存区，用于保存游标、水位标记和监视列表（每个值上限16 KB，每个作业上限64 KB——每次运行都会将其注入提示词，因此这些限制是有意为之）。可通过hermes cron notepad <job_id> set <key> <value>写入，运行中的agent会借助其终端工具调用此命令。³⁷
• 监控模式。 作业可以附加一个低成本的monitor_script／monitor_url源，并在每个周期开始时优先运行：如果输出没有变化（按精确字节比较），则完全跳过agent运行——不会调用LLM、不会发送结果，只记录一次静默的no_change运行；如果检测到变化，则注入差异块并正常运行agent。监控脚本应输出稳定内容，否则每个周期都会被视为发生了变化。³⁷
• 按作业设置推理强度，并发送至Bot Chat。 --reasoning-effort会固定某个作业的思考级别（从none到ultra），覆盖该作业运行时的全局及按模型设置；deliver=bot-chat则会将输出作为真实传入消息送达某个profile的规范Bot Chat会话，让机器人“处理一切需要执行的事项，并在聊天中作出响应”，而不是仅由用户在频道中阅读。³⁷

MCP集成

Hermes既可作为客户端，也可作为服务器支持Model Context Protocol：⁶

作为客户端——将Hermes连接到外部MCP服务器，以扩展其工具范围：

hermes mcp add <name> --url https://example.com/mcp
hermes mcp add <name> --command npx --args "-y,@modelcontextprotocol/server-github"
hermes mcp list
hermes mcp test <name>
hermes mcp remove <name>
hermes mcp configure <name>   # Toggle individual tool selection
hermes mcp login <name>       # Force re-auth for an OAuth server (--flow browser|device)
hermes mcp reauth [--all]     # Re-authenticate one OAuth server, or every one

也可以在config.yaml中手动配置：¹⁴

mcp_servers:
  github:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxx"

自v0.19.0起，MCP工具按照mcp__server__tool命名约定向模型公开——每个工具名称都会包含其服务器名称，因此两个服务器提供同名工具时不再发生冲突——同时，MCP服务器的日志通知也会显示在agent.log中。⁵⁶

v0.21.1为MCP OAuth新增了设备代码流程：hermes mcp login <name>接受--flow {browser,device}——browser是现有的PKCE流程，device是适用于无头或远程计算机的RFC 8628设备代码登录流程——该标志会覆盖服务器的oauth.flow配置。同一版本还会在整个OAuth会话期间强制执行profile所有权检查；遇到格式错误的OAuth元数据缓存时会予以忽略，避免服务器卡死；并通过客户端本地回调中继桌面端MCP OAuth。现在，-t／--toolsets还会筛选需要启动的已配置MCP服务器，使限定范围的调用无需冷启动无关服务器。⁴⁴

v0.21.0将桌面端的MCP界面升级为命令中心：服务器与目录合并到同一个页面；支持拖入式“粘贴任意内容”导入；后台健康检查可在工具调用失败前提示身份验证即将过期；群组成本／用量叠加层会显示每台服务器的架构token估算值及30天用量；hermes://深层链接则可在明确确认后安装MCP服务器。³⁵

v0.21.4版本周期新增了mcp.discovery_concurrency（默认值为4；0表示不受限制，#117373），用于限制发现流程同时连接的已配置MCP服务器数量。所有服务器仍会建立连接——该限制仅用于避免它们同时发起连接——如果值不是整数或为负数，系统会记录警告并回退到默认值。⁵¹

作为服务器——向其他agent公开Hermes对话：

hermes mcp serve
hermes mcp serve -v    # Verbose

上下文压缩

Hermes会自动压缩过长的对话，使其保持在模型的上下文窗口之内。压缩摘要器会单独调用一次LLM——您可以将其指向任意提供商或端点。⁴ 自v0.20.6起，保留尾部策略默认为精简（compression.tail_mode: lean）；在该标签中，摘要器的模型、提供商和端点选项位于auxiliary.compression.*下，而非旧版的compression.summary_*。旧配置键会在首次加载时自动迁移（配置版本17）。³⁰³¹

compression:
  enabled: true
  threshold: 0.50          # Compress at this % of context limit
  threshold_tokens: null   # Optional absolute token cap -- trigger fires at the lower of ratio vs cap
  target_ratio: 0.20       # Fraction of threshold to preserve as recent tail (legacy tail mode)
  tail_mode: lean          # Tail retention: "lean" (default) or "legacy"
  protect_last_n: 20       # Min recent messages to keep uncompressed
  protect_first_n: 3       # Non-system head messages pinned across compactions

auxiliary:
  compression:
    model: ""              # Empty = main chat model; e.g. "google/gemini-3-flash-preview"
    provider: "auto"       # "auto", "openrouter", "nous", "codex", "main", etc.
    base_url: null         # Custom OpenAI-compatible endpoint (overrides provider)

tail_mode的作用。 legacy会保留由target_ratio决定大小的原样尾部——在大窗口或提高阈值的配置中，每次压缩都会因此囤积100–240K个token。lean则保留经过限制的原样尾部，其大小为上下文窗口的2.5%（下限10K，上限25K），并改由摘要维持连续性：为已压缩区域生成详细且保留标识符的会话日志（每次尝试调用一次辅助摘要器）；通过机械方式提取锚点索引（PR编号、SHA、路径、错误字符串——使用正则表达式，绝不改述）；逐字引用每条真实用户消息；并提供session_search恢复指针，使agent能够重新访问摘要中省略的任何内容。文档对500K token真实会话的测量结果显示：保留约49K个token，而非约162K个。精简尾部中的旧工具结果会降级为包含恢复指针的单行存根，未知的tail_mode值则会回退到lean。³¹

提供商选项：⁴³¹

摘要模型支持的上下文长度必须至少与主模型相同，因为它会在一次调用中接收对话的完整中间部分——如果摘要模型的窗口较小，调用将失败，中间轮次也会在没有摘要的情况下被丢弃。⁴³¹

预算压力警告

当agent执行包含大量工具调用的复杂任务时，可能会在未察觉的情况下耗尽迭代预算（自v0.20.0起默认为500轮，此前为90轮）。预算压力机制会自动向模型发出警告：⁴

流式传输超时

LLM流式连接设有两层超时机制，并会针对本地提供商（localhost、局域网IP）自动调整：⁴

本地端点的套接字读取超时会提高至30分钟，因为本地LLM在处理大型上下文时，可能需要数分钟完成预填充，之后才会生成首个token。⁴

本地Web控制面板（v0.9.0及更高版本）

这是一个基于浏览器的控制面板，用于在本地管理Hermes Agent。无需修改配置文件或使用终端，即可配置设置、监控会话、浏览skill并管理gateway。¹⁶ 使用hermes dashboard启动。对于偏好GUI的新用户而言，这是最简便的上手方式。

后台进程监控（v0.9.0+）

watch_patterns允许您设置模式来监控后台进程输出，并在匹配时实时收到通知。¹⁶无须轮询，即可监控错误、等待特定事件（“正在监听端口”），或查看构建日志。结合v0.8.0中用于在后台任务完成时发出通知的notify_on_complete，Hermes现在具备了完整的后台进程可观测层。¹⁵

可插拔Context Engine（v0.9.0+）

现在可通过hermes plugins将上下文管理用作可插拔插槽。您可以换用自定义context engine，控制agent在每轮中看到的内容，包括过滤、摘要或注入特定领域的上下文。¹⁶这将上下文策略与核心agent循环解耦，支持针对不同项目或领域自定义上下文。

备份与恢复（v0.9.0+）

hermes backup会为您的配置、会话、skills和memory创建完整归档。hermes import则从备份归档中恢复这些内容。¹⁶您可以借此在不同设备间迁移、在重大变更前创建快照，或与团队成员共享经过验证的配置。

Termux / Android支持（v0.9.0+）

Hermes可通过Termux在Android上原生运行。经过调整的安装路径、面向移动屏幕的TUI优化、语音后端支持以及/image命令均可在设备端使用。¹⁶

安全加固（v0.13.0+）

v0.13.0修复了8个P0安全问题，并将一项默认设置改为更有利于用户的选项。¹⁸随后发布的v0.14.0又修复了12个P0和50个P1问题，包括防范sudo暴力破解、加固sudo标准输入、修复危险命令绕过问题、在工具错误重新注入模型前进行清理、为仪表板插件API添加身份验证、完善skills-hub的SSRF防护，以及在安装期间扫描供应链安全公告。¹⁹

如果您维护Hermes部署，应将v0.13.0和v0.14.0视为与安全相关的升级，而非普通的功能更新。v0.13.0修复了Discord跨guild绕过问题和两个TOCTOU窗口；v0.14.0则进一步加固了sudo处理、工具错误重新注入、插件API、skills-hub的SSRF防护以及依赖项安全公告检查。

v0.21.0带来了第四轮安全加固。现在，写入受保护的agent指令文件——AGENTS.md、CLAUDE.md、SOUL.md、.cursorrules、skills和memory存储——始终需要获得批准，因此遭到提示词注入的agent无法悄然改写自身的长期指令。该防护默认启用（security.protected_instruction_files: true，并通过protected_instruction_extra_patterns中的fnmatch基本名称扩展列表进行扩展）。源代码还明确指出了其所阻断的攻击方式：“通过注入的指令编辑AGENTS.md / CLAUDE.md / SOUL.md”，并强调指令文件会从cwd目录树中加载，因此“agent日后可能运行所在位置中的任何AGENTS.md都是现实攻击目标”。³⁵³⁹同一版本还修复了终端错误、.env文件读取、checkpoint和ACP日志中的敏感信息泄露缺口；让审批系统能够识别Windows上的破坏性命令和路径；通过稳定的TCC签名身份，使macOS权限授权在更新后依然有效（一次性设置：hermes desktop --setup-tcc-identity，仅适用于macOS，需要openssl/security/codesign）；在上游遭到入侵后移除了Blender MCP目录条目及其skill；并为插件安装增加了Tier-1安全扫描。³⁵³⁹

面向实践者的架构

本节适合希望了解底层运行机制，以便进行调试、扩展或分析性能的读者。内容综合整理自上游架构文档。³

入口点 → AIAgent

Hermes 的每个入口点最终都会调用 AIAgent.run_conversation()：

┌──────────────────────────────────────────────────────────────────┐
│                        Entry Points                              │
│                                                                  │
│  CLI (cli.py)    Gateway (gateway/run.py)    ACP (acp_adapter/)  │
│  Batch Runner    API Server                  Python Library     │
└──────────┬──────────────┬───────────────────────┬────────────────┘
           │              │                       │
           ▼              ▼                       ▼
┌──────────────────────────────────────────────────────────────────┐
│                     AIAgent (run_agent.py)                       │
│                                                                  │
│  ┌─────────────┐  ┌──────────────┐  ┌──────────────┐             │
│  │ Prompt      │  │ Provider     │  │ Tool         │             │
│  │ Builder     │  │ Resolution   │  │ Dispatch     │             │
│  └──────┬──────┘  └──────┬───────┘  └──────┬───────┘             │
│         │                │                 │                    │
│  ┌──────┴───────┐ ┌──────┴───────┐  ┌──────┴───────┐             │
│  │ Compression  │ │ 3 API Modes  │  │ Tool Registry│             │
│  │ & Caching    │ │ chat_compl   │  │ 47 tools     │             │
│  │              │ │ codex_resp   │  │ 20 toolsets  │             │
│  │              │ │ anthropic    │  │              │             │
│  └──────────────┘ └──────────────┘  └──────────────┘             │
└──────────────────────────────────────────────────────────────────┘

示意图改编自上游架构文档。³

横幅中的“47 个工具/20 个 toolset”与“28 个工具”。“47 个工具”是上游代码仓库中工具注册表的总数，即 Hermes 随源代码提供的所有 toolset 中的全部工具。实际运行的 CLI 会在启动横幅中显示一个较小的数字（我用于验证本指南的安装环境显示 28 tools / 89 skills）。这并非错误。许多 toolset 需要主动启用，并且必须在 config.yaml 的 toolsets: 下显式配置，例如消息平台适配器、浏览器自动化和资源消耗较大的抓取工具等。注册表总数表示“有哪些工具可用”，横幅中的数字则表示“当前 profile 启用了哪些工具”。可使用 hermes tools --list 查看已启用的 toolset，并通过 ~/.hermes/config.yaml 中的 toolsets: 块启用或禁用单个 toolset（也可以在运行中的会话内使用 /tools list、/tools enable <name> 或 /tools disable <name>；移除工具会触发会话重置，以便代理重新构建其工具清单）。

3 种 API 模式

Hermes 将不同提供商之间的差异抽象为 3 种 API 模式，并在运行时自动选择：³

runtime_provider.py 解析器会将 (provider, model) 元组映射为 (api_mode, api_key, base_url)，支持 18 个以上的提供商，并负责处理 OAuth 流程、凭据池和别名解析。³

CLI 会话中的数据流

User input → HermesCLI.process_input()
  → AIAgent.run_conversation()
    → agent.prompt_builder.build_system_prompt()
    → runtime_provider.resolve_runtime_provider()
    → API call (chat_completions / codex_responses / anthropic_messages)
    → tool_calls? → model_tools.handle_function_call() → loop
    → final response → display → save to SessionDB

源自上游架构页面。³

提示词组装顺序

提示词栈包括：¹³

1. SOUL.md（代理身份；若不可用，则使用内置后备内容）
2. 根据工具提供的行为指导
3. 记忆与用户上下文（MEMORY.md、USER.md）
4. Skills 指导
5. 上下文文件（AGENTS.md、.cursorrules）
6. 时间戳
7. 特定平台的格式提示
8. 可选的系统提示词叠加层，例如 /personality

SOUL.md 是基础，其他所有内容都构建于其上。¹³

会话存储

基于 SQLite 的会话存储，支持 FTS5 全文搜索。会话具备谱系跟踪功能（记录压缩前后的父子关系）、按平台隔离，并采用带争用处理的原子写入。³

如果 v0.21.x 安装中的存储出现问题，请升级至 v0.21.2 或更高版本：该版本解决了 v0.21.0 时期的一系列 state.db 脆弱性问题，包括后启动的写入进程相互取消对方的锁、正常数据库被误报为损坏，以及单条异常记录导致 sessions list 整体失败。它还将托管房间的协调状态从根存储迁移至专用的 shared-state.db，因此 profile gateway 不再以可写方式打开主会话存储。现在，hermes doctor 会分别指出结构损坏和 FTS 索引损坏；FTS 损坏只会导致搜索功能降级，而不会使当前轮次失败。hermes sessions recover --inspect-only（离线、非破坏性、固定到指定 profile）则会报告规范表的可读性，且不会创建输出数据库——该子命令早已存在，只是此前未在此处记录。请参阅《v0.21.2 的新增功能》。⁴⁸ 对于停留在错误 SQLite 日志模式的存储，v0.21.4 发布周期新增了离线转换器 hermes sessions set-journal-mode delete|wal（请参阅顶层命令中的 hermes sessions 行）。⁵¹

插件系统

插件有 3 个发现来源：~/.hermes/plugins/（用户）、.hermes/plugins/（项目）和 pip 入口点。插件通过上下文 API 注册工具、钩子和 CLI 命令。内存提供程序是一类特殊插件，位于 plugins/memory/ 下。³ 从 v0.21.2 起，系统还提供了一个精选的 SHA 固定插件目录，可按名称浏览和安装插件；同时新增 hermes plugins pack，用于创建“声明式、可共享的插件集合”：通过单个 hermes-pack.yaml 将一组插件固定到确切的提交 SHA。安装该集合时会分别执行常规的固定版本安装，而功能授权仍由每个插件单独确认。⁴⁸

v0.21.4 发布周期将该目录从 CLI 界面扩展为随产品交付的构件。代码仓库中的 plugin-catalog/ 目录从 v2026.9.14 的 9 个条目增加到 v2026.9.21 的 228 个条目——每个插件对应一份经过审核的 YAML（包含名称、代码仓库、维护者、等级、类别和功能），固定到一个确切的 40 字符提交 SHA；存在于该目录中即表示获准收录。这些数据会发布为供 CLI 使用的 plugin-catalog.json（实时获取并缓存在 ~/.hermes/cache/ 下）。文档网站现在会根据同一份数据，为每个插件（/docs/plugins/<name>）和每位作者（/docs/plugins/by/<slug>）生成页面。每个页面都会呈现从固定提交而非分支最新版本获取的插件 README，并通过构建时白名单剔除原始 HTML；新增和更新排序所用的时间戳来自提交者日期。v0.21.4 发行说明中提及的 10 个社区插件，在该标签下均已收录于目录，并使用其实际目录 slug：hermes-tailscale、hermes-ssh、shodan、hermes-terminal、hermes-rss（另有独立的 rss-reader）、hermes-resetwatch、done-bell、kiwi、cognee 和 web-octen。在桌面端，Plugins 中心现在可以通过确认对话框卸载插件——目录插件通过 plugins.manage remove 卸载，独立桌面插件则通过 Electron 加载器卸载。⁵¹

hermes plugins                       # Interactive enable/disable UI
hermes plugins browse                # List every curated plugin catalog entry (v0.21.2+)
hermes plugins search <query>        # Search the curated plugin catalog (v0.21.2+)
hermes plugins install <name|repo>   # Install from the curated catalog, a Git URL, or owner/repo
hermes plugins enable <name>
hermes plugins disable <name>
hermes plugins list
hermes plugins pack install <src>    # Shareable SHA-pinned plugin sets; also: pack export, pack show (v0.21.2+)

兼容期（v0.21.1）现已结束：外部插件必须在 2026年9月14日之前迁离拆分前的导入路径。2026年9月的拆分（PR #102117）迁移了插件经常导入的内部组件，临时的 COMPAT_MANIFEST.md 层则从旧模块重新导出了 1,148 个已迁移的公共名称，并针对每个名称在每个进程中发出一次警告（HermesPluginCompatWarning）。移除操作已按计划于 2026年9月14日生效，通过已发布代码中的日期门控实现（hermes_cli/plugin_compat.py 内的 COMPAT_REMOVAL_DATE；无需回滚代码）：从该日期起，受影响的插件会被禁用，而不会被加载。CLI 横幅、hermes doctor 和 hermes update 中会显示红色通知，桌面端会显示一次性模态对话框，hermes plugins list 中也会列出具体原因。对于作者：hermes plugins compat <path> 仍会输出所有使用旧路径的位置，包括 file:line 和“旧路径 -> 新路径”，只要仍有任何旧路径残留，就会以状态码 1 退出（添加 --json 可获得机器可读输出）。仍需使用无人维护插件的用户，可以在 config.yaml 中设置 plugins.allow_deprecated_imports: true——其值必须是字面量 YAML 布尔值，不能是带引号的字符串。目前该应急开关仍然有效，因为删除旧路径的回滚尚未落地：在 v2026.9.14、v2026.9.21、v2026.9.24 以及截至9月24日的 main 分支中，清单和兼容垫片依然存在（v0.21.4 发布周期对兼容模块的改动仅限于缓存插件扫描和规范化 Windows 路径；v0.21.5 发布周期未修改 hermes_cli/plugin_compat.py，仅移除了已删除 Hindsight 模块对应的清单条目）。一旦该回滚落地，应急开关将立即失效，因为旧路径本身也会消失。兼容层仅涵盖公共顶层名称；私有名称和测试 monkeypatch 接缝从来都不属于受支持界面，因此不会恢复。⁴²⁵³

设计原则

源自上游架构页面：³

从 OpenClaw 迁移

Hermes Agent 是 OpenClaw 的继任者。如果您要从现有的 OpenClaw 安装迁移：⁶⁵

hermes claw migrate --dry-run                    # Preview what would be migrated
hermes claw migrate --preset full                # Full migration including API keys
hermes claw migrate --preset user-data --overwrite   # User data only, no secrets
hermes claw migrate --source /custom/path        # Non-default OpenClaw location

hermes claw migrate 默认从 ~/.openclaw 读取数据（也会自动检测旧版 ~/.clawdbot 和 ~/.moldbot 目录），并写入 ~/.hermes。⁶

直接导入（30 多个类别）：SOUL.md、MEMORY.md、USER.md、AGENTS.md、来自 4 个源目录的 skill、默认模型、自定义提供商、MCP 服务器、消息平台令牌和允许列表（Telegram、Discord、Slack、WhatsApp、Signal、Matrix、Mattermost）、agent 默认设置（推理强度、压缩、人工延迟、时区、沙箱）、会话重置策略（现已停用：自 v0.21.1 起，计时器不再轮换对话⁴³）、审批规则、TTS 配置、浏览器设置、工具设置、执行超时、命令允许列表、gateway 配置，以及来自 3 个来源的 API 密钥。⁶

归档以供手动审查：cron 任务、插件、钩子/webhook、内存后端（QMD）、skill 注册表配置、UI/身份、日志记录、多 agent 设置、频道绑定、IDENTITY.md、TOOLS.md、HEARTBEAT.md、BOOTSTRAP.md。⁶

API 密钥解析会按优先级依次检查 3 个来源：配置值 → ~/.openclaw/.env → auth-profiles.json。⁶

故障排除

“未配置推理提供商。请运行 ‘hermes model’ 选择提供商和模型”

每次全新安装都会遇到的第一个错误：Hermes 尚未解析出可用的提供商。它的含义直截了当——3 种身份验证路径均未提供可用的提供商。请运行：

hermes model

交互式选择器会引导您完成所有受支持提供商的配置，包括 OAuth 设备代码流程（Nous Portal、GitHub Copilot、Anthropic、OpenAI Codex），以及用于自托管服务器的自定义端点。如果原本预期提供商已经配置好，hermes doctor 会显示 Hermes 实际能够检测到哪些凭据。常见原因包括：API 密钥设置在错误的位置（应放在 .env 中或通过 hermes config set 设置，而不是放在 shell 配置文件中）、~/.hermes/auth.json 中的 OAuth 凭据已过期，或 config.yaml 中的自定义端点缺少 base_url。有关身份验证路径的详细说明，请参阅身份验证与提供商。²⁷

“未设置 API 密钥”

运行 hermes model 以交互方式配置提供商，或运行 hermes config set OPENROUTER_API_KEY your_key。hermes doctor 命令会准确告知您缺少哪些密钥。⁷

启动时出现“上下文限制：2048 个令牌”（本地模型）

Hermes 会通过服务器的 /v1/models 端点自动检测上下文长度，但许多本地服务器会报告较低的默认值。请在 config.yaml 中明确设置：²

model:
  default: your-model
  provider: custom
  base_url: http://localhost:11434/v1
  context_length: 32768

工具调用显示为文本，而未实际执行

您的服务器未启用工具调用，或者该服务器的实现不支持当前模型执行工具调用。²

响应在句子中途被截断

可能有以下两个原因：²

1. 服务器的输出上限过低（max_tokens）——SGLang 默认每次响应最多输出 128 个令牌。请在服务器上设置 --default-max-tokens，或在 config.yaml 中配置 model.max_tokens。
2. 上下文耗尽——模型已填满上下文窗口。请增大 model.context_length，或在 Hermes 中启用上下文压缩。

从 WSL2 连接 Windows 上托管的模型服务器时出现“连接被拒绝”

WSL2 使用具有独立子网的虚拟网络适配器——WSL2 内的 localhost 指向 Linux 虚拟机，而非 Windows 主机。有两种解决方案：²

镜像网络模式（Windows 11 22H2 及更高版本）：编辑 %USERPROFILE%\.wslconfig：

[wsl2]
networkingMode=mirrored

然后运行 wsl --shutdown 并重新启动。此时，localhost 即可双向访问。

主机 IP 备用方案（旧版 Windows）：从 WSL2 内部获取 Windows 主机 IP，并使用该地址代替 localhost：

ip route show | grep -i default | awk '{ print $3 }'
# Use that IP as the base_url host

此外，还需让模型服务器绑定到 0.0.0.0，而不是 127.0.0.1——对于 Ollama，请设置 OLLAMA_HOST=0.0.0.0；对于 llama-server/SGLang，请添加 --host 0.0.0.0；对于 LM Studio，请启用“Serve on Network”。²

迭代预算忽略 agent.max_turns

如果活动行显示 N/90（或其他过期上限），而 config.yaml 中设置的是 agent.max_turns: 500，最可能的原因是 ~/.hermes/.env 中残留了一行过期的 HERMES_MAX_ITERATIONS：设置向导过去会将预算同时写入两个存储位置。如果启动桥接程序因更早出现的配置解析错误而退出，.env 中的幽灵配置便会悄然生效。自 v0.21.1 起，hermes doctor 会检测这组遮蔽配置，而 hermes doctor --fix 会删除 .env 中的对应行，使 config.yaml 成为权威配置来源。⁴¹

所有内容都在哪里？

此时，hermes status 和 hermes dump 会很有帮助。hermes logs list 会显示所有日志文件及其大小。hermes config path 会输出配置文件的位置。hermes config env-path 会输出 .env 的位置。⁶

常见问题

Hermes Agent 和 Claude Code 有什么区别？

Claude Code 是 Anthropic 官方推出的 CLI，仅限使用 Anthropic 模型。Hermes Agent 是 Nous Research 推出的开源智能体框架，可与任何兼容 OpenAI 的提供商配合使用，包括 Nous Portal、OpenRouter、Anthropic、GitHub Copilot、z.ai、Kimi、MiniMax、DeepSeek、Hugging Face、Google，或您自行托管的端点。¹² Hermes 还提供适用于 Telegram/Discord/Slack/WhatsApp/Signal 的消息 gateway，而 Claude Code 并不具备此功能。

可以将 Hermes 与 Anthropic API 密钥配合使用吗？

可以。有3种方式：²

1. 在 ~/.hermes/.env 中设置 ANTHROPIC_API_KEY，然后运行 hermes chat --provider anthropic --model claude-sonnet-4-6
2. 运行 hermes model 并选择 Anthropic——如果 Claude Code 的凭据存储可用，Hermes 将使用其中的凭据
3. 手动设置 ANTHROPIC_TOKEN（setup-token 或 OAuth token）作为后备方案

如果您已在同一台计算机上使用 Claude Code，建议选择方式2——这样可确保能够刷新的 Claude 凭据继续保持可刷新状态。

如何在不丢失对话的情况下切换提供商？

在会话中使用 /model provider:model。对话历史记录、memory 和 skills 都会完整保留：⁹

/model zai:glm-5
/model openrouter:anthropic/claude-sonnet-4
/model custom:local:qwen-2.5

我配置了 Anthropic，但视觉/Web/压缩功能无法使用

在当前版本中，过去那种问题基本不会再发生。默认情况下（auxiliary.*.provider: "auto"），所有辅助任务——视觉、审批分类、压缩、会话标题——都会在您的主聊天模型上运行。因此，仅配置 Anthropic 时，这些任务会使用已有的 OAuth。旧的默认机制（依次尝试通过 OpenRouter 使用 Gemini Flash、Nous、Codex 自动检测，并在均未配置时静默降级）已被移除：“auto 现在会让所有用户使用主模型，而 config.yaml 中针对各项任务的覆盖配置仍然优先。”³⁴

如果辅助任务仍然失败，请检查是否存在明确的任务级覆盖配置，指向了从未配置的提供商（即 config.yaml 中的 auxiliary.<task>.provider / .model），或是否残留旧版配置键。从标签 v2026.8.31 开始，压缩摘要器与其他辅助槽位采用相同的配置方式，即 auxiliary.compression.provider；旧版 compression.summary_* 配置键会自动迁移至此处（配置版本17）。³¹ Web 内容提取也不再属于 LLM 任务（“不涉及 LLM”），因此在当前版本中，Web 摘要失败并非辅助模型问题。³⁴ 如需将某项任务明确固定回主提供商：

auxiliary:
  vision:      { provider: "main" }
  compression: { provider: "main" }

SOUL.md 和 AGENTS.md 有什么区别？

SOUL.md 定义智能体的身份，包括语气、风格和默认沟通方式。它位于 ~/.hermes/SOUL.md，无论身处何处都会随您生效。AGENTS.md 则是项目专用文件，用于记录架构、约定、命令和路径，存放在项目目录中。¹³ 如果内容应在所有场景中随您生效，请写入 SOUL.md；如果内容只属于某个项目，请写入 AGENTS.md。

如何并行运行多个 Hermes 实例？

使用 profiles。每个 profile 都有各自独立的 HERMES_HOME、配置、memory、会话和 gateway PID：⁶

hermes profile create work --clone
hermes profile use work                 # Sticky default
hermes -p work chat -q "..."            # One-off without switching
hermes profile alias work --name h-work # Wrapper script

Hermes 支持本地 LLM 吗？

支持，可通过自定义端点路径实现。Hermes 可与任何兼容 OpenAI 的服务器配合使用，包括 Ollama、vLLM、SGLang、llama.cpp/llama-server、LM Studio、LocalAI、Jan，或您自行搭建的服务器。² 各服务器的配置方法请参阅自定义与自行托管的端点。

为什么启动横幅显示的工具数量少于指南所述数量？

本指南引用的47个工具和20个 toolsets 来自上游架构注册表，代表 Hermes 在所有 toolset 中提供了源代码的工具总数。实际运行的安装版本会在横幅中显示更少的数量（本指南使用的参考安装显示28个工具），因为 Hermes 启动时仅启用默认的 toolset 集合。许多 toolsets 都需要主动启用：消息 gateway 适配器、浏览器自动化、较重量级的抓取技术栈以及若干专用集成，都必须先在 ~/.hermes/config.yaml 的 toolsets: 下明确列出才会加载。注册表总数表示“启用后可用的工具”，横幅总数则表示“当前 profile 实际加载的工具”。使用 hermes tools --list 可查看哪些 toolsets 已启用，以及哪些虽可用但处于禁用状态。运行时可通过 /tools enable <name> 和 /tools disable <name> 切换各个 toolset（禁用操作会触发会话重置，以便智能体按照新的工具结构重建工具清单）。

主提供商发生故障时，Hermes 如何处理模型回退？

在 config.yaml 中配置 fallback_model 块：²

fallback_model:
  provider: openrouter
  model: anthropic/claude-sonnet-4

主模型失败时（例如触发速率限制、服务器错误或身份验证失败），Hermes 会在会话过程中切换至后备模型，同时保留对话历史记录。每个会话最多触发1次。

智能体能否随着时间推移改进自己的 skills？

可以——这正是 Hermes Agent 的“自我改进”能力。智能体可以通过 skill_manage 工具创建、更新和删除 skills。找到一套并非显而易见的工作流程后，它会将相应方法保存为 skill，以便日后复用。¹¹ 完成复杂任务（调用工具5次以上）、遇到错误并找到可行路径、您纠正其处理方式，或发现不易掌握的工作流程时，智能体会创建 skills。

是否提供 IDE 集成？

是的——Hermes 可以作为 ACP（Agent Client Protocol）服务器运行，供 VS Code、Zed 和 JetBrains 使用：⁶

pip install -e '.[acp]'
hermes acp

更新日志