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

简而言之： Hermes Agent 是 Nous Research 推出的开源自我改进型 AI agent。它既可作为 CLI 运行，也可作为多平台消息 gateway 使用；它会在磁盘上存储持久身份和长期记忆，汇集能够在使用过程中持续改进的 skills，并可与任何兼容 OpenAI 的 LLM 提供商协同工作——包括 Nous Portal、OpenRouter、Anthropic、GitHub Copilot、z.ai、Kimi、MiniMax、DeepSeek、Qwen Cloud、Hugging Face、Google、xAI/SuperGrok，或您自行托管的端点。¹²¹⁹ 当前版本为 v0.21.7（标签 v0.21.7，发布于2026年10月11日），这是 v0.21 系列的第5个汇总补丁，也是首个通过项目全新稳定版发布流水线交付所有渠道的版本；v0.21.7 的新增功能介绍了具体变更，后续发布章节则按时间从新到旧排列。⁵⁶ 对大多数新用户而言，最棘手的部分是提供商身份验证：在标签 v0.21.6 中，Hermes 的静态选择器列表内置了39个提供商，并会根据41个捆绑提供商插件自动扩展该列表，此外还支持自定义端点；身份验证分为3条不同路径（.env 中的 API 密钥、通过 hermes model 使用 OAuth，或在 config.yaml 中配置自定义端点）。⁵³⁵⁵ 首先需要掌握的是身份验证模型——其他一切都取决于最终解析到的提供商。

Hermes Agent 是一套完整的 agent 运行时，而非简单的聊天封装。它可以读取文件系统、在沙盒后端执行命令、抓取网页、生成 subagents、运行预定的 cron 任务、通过单个 gateway 进程与 Telegram/Discord/Slack/WhatsApp/Signal/Email 通信，并根据经验创建自己的 skills。¹ CLI 是构建在 run_agent.py 对话循环之上的终端 UI；gateway 则是一个长期运行的进程，负责将消息平台发来的消息路由至同一对话循环。³

Hermes 的普通用法与专家级用法之间，关键在于以下5个系统。 掌握它们，Hermes 就能成为事半功倍的利器：

1. 提供商解析：身份验证流程如何映射到 API 调用
2. 配置层级：config.yaml + .env + auth.json + SOUL.md + AGENTS.md
3. 工具与 toolset 系统：agent 能够执行哪些操作，以及各平台如何限制这些能力
4. Skills 系统：由 agent 创建并持续演进的程序性记忆
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，但其余内容由 agent 自行维护。⁴
• 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、skills、上下文文件和工具指南构建系统提示词（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 数据库中³

理解此循环至关重要，因为每项功能——个性、记忆、skills、压缩、回退——都依附于其中某个阶段。阅读配置键并思考其用途时，答案通常是：“它用于调节上述循环的第1、2、3或4阶段。”

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

目录结构就是系统本身。 Hermes 将所有内容存储在 ~/.hermes/ 下（非默认 profiles 则存储在 $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)

上述每个文件各司其职，彼此互不重叠。如果想知道“TERM_0 将 X 存储在哪里”，答案就在这些位置之中。

v0.21.7 的新变化（10月11日汇总）

Hermes Agent v0.21.7（标签为 v0.21.7，日期为2026年10月11日，于10月12日发布）是当前版本，也是 v0.21.x 系列的第5个小型汇总版本。v0.21.6 仅发布了标签和 Docker 镜像，而此次版本覆盖了所有渠道：桌面应用（macOS Apple silicon 和 Windows）、Microsoft Store 和 MSIX 构建版本、安装程序、Docker 以及 Hermes Cloud。自 v0.21.6 以来，共有“740个非合并提交”，涉及“4,156个变更文件”“204个已合并 PR”和“69个已关闭问题”（GitHub 的比较结果将合并提交计算在内，共计777个提交）。精选说明再次推迟至 v0.22.0。以下是该版本记录并经标签源码核实的内容：⁵⁶⁵⁷

• 源码安装现在会跟随带标签的版本。 在官方仓库的检出中运行 hermes update，现在会更新至最新发布的 vX.Y.Z 版本及其对应的确切提交，而非跟随 main 上的每个提交。如果安装版本已经领先于最新发布版本，则会保持不变，直至下一个版本发布；解析器也绝不会根据推测将检出回退：若无法确定版本关系（历史记录较浅或无法访问 GitHub），则保留当前 HEAD。若要继续跟随每个提交，请运行 hermes update --set-channel main；--channel <name> 可仅针对单次运行覆盖该设置（stable 和 canary 选择已发布版本，main 选择分支顶端）。此选择按安装记录在 config.yaml 的 update.installs 下，以根据安装路径生成的 ID 为键（运行 hermes update --install-id 可显示该 ID），因为同一个 ~/.hermes 可以同时服务于主机安装、Docker gateway 和桌面应用。分叉仓库、镜像和本地路径来源仍会跟随 main；Store、MSIX 和捆绑式桌面安装不受影响。
• 桌面应用提供相同的切换选项。 对于源码安装，“设置 ▸ 关于 ▸ 更新”中新增了“更新渠道”一行，可选择“稳定版本”或“每个提交”，更新对话框也会显示当前所在的渠道。
• 恢复会话时会保留推理内容。 在运行 hermes chat --resume 后，以及上游验证签名思考块的下一次 gateway 轮次中，这些思考块会继续重放；Bedrock Converse 推理模型也不再拒绝恢复的会话。若上游拒绝某个签名，系统会为其生成指纹，并在重建请求时将其过滤掉，而不会中断会话。
• 在某些防火墙之后，更新不再失败。 使用 main 的安装不再获取可能被区域防火墙以 403 响应拦截的版本记录。设置 GitHub 令牌时（GITHUB_TOKEN 或通过 gh auth login 登录），稳定版本检查会使用该令牌；若令牌被拒绝，则以匿名方式重试；遇到 GitHub 速率限制时，也会如实报告速率限制，而非显示“没有版本”。
• Holographic 移出核心代码树。 目前捆绑的记忆提供商仅有 ByteRover 和 RetainDB；Holographic 改为从插件目录安装（社区层级，requires_hermes: ">=0.21.5"），自动迁移机制会像处理其他6个提供商一样处理它。请参阅外部记忆提供商。
• 插件目录从493项增至552项；根据版本说明，新增内容包括 memory-shield、command-ledger、Memoria、Model Router、wyoming-voice-bridge、codex-account-switch 和 redline。提供商插件仍为41个目录，静态选择器仍为39行。
• 此外，根据版本说明： 插件可以运行内置桌面操作（ctx.runAction，例如 view.showBrowser），并通过宠物气泡播报消息（ctx.pet.say）；Codex 请求由核心发出，因此插件永远不会持有令牌；会话中途安装的 skill 无需重新构建提示词即可供模型使用；Krea 2 Medium Turbo 成为新付费订阅者的默认图像通道，当托管式 Krea 拒绝请求时则回退至 FAL；桌面更新速度更快；固定版本安装只检出指定的固定版本；压缩标记会发送至 Relay（agent/relay_compaction.py 会将 hermes.compaction 记录作为 NeMo Relay 标记发出）。

更新方式：桌面应用会自行更新，Store 安装则通过 Store 更新；CLI 可使用 hermes update 或安装程序的一行命令；Docker 和 Hermes Cloud 拉取 nousresearch/hermes-agent:stable（或 :latest）。⁵⁶

v0.21.6 新增内容（10月8日汇总版）

Hermes Agent v0.21.6（标签 v0.21.6，2026年10月8日）是10月8日至10月11日期间的当前版本，也是 v0.21.x 系列第4个精简汇总版，并首次由项目的新稳定版本发布流水线构建：“一次尝试引用、一个经过测试的 Docker 镜像，以及发布时的凭证标签”。此次仅发布标签、GitHub 版本和 Docker 镜像；桌面应用、Termux 软件包和 Microsoft Store 版本将维持当前版本，直至下一个捆绑版本发布。自 v0.21.5 以来的变更规模创下新高：涉及“8,867个非合并提交”“8,342个变更文件”“2,106个已合并 PR”和“3,027个已关闭问题”（GitHub 比较结果计入合并提交后为9,180个提交）。精选说明再次推迟至 v0.22.0。发布说明列出了尚未记录的内容；以下各项均已根据该标签的源代码核验：⁵⁴⁵⁵

• 说话时实时转写。 stt.streaming: true 可在 CLI、TUI 和桌面端于话语尚未结束时流式显示部分文本。此功能默认关闭，支持 openai、xai 和 elevenlabs STT 提供商（stt.streaming_model 指定唯一支持话语中途增量更新的模型；OpenAI 对应 gpt-live-transcribe），流式处理失败时会回退到文件路径方案。
• 语音轮次拥有独立的模型槽位。 auxiliary.voice_chat 可将语音轮次（CLI 语音输入、桌面端或 TUI 语音对话、消息平台语音留言）路由至比会话主模型更快的模型，默认设置为 reasoning_effort: none。该路由在系统提示词构建完成后绑定，并会在内存同步和后台审查前解除。如果某一轮次无法满足语音模型的压缩阈值，则仍使用主模型。请参阅辅助模型。
• 第三方插件可在进程外运行。 plugins.isolation: host（默认为 in_process）会按 profile 将通用插件加载到独立的插件宿主进程中，并拒绝所有其他会在进程内导入用户代码的路径（类别提供商、模型提供商 profile、仪表板插件 API）；捆绑插件仍在进程内运行。插件即使挂起或崩溃，也只会导致其宿主进程退出，不会拖垮 gateway。请参阅插件系统。
• 另外4个内存提供商移出核心代码树。 Honcho、Mem0、OpenViking 和 Supermemory 现在通过插件目录安装（社区层级，由各自厂商维护），与 Hindsight 采用相同方式；捆绑提供商则包括 ByteRover、Holographic 和 RetainDB。v0.21.5 引入的自动迁移现已覆盖全部8个名称。请参阅外部内存提供商。
• 插件兼容层已移除。 hermes_cli/plugin_compat.py 现为空操作存根，COMPAT_MANIFEST.md 和兼容垫片已被删除，plugins.allow_deprecated_imports 也不复存在；仍导入拆分前路径的插件将无法导入。请参阅插件系统。
• hermes status 优先显示摘要。 默认输出中，每个组件占一行；--full（别名 --all）会打印所有部分，--deep 则会运行耗时较长的检查。发布说明还提及 --short 标志，但该标签对应的解析器并无此选项，因为摘要已是默认输出。
• 可插拔的分层语言包。 display.language 接受由捆绑目录（该标签下有17种）、profile 的覆盖目录或插件语言包提供的任何 id。hermes config set display.language <id> 会先发现插件，因此刚安装的语言包也能立即生效。核心字符串与 TUI 字符串以不同层分别提供（locales/<lang>.yaml 和 locales/<lang>.tui.yaml；该标签下有16个 TUI 语言包）。请参阅本地化。
• 新增3个提供商插件：lmstudio、solstice 和 tencent-tokenhub，使 plugins/model-providers/ 下的目录数量从38个增至41个；静态选择器列表仍为39行。Nous 和 OpenRouter 选择器新增 GPT-6.1 Sol（含 -pro 变体）、Claude Sonnet 5.5 和 Claude Haiku 5.5，openai-api 和 Bedrock 列表也新增 GPT-6.1 Sol。本地模型方面：hermes model 可直接列出 Ollama、LM Studio 和 Ollama Cloud 模型；根据发布说明，捆绑的本地运行时还在 Linux x64 和 arm64 上新增 llama.cpp CUDA 构建（llamacpp-cuda）。
• 审批规则新增2种检测机制。 如果 curl 或 wget 上传命令（-d、-F、-T）携带名称疑似机密信息的变量或凭据文件，或通过管道将凭据文件传给此类命令，系统会将其标记为可能的数据外泄；命令中若含不可见或双向 Unicode 控制字符，则会被标记为可能的混淆行为，因为您批准时看到的内容可能与实际运行的内容不同。
• Cron 可应对存储不可写的情况。 磁盘已满或挂载为只读（ENOSPC、EROFS、EACCES）时，cron 存储只会降级一次，不再每隔60秒发出警告；重新探测的频率最多为每分钟一次，hermes cron status 和 hermes doctor 均会报告此状态（该版本还新增了主频道警告）。
• Discord 设置流程会检查机器人令牌并输出邀请链接，其中包含适配器所需的权限位；若 Message Content Intent 仍处于关闭状态，也会特别提示，因为在此情况下 Discord 会拒绝机器人的连接。请参阅消息 gateway。
• 其他内容：新增 activate.fish，即 ./activate 开发环境脚本的 fish 对应版本；根据发布说明，还新增了统一的 Kanban 工作流定义。此外，发布说明中列出但未随此版本桌面构建交付的功能包括：将收藏和置顶模型显示在桌面端选择器顶部、在订阅用量触及上限前显示用量标记、说明限流原因及截止时间的提供商速率限制通知、审查窗格中的差异范围选择器，以及跟随轮次启停的保持唤醒功能。

安全修复（发布说明中均注明了贡献者）：修复了由 Tenable Research 报告的4个仪表板身份验证问题——伪造的 X-Forwarded-For 标头可能重置密码登录速率限制并绕过每 IP 上限；未经身份验证的登录请求可能向身份验证审计日志写入无限长度的值；公开的 /auth/ 路由未限制请求体大小；原生登录可能将登录代码发送至非环回重定向地址，从而导致会话被接管。自动 git 调用（会话工作区快照、subagent worktree、kanban、worktree 清理、hermes -w）可能在首次提示前运行由不受信任仓库自身配置定义的 clean、smudge 或 process 过滤器程序；现在，如果无法消除这些过滤器的影响，相关操作将被拒绝。此外，电子邮件 From 标头中带引号的显示名称可能冒充允许的发件人通过电子邮件允许列表；现在会先展开标头，再使用 parseaddr 解析（GHSA-rxqh-5572-8m77）。任何仪表板、gateway 或电子邮件部署都应将此标签视为与安全密切相关的升级。⁵⁴⁵⁵

更新方式：运行 hermes update 或安装程序单行命令；Docker 和 Hermes Cloud 拉取 nousresearch/hermes-agent:stable（或 :latest）。⁵⁴

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

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

• Hindsight 内存移出核心代码树。 捆绑的 Hindsight 提供商和 hermes-agent[hindsight] pip extra 已被移除；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 仍然有效。v0.21.6 移除了兼容层及此配置键（请参阅v0.21.6 新增内容）。

更新方式：运行 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 个已关闭 issue”。按提交数计算，这是项目历史上标签间变更规模第二大的版本，仅次于 v0.21.1 的 5,139 个提交；按已合并 PR 数计算，则是规模最大的版本。经过整理的完整说明再次推迟，原文如下：“此时间窗口的完整精选发布说明将随 v0.22.0 一同发布，涵盖从 v0.21.0 开始的所有内容”，并且“此时间窗口内的任何内容都不会遗漏。”发布说明确实列出了尚未记录的内容，以下各项均已对照该标签的源代码核验；若某项影响本指南中的既有章节，则会在条目内提供链接。⁵⁰⁵¹

• 每台主机仅运行一个 gateway，Desktop 采用连接而非重新启动。 规则是每台主机、每个操作系统用户只能运行一个 hermes serve 和一个 hermes gateway run，两者各自对所有 profile 进行多路复用——这一规则由新增的主机级单实例层强制执行：胜出进程在整个生命周期内持有主机锁，同时通过包含 (pid, createTime) 的会合记录，使第二次调用能够确认锁的所有者仍是同一存活进程，从而连接到该进程，而不是绑定第二个端口。系统始终通过证据判定状态是否过期，绝不主观假定；Desktop 应用也从自身一侧采用相同机制，连接到主机上正在运行的后端，而不是再启动一个实例。消息 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 系统新增了“固定 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：字体设置、一键更新引擎及卸载插件。 Settings 新增按 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 个社区插件在该标签中均已收录于目录。插件系统介绍了详细信息。⁵¹
• 此外还有大量修复，涉及 profile/多路复用隔离、cron、kanban、Desktop 和 state.db；发布说明仅将它们作为一个类别提及，完整整理记录将由 v0.22.0 给出。⁵⁰

插件兼容层的回退在此时间窗口内仍未落地。 COMPAT_MANIFEST.md、compat_manifest.json 和兼容垫片在 v2026.9.21 中仍然存在；此时间窗口内对 hermes_cli/plugin_compat.py 的改动仅包括进程级扫描缓存（多路复用 gateway 对每个提供服务的 profile 只发现一次插件；在启动路径上，重新解析每个插件的源代码会给每个 profile 增加约 0.4 秒开销），以及 Windows 上使用 POSIX 格式的命中路径（#112576）——日期门控和字面量布尔值应急开关均未改变，因此 plugins.allow_deprecated_imports: true 仍可让受影响的插件继续加载。插件系统中的兼容性说明框介绍了当前状态。⁴²

更新方式没有变化：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 会自动更新到最新的发布标签，而远程 gateway 的登录修复需要借此抵达这些 agent。（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（如果清单文件消失，则会提前生效），因此受影响的外部插件现在会在加载时被禁用，并显示红色通知。尚未发生的是：真正删除旧导入路径的回退。COMPAT_MANIFEST.md、compat_manifest.json 和兼容垫片在该标签中仍然存在——截至9月22日，在 v2026.9.21 和 main 上也依然如此——这正是 plugins.allow_deprecated_imports: true 仍可作为应急开关的原因：只要加载器获准继续执行，旧路径仍能解析。这里有两个容易踩坑之处：该键必须是字面量 YAML 布尔值（代码仅接受布尔值 True；按照源代码注释“Literal boolean only”，"true" 或 "false" 之类的带引号字符串会被视为未设置）；一旦回退落地，该开关便会失效，因为相关路径本身将被删除。插件系统中的兼容性说明框介绍了当前状态。⁴²⁴⁹

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、导出或洞察功能整体失效（异常记录会显示为 ?，同时给出标明相应会话的警告）；会话绝不会绑定或读取其他 profile 的数据库；只读打开也不再获取写入锁，因此在繁忙 gateway 后运行的一次性 hermes，等待后失败的耗时从4至20秒缩短至0.01秒。⁴⁸
• 强化多 profile 隔离。 自 v0.19.0 起，本指南一直在转述项目方的主张：profile 路由可让每个 profile 拥有“完全隔离的配置、skill、内存和密钥”。到了 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:），密码只在填写时解析；外部密码管理器会保持锁定，直至您为当前会话将其解锁；主密码“绝不会成为 tool 参数，绝不会进入 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；连接器工具（Gmail、Linear、Notion 等）则可通过 tool_search 搜索。桌面端的引导式首次启动由 HERMES_GUEST_ONBOARDING=1 控制，而且只有字面值 1 才会启用：桌面端自身的测试明确验证，'true'、'0' 和空值均不会开启此功能；启动决策还会写入所生成后端的环境中，确保继承的值绝不会意外渗入。请参阅 Nous Tool Gateway。⁴⁸
• 桌面端后端生成风暴已成为过去。 Bot Mode 过去会在启动时以及每次 roster 轮询时，为每个 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个“延迟迁移”公共名称；解析这些名称时，每个进程中的每个名称只会发出一次 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]；这两个命令早在此时间窗口之前便已存在，只是此前未在本文档中说明。⁴⁴
• 委派现在会如实处理后台工作。 以下是 delegate_task 的6项可靠性改进，均直接核对了该标签版本的委派工具源代码。（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 选择器、标记，以及与布局相关的计算样式，让代理可以在源代码中准确找到该元素，而不必仅凭图片猜测（标记离开页面前，会对密码、隐藏值及类似密钥的属性进行脱敏）。较大的批次会按页面区域分组，因此二十多条评论会归并为少量工作单元，通常分别涉及不同文件——这正是将其安全分发给并行工作器的关键。除此之外，还新增了结构化会话控件和会话自动化控件、拖动创建会话功能、用于导入其他编码代理记录的会话导入视图、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 会将每次运行的输出传递至下一次，让监控程序能根据已报告的内容进行去重；每项作业都有持久的记事本式 scratchpad；在没有任何变化时，监控模式作业会完全跳过 LLM；可以为每项作业固定推理强度；cron 输出还可以进入机器人的规范 Bot Chat，并由机器人真正作出响应。计划任务（Cron）章节现已记录各项机制在对应标签版本中的具体情况。³⁵³⁷
• 实时 subagent 编排。 delegate_task 新增控制操作：列出正在运行的子代理、在执行途中引导某个子代理调整方向，或者提前停止并保留部分结果。子代理输出可以根据 JSON schema 进行验证，结果中会显示每次委派的成本；默认值也提升至每个 subagent 250次迭代以及10个并发子代理（这是 v0.19.0 中取代 max_async_children 的统一上限）。³⁵³⁸
• MCP 指挥中心。 MCP 服务器与目录合并到同一个桌面页面中，支持通过拖入方式“粘贴任意内容”进行导入；后台健康检查会在工具调用失败前提醒您重新授权；还提供全体服务器的成本与用量叠加视图（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 与一轮模型目录更新。 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。模型目录则新增 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，无需等待新版本即可修正任意模型的 context window 或定价；provider 现在也能以通过 pip 安装的软件包形式发布，并经由 entry point 自动发现。此外，统一的选择保护注册表会在所有选择器界面发出警告，提醒某个模型是否会使用您的数据进行训练。³⁵³⁶
• 全方位安全加固。 写入受保护的代理指令文件（AGENTS.md、skills、memory stores）现在始终需要审批，因此遭到提示词注入的代理无法悄然改写自身的长期指令；一次深入的敏感信息脱敏排查修补了终端错误、.env 读取、checkpoint 和 ACP 日志中的机密泄露缺口；审批系统新增对 Windows 破坏性命令的识别；借助稳定的 TCC 签名身份（hermes desktop --setup-tcc-identity），macOS 权限授权可在更新后继续保留；Blender MCP 目录条目及其 skill 则因上游遭到入侵而被移除。有关对应标签版本的详细信息，请参阅安全加固。³⁵³⁹
• Gateway 日趋成熟。 Slack 新增原生实时卡片（真正的流式回复，以及可选启用的计划/任务卡片）和出站链接预览抑制功能；Telegram 新增内联选择器，可通过 @botname 搜索每条命令和每项 skill，从而绕过 Telegram 的命令菜单数量上限；relay 通道进一步成熟（原生插件初始化、支持草稿流式传输的实时卡片操作、会话跨度分段，并恢复语音消息 STT）；gateway 控制套接字让集群使用方可以查询 gateway，也让更新程序能够优雅地暂停它，而不必终止整个进程树；当看门狗触发时，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 新增功能是这一整段时期的精选记录（该版本确认这些发布窗口“are fully documented here”）。下方各区块仍作为发布当时的逐标签记录保留——它们注明了每个标签具体引入的内容，而精选说明则将这些内容合并呈现。^58233035

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 日趋成熟：新增群组房间线程、可折叠对话摘要、斑点脸头像，以及支持拖放的 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 Keychain 提示。³⁰
• 选择器新增多款模型：GLM-5.3-Flash、免费的 MiniMax M3，以及 MiniMax H3 Max video。³⁰
• 为 web_search/web_extract 加入 TTL 结果缓存，并支持带词干提取的多查询 tool_search。³⁰
• 精简尾部压缩现已成为默认设置——下方的上下文压缩部分记录了该标签发布时的配置。³⁰³¹
• 终端后端现已支持插件化——请参阅终端后端。³⁰³²
• 更新程序和设备群如实反馈状态：更新程序会通过控制套接字暂停 gateway，而非终止整个进程树；通过镜像或软件包管理的安装则会拒绝不安全的原地更新。³⁰
• Cron 新增持久事件确认并提供更清晰的代码版本偏差失败信息，同时加入 Slack 链接展开控制和共享 Docker 容器身份。³⁰

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

v0.19.0 新增内容（Quicksilver 版本）

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

• 所有平台的首个 token 响应速度均提升约 80%。 CLI、gateway、TUI、桌面端和 cron 的冷启动提交至分发耗时均从约 4.3 秒降至约 0.9 秒——Discord 能力检测已移出关键路径；对于已知的非 Ollama 提供商，将跳过 Ollama 探测；代理初始化中的阻塞操作也已移除。感知延迟同样得到专项优化：推理模型现在默认实时流式显示思考过程（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> 会将拒绝原因告知代理，促使其调整方案；重新加入并支持规则键的插件 pre_tool_call 批准操作，则可将工具调用升级为人工审批。⁶⁰
• 终端账单管理：/subscription 和 /topup。 无需离开终端即可管理 Nous Portal 套餐——查看当前套餐和剩余额度，准确预览升级费用或降级生效时间，并在应用变更后撤销操作。桌面应用也新增了相应的账单设置选项卡。⁶⁰
• 实时查看子代理工作；已完成的答案永不丢失。 delegate_task 分发任务后会返回实时对话记录文件，子代理一经启动即可使用 tail -f 查看——每个工具调用、结果和流式回复都会写入日志，每个子代理各有一份易于阅读的记录。后台委派任务的完成结果可在重启后保留；最终 gateway 响应会记录在 state.db 的交付义务账本中。如果 gateway 在发送途中崩溃，响应将在下次启动时重新交付。max_async_children 配置选项已弃用，统一委派并发上限将取而代之。⁶⁰
• 一个 gateway，多个 profile。 单个复用型 gateway 可共享一个机器人令牌，并将特定服务器、频道或线程路由至不同的 profile——每个 profile 都拥有完全隔离的配置、skills、内存和密钥——同时支持通过 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日）以“判断”为名：代理不再直接宣称成功，而是验证自己的工作；同时，集成推理过程也真正做到了可供检查。此版本还清空了全部 P0/P1 待办事项——在 12 天内解决了约 692 个最高优先级项目。²²

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

如果从 v0.17.x 升级，此版本不会破坏 CLI。最值得升级的功能包括完成契约（可自行验证的目标）、支持检查集成过程的一流 MoA，以及用于捕获 skill 的 /learn。

v0.17.0 的新增功能（触达版本）

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（100万上下文）、anthropic/claude-fable-5、laguna-m.1、nemotron-3-ultra 和 grok-composer-2.5-fast（通过 xAI OAuth 使用的 Cursor 模型，20万上下文）。xAI 默认模型已改为 grok-build-0.1，Anthropic 自适应模型现在遵循现代思考协议（绝不会发送 reasoning 字段）。²¹
• 桌面端和仪表板。 桌面端新增后台子智能体，可通过实时“监视窗口”流式展示委派活动（delegate_task(background=true)），还新增 Composer 模型选择器、可重新绑定的键盘快捷键、原生操作系统通知、各线程独立的 Composer 草稿、VS Code Marketplace 主题，以及日语和繁体中文界面。仪表板新增完整的 profile 构建器（无需编辑 config.yaml 即可配置模型、skills 和 MCP）、全局 profile 切换器、经过重构且带安全扫描功能的 Skills Hub、Automation Blueprints（适用于表单、斜杠命令、对话和文档的参数化模板），以及位于 OAuth 访问控制之后、会返回 401 的安全登录机制。²¹
• Skills 和工具。 image_generate 现在不仅能从零创建图像，还能通过所有受支持的图像提供商编辑和转换源图像；memory 工具新增 operations 数组，可在单次调用中以原子方式批量添加、替换或移除内容；新的 simplify-code skill 会执行由 3 个智能体并行完成的审查和清理流程，并通过切斯特顿围栏风险级别进行把关；布尔值 write_approval 则取代了三态 write_mode。²¹
• 架构。 后台子智能体会立即返回句柄，并将其结果作为新一轮对话重新送入；MCP 信息征询处理程序支持在工具调用过程中请求确认，较晚连接的 MCP 工具会在对话轮次之间公开（且可安全缓存）；cron 改为可插拔的 CronScheduler，并新增 Chronos 托管 cron 提供商；新的 Managed 作用域（/etc/hermes）允许管理员锁定用户无法修改的配置，此外还新增用于多 gateway 拓扑的 Gateway-Gateway 中继。²¹
• 新增命令。 /version、/billing（交互式终端计费）、hermes photon login（iMessage 身份验证）和 hermes curator run --consolidate——整合现改为选择启用，因此常规后台整理不会消耗任何令牌。²¹
• 安全性。 v0.17.0 修复了绕过 shell 转义拒绝列表的漏洞；缺少审批模块或自有策略 gateway 适配器时默认拒绝执行；净化 cron 作业脚本子进程的环境；隐去请求调试转储中的机密信息；检查 MCP stdio 配置中的数据外泄模式；并升级 urllib3 和 PyJWT 以修复 CVE。²¹

如果从 v0.16.x 升级，这些变化都不会破坏 CLI；只是在同一个智能体周围新增了渠道、模型和交互界面。无需中继的 iMessage、官方 WhatsApp 适配器以及管理员 Managed 作用域，是此次升级最值得关注的理由。

v0.16.0 的新增功能（界面版本）

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 会话，以及使用跨 profile 的 @session 引用关联这些会话。桌面界面还通过类型化 i18n 层提供完整的简体中文翻译（display.language；英语仍为默认语言）。²⁰
• 浏览器管理面板。 本地 Web 仪表板已从状态视图升级为完整的管理面板：包括带启用/禁用开关的 MCP 目录、凭据管理、Webhook 和钩子创建、内存配置、gateway 控制，以及提供更新前检查和一键 Debug Share 的 System 页面。新的 Channels 页面允许通过浏览器配置 gateway 的所有消息平台（Telegram、Discord、Slack 等）。身份验证现在支持插拔：用户名和密码登录、通用的自托管 OIDC 提供商、用于注册自托管 OAuth 客户端的 hermes dashboard register，以及刷新令牌会话轮换。²⁰
• 新增 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（100万上下文，原生 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 在被请求之前不会进入索引。NVIDIA/skills 现与 OpenAI、Anthropic 和 HuggingFace 一同成为 Skills Hub 默认信任的 tap。MCP 和插件工具新增渐进式（限定作用域的）工具公开机制；此外还修复了一个 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 的新增功能（基础版本）

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 可以在下一轮对话之前显示每轮的文件变更摘要和语言服务器语义诊断，使其更接近循证驱动的智能体工作方式。
• 桌面和媒体工具能力进一步扩展。 对于非 Anthropic 提供商，computer_use 可通过 cua-driver 工作；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 issue或Discord讨论串中——它会以纯文本形式汇总您的完整设置，同时隐去所有敏感信息。⁸

手动安装

如果需要完全掌控安装过程——例如自定义Python版本、指定extras或集成Nix/NixOS——上游安装指南提供了循序渐进的手动操作说明。⁷ 以下是可通过uv pip install -e ".[<extras>]"组合安装的主要可选extras：

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

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

这是因为在Android上安装.[all]时，voice extra会引入faster-whisper，后者依赖的ctranslate2 wheel并未针对Android发布。⁷

身份验证与提供商

在标签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的免费层现已拒绝来自其自有客户端之外的匿名流量，无密钥的opencode-free提供商已于9月18日移除。⁵³在标签v0.21.6中，静态列表仍有39行，目录数则为41：已有静态行的lmstudio和tencent-tokenhub新增了插件目录，而没有静态行的solstice则通过自动扩展加入。⁵⁵除此之外，还有自定义端点和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 自身的凭据存储，而不是将 token 复制到 ~/.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 设备代码登录

token 类型至关重要。 Copilot API 不支持经典 Personal Access Token（ghp_*）。支持的类型包括 OAuth token（gho_*）、细粒度 PAT（具有 Copilot Requests 权限的 github_pat_*）以及 GitHub App token（ghu_*）。如果 gh auth token 返回 ghp_* token，请改用 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 会探测多个端点（全球、中国及 coding 变体），找出能够接受您的 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 token，便于在不修改代码的情况下，将速率限制分摊到多个密钥上。⁶ 旧版 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将Hermes指向http://localhost:1234/v1。

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

命名自定义provider

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

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菜单中选择命名自定义provider。²

可插拔provider架构（v0.13.0+）

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

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

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

上下文长度检测

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

• 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使用多来源解析链检测上下文窗口：配置覆盖→自定义provider的逐模型设置→持久化缓存→端点/models→Anthropic /v1/models→OpenRouter API→Nous Portal→models.dev（由社区维护、涵盖3800多个模型的注册表）→后备默认值（128K）。²该系统能够识别provider，因此同一模型可能因服务它的provider不同而具有不同的上下文限制（例如，claude-opus-4.6通过Anthropic直连时为1M，但通过GitHub Copilot时为128K）。²

智能模型路由：provider轮换与故障转移

Hermes不会将您局限于单一provider上的单一模型。智能模型路由是一组 用于确定实际由哪个provider和模型处理特定请求的机制：凭据池在多个密钥之间 分摊负载；主模型故障时，已配置的后备模型会接管；下方的辅助槽位则会将次要任务 路由到更便宜的模型，而不受主模型影响。²⁶请将这三项结合配置——这决定了agent 是因速率限制而停滞不前，还是能够继续工作。

凭据池。如果同一provider有多个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

后备机制会在会话中途切换模型和provider，同时保留对话内容。每个会话最多触发一次。²支持故障转移的provider包括：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 规约制定器/分解器系列，以及自 v0.21.6 起支持的语音轮次（auxiliary.voice_chat，默认使用更快的模型并设为 reasoning_effort: none 来执行语音轮次；如果请求无法满足语音模型的压缩阈值，则继续使用主模型）。⁴³⁴⁵⁵ 默认情况下（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，然后选择“配置辅助模型”，即可通过交互式选择器逐项设置。³⁴

"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

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

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:键确定。英语仍为默认语言，也是翻译尚未覆盖的所有字符串的事实来源。v0.21.6支持可插拔语言：display.language接受由17个内置目录、profile的叠加目录或已安装插件语言包提供的任意id；hermes config set display.language <id>会先执行插件发现，因此刚安装的语言包也会被接受。核心字符串与TUI字符串分别位于不同层（locales/<lang>.yaml和locales/<lang>.tui.yaml；该标签包含16个TUI语言包）。⁵⁵

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的允许列表、向其主机发送凭据、将其保险库机密交给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更强大，因为它支持同时按日志级别、会话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调用、工具分派、会话生命周期、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 中定义快捷命令，将短名称作为较长 prompt 的别名：⁹

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）——将当前聊天设为平台 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。⁹

工具与 Toolsets

Hermes 内置了丰富的工具注册表，涵盖网页搜索、浏览器自动化、终端执行、文件编辑、记忆、委派、RL 训练、消息传递、Home Assistant 集成等功能。¹⁰工具按逻辑组织为不同的 toolsets，可针对各个平台启用或禁用。

高层类别

常见的 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 capabilities、禁止权限提升、限制 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）， 因此某个不稳定的子任务不会耗尽整个运行过程的容错额度。由于看板具备 持久性，群体在重启后仍可继续运行——工作进程会重新连接，并基于同一状态恢复工作。

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

Skills 系统

Skills 是代理可在需要时加载的按需知识文档。它们采用渐进式披露模式，以尽量减少 token 用量，并兼容 agentskills.io 开放标准。¹¹

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

渐进式披露

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)

只有实际需要某项 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.

条件激活

Skills 可以根据可用工具决定显示或隐藏。这对于后备 skills 最为实用——它们是免费的本地替代方案，仅应在高级工具不可用时出现：¹¹

示例：内置的 duckduckgo-search skill 使用 fallback_for_toolsets: [web]。设置 FIRECRAWL_API_KEY 后，web toolset 即可使用，代理会使用 web_search，而 DuckDuckGo skill 则保持隐藏。若没有 API 密钥，DuckDuckGo skill 会自动作为后备方案出现。¹¹

代理管理的 Skills

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

代理会在以下情况下创建 skills：¹¹ - 成功完成复杂任务后（调用工具5次以上） - 遇到错误或走入死胡同，并最终找到可行路径时 - 用户纠正其处理方法时 - 发现复杂工作流时

操作：¹¹

Skill Hub

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

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 taps（无需设置即可浏览）：openai/skills、anthropics/skills、huggingface/skills、NVIDIA/skills、garrytan/gstack。claude-marketplace 来源已在 v0.20.0 中移除；browse-sh 在来源列表中取而代之。¹¹⁵⁹

安全扫描

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

信任级别：¹¹

对于社区 skills，--force 可以绕过非危险的策略阻止，但无法绕过扫描给出的 dangerous 判定。¹¹

外部 Skill 目录

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

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

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

固定加载的 Skills：skills.auto_load（v0.21.4 时间窗口）

在 config.yaml 的 skills.auto_load 下列出的 skill 名称会被固定加载，并在每个新会话中完整载入——无论是 CLI、TUI、gateway、cron 还是 API：⁵¹

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

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

持久记忆

Hermes 具备容量受限、经过筛选且可跨会话保留的记忆。代理的记忆由两个文件组成，均存储在 ~/.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 阶段新增了两项功能，均已在标签 v2026.9.21 中验证。第一项是时间范围：发现参数接受 after（会话开始时间的包含式下限）和 before（不包含式上限）。二者均可使用 ISO 日期/日期时间——仅提供日期时，表示当天 UTC 零时——也可使用相对时长（7d、24h、2w）。这些参数仅适用于明确指定时间范围的查询；sort 仍然只是排序偏向，而非范围限制。第二项是零结果召回重试：FTS5 会在搜索词之间隐式使用 AND，因此，经过改写的多词查询可能无法命中缺少其中任意一个词的已存储句子。当精确查询和子字符串回退均未返回结果时，搜索会重试索引，匹配任意一个词，并优先排列覆盖更多搜索词的记录。已有命中仍保持精确匹配语义（仅在零结果时才会触发重试），而包含显式 OR/NOT 的查询、单词查询和经 CJK 路由的查询均不受影响。⁵¹

外部记忆提供商

若需要超越 MEMORY.md 和 USER.md 的深层持久记忆，Hermes 在 v0.21.7 中内置了两个外部记忆提供商插件：RetainDB 和 ByteRover。另有6个可从插件目录安装：在 v0.21.7 中移出核心代码树的 Holographic；在 v0.21.6 中移出的 Honcho、OpenViking、Mem0 和 Supermemory；以及在 v0.21.5 中移出的 Hindsight。这6个插件均属于社区级条目，由各自供应商维护。¹²⁵⁵⁵⁷

Hindsight 在 v0.21.4 及之前版本中随核心代码树提供，并在 v0.21.5 中迁移至目录，由 Vectorize 维护；Honcho、Mem0、OpenViking 和 Supermemory 随后于 v0.21.6 迁移，Holographic 则于 v0.21.7 迁移。现有配置会自行迁移：如果 memory.provider 指定了其中之一，hermes update 会在每个使用该插件的 profile 主目录中安装相应的目录插件；若首次启动代理时仍未安装，也会自动完成安装。若设置了 security.allow_lazy_installs: false，代理启动流程只会记录一条消息，因此需要自行运行 hermes plugins install <name>。插件会安装到 ~/.hermes/plugins/<name>/，并添加到 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)

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

会话自动恢复（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 适配器。^364171819 这里的 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 将 Google Chat 作为第 20 个平台加入，沿用同一套可插拔适配器架构；IRC 和 Microsoft Teams 也迁移到了新的适配器模式，并采用通用的 env_enablement_fn / cron_deliver_env_var 插件钩子。¹⁸ v0.14.0 增加了 LINE 和 SimpleX Chat，并完善了 Microsoft Teams 的端到端技术栈，涵盖 Graph 身份验证、webhook 监听器、管线运行时和出站投递。¹⁹ v0.17.0（2026年6月19日）通过 Photon Spectrum 增加了无需中继的 iMessage 支持（使用 hermes photon login 进行设备代码 OAuth，无需 Mac/BlueBubbles 中继），还加入了官方 WhatsApp Business Cloud API 适配器（不再需要桥接进程）、SimpleX 群组和原生附件支持，以及作为随附平台插件的 Raft。²¹ 文档表格中还列出了另外两个平台，但发行说明并未特别提及：ntfy 是一种轻量级 HTTP 发布-订阅推送通道（通过 ntfy 移动应用订阅主题，向主题发送消息即可与代理交流，并在手机上接收回复；既可使用公共 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、频道映射和允许列表。⁶ 自 v0.21.6 起，Discord 设置步骤会验证机器人令牌，并输出一个包含适配器所需权限位的邀请链接；它还会明确提示仍处于关闭状态的 Message Content Intent，因为这会导致 Discord 拒绝机器人的连接。⁵⁴⁵⁵

消息流转方式

根据上游架构文档：³

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 主机的凭据、泄漏至 stdio MCP 服务器的默认 profile 保管库密钥、跨 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 仍可共存：如果正在运行的是另一个 profile 的独立（非多路复用）gateway，您的 profile 会像以前一样在旁边启动自己的 gateway，直至强制执行迁移（#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；主机永远不会服务该 profile，而它的 stop/start 会作用于自己的进程。文档将此键称为“临时兼容性垫片”，而非受支持的拓扑；如果在默认 profile 中设置，系统会发出警告并忽略它。若 gateway 分布在不同的操作系统用户下，或者 HERMES_HOME 位于默认主目录的 profiles/ 之外，则仍需要使用 --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 系统，其中的作业是代理任务，而不是 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.

代理将通过其工具设置 cron 作业。作业会持久保存在 JSON 中，并在重启后继续存在。³

v0.21.0 为计划作业赋予了记忆与判断能力。 共包含以下4种机制，均已在标签 v2026.8.31 中验证：³⁵³⁷

• 连续性。 continuity=true 会在每次运行时注入该作业自身最近一次的输出，使侦察或监控任务“醒来时能看到上次报告的内容，从而去重并接续先前进度”——注入的引导语是“避免重复已经报告的内容”；首次运行不受影响；在内部，该标志以 context_from 中保留的 self 条目存储。可通过 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> 写入，运行中的代理会借助其终端工具调用该命令。³⁷
• 监控模式。 作业可附加低成本的 monitor_script/monitor_url 数据源，并在每次触发时优先运行：若输出未发生变化（按精确字节比较），便会完全跳过代理运行——不调用 LLM、不发送结果，只留下静默的 no_change 运行记录；若检测到变化，则注入差异块并正常运行代理。监控脚本应输出稳定内容，否则每次触发都会被视为发生变化。³⁷
• 按作业设置推理强度，并发送至 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 界面升级为命令中心：服务器与目录合并到同一页面；支持通过拖入内容实现“粘贴任何内容”式导入；后台健康检查会在工具调用失败前显示即将过期的身份验证；服务器群组成本与用量叠加层会显示每台服务器的 schema token 估算值及30天用量；hermes:// 深层链接则可在用户明确确认后安装 MCP 服务器。³⁵

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

作为服务器——将 Hermes 对话开放给其他代理：

hermes mcp serve
hermes mcp serve -v    # Verbose

上下文压缩

Hermes 会自动压缩过长的对话，使其保持在模型的上下文窗口之内。压缩摘要器会单独调用一次 LLM——您可以将其指向任意提供商或端点。⁴ 自 v0.20.6 起，保留尾部策略默认为 lean（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 恢复指针，使代理能够重新访问被摘要掉的任何内容。文档对实际500K-token 会话的测量结果显示：保留量约为49K token，而非约162K。lean 尾部中的旧工具结果会降级为仅包含恢复指针的单行占位信息；未知的 tail_mode 值则会回退到 lean。³¹

提供商选项：⁴³¹

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

预算压力警告

当代理使用大量工具调用处理复杂任务时，可能会在毫无察觉的情况下耗尽迭代预算（自 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会为您的配置、会话、skill和内存创建完整归档。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-stdin攻击、修复危险命令绕过漏洞、在工具错误重新注入模型前进行清理、为仪表板插件API增加身份验证、完善skills-hub的SSRF防护，以及在安装期间扫描供应链安全通告。¹⁹

如果您负责维护Hermes部署，应将v0.13.0和v0.14.0视为与安全密切相关的升级，而非普通功能更新。v0.13.0修复了Discord跨服务器绕过漏洞和两个TOCTOU窗口；v0.14.0则进一步加固了sudo处理、工具错误重新注入、插件API、skills-hub SSRF防护和依赖项安全通告等方面。

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

v0.21.6带来第五轮安全加固。其中包括Tenable Research报告的4项仪表板身份验证修复（使用X-Forwarded-For欺骗登录速率限制、未经身份验证的请求可导致身份验证审计记录无限写入、公开的/auth/路由未限制请求正文大小，以及登录代码被发送至非环回重定向地址而导致会话可被接管）；自动git调用在首次提示前不再运行不受信任代码库自身的clean、smudge或process过滤器程序；以及使用parseaddr解析电子邮件From标头，防止带引号的显示名称绕过允许列表。详情请参阅v0.21.6的新增内容。⁵⁴⁵⁵

面向实践者的架构

本节面向希望了解底层工作原理，以便调试、扩展或分析性能的读者。内容综合自上游架构文档。³

入口点 → 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>；移除工具会触发会话重置，以便agent重新构建工具清单）。

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（agent身份；若不可用，则使用内置后备内容）
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.6开始，plugins.isolation: host（默认值为in_process）可将第三方Python插件代码隔离在Hermes进程之外：普通插件按profile分别加载到一个插件宿主进程中，并且只能通过ctx与Hermes通信；所有其他可能在进程内导入用户代码的路径（类别提供商、模型提供商profile、仪表板插件API）都会拒绝加载并说明原因；捆绑插件则继续在进程内运行。这样一来，某个插件挂起或崩溃时，只会导致其宿主进程停止，而不会拖垮gateway。⁵⁵从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；出现在该目录中即代表获准收录。这些数据以plugin-catalog.json形式发布，供CLI使用（实时获取，并缓存在~/.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接缝从未属于受支持的接口，也不会恢复。⁴²⁵³ 到v0.21.6时，这一应急途径已经关闭：清单、垫片、hermes plugins compat扫描器和plugins.allow_deprecated_imports均已移除；hermes_cli/plugin_compat.py仅作为无功能的存根保留，供仍从旧版检出运行的更新程序使用。若插件仍然导入拆分前的路径，其导入将失败。⁵⁵

设计原则

摘自上游架构页面：³

从 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 个源目录的 skills、默认模型、自定义提供商、MCP 服务器、消息平台令牌和允许列表（Telegram、Discord、Slack、WhatsApp、Signal、Matrix、Mattermost）、代理默认设置（推理强度、压缩、人性化延迟、时区、沙盒）、会话重置策略（现已停用：自 v0.21.1 起，计时器不再轮换对话⁴³）、审批规则、TTS 配置、浏览器设置、工具设置、执行超时、命令允许列表、gateway 配置，以及来自 3 个来源的 API 密钥。⁶

归档以供手动审查：cron 作业、插件、钩子/webhook、内存后端（QMD）、skills 注册表配置、UI/身份、日志、多代理设置、频道绑定、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 profile 中）、~/.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。对话历史记录、内存和 skills 都会随之保留：⁹

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

我配置了 Anthropic，但视觉、网页和压缩功能无法使用

在当前版本中，过去那种情况基本不会再发生。默认情况下（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）。³¹ 网页提取已不再属于 LLM 任务（“不涉及 LLM”），因此在当前版本中，网页摘要失败并非辅助模型问题。³⁴ 如需明确将某项任务固定回主提供商：

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、配置、内存、会话和 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？