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

简要说明：Hermes Agent是Nous Research推出的开源自我改进AI agent。它可作为CLI和多平台消息gateway运行，将持久身份与长期记忆存储在磁盘上，聚合会随使用不断改进的skill，并可与任何兼容OpenAI的LLMprovider配合使用——Nous Portal、OpenRouter、Anthropic、GitHub Copilot、z.ai、Kimi、MiniMax、DeepSeek、Qwen Cloud、Hugging Face、Google、xAI/SuperGrok，或您自行托管的endpoint。¹²¹⁹截至v0.14.0（2026年5月16日），Hermes新增支持搭配grok-4.3 1M context的SuperGrok OAuth、面向OAuthprovider的兼容OpenAI的本地proxy（hermes proxy）、一等x_search支持、PyPI安装支持（自v0.19.0起已弃用——单行安装程序才是受支持的路径）、延迟依赖安装、支持LINE和SimpleX Chat在内的28个消息平台、/handoff、写入后的LSP语义诊断、统一的video_generate、通过cua-driver为非Anthropicprovider提供的computer_use、原生Windows beta，以及12项P0和50项P1问题的关闭。¹⁹对大多数新用户而言，最难的部分是provider身份验证：Hermes支持约20个一等provider以及自定义endpoint，并提供3条不同的身份验证路径（.env中的APIkey、通过hermes model进行的OAuth，或config.yaml中的自定义endpoint）。身份验证模型是首先要掌握的内容——其余一切都取决于最终解析到哪个provider。

Hermes Agent作为完整的agent runtime运行，而非聊天包装器。它会读取您的文件系统、在沙盒backend中执行命令、抓取网页、生成subagent、运行定时cron job，通过单一gateway进程与Telegram/Discord/Slack/WhatsApp/Signal/Email通信，并从经验中创建自己的skill。¹CLI是构建在run_agent.py对话循环之上的terminal UI；gateway则是一个长期运行的进程，将消息平台中的消息路由到同一对话循环。³

普通使用与专家级使用Hermes的差异，归根结底在于5个系统。掌握它们，Hermes就会成为效率倍增器：

1. Provider解析：身份验证流程如何映射到API调用
2. 配置层级：config.yaml+.env+auth.json+SOUL.md+AGENTS.md
3. Tool+toolset系统：agent能够做什么，以及按平台设置的权限控制
4. Skills系统：agent创建并演化的程序性记忆
5. Gateway+cron+profile：让Hermes在您日常所在之处运行，而不只是当前所在之处

关键要点

• Provider身份验证有3条路径，而非1条。.env中的APIkey、通过hermes model/hermes auth进行的OAuth，或config.yaml中的自定义endpoint。应选择与您的provider匹配的路径，而非看起来熟悉的那一条。
• 切换provider只需一条命令。hermes model会以交互方式引导您完成所有受支持provider的配置，包括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。默认情况下，它会通过自动检测使用Gemini Flash（OpenRouter→Nous→Codex）；若这些均未配置，这些功能会悄然降级，直到您将辅助slot指向主provider。⁴

v0.14的变化

v0.14.0并非围绕某个单一的头条功能，而是着力减少设置阻力，同时扩大Hermes可运行的范围。¹⁹主要运行层面的变化包括：

• 安装与启动更加轻量。pip install hermes-agent可通过PyPI安装，重量级adapter会在首次使用时延迟安装，启动路径也延后了足够多的工作，将冷启动时间缩短约19秒。（此后v0.19.0已弃用pip安装——请参阅安装。）
• 订阅可成为本地APIendpoint。hermes proxy可将由OAuth支持的provider，例如Claude Pro、ChatGPT Pro和SuperGrok，转化为兼容OpenAI的本地endpoint，供Codex、Aider、Cline和Continue等工具使用。
• Gateway覆盖范围扩大。LINE和SimpleX Chat使平台数量增至22个，Microsoft Teams实现了端到端接入，默认启用Discord历史记录回填，Telegram/Discord的clarify提示现已使用原生按钮。
• 写入时验证得到改进。编辑后，Hermes可在下一轮前显示按轮次统计的文件变更摘要和language server语义诊断，使其更接近以证据为导向的agent工作方式。
• 桌面与媒体工具更加丰富。非Anthropicprovider可通过cua-driver使用computer_use，video_generate在可插拔backend之后实现统一，vision_analyze则将原始像素发送给真正具备视觉能力的模型。

以下每一节均以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. 通过 prompt_builder.py，根据 SOUL.md、MEMORY.md、USER.md、skills、上下文文件和工具指南构建系统提示词³
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 服务器。平台差异体现在入口点，而非 agent 本身。³因此，同样的斜杠命令既可在终端中使用，也可在 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)

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

v0.20.0 的新增功能（The Herald Release）

Hermes Agent v0.20.0（标签 v2026.8.3，发布于2026年8月3日）是当前功能版本；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.19.0 以来，这一发布窗口涵盖约3650次提交、1400个已合并 PR 和1200个已关闭问题，共有650多名贡献者参与。²⁴

其中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行提高到2000行。²⁴

此版本的其余更新包括：

• 对话式语音。支持可随时打断的流式 TTS，以及设备端唤醒词。²⁴
• A2A v1.0。新增 agent 间协议插件，解决了问题 #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 设置。²⁴
• 新增 secrets 管理功能。新增可与所有 vault 组合使用的命令辅助型 secret 来源、支持一条命令完成令牌轮换并提供可操作的启动错误信息、适用于 Bitwarden 的可选加密紧急缓存、按 profile 主目录限定作用域的 vault 注入密钥，以及 config.yaml 与 MCP 配置之间的 ${env:VAR} SecretRef 一致性支持。下文介绍的3种身份验证路径模型保持不变。²⁴
• 更快的热启动。hermes -w 的冷启动时间从约14秒降至1.8秒。²⁴
• 桌面端正式成为一个平台。新增带版本化卡片和沙盒化实时预览的构件、以看板为首个桌面插件的 Plugin SDK、用于快速输入的全局快捷键、多 GUI 窗口、SSH 远程后端模式，以及符合 RFC 8252 的原生登录。²⁴

v0.20.3 和 v0.20.4 汇总版本（8月17日至18日）

v0.20.0 之后，项目采用高频标签汇总发布节奏，最新的两个版本不只是稳定性更新。两者均说明：“full curated release notes for this window will ship with v0.21.0”——因此，以下摘要来自各版本自身对发布窗口的描述，而非经过整理的功能列表。²³

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；同时修复 Bot Mode 群聊问题（长时间运行的成员轮次、Markdown 渲染、跨设备路由）。²³
• 安装 skill 时启用 NVIDIA SkillEvaluator Tier 1 建议性扫描——安装 skill 时会执行许可证和安全检查。²³
• 强化 cron 媒体发送能力（可配置超时、手动运行附件、显示错过的触发事件），修复 SessionDB 事件循环线程和争用问题，确保 hermes update 如实报告停放分支状态，并为看板新增操作系统原生通知。²³

更新方式保持不变：现有安装运行 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个已关闭 issue，以及450多位社区贡献者。²⁵

• 首个 token 速度提升约80%，覆盖所有平台。 从冷启动提交到分发的时间，在CLI、gateway、TUI、桌面端和cron中均从约4.3秒降至约0.9秒——Discord能力检测移出关键路径；对于已知非Ollama提供商，会跳过Ollama探测；代理初始化中的阻塞性工作也已移除。感知延迟也得到专门优化：推理模型现在默认实时流式输出其思考过程（display.show_reasoning已开启），响应框按 token 而非按行渲染。²⁵
• 桌面端和TUI渲染优化。 桌面应用经历了约20个PR的性能改造：通过增量块词法分析，流式Markdown分割器的CPU占用降低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的approve操作（已携带规则键重新引入）会将工具调用升级为人工审批。²⁵
• 终端计费：/subscription和/topup。 无需离开终端即可管理Nous Portal套餐——查看套餐和剩余额度，准确预览升级费用或降级何时生效，并可应用变更后撤销。桌面应用也新增了相应的计费设置选项卡。²⁵
• 查看子代理工作；绝不丢失已完成的回答。 delegate_task分发任务会在子代理启动时立即返回可供您tail -f查看的实时转录文件——每个子代理都有一份人类可读的日志，记录所有工具调用、结果和流式回复。后台委派完成状态可跨重启持久保留；最终gateway响应会记录在state.db中的投递义务账本内，如果gateway在发送中途停止，会在下次启动时重新投递。max_async_children配置选项已弃用，改用统一的委派并发上限。²⁵
• 一个gateway，多个profile。 单个复用gateway共享一个机器人 token，即可将特定服务器、频道或线程路由到不同profile——每个profile均拥有完全隔离的配置、skill、内存和密钥——并支持GATEWAY_MULTIPLEX_PROFILES覆盖。路由索引已移入state.db；sessions.json现在只是可选的旧版镜像。²⁵
• 提供商和模型更新。 Fireworks AI成为一等支持的提供商（支持成本估算，在提供商选择器中位列第2），同时加入DeepInfra和Upstage Solar。目录新增GPT-5.6（Sol/Terra/Luna + Pro，端到端接入）、grok-4.5（GA）、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提供单轮模型覆盖；slash-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积压事项——约692项最高优先级事项在12天内得到解决。²²

• 作为一等模型的Mixture-of-Agents。 MoA现在可像其他模型一样在所有界面中选择，并且集成推理过程可见：每个参考模型的完整输出都会以独立标注块呈现，并实时流式输出回答——您可以观察集成模型的思考过程，而不再只能得到不透明的合并答案。²²
• /goal的完成契约。 代理会在报告目标完成前运行项目检查来验证自己的工作，而不是直接宣称成功——将判断应用于自身。²²
• /learn——将任何描述转化为skill。 只需描述一个工作流，即可将其转化为可复用skill；生成的skill会自动遵循仓库的CONTRIBUTING.md约定。²²
• /journey时间线。 提供随时间变化的内存和skill可视化历史，并支持编辑；桌面端还提供内存图谱。²²
• 后台子代理扇出。 可委派多个并发运行的任务，而不会阻塞对话——v0.17.0中的单个后台子代理现已扩展为一支队伍。²²
• 桌面端Projects。 提供一等支持的编码Projects，采用项目/仓库/泳道组织模型。²²
• 可缩减至零的gateway。 gateway可在空闲时进入休眠状态，并协调排空过程以实现无缝部署——对于将Hermes作为常驻服务运行的用户尤为重要。²²
• Google Vertex AI支持。 通过GCP服务账号访问Gemini，并自动刷新OAuth2 token，加入提供商目录。²²
• /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 界面保持不变。²¹

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

如果您正从v0.16.x升级，这里没有任何内容会破坏 CLI；它是在同一代理周边新增的渠道、模型和界面。无需中继的iMessage、官方WhatsApp适配器以及管理员Managed scope是升级的主要理由。

v0.16.0 有哪些新功能（界面版本）

Hermes Agent v0.16.0（标签 v2026.6.5，2026年6月5日）以它为以 CLI 为先的代理带来的新界面而得名。核心变化是Hermes不再仅限于终端。²⁰

• 原生桌面应用。 Hermes Desktop是面向macOS、Linux和Windows的新Electron应用，支持一键安装和应用内自更新。它提供流式聊天窗口、拖放文件、从剪贴板粘贴图像、Cmd+K 命令面板、支持归档和搜索的会话列表，以及状态栏模型选择器。它可通过安全的 WebSocket 连接远程Hermes gateway，并通过 OAuth 或用户名/密码认证；支持按profile设置远程主机，以及通过跨profile @session 引用关联的并发多profile会话。桌面UI还通过类型化i18n层提供完整的简体中文（简体中文）翻译（display.language；英语仍为默认语言）。²⁰
• 浏览器管理面板。 本地Web仪表板从状态视图升级为完整管理面板：包含可启用/禁用开关的 MCP 目录、凭据管理、webhook和hook创建、内存配置、gateway控制，以及带更新前检查和一键Debug Share的System页面。新的Channels页面可在浏览器中配置所有gateway消息平台（Telegram、Discord、Slack等）。认证现已可插拔：用户名/密码登录、通用自托管OIDC提供商、用于自托管 OAuth 客户端的 hermes dashboard register，以及刷新token会话轮换。²⁰
• 新增 CLI 和斜杠命令。 /undo [N] 会备份最近N轮用户对话，并提供预填充和软删除；它可在 CLI、TUI以及各消息平台中使用。可配置的默认界面（cli 与 tui）现已推出，并支持 --cli 覆盖；TUI新增统一的 /model 命令和Sessions覆盖层。hermes portal 是Nous Portal引导流程的人类可读别名，首次运行新增Quick Setup与Full Setup两种路径，并加入两项诊断：hermes prompt-size 和 hermes sessions optimize。²⁰
• 新增模型和提供商。 选择器新增 deepseek-v4-flash、MiniMax-M3（1M上下文、原生MiniMax提供商）、qwen3.7-plus（Nous + OpenRouter）和 gemini-3.5-flash（Gemini OAuth + API key）。一流的xAI Grok OAuth 提供商加入桌面启动器；模型选择器在所有界面中支持模糊搜索；多端点提供商归并为同一行；目录刷新频率则从每日改为每小时。²⁰
• 更精简的skills和渐进式披露。 默认skill集移除了冗余和失效的skill（Spotify迁移为原生插件，Linear迁移至 hermes mcp install linear，并移除了若干过时条目），将更多内容移入可选项，并新增 environments: frontmatter相关性门控（kanban/docker/s6），在请求前将特定上下文的skill排除在索引之外。NVIDIA/skills 现与OpenAI、Anthropic 和HuggingFace并列，成为默认受信任的Skills Hub来源。MCP 和插件工具新增渐进式（作用域化）工具披露，并修复了一个在未获取token时错误报告 OAuth 成功的 MCP 问题。²⁰
• 安全性。 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，桌面应用和管理面板就是升级理由。

安装

单行安装脚本是受支持的安装方式。它会处理 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 formula现在均被标记为“不受支持的旧版”安装方式——当Hermes检测到这类安装时，所有界面都会发出警告（但不会阻止使用）；同时，计划停止向PyPI/Homebrew发布。如果您通过pip或brew安装，请迁移至上述安装脚本。²⁵

适用于Linux、macOS、WSL2以及Android/Termux（安装脚本会自动检测Termux，并切换至经过测试的Android软件包）。⁷ 原生Windows现已成为Tier 1平台，不再是v0.14.0发布时的早期beta版本——可使用iex (irm https://hermes-agent.nousresearch.com/install.ps1)安装。文档明确指出一项注意事项：macOS仅支持Apple Silicon，不支持Intel Mac。²⁴ 从历史来看，v0.14.0通过PowerShell安装程序在早期beta中加入了原生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
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版本、指定额外组件或集成Nix/NixOS——上游安装指南提供了逐步说明。⁷ 可通过uv pip install -e ".[<extras>]"组合使用的关键可选组件如下：

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

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

这是因为Android上的.[all]会通过voice附加组件拉取faster-whisper，后者依赖未针对Android发布的ctranslate2 wheels。⁷

身份验证与提供商

Hermes支持约22个一流提供商以及自定义端点（v0.19.0新增Fireworks AI、DeepInfra和Upstage Solar），并提供3种不同的身份验证路径。以下按路径整理了完整的身份验证范围，方便您找到与现有条件相匹配的方案。

三种身份验证路径

Hermes中的每个提供商都符合以下3种身份验证模式之一：

路径1——.env中的API密钥。 将密钥放入~/.hermes/.env，Hermes会在启动时读取。适用于OpenRouter、AI Gateway、z.ai/GLM、Kimi/Moonshot、MiniMax（及MiniMax China）、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 proxy、Together AI、Groq、Azure OpenAI，或您自行托管的服务器。通过hermes model → Custom endpoint一次配置后，将持久化到config.yaml。²

完整提供商矩阵

以下是全部一流提供商，以及各自准确的设置流程。²

从v0.19.0起，您还可以清理未使用的提供商：每个提供商的enabled: false标记和excluded_providers配置键可将其从/model选择器及内置提供商解析中移除。²⁵

Anthropic：三种身份验证方法

Anthropic单独成节，是因为Hermes支持3条不同路径接入Claude，选择正确的路径至关重要。根据上游文档：²

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

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

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

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

通过hermes model选择Anthropic OAuth时，Hermes会优先使用Claude Code自身的凭据存储，而非将令牌复制到~/.hermes/.env。这样可让可刷新的Claude凭据继续保持可刷新状态。² 如果您已在同一台机器上使用Claude Code，这是最简洁的路径。

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

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

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

GitHub Copilot：两种模式

Copilot支持两种模式：直接Copilot API（推荐）和Copilot ACP（将本地Copilot CLI作为子进程启动）。²

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

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

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

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

中国AI提供商（一流支持）

Hermes内置支持z.ai/GLM、Kimi/Moonshot、MiniMax（全球+中国端点）和Alibaba Cloud，并为其提供专用的提供商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提供商时，Hermes会探测多个端点（全球、中国、编程变体），以找出接受您API密钥的端点。可用端点会自动缓存——大多数用户无需设置GLM_BASE_URL。²

xAI (Grok)会自动启用提示词缓存。 当基础URL包含x.ai时，Hermes会在每个请求中发送x-grok-conv-id标头，将会话期间的请求路由到同一台服务器，从而复用缓存的系统提示词和历史记录。² 此功能自动启用，无需配置。

hermes auth命令

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

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

凭据池用于为同一提供商轮换多个API密钥或OAuth令牌——可在不修改代码的情况下，将速率限制分摊到多个密钥。⁶ 旧版hermes login/hermes logout命令已移除；请改用hermes auth。⁶

自定义与自行托管的端点

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

交互式设置（推荐）：

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

手动配置config.yaml：

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

两种方式都会持久化到config.yaml，它是主模型、提供商和基础URL的唯一事实来源。² 旧版环境变量OPENAI_BASE_URL和LLM_MODEL不再用于主模型配置——请使用hermes model或直接编辑config.yaml。² （OPENAI_BASE_URL+OPENAI_API_KEY仍会作为辅助provider: "main"路由路径的回退方案被识别；如果您在那里使用它们，请勿贸然删除。）⁴

在会话中途切换自定义端点：

/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默认上下文长度很低（显存低于24GB时为4,096个token）。必须通过OLLAMA_CONTEXT_LENGTH或Modelfile调高；兼容OpenAI的API不接受来自客户端的上下文长度，因此Hermes无法为您设置。² 用于Agent时，至少设置为16k–32k。

vLLM——高性能GPU服务：

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

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

SGLang——通过RadixAttention实现KV缓存复用的高速服务：

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

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

llama.cpp / llama-server——CPU与Apple Silicon Metal：

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

工具调用必须使用--jinja。 缺少该标志时，llama-server会完全忽略tools参数，模型会通过在响应文本中写入JSON来尝试调用工具——Hermes无法将其解析为实际工具调用。²

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

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

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

命名自定义提供商

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

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

随后可使用三段式语法在会话中途切换：

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

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

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

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

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

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

上下文长度检测

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

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

当自动检测错误地识别窗口大小时，请设置context_length：

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

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

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

Hermes不会将您固定在某个提供商的某个模型上。智能模型路由是一组决定实际由哪个提供商和模型处理某个请求的机制：凭据池将负载分散到多个密钥，配置的回退会在主模型失败时接管，下方的辅助槽位则将侧边任务独立路由到比主模型更经济的模型。²⁶ 请结合配置这3项——它们决定了Agent是在速率限制下停滞，还是能够持续工作。

凭据池。 当同一提供商拥有多个API密钥时，可通过hermes auth配置轮换策略。这是将速率限制分摊到多个密钥的方式。⁶

回退模型。 配置一个备用provider:model；当主模型失败时（速率限制、服务器错误、身份验证失败），Hermes会自动切换至该模型：²

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

回退会在不丢失对话的情况下，于会话中途切换模型和提供商。每个会话最多触发一次。² 支持回退的提供商：openrouter、nous、openai-codex、copilot、copilot-acp、anthropic、huggingface、zai、kimi-coding、minimax、minimax-cn、deepseek、ai-gateway、opencode-zen、opencode-go、kilocode、alibaba、custom。²

辅助模型

Hermes使用轻量级“辅助”模型处理侧边任务：图像分析、网页摘要、浏览器截图分析、危险命令审批分类、上下文压缩、会话搜索摘要、skill匹配、MCP工具分派和内存刷新。⁴ 默认情况下，这些任务通过自动检测使用Gemini Flash（OpenRouter→Nous→Codex）。

您可以为每项辅助任务配置所用的模型和提供商。 每个辅助槽位均使用相同的3个配置项：provider、model、base_url。⁴

auxiliary:
  vision:
    provider: "auto"                # "auto", "openrouter", "nous", "codex", "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: 30
    download_timeout: 30
  web_extract:
    provider: "auto"
    model: ""
    timeout: 360
  approval:
    provider: "auto"
    model: ""
    timeout: 30
  compression:
    timeout: 120
  session_search: { provider: "auto", model: "", timeout: 30 }
  skills_hub:    { provider: "auto", model: "", timeout: 30 }
  mcp:           { provider: "auto", model: "", timeout: 30 }
  flush_memories:{ provider: "auto", model: "", timeout: 30 }

"main"提供商选项表示“使用主Agent正在使用的提供商”——仅在auxiliary:、compression:和fallback_model:配置中有效。它不适用于顶层model.provider设置。如果将自定义兼容OpenAI的端点作为主模型，请在model:部分设置provider: custom。⁴

这很重要： 如果您只配置了Anthropic OAuth（没有OpenRouter密钥），图像、网页摘要和压缩功能将降级或失败，因为默认辅助回退链会先尝试OpenRouter。请为辅助任务添加OPENROUTER_API_KEY，或重新配置每个辅助槽位以使用主提供商：

auxiliary:
  vision:
    provider: "main"
  web_extract:
    provider: "main"

这是新Hermes用户最常见的“我的功能悄悄失效”问题。

配置系统

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密钥、bot令牌、密码）→.env - 其他所有内容（模型、终端后端、压缩设置、内存限制、toolsets）→config.yaml

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

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

管理配置

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

示例：⁴

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

每次执行hermes update后，都应运行hermes config check和hermes config migrate。它们能发现文件中尚未包含的新配置选项。⁶

配置优先级

Hermes会从多个来源加载配置。当多个来源设置同一值时，优先级更高的来源生效：⁴

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

CLI标志始终会在该次调用中优先。config.yaml则是长期的唯一事实来源。

本地化（v0.13.0+）

v0.13.0为CLI和gateway消息新增了7种语言区域：中文（简体）、日语、德语、西班牙语、法语、乌克兰语和土耳其语。¹⁸v0.14.0实现了所有gateway命令和Web仪表板的本地化，另外新增8种语言区域，使总数达到16种。¹⁹目前文档仅提供zh-Hans本地化版本。语言区域由LC_ALL/LANG环境变量或config.yaml中显式设置的locale:键确定。英语仍是默认语言，也是所有尚未覆盖翻译字符串的唯一事实来源。

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

Profiles让您可以拥有多个相互隔离的Hermes实例，每个实例都有各自的配置、会话、skills、memory和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，而不会相互干扰。⁶³

CLI 命令

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

全局选项

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

顶层命令

hermes chat——主要入口

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

hermes chat -q "Summarize the latest PRs"           # One-shot, non-interactive
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——所有 agent 活动（API 调用、工具分派、会话生命周期、INFO+） - errors.log——仅警告和错误（agent.log 的筛选子集） - gateway.log——消息 gateway 活动（平台连接、分派、webhook）

Python 的 RotatingFileHandler 会自动轮转日志——请查找 agent.log.1、agent.log.2 等文件。⁶

hermes doctor——诊断

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

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

斜杠命令

斜杠命令在活跃的聊天会话（CLI或消息平台）中运行。它们由hermes_cli/commands.py中的共享COMMAND_REGISTRY分发，因此大多数命令在不同界面中的行为一致。⁹

会话控制

配置与模型

/model命令是会话中途切换 provider 的主力工具：⁹

/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——单轮模型覆盖，响应后会自动恢复为之前的模型。²⁵

工具、Skills与信息

动态 Skill 斜杠命令

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

/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起，斜杠skill调用可以叠加：/skill-a /skill-b do XYZ会在单轮中按顺序加载两个skill，并为链式名称提供自动补全和灰显提示文本。²⁵

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

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

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

前缀匹配

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

消息平台专用命令

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

• /status——显示会话信息
• /sethome（别名/set-home）——将当前聊天标记为平台主页
• /approve [session|always]——批准待处理的危险命令
• /deny [reason]——拒绝待处理的危险命令。自v0.19.0起，/deny <reason>会将您的拒绝理由转告 agent，使其纠正方向而不是盲目重试。²⁵
• /update——将Hermes Agent更新至最新版本
• /commands [page]——浏览所有命令和skills（分页）

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

工具与工具集

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

高级分类

常见的工具集名称包括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>切换工具；这会重置会话，以便新的工具集生效。⁹

终端后端

终端工具可在6种不同环境中执行命令：¹⁰

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

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

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个进程）、完整命名空间隔离，以及通过 volumes 提供持久化工作区。¹⁰

后台进程

终端工具支持通过显式进程管理执行后台任务：¹⁰

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

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

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

Sudo

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

多 Agent Kanban（v0.13.0+）

v0.13.0将多 Agent 协作提升为一等原语：一个持久化 Kanban 看板，可跨 Agent 和跨重启跟踪任务、状态及工作者身份。¹⁸该看板让一组 Hermes 工作者能够真正完成工作，而不是因无效交接而停滞不前。

Kanban 看板可自然配合/goal（锁定目标的 Ralph 循环）处理目标侧任务，并配合现有的delegate_task工具实现生成语义。由此形成的群体模式中，每个 Agent 都共享同一个事实来源，明确下一步该做什么、由谁执行，以及哪些任务受阻。

什么是 Hermes 群体？

群体是多个 Hermes 工作者针对同一个共享 Kanban 看板并行运行。 它并非需要启用的独立子系统，而是看板带来的能力。看板提供了并行 Agent 无法自行提供的关键要素：对我下一步该接手什么，以及是否已有其他人正在处理它？这一问题给出唯一且权威的答案。

v0.15.0将这种模式提升为受支持的拓扑，新增了用于并行工作者协调的群体拓扑、将高级目标自动分解为子任务的自动分解、每任务模型覆盖、定时任务以及工作树管理，从而避免并行工作者在同一个检出目录中发生冲突。²⁸

实际流程是：向群体提供一个目标，由自动分解将其拆分为看板任务，然后让工作者认领、执行并返回结果。重试预算按任务设置（max_retries），因此一个脆弱的子任务不会耗尽整个运行的容错空间。由于看板具有持久性，群体可跨重启继续运行——工作者会重新附着到同一状态并恢复工作。

群体的质量取决于任务分解。 看板负责协调工作者；它无法将拆分不当的目标变成优质目标。共享隐藏状态的任务仍会相互冲突，无论是否使用工作树。

skill 系统

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

所有 skill 都位于 ~/.hermes/skills/——这是主要目录和唯一事实来源。全新安装时，会从仓库复制内置 skill。通过 Hub 安装的 skill 和代理创建的 skill 也都存放在这里。¹¹

渐进式披露

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

代理仅在实际需要时才加载完整的 skill 内容。¹¹

SKILL.md 格式

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

# Skill Title

## When to Use
Trigger conditions for this skill.

## Procedure
1. Step one
2. Step two

## Pitfalls
- Known failure modes and fixes

## Verification
How to confirm it worked.

条件激活

skill 可以根据可用工具决定显示或隐藏自身。这对后备 skill尤其有用——即仅在高级工具不可用时才应出现的免费或本地替代方案：¹¹

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

代理管理的 skill

代理可以通过 skill_manage 工具创建、更新和删除自己的 skill。这是代理的过程性记忆——当它摸索出一套非同寻常的工作流时，会将该方法保存为 skill，以便日后复用。¹¹

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

操作：¹¹

Skill Hub

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

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

集成的 Hub 来源：¹¹

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

安全扫描

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

信任级别：¹¹

--force 可以覆盖社区 skill 的非危险策略拦截，但无法覆盖 dangerous 扫描判定。¹¹

外部 skill 目录

您可以让 Hermes 指向其他 skill 目录；这些目录会与本地目录一同接受扫描：¹¹

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

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

持久记忆

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

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

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

应保存的内容

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

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

会话搜索

除MEMORY.md和USER.md外，代理还可使用session_search工具搜索过去的对话。所有CLI和消息会话均存储在SQLite（~/.hermes/state.db）中，并支持FTS5全文搜索。查询会返回相关的历史对话，并由Gemini Flash进行摘要。¹²

外部记忆提供程序

如需超出MEMORY.md和USER.md的更深层持久记忆，Hermes内置了8个外部记忆提供程序插件：Honcho、OpenViking、Mem0、Hindsight、Holographic、RetainDB、ByteRover和Supermemory。¹²

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

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自动创建默认的SOUL.md（自定义profile则位于$HERMES_HOME/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 subscribers可通过现有的 Portal 凭据，获得一组经过精选的工具托管访问权限——无需额外管理 API 密钥。³⁰ Hermes CLI本身仍采用 MIT 许可证，并且完全开源。变化在于，您的 Portal auth 如今解锁的不止是模型推理。

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 subscription，而不是直接 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 凭据自动检测 subscription，无需单独登录。自 v0.19.0 起，您也可以在会话中直接管理 subscription：/subscription会显示您的套餐和剩余额度，准确预览升级费用或降级生效时间，并通过计划变更横幅和撤销功能应用变更；/topup可添加额度。桌面应用也提供了对应的账单设置标签页。²⁵

定价与访问

定价和套餐名称发布在 Nous Portal 定价页面（https://portal.nousresearch.com/pricing）。本指南不逐一列出套餐，因为它们属于 Portal 产品的职责范围，而非 Hermes CLI，并且会独立于 Hermes 发布版本而变化。请在 https://portal.nousresearch.com/注册，并查看定价页面了解当前套餐。

弃用通知

• HERMES_ENABLE_NOUS_MANAGED_TOOLS env var 已在 v0.10.0 中移除。托管工具现在通过按工具设置的 use_gateway 配置字段启用，并受您的 Portal subscription 状态控制。³⁰

定位：此版本不是什么

Hermes Agent CLI并未受 subscription 限制。项目仍采用 MIT 许可证，所有核心功能（CLI、skills、memory、messaging gateway、cron、MCP、本地 dashboard，以及面向每个 provider 的 BYOK）均可端到端使用，无需向任何人付费。v0.10.0 为已订阅 Nous Portal 的用户增加了一条便捷路径，并未从免费路径中移除任何功能。

Messaging Gateway

Hermes 可作为长期运行的 gateway process，通过单个 gateway process 连接28 个 messaging platforms：Telegram、Discord、Slack、WhatsApp、Signal、SMS、Email、Home Assistant、Mattermost、Matrix、DingTalk、Feishu/Lark、WeCom、Weixin（WeChat）、BlueBubbles（iMessage）、QQBot、Microsoft Teams、Tencent Yuanbao、Google Chat、LINE、SimpleX Chat，以及通用 Webhook adapter。^329171819 v0.9.0 通过 BlueBubbles 添加了 iMessage（自动 webhook 注册、设置向导、崩溃韧性），并通过 iLink Bot API添加了原生 WeChat 支持，同时提供适用于企业应用的 WeCom callback mode。¹⁶ v0.11.0 添加了 QQBot。²⁹ v0.12.0 添加了 Microsoft Teams 和 Tencent Yuanbao。¹⁷ v0.13.0 将 Google Chat 作为第 20 个平台加入，沿用同一套可插拔 adapter 架构；IRC 和 Microsoft Teams 也迁移到新的 adapter 模式，并使用通用的 env_enablement_fn / cron_deliver_env_var plugin hooks。¹⁸ v0.14.0 新增 LINE 和 SimpleX Chat，并通过 Graph auth、webhook listener、pipeline runtime 和 outbound delivery 完成了 Microsoft Teams 的端到端支持。¹⁹ v0.17.0（2026年6月19日）通过 Photon Spectrum 新增无需 relay 的 iMessage（使用 hermes photon login进行 device-code OAuth——无需 Mac/BlueBubbles relay），新增官方 WhatsApp Business Cloud API adapter（替代 bridge-process 要求）、SimpleX groups 和原生 attachments，并将 Raft作为捆绑的平台 plugin 加入。²¹

设置

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 tokens、bot IDs、channel mappings、allowlists。⁶

消息流转方式

根据上游架构文档：³

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

每个 messaging platform 都通过与 CLI相同的 AIAgent conversation loop 运行。因此，slash commands 在两处的工作方式完全一致；在 Telegram 中安排的 cron job 也能将其输出发送到 Discord——平台差异仅存在于边缘层。³

v0.19.0 新增基于 profile 的消息路由与持久化交付。共享一个 bot token 的单个 multiplexed gateway，可将特定 guilds、channels 或 threads 路由到不同的 profiles——每个 profile 都拥有完全隔离的 config、skills、memory 和 secrets——并支持 GATEWAY_MULTIPLEX_PROFILES override；一轮加固改进确保单个配置错误的 profile 不再导致整个 gateway 宕机。在底层，routing index 已迁移到 state.db（sessions.json现在是可选的 legacy mirror）；同时，平台发送环节附近会在持久化 delivery-obligation ledger 中记录最终响应——若已完成的回答遇到 gateway 崩溃，将在下次启动时重新交付，而不会悄然丢失。²⁵

用户授权与配对

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

配对码可防止陌生人随意与您的 gateway 交互。用户从其 messaging platform 发送配对码；您使用 hermes pairing approve批准后，他们便会获得授权。⁶

Scheduled Tasks（Cron）

Hermes 拥有一套一等公民的 cron 系统，其中 jobs 是agent tasks，而非 shell commands。每个 scheduled job 都会通过全新的 AIAgent运行，使用配置的 prompt、可选的附加 skills，并将结果发送至任意平台：³⁶

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

或者在 messaging chat 中以对话方式创建：

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

agent 会通过其 tools 设置 cron job。jobs 会持久化到 JSON中，并在重启后继续保留。³

MCP Integration

Hermes 同时支持作为 Model Context Protocol client 和 server：⁶

作为 client——将 Hermes 连接到外部 MCP servers，以扩展其 tool surface：

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

或者在 config.yaml中手动配置：¹⁴

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

自 v0.19.0 起，MCP tools 会按照 mcp__server__tool命名约定暴露给模型——每个 tool name 都携带其 server name，因此两个 server 暴露同名 tool 时不再冲突——而且 MCP server log notifications 会显示在 agent.log中。²⁵

作为 server——将 Hermes conversations 暴露给其他 agents：

hermes mcp serve
hermes mcp serve -v    # Verbose

上下文压缩

Hermes 会自动压缩较长的对话，以保持在模型的上下文窗口范围内。压缩摘要器是一个独立的 LLM 调用——您可以将其指向任意提供商或端点。⁴

compression:
  enabled: true
  threshold: 0.50                           # Compress at this % of context limit
  target_ratio: 0.20                        # Fraction to preserve as recent tail
  protect_last_n: 20                        # Min recent messages to keep uncompressed
  summary_model: "google/gemini-3-flash-preview"
  summary_provider: "auto"                  # "auto", "openrouter", "nous", "codex", "main", etc.
  summary_base_url: null                    # Custom OpenAI-compatible endpoint

提供商选项：⁴

summary_model必须支持至少与主模型相同大小的上下文长度，因为它会接收对话中间部分的完整内容以进行压缩。⁴

预算压力警告

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

流超时

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

本地端点的Socket读取超时会提高到30分钟，因为本地LLM在大型上下文上进行预填充时，可能需要数分钟才会生成第一个token。⁴

本地Web仪表板（v0.9.0+）

用于在本地管理Hermes Agent的浏览器仪表板。无需接触配置文件或终端，即可配置设置、监控会话、浏览skill以及管理gateway。¹⁶ 使用hermes dashboard启动。对于偏好GUI的新用户而言，这是最简单的入门路径。

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

watch_patterns允许您设置要在后台进程输出中监控的模式，并在匹配时实时收到通知。¹⁶ 可用于监控错误、等待特定事件（“listening on port”），或观察构建日志——全程无需轮询。结合v0.8.0引入的notify_on_complete（会在后台任务完成时发出通知），Hermes现已具备完整的后台进程可观测性层。¹⁵

可插拔上下文引擎（v0.9.0+）

现在可通过hermes plugins使用可插拔插槽管理上下文。您可以替换为自定义上下文引擎，以控制代理在每轮中看到的内容——包括过滤、摘要或注入特定领域的上下文。¹⁶ 这将上下文策略与核心代理循环解耦，从而支持按项目或领域定制上下文。

备份与恢复（v0.9.0+）

hermes backup会创建包含配置、会话、skill和memory的完整归档。hermes import则从备份归档中恢复。¹⁶ 可用于在机器之间迁移、在重大变更前创建快照，或与团队成员共享经过验证的良好配置。

Termux / Android支持（v0.9.0+）

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

安全加固（v0.13.0+）

v0.13.0修复了8个P0安全问题，并将一项默认设置改为更有利于用户。¹⁸ v0.14.0随后又修复了12个P0和50个P1问题，其中包括sudo暴力破解／sudo-stdin加固、危险命令绕过修复、模型重新注入前的工具错误净化、仪表板插件API认证、skills-hub SSRF覆盖，以及安装期间的供应链公告扫描。¹⁹

如果您维护Hermes部署，请将v0.13.0和v0.14.0视为与安全相关的升级，而不只是功能发布。v0.13.0修复了Discord跨guild绕过和两个TOCTOU窗口；v0.14.0则针对sudo处理、工具错误重新注入、插件API、skills-hub SSRF和依赖项公告进行了又一轮加固。

面向实践者的架构

本节面向希望了解底层运行机制的人，以便调试、扩展或分析性能。这是对上游架构文档的综合整理。³

入口点→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 tools/20 toolsets”与启动横幅中的“28 tools”。 “47 tools”是上游仓库中工具注册表的总数——即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重新构建其工具清单）。

三种API模式

Hermes将provider差异抽象为三种API模式，并在运行时自动选择：³

runtime_provider.py解析器将(provider, model)元组映射为(api_mode, api_key, base_url)，覆盖18个以上provider，并处理OAuth流程、凭证池和别名解析。³

CLI会话中的数据流

User input → HermesCLI.process_input()
  → AIAgent.run_conversation()
    → 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

摘自上游架构页面。³

Prompt组装顺序

prompt栈包括：¹³

1. SOUL.md（agent身份；不可用时使用内置回退内容）
2. 工具感知行为指南
3. memory/用户上下文（MEMORY.md、USER.md）
4. skill指南
5. 上下文文件（AGENTS.md、.cursorrules）
6. 时间戳
7. 平台特定的格式提示
8. 可选的系统prompt叠加层，例如/personality

SOUL.md是基础，其他内容均构建于其之上。¹³

会话存储

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

插件系统

有三个发现来源：~/.hermes/plugins/（用户）、.hermes/plugins/（项目）和pip入口点。插件通过上下文API注册工具、hooks和CLI命令。memory provider是位于plugins/memory/下的专用插件类型。³

hermes plugins                       # Interactive enable/disable UI
hermes plugins install <repo>        # Install from Git URL or owner/repo
hermes plugins enable <name>
hermes plugins disable <name>
hermes plugins list

设计原则

摘自上游架构页面：³

从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、默认model、自定义provider、MCP服务器、消息平台token和allowlist（Telegram、Discord、Slack、WhatsApp、Signal、Matrix、Mattermost）、agent默认设置（reasoning effort、compression、human delay、timezone、sandbox）、会话重置策略、审批规则、TTS config、浏览器设置、工具设置、exec timeout、命令allowlist、gateway config，以及来自3个来源的API密钥。⁶

归档以供手动审查：cron jobs、plugins、hooks/webhooks、memory backend（QMD）、skills registry config、UI/identity、logging、multi-agent设置、channel bindings、IDENTITY.md、TOOLS.md、HEARTBEAT.md、BOOTSTRAP.md。⁶

API密钥解析会按优先级顺序检查三个来源：config值→~/.openclaw/.env→auth-profiles.json。⁶

故障排除

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

这是每次全新安装都会遇到的第一个错误：Hermes尚未解析出提供商。它的含义正如字面所示——三种认证路径均未产生可用的提供商。请运行：

hermes model

交互式选择器会引导您完成所有受支持提供商的配置，包括OAuth设备代码流程（Nous Portal、GitHubCopilot、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 tokens”（本地模型）

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

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

Tool调用显示为文本而非执行

您的服务器未启用Tool调用，或者该模型不支持通过该服务器实现进行Tool调用。²

回复在句子中途被截断

可能有两种原因：²

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

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

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

镜像网络（Windows 11 22H2+）：编辑%USERPROFILE%\.wslconfig：

[wsl2]
networkingMode=mirrored

然后执行wsl --shutdown并重启。此时localhost可双向使用。

主机IP备用方案（较旧的Windows）：从WSL2内部获取Windows主机IP，并使用该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中启用“在网络上提供服务”。²

所有内容在哪里？

此时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推出的开源Agent框架，可与任何兼容OpenAI的提供商配合使用——Nous Portal、OpenRouter、Anthropic、GitHubCopilot、z.ai、Kimi、MiniMax、DeepSeek、Hugging Face、Google，或您自行托管的端点。¹²Hermes还提供Telegram/Discord/Slack/WhatsApp/Signal消息gateway，而Claude Code没有这一功能。

能否将Hermes与Anthropic API密钥搭配使用？

可以。有三种方式：²

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

若您已在同一台机器上使用Claude Code，建议采用方式2——它能让可刷新的Claude凭据继续保持可刷新状态。

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

在会话内使用/model provider:model。对话历史、memory和skills都会一并保留：⁹

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

我配置了Anthropic，但vision/web/compression无法正常工作

您遇到了辅助模型回退机制。Vision、web摘要、压缩及其他辅助任务使用独立的辅助LLM——默认通过自动检测使用Gemini Flash（OpenRouter→Nous→Codex）。如果这些都未配置，而您只设置了Anthropic，这些功能会悄然降级。⁴

修复方法：为辅助任务添加OPENROUTER_API_KEY，或重新配置辅助槽位以使用主提供商。请注意，上下文压缩位于独立的顶级compression:块中，并使用summary_provider，而不是auxiliary.compression.provider——auxiliary.compression槽位仅提供timeout。完整修复如下：

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

compression:
  summary_provider: "main"

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

SOUL.md定义Agent的身份——语气、风格与沟通默认设置。它位于~/.hermes/SOUL.md，会始终随您同行。AGENTS.md则面向特定项目——架构、约定、命令、路径——并位于项目目录中。¹³若应随您处处使用，请放入SOUL.md。若属于某个项目，请放入AGENTS.md。

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

使用profiles。每个profile都有各自的HERMES_HOME、配置、memory、sessions和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，或您自行托管的服务器。²请参阅自定义与自托管端点，了解各服务器的设置方法。

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

本指南引用上游架构注册表中的47个Tool/20个toolset——这是Hermes在所有toolset中提供源代码的Tool完整数量。您正在运行的安装会在横幅中显示较小的数量（本指南所用的参考安装显示28个Tool），因为Hermes启动时只启用默认toolset集合。许多toolset需要选择启用：消息gateway适配器、浏览器自动化、较重的抓取栈，以及多项专用集成，都必须先在~/.hermes/config.yaml的toolsets:下显式列出，才会加载。注册表总数＝“启用后可用的全部内容”。横幅总数＝“当前profile实际加载的内容”。使用hermes tools --list查看哪些toolset已启用，以及哪些可用但被禁用。可通过/tools enable <name>和/tools disable <name>在运行时切换单个toolset（禁用会触发会话重置，以便Agent根据新的结构重建其Tool清单）。

当主提供商失败时，Hermes如何处理模型回退？

在config.yaml中配置fallback_model块：²

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

当主提供商失败时（速率限制、服务器错误、认证失败），Hermes会在会话中途切换到备用模型，而不会丢失对话历史。每个会话最多触发一次。

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

可以——这正是Hermes Agent“self-improving”的部分。Agent可通过skill_manageTool创建、更新和删除skills。当它总结出一个非平凡的工作流时，会将该方法保存为skill，以便日后复用。¹¹Agent会在完成复杂任务（5次以上Tool调用）后、遇到错误并找到可行路径后、您纠正其方法后，或发现非平凡工作流时创建skills。

是否有IDE集成？

有——Hermes可作为ACP（Agent Client Protocol）服务器运行，适用于VS Code、Zed和JetBrains：⁶

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

更新日志

参考资料