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

TL;DR：Hermes Agent是Nous Research推出的开源自我改进型AI Agent。它既可作为CLI运行，也可作为多平台消息gateway运行；它会在磁盘上存储持久身份和持久记忆，聚合会随使用而改进的skill，并可配合任何兼容OpenAI的LLM提供商使用——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上下文的SuperGrok OAuth、面向OAuth提供商的兼容OpenAI的本地代理（hermes proxy）、一等支持的x_search、PyPI安装支持、lazy依赖安装、包含LINE和SimpleX Chat在内的22个消息平台、/handoff、写入后的LSP语义诊断、统一的video_generate、通过cua-driver为非Anthropic提供商提供的computer_use、原生Windows beta，以及12个P0/50个P1问题闭环。¹⁹对大多数新用户来说，最难的部分是提供商认证：Hermes支持约20个一等提供商以及custom endpoints，并提供3条不同的认证路径（.env中的API密钥、通过hermes model进行OAuth，或在config.yaml中配置custom endpoint）。认证模型是首先要掌握的内容——其他一切都取决于最终解析到哪个提供商。

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中配置custom endpoint。请选择与提供商匹配的路径，而不是看起来熟悉的路径。
• 切换提供商只需一条命令。hermes model会以交互方式引导您完成所有受支持的提供商配置，包括OAuth登录；/model provider:model可在会话中途切换模型，且不会丢失历史记录。²
• 用户可编辑的配置界面主要是两个文件。~/.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）——如果这些都未配置，相关功能会静默降级，直到您将辅助槽位指向主提供商。⁴

v0.14带来了哪些变化

v0.14.0并非只围绕一个头条功能，而是重点降低设置阻力，同时拓宽Hermes的运行范围。¹⁹主要的操作层面变化如下：

• 安装和启动更轻量。pip install hermes-agent可从PyPI安装，重型适配器会在首次使用时lazy安装，启动路径也延后了足够多的工作，使冷启动时间大约减少19秒。
• 订阅可以变成本地APIendpoint。hermes proxy会把OAuth支持的提供商（例如Claude Pro、ChatGPT Pro和SuperGrok）转换为兼容OpenAI的本地endpoint，供Codex、Aider、Cline和Continue等工具使用。
• Gateway覆盖范围扩大。LINE和SimpleX Chat将平台总数提升到22个；Microsoft Teams已实现端到端接入；Discord历史回填默认开启；Telegram/Discord的clarify提示现在使用原生按钮。
• 写入时验证得到改进。编辑后，Hermes可以在下一轮之前显示每轮文件变更摘要和语言服务器语义诊断，使其更接近以证据驱动的Agent工作方式。
• 桌面和媒体工具范围更广。computer_use通过cua-driver支持非Anthropic提供商，video_generate统一到可插拔后端之后，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、skill、上下文文件和工具指导构建系统提示词³
2. 通过 runtime_provider.py 解析运行时 provider——这一步会选择您的身份验证、base URL 和API模式³
3. 使用 3 种API模式之一调用 provider：chat_completions、codex_responses 或 anthropic_messages³
4. 通过 model_tools.py 和中心工具注册表（tools/registry.py）分发返回的任何工具调用³
5. 持续循环，直到模型生成最终响应，然后将会话持久化到带 FTS5 的 SQLite 中³

理解这个循环很重要，因为每项功能——personality、memory、skill、compression、fallback——都会附着到其中某个阶段。当您阅读某个配置键并想知道它的作用时，答案通常是：“它是上面循环中第 1、2、3 或 4 阶段的一个调节项。”

平台无关核心。 一个 AIAgent 类同时服务于CLI、gateway、ACP、batch 和API服务器。平台差异存在于入口点，而不在 agent 本身。³这就是为什么同样的 slash commands 可以同时在终端和 Telegram 中工作——它们都由 hermes_cli/commands.py 中共享的 COMMAND_REGISTRY 分发。⁶

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

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

上面的每个文件都有明确职责，彼此并不重叠。如果您想知道“Hermes 把 X 存在哪里”，答案就在其中之一。

安装

对大多数用户来说，单行安装器仍然是推荐的引导式路径。它会处理Python、uv、Node.js、ripgrep、ffmpeg、仓库克隆、虚拟环境，以及全局 hermes 命令。⁷v0.14.0 还发布了真正的 PyPI 包，因此当您已经能控制Python环境时，pip install hermes-agent 现在也是一种可行的直接安装方式。¹⁹

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

pip install hermes-agent
hermes

适用于 Linux、macOS、WSL2 和 Android/Termux（安装器会自动检测 Termux，并切换到经过测试的 Android bundle）。⁷v0.14.0 通过 PowerShell 安装器加入了早期 beta 阶段的原生 Windows 支持，但在 Windows 路径成熟之前，生产使用仍更建议选择 WSL2。¹⁹

完成后：

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

唯一前置条件是 git。安装器会通过 uv 自动配置Python 3.11（无需 sudo）、Node.js v22（用于浏览器自动化和 WhatsApp bridge）、ripgrep 和 ffmpeg。⁷

验证安装

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 会准确说明缺少什么以及如何修复。⁷当您需要在GitHub issue 或 Discord 线程中寻求帮助时，hermes dump 是可以粘贴的诊断命令——它会生成一份纯文本格式的完整设置摘要，并对 secrets 进行脱敏。⁸

手动安装

如果需要完全控制——自定义Python版本、指定 extras、Nix/NixOS 集成——上游安装指南已经逐步记录了手动流程。⁷可以与 uv pip install -e ".[<extras>]" 组合使用的关键可选 extras 如下：

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

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

这是因为 Android 上的 .[all] 会通过 voice extra 拉取 faster-whisper，而后者依赖的 ctranslate2 wheel 并未针对 Android 发布。⁷

身份验证与提供商

Hermes支持约19个一流提供商以及自定义端点，并提供3条不同的身份验证路径。下面按路径整理了完整的身份验证范围，便于您找到与现有条件匹配的方式。

3条身份验证路径

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

路径1——.env中的API key。 将密钥放入~/.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以及多数第三方提供商均使用此方式。²

路径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。²

完整提供商矩阵

下面是一流提供商的完整列表，并列出每个提供商的确切设置流程。²

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：两种模式

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设备代码登录

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提供商（一流支持）

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环境变量覆盖Base URL。²

Z.AI会自动检测端点。 使用z.ai/GLM提供商时，Hermes会探测多个端点（全球、中国、coding变体），以找到能接受您API key的端点。可用端点会自动缓存——多数用户不需要GLM_BASE_URL。²

xAI (Grok)会自动启用提示缓存。 当Base 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 key或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，它是main-model、provider和base URL的唯一事实来源。² 旧版环境变量OPENAI_BASE_URL和LLM_MODEL已不再用于main-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 VRAM下为4,096 tokens）。必须通过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子类，用于声明身份验证路径、Base 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 key。请将该代理视为本地开发基础设施：有意绑定，不要大范围暴露，并留意各提供商的特定条款。

上下文长度检测

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

• 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）。²

提供商轮换与回退

凭据池。 当您有同一提供商的多个API key时，可通过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 key），视觉、网页摘要和压缩功能会降级或失败，因为默认辅助回退链会先尝试OpenRouter。请为辅助任务添加OPENROUTER_API_KEY，或将每个辅助槽位重新配置为使用主提供商：

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

这是Hermes新用户最常遇到的“我的功能悄悄不能用”陷阱。

配置系统

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

配置文件布局

根据上游文档，以下文件共同构成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 keys、bot tokens、密码）→ .env - 其他所有内容（model、终端后端、压缩设置、内存限制、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 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 config check和hermes config migrate是在每次hermes update之后都应运行的命令——它们会发现您的文件中尚未包含的新配置选项。⁶

配置优先级

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 dashboard 本地化，又新增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>/），因此多个profiles可以同时运行gateway，互不干扰。⁶³

CLI 命令

本节是顶层 CLI 命令的实践者参考手册。如需查看基于代码的权威参考，请参阅上游 CLI Commands Reference。⁶

全局选项

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——所有代理活动（API 调用、工具调度、会话生命周期，INFO 及以上） - errors.log——仅包含警告和错误（agent.log 的过滤子集） - gateway.log——消息网关活动（平台连接、消息分发、webhook）

日志轮转由 Python 的 RotatingFileHandler 自动处理——可查找 agent.log.1、agent.log.2 等文件。⁶

hermes doctor——诊断工具

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

如需将诊断信息分享给他人，使用 hermes dump——它会生成一份紧凑的纯文本摘要，其中 API 密钥已脱敏，可直接粘贴到 GitHub issue 或 Discord 讨论中。⁶

Slash Commands

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

会话控制

配置与Model

/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

工具、Skills与信息

动态Skill Slash Commands

每个已安装的skill都会自动作为slash command暴露：⁹

/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

也可以在config.yaml中定义quick commands，将短名称别名到更长的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——拒绝待处理的危险命令
• /update——将Hermes Agent更新到最新版本
• /commands [page]——浏览所有命令和skills（分页）

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

Tools 与 toolsets

Hermes内置了覆盖范围广泛的工具注册表，涵盖网页搜索、浏览器自动化、终端执行、文件编辑、memory、委派、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>切换工具，这会重置会话，使新的工具集生效。⁹

终端后端

终端工具可在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个进程）、完整namespace隔离、通过卷提供持久化工作区。¹⁰

后台进程

终端工具支持带显式进程管理的后台执行：¹⁰

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。¹⁰

Multi-Agent Kanban（v0.13.0+）

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

Kanban看板很自然地与目标侧的/goal（locked-target Ralph loop）以及现有的delegate_task工具的spawn语义配合使用。其结果是一种swarm模式：每个agent都共享同一个事实来源，明确下一步要做什么、谁在做，以及哪里卡住了。

Skills系统

Skills是智能体可在需要时加载的按需知识文档。它们遵循渐进式披露模式，以最大限度减少token使用量，并兼容agentskills.io开放标准。¹¹

所有skills都位于~/.hermes/skills/——这是主目录，也是事实来源。全新安装时，内置skills会从repo复制过来。通过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可以根据可用tools显示或隐藏自身。这对fallback skills最有用——这些免费或本地替代方案只应在高级tool不可用时出现：¹¹

示例：内置的duckduckgo-search skill使用fallback_for_toolsets: [web]。当您设置了FIRECRAWL_API_KEY时，web toolset可用，智能体会使用web_search——DuckDuckGo skill会保持隐藏。如果没有API密钥，DuckDuckGo skill会自动作为fallback出现。¹¹

智能体管理的Skills

智能体可以通过skill_manage tool创建、更新和删除自己的skills。这是智能体的程序性记忆——当它弄清楚一个非平凡workflow时，会把方法保存为skill，供后续复用。¹¹

智能体创建skills的时机：¹¹ - 成功完成复杂任务后（5次以上tool调用） - 遇到错误或死胡同，并找到可行路径时 - 用户纠正其方法时 - 发现非平凡workflow时

操作：¹¹

Skill Hub

从在线registries浏览、搜索、安装和管理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、VoltAgent/awesome-agent-skills、garrytan/gstack。¹¹

安全扫描

所有通过Hub安装的skills都会经过安全扫描器检查，覆盖数据外泄、prompt injection、破坏性命令、供应链信号以及其他威胁。¹¹

信任级别：¹¹

--force可以覆盖community skills的非危险策略阻止。它不会覆盖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风格docstrings”→memory - 已完成工作：“已于2026年1月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路径。

Personality与SOUL.md

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

Hermes会自动在~/.hermes/SOUL.md（或自定义profile的$HERMES_HOME/SOUL.md）播种默认SOUL.md。现有用户文件绝不会被覆盖。Hermes只会从HERMES_HOME加载SOUL.md，不会查找当前工作目录。这让personality在不同项目之间保持可预测。¹³

SOUL.md中应包含什么

将其用于持久的语气和personality指导：¹³ - 语气 - 沟通风格 - 直接程度 - 默认交互风格 - 在风格上应避免什么 - Hermes应如何处理不确定性、分歧和模糊性

少用它来记录：¹³ - 一次性项目说明 - 文件路径 - 仓库约定 - 临时工作流细节

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

SOUL.md与AGENTS.md

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

SOUL.md——身份、语气、风格、沟通默认值、personality层面的行为。

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

一个实用规则是：如果它应该随您在任何地方生效，就属于SOUL.md。如果它属于某个项目，就属于AGENTS.md。¹³

内置Personalities

Hermes随附可通过/personality切换的内置personalities：¹³

config.yaml中的自定义personalities：¹³

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 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订阅中扣除，而不是从直接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 subscribe或hermes login --portal命令。订阅会根据您在hermes auth中已有的Portal OAuth凭据自动检测。

定价和访问权限

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

弃用通知

• HERMES_ENABLE_NOUS_MANAGED_TOOLS环境变量已在v0.10.0中移除。托管工具现在通过按工具设置的use_gateway配置字段启用，并受您的Portal订阅状态限制。²¹

定位：此版本不是什么

Hermes Agent CLI并未被订阅门槛限制。该项目仍采用MIT许可证，所有核心功能（CLI、skills、memory、messaging gateway、cron、MCP、local dashboard、每个提供方的BYOK）无需向任何人付费即可端到端运行。v0.10.0为已经为Nous Portal付费的用户增加了一条便利路径——它没有从免费路径中移除任何内容。

Messaging Gateway

Hermes可以作为长期运行的gateway进程运行，通过单个gateway进程连接到22个消息平台：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适配器。^320171819 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，并以Graph auth、webhook listener、pipeline runtime和outbound delivery补齐了Microsoft Teams的端到端栈。¹⁹

设置

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令牌、bot ID、频道映射、allowlist。⁶

消息流转方式

来自上游架构文档：³

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会话循环运行。这就是为什么slash command在两处表现完全一致，也解释了为什么在Telegram中调度的cron job可以把输出发送到Discord——平台差异只存在于边缘层。³

用户授权与配对

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批准后，该用户从此即获得授权。⁶

计划任务（Cron）

Hermes拥有一套一等cron系统，其中job是agent task，而不是shell command。每个计划job都会通过全新的AIAgent运行，使用配置的prompt、可选附加skill，并将结果投递到任意平台：³⁶

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

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

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

agent会通过其工具设置cron job。job会持久保存在JSON中，并在重启后继续存在。³

MCP集成

Hermes既可以作为client，也可以作为server支持Model Context Protocol：⁶

作为client——将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

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

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

作为server——将Hermes会话暴露给其他agent：

hermes mcp serve
hermes mcp serve -v    # Verbose

上下文压缩

Hermes会自动压缩长会话，以保持在模型的上下文窗口内。压缩摘要器是一次独立的LLM调用——您可以将它指向任意provider或endpoint。⁴

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

Provider选项：⁴

summary_model必须支持至少与主模型一样长的上下文长度，因为它会接收会话的完整中间部分用于压缩。⁴

预算压力警告

当agent处理包含大量tool call的复杂任务时，可能会在不自知的情况下耗尽迭代预算（默认：90轮）。预算压力会自动向模型发出警告：⁴

流式超时

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

对于本地endpoint，socket读取超时会提高到30分钟，因为本地LLM在大上下文中可能需要数分钟进行prefill，之后才生成第一个token。⁴

本地Web Dashboard（v0.9.0+）

这是一个基于浏览器的dashboard，用于在本地管理您的Hermes Agent。无需接触配置文件或终端，即可配置设置、监控session、浏览skill并管理gateway。¹⁶ 使用hermes dashboard启动。对于偏好GUI的新用户来说，这是最简单的上手路径。

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

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

可插拔Context Engine（v0.9.0+）

现在，上下文管理通过hermes plugins成为一个可插拔槽位。您可以替换为自定义context engine，控制agent在每一轮看到的内容，包括过滤、摘要，或注入特定领域的上下文。¹⁶ 这将上下文策略从核心agent循环中解耦出来，支持按项目或按领域定制上下文。

备份与恢复（v0.9.0+）

hermes backup会创建包含配置、session、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加固、危险命令绕过修复、工具错误重新注入模型前的清理、dashboard插件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）。这不是bug。许多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

来自上游架构页面。³

提示组装顺序

提示栈包括：¹³

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

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

会话存储

基于SQLite的会话存储，配有FTS5全文搜索。会话具备谱系跟踪（压缩前后的父/子关系）、按平台隔离，以及带冲突处理的原子写入。³

插件系统

三个发现来源：~/.hermes/plugins/（用户）、.hermes/plugins/（项目）和pip入口点。插件通过上下文API注册工具、hook和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和允许列表（Telegram、Discord、Slack、WhatsApp、Signal、Matrix、Mattermost）、agent默认值（reasoning effort、compression、human delay、timezone、sandbox）、会话重置策略、approval规则、TTS配置、浏览器设置、工具设置、exec超时、命令允许列表、gateway配置，以及来自3个来源的APIkey。⁶

归档以供手动审查： cron作业、插件、hook/webhook、memory后端（QMD）、skills注册表配置、UI/身份、日志、多agent设置、channel绑定、IDENTITY.md、TOOLS.md、HEARTBEAT.md、BOOTSTRAP.md。⁶

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

故障排除

“API key not set”

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

启动时出现 “Context limit: 2048 tokens”(本地模型)

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 tokens。在服务器上设置 --default-max-tokens,或在 config.yaml 中配置 model.max_tokens。
2. 上下文耗尽——模型填满了上下文窗口。增大 model.context_length,或在 Hermes 中启用上下文压缩。

从 WSL2 连接到 Windows 上托管的模型服务器时出现 “Connection refused”

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 }'
# 将该 IP 用作 base_url 的主机

您还需要让模型服务器绑定到 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”。²

一切都在哪里?

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、GitHub Copilot、z.ai、Kimi、MiniMax、DeepSeek、Hugging Face、Google,或您自托管的端点。¹² Hermes 还提供了 Claude Code 所没有的、面向 Telegram/Discord/Slack/WhatsApp/Signal 的消息 gateway。

我可以用 Anthropic 的 API key 来使用 Hermes 吗?

可以。有三种方式:²

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。对话历史、记忆和 skills 都会延续:⁹

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

我配置了 Anthropic,但视觉/网页/压缩功能不工作

您遇到的是辅助模型回退问题。视觉、网页摘要、压缩等附属任务使用的是独立的辅助 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 实例?

使用 profile。每个 profile 都拥有独立的 HERMES_HOME、config、记忆、会话和 gateway PID:⁶

hermes profile create work --clone
hermes profile use work                 # 粘性默认
hermes -p work chat -q "..."            # 一次性使用,无需切换
hermes profile alias work --name h-work # 包装脚本

Hermes 支持本地 LLM 吗?

支持,通过自定义端点路径。Hermes 可与任何兼容 OpenAI 的服务器配合使用:Ollama、vLLM、SGLang、llama.cpp/llama-server、LM Studio、LocalAI、Jan,或您自己的服务器。² 各服务器的具体设置请参见 Custom & Self-Hosted Endpoints。

为什么我的启动横幅显示的工具数比指南中所说的 Hermes 拥有的少?

指南引用了上游架构注册表中的 47 个工具 / 20 个 toolset——这是 Hermes 在所有 toolset 中提供源代码的工具总数。您正在运行的安装在横幅中显示的数量较小(本指南所用的参考安装报告 28 个工具),因为 Hermes 在启动时仅启用默认的 toolset 集合。许多 toolset 是按需启用的:消息 gateway 适配器、浏览器自动化、较重的抓取栈以及几个专门的集成,必须先在 ~/.hermes/config.yaml 的 toolsets: 下显式列出才会被加载。注册表总数 = “如果启用了的话有多少可用”。横幅总数 = “您当前 profile 实际加载了多少”。使用 hermes tools --list 查看哪些 toolset 处于活跃状态、哪些可用但已禁用。在运行时使用 /tools enable <name> 和 /tools disable <name> 切换单个 toolset(禁用会触发会话重置,以便 agent 用新的形态重建其工具清单)。

当我的主提供商失败时,Hermes 如何处理模型回退?

在 config.yaml 中配置 fallback_model 块:²

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

当主提供商失败时(限流、服务器错误、认证失败),Hermes 会在会话中途切换到回退模型,且不会丢失对话历史。每个会话最多触发一次。

agent 能随着时间推移自我提升 skills 吗?

可以——这正是 Hermes Agent “自我提升” 的部分。agent 可以通过 skill_manage 工具创建、更新和删除 skills。当它摸索出一个非平凡的工作流时,会把该方法保存为 skill 以供将来复用。¹¹ agent 会在完成复杂任务后(5 次以上工具调用)、遇到错误并找到可行路径时、您纠正其方法时,或它发现非平凡工作流时创建 skills。

有 IDE 集成吗?

有——Hermes 可以作为 ACP(Agent Client Protocol)服务器运行,支持 VS Code、Zed 和 JetBrains:⁶

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

更新日志

参考资料