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

TL;DR： Hermes Agent是Nous Research推出的开源自我改进型AI代理。它以CLI形式运行,同时作为多平台消息网关,在磁盘上存储持久身份和持久内存,聚合可随使用而改进的技能,并与任何兼容OpenAI的LLM提供商协作——Nous Portal、OpenRouter、Anthropic、GitHub Copilot、z.ai、Kimi、MiniMax、DeepSeek、Alibaba、Hugging Face、Google,或您自己自托管的端点。¹² 对大多数新用户而言,最困难的部分是提供商认证:Hermes支持约19个一级提供商及自定义端点,以及三种独立的认证路径(.env中的API密钥、通过hermes model的OAuth,或config.yaml中的自定义端点)。认证模型是首要学习的内容——其他一切都取决于解析出哪个提供商。

Hermes Agent作为完整的代理运行时运行,而非聊天封装器。它读取您的文件系统、在沙箱后端中执行命令、抓取网络、生成子代理、运行计划cron任务,通过单一网关进程与Telegram/Discord/Slack/WhatsApp/Signal/Email通信,并根据经验创建自己的技能。¹ CLI是构建在run_agent.py对话循环之上的终端UI;网关是一个长时间运行的进程,通过同一对话循环路由来自消息平台的消息。³

普通用户与Hermes专家之间的差距取决于五大系统。 掌握这些,Hermes就会成为效能倍增器:

1. 提供商解析:认证流程如何映射到API调用
2. 配置层级:config.yaml + .env + auth.json + SOUL.md + AGENTS.md
3. Tool + toolset系统:代理能做什么,按平台分级控制
4. Skills系统:代理创建和演进的程序性记忆
5. Gateway + cron + profile:让Hermes在您生活之处运行,而不仅仅是您当下所在之处

核心要点

• 提供商认证有三条路径,而非一条。 .env中的API密钥、通过hermes model/hermes auth的OAuth,或config.yaml中的自定义端点。选择与您的提供商匹配的路径,而不是您熟悉的那条。
• 切换提供商只需一个命令。 hermes model会以交互方式引导您完成每个受支持的提供商,包括OAuth登录,而/model provider:model可在不丢失历史记录的情况下进行会话中切换。²
• 两个文件是用户可编辑的配置表面。 ~/.hermes/config.yaml保存设置,~/.hermes/.env保存密钥。auth.json、SOUL.md、MEMORY.md和skills/由Hermes直接管理——您可以手动编辑SOUL.md,但其余文件由代理本身处理。⁴
• Hermes是OpenClaw的继任者。 如果您正在迁移,hermes claw migrate会自动导入30多类状态。⁵
• 服务质量取决于您的辅助模型。 视觉、网页摘要、压缩和内存刷新都使用独立的辅助LLM。默认情况下,通过自动检测使用Gemini Flash(OpenRouter → Nous → Codex)——如果上述都未配置,这些功能会静默降级,直到您将辅助槽位指向主提供商为止。⁴

下方每个章节均以上游文档hermes-agent.nousresearch.com/docs及源码树github.com/NousResearch/hermes-agent为依据。每个事实性论断都附有脚注,指向其来源的具体上游页面。

选择您的路径

Hermes 工作原理：心智模型

Hermes 围绕一个统一的对话循环构建，任何入口点都可以调用该循环。入口点包括 CLI（cli.py）、消息网关（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. 使用三种 API 模式之一调用提供商：chat_completions、codex_responses 或 anthropic_messages³
4. 通过 model_tools.py 和中央工具注册表（tools/registry.py）分发返回的工具调用³
5. 持续循环直到模型生成最终响应，然后将会话持久化到支持 FTS5 的 SQLite 中³

理解这个循环至关重要，因为每个功能——个性、记忆、skills、压缩、降级回退——都挂载在其中某个阶段上。当您查看某个配置项想弄清它的作用时，答案通常是”它是上述循环中第 1、2、3 或 4 阶段的一个调节旋钮”。

平台无关的核心。 同一个 AIAgent 类服务于 CLI、网关、ACP、批处理和 API 服务器。平台差异体现在入口点，而非代理本身。³ 这就是为什么相同的斜杠命令在终端和 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 把某项数据存在哪里”，答案就在这些文件中。

安装

一键安装脚本适用于 95% 的用户。它会自动处理 Python、uv、Node.js、ripgrep、ffmpeg、仓库克隆、虚拟环境以及全局 hermes 命令的配置。⁷

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

支持 Linux、macOS、WSL2 和 Android/Termux（安装脚本会自动检测 Termux 并切换到经过测试的 Android 软件包）。⁷ 原生 Windows 不受支持——请安装 WSL2 后在其中运行上述命令。⁷

安装完成后：

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

唯一的前置依赖是 git。安装脚本会通过 uv 自动配置 Python 3.11（无需 sudo）、Node.js v22（用于浏览器自动化和 WhatsApp 桥接）、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 会准确告知缺失的依赖及修复方法。⁷ 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，而该库依赖的 ctranslate2 wheels 并未发布 Android 版本。⁷

认证与提供商

Hermes 支持约 19 个一流提供商以及自定义端点，并提供三条不同的认证路径。以下是完整的认证体系，按路径组织，方便您找到与您手头资源匹配的方式。

三条认证路径

Hermes 中的每个提供商都遵循以下三种认证模式之一：

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

完整提供商矩阵

以下是一流提供商的完整列表，以及每个提供商的具体配置流程。²

Anthropic：三种认证方式

Anthropic 单独成节，因为 Hermes 支持三条不同的路径接入 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 不支持经典个人访问令牌（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（全球 + 中国端点）和阿里云，使用专用的 provider ID。²

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

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

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

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

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

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

Z.AI 自动检测端点。 使用 z.ai/GLM 提供商时，Hermes 会探测多个端点（全球版、中国版、coding 变体），找到能接受您 API key 的那一个。可用端点会自动缓存 — 大多数用户无需配置 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 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，它是主模型、提供商和 base 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 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 — 带图形界面的桌面应用：

从 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 提供商扩展背后的架构变化：不再需要修改核心代码来添加提供商，而是发布一个插件。

上下文长度检测

按上游文档的说法，有两个设置经常被混淆：²

• 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 通过多源解析链来检测上下文窗口：config 覆盖 → 自定义提供商按模型 → 持久缓存 → 端点 /models → Anthropic /v1/models → OpenRouter API → Nous Portal → models.dev（社区维护的注册表，覆盖 3800+ 模型）→ 回退默认值（128K）。² 该系统是 provider-aware 的，因此同一个模型在不同服务方下可能有不同的上下文上限（例如 claude-opus-4.6 在 Anthropic direct 上是 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 使用轻量级”辅助”模型处理边缘任务：图像分析、网页摘要、浏览器截图分析、危险命令审批分类、上下文压缩、会话搜索摘要、技能匹配、MCP 工具分发以及内存清理。⁴ 默认情况下，这些任务通过自动检测使用 Gemini Flash（OpenRouter → Nous → Codex）。

您可以为每个辅助任务配置使用哪个模型和提供商。 每个辅助槽都使用相同的三个旋钮：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中看不到的全局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密钥、bot tokens、密码）→ .env - 其他所有内容（model、terminal backend、压缩设置、memory限制、toolset）→ config.yaml

可以在config.yaml中通过shell风格的插值引用密钥：⁴

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

管理配置

hermes config                # View current configuration
hermes config show           # Same as above
hermes config edit           # Open config.yaml in your editor
hermes config set KEY VAL    # Set a specific value
hermes config 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种语言：简体中文、日语、德语、西班牙语、法语、乌克兰语和土耳其语。¹⁸ 目前文档仅本地化为zh-Hans。语言环境从LC_ALL/LANG环境变量或config.yaml中显式的locale:键解析。英语仍为默认语言，对于翻译尚未覆盖的任何字符串，英语为权威来源。

Profile——多个隔离的Hermes实例

Profile让您拥有多个隔离的Hermes实例，每个实例都有自己的配置、会话、skill、memory和gateway PID。这就是您并排运行”work Hermes”和”personal 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 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 讨论中。⁶

斜杠命令

斜杠命令在活动聊天会话（CLI或消息平台）内运行。它们由hermes_cli/commands.py中共享的COMMAND_REGISTRY分发，这就是为什么大多数命令在不同界面上的工作方式完全相同。⁹

会话控制

配置与模型

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

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

工具、技能与信息

动态技能斜杠命令

每个已安装的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

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

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

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

前缀匹配

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

消息平台专属命令

有些命令仅在消息平台上可用（Telegram、Discord、Slack、WhatsApp、Signal、Email、Home Assistant）：⁹

• /status——显示会话信息
• /sethome（别名/set-home）——将当前聊天标记为平台主目录
• /approve [session|always]——批准待处理的危险命令
• /deny——拒绝待处理的危险命令
• /update——将Hermes Agent更新至最新版本
• /commands [page]——浏览所有命令和技能（分页显示）

还有一些是CLI专属：/skin、/tools、/toolsets、/browser、/config、/cron、/skills、/platforms、/paste、/statusbar、/plugins。⁹

工具与工具集

Hermes 内置了广泛的工具注册表，涵盖网络搜索、浏览器自动化、终端执行、文件编辑、内存、委托、RL 训练、消息投递、Home Assistant 集成等。¹⁰ 工具被组织为逻辑性的工具集（toolset），可按平台启用或禁用。

高层级类别

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

管理工具

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

工具也可以在会话进行中通过 /tools disable <name> 和 /tools enable <name> 进行切换，这会重置会话以使新的工具集生效。⁹

终端后端

terminal 工具可在六种不同环境中执行命令：¹⁰

通过 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 后端（推荐用于安全场景——智能体无法修改自己的代码）：¹⁰

terminal:
  backend: ssh

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

Docker 后端：

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

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

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

设置 container_persistent: true 后，已安装的软件包、文件和配置可在多次会话间保留。¹⁰

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

后台进程

terminal 工具支持后台执行，并提供显式的进程管理：¹⁰

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

多智能体 Kanban（v0.13.0+）

v0.13.0 将多智能体协作变为一等原语：一个持久化的 Kanban 看板，跨智能体、跨重启地追踪任务、状态和工作者身份。¹⁸ 正是这个看板让一群 Hermes worker 真正完成工作，而不是卡在断掉的交接上。

Kanban 看板天然地与 /goal（锁定目标的 Ralph 循环）在目标侧配合，并与现有的 delegate_task 工具在生成语义上配合。最终形成的 swarm 模式，让每个智能体共享同一份关于”接下来做什么、谁在做、卡在哪里”的事实来源。

Skills 系统

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

所有 skills 都位于 ~/.hermes/skills/——主目录与事实来源。全新安装时，捆绑的 skills 会从仓库复制过来。通过 hub 安装的 skills 和智能体创建的 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

## 验证
如何确认其生效。

条件激活

skill可以根据可用的工具来显示或隐藏自身。这对于回退skill最为有用——只在高级工具不可用时才出现的免费或本地替代方案：¹¹

示例:内置的duckduckgo-search skill使用fallback_for_toolsets: [web]。当您设置了FIRECRAWL_API_KEY时,web toolset可用,代理会使用web_search——DuckDuckGo skill保持隐藏。如果没有API密钥,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 tap(无需配置即可浏览):openai/skills、anthropics/skills、VoltAgent/awesome-agent-skills、garrytan/gstack。¹¹

安全扫描

所有从hub安装的skill都会经过安全扫描器,检查数据外泄、提示注入、破坏性命令、供应链信号等威胁。¹¹

信任级别:¹¹

--force可以为社区skill覆盖非危险性策略阻止。但它不能覆盖dangerous扫描判定。¹¹

外部skill目录

您可以让Hermes扫描本地skill目录之外的其他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的前缀缓存以提升性能。会话期间所做的更改会立即持久化到磁盘,但要到下一次会话才会出现在系统提示中。¹²

应保存的内容

应保存这些(代理会主动执行):¹² - 用户偏好: “I prefer TypeScript over JavaScript” → user - 环境事实: “This server runs Debian 12 with PostgreSQL 16” → memory - 纠正: “Don’t use sudo for Docker commands, user is in docker group” → memory - 约定: “Project uses tabs, 120-char line width, Google-style docstrings” → memory - 已完成的工作: “Migrated database from MySQL to PostgreSQL on 2026-01-15” → memory

应跳过这些:¹² - 琐碎或显而易见的信息 - 容易重新发现的事实 - 原始数据转储(对记忆来说太大) - 仅与会话相关的临时信息 - 已存在于上下文文件中的信息

会话搜索

除了MEMORY.md和USER.md,代理还可以使用session_search工具搜索过去的对话。所有CLI和消息会话都存储在SQLite(~/.hermes/state.db)中,并支持FTS5全文搜索。查询会返回相关的过往对话,并通过Gemini Flash进行摘要。¹²

外部记忆提供方

对于超出MEMORY.md和USER.md范围的更深层持久化记忆,Hermes内置了八个外部记忆提供方插件: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(或自定义profile使用$HERMES_HOME/SOUL.md)自动播种默认的SOUL.md。已存在的用户文件永远不会被覆盖。Hermes仅从HERMES_HOME加载SOUL.md——不会查找当前工作目录。这使得个性在跨项目时表现可预测。¹³

SOUL.md应包含什么

用于持久的语气和个性指引:¹³ - 语气 - 沟通风格 - 直率程度 - 默认交互方式 - 风格上需要避免的内容 - Hermes应如何处理不确定性、分歧与歧义

不太适合用于:¹³ - 一次性的项目指令 - 文件路径 - 仓库约定 - 临时性的工作流细节

这些内容属于AGENTS.md,而非SOUL.md。

SOUL.md与AGENTS.md的区别

这是Hermes身份管理中最重要的区分:¹³

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

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

一条实用的规则:如果某项内容应当跟随您到任何地方,它属于SOUL.md;如果它属于某个项目,则属于AGENTS.md。¹³

内置个性

Hermes自带多种内置个性,您可以通过/personality切换:¹³

自定义个性写入config.yaml:¹³

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

然后通过/personality codereviewer切换。

SOUL.md与/personality的区别

SOUL.md是基线声音。/personality是会话级别的覆盖层。¹³建议保留一个务实的默认SOUL.md,然后在辅导对话中使用/personality teacher,或在头脑风暴时使用/personality creative。

Nous Tool Gateway(v0.10.0+)

自Hermes Agent v0.10.0(2026-04-16)起,付费的Nous Portal订阅用户可通过其现有Portal凭证获得对一组精选工具的托管访问——无需额外管理API密钥。²⁰ Hermes CLI本身仍保持MIT许可并完全开源。变化在于您的Portal认证现在不仅仅解锁模型推理。

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、skill、记忆、messaging gateway、cron、MCP、本地仪表板、面向每个提供方的BYOK)无需向任何人付费即可端到端使用。v0.10.0为已经付费使用Nous Portal的用户增加了一条便捷路径——并未从免费路径中移除任何东西。

Messaging Gateway

Hermes可作为长期运行的gateway进程,通过单个gateway进程连接20个消息平台: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,以及一个通用的Webhook适配器。^3191718 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插件挂钩。¹⁸

设置

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

交互式设置会引导您完成各平台的连接:API令牌、机器人ID、频道映射、允许列表。⁶

消息流转方式

来自上游架构文档:³

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

每个消息平台都通过与CLI相同的AIAgent对话循环运行。这就是为什么斜杠命令在两处的工作方式完全一致,以及为什么在Telegram中调度的cron任务可以将其输出投递到Discord——平台差异仅存在于边缘层。³

用户授权与配对

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系统,任务为agent task,而非shell命令。每个计划任务都通过一个全新的AIAgent运行,使用配置好的提示词、可选附加的skill,并将结果投递到任意平台:³⁶

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

或者在消息聊天中以对话方式创建:

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

agent会通过其工具设置cron任务。任务持久化保存于JSON中,并在重启后保留。³

MCP 集成

Hermes 支持将 Model Context Protocol 同时作为客户端和服务端使用:⁶

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

hermes mcp add <name> --url https://example.com/mcp
hermes mcp add <name> --command npx --args "-y,@modelcontextprotocol/server-github"
hermes mcp list
hermes mcp test <name>
hermes mcp remove <name>
hermes mcp configure <name>   # Toggle individual tool selection

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

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

作为服务端 — 将 Hermes 对话暴露给其他 agent:

hermes mcp serve
hermes mcp serve -v    # Verbose

上下文压缩

Hermes 会自动压缩长对话,以保持在所用模型的上下文窗口内。压缩摘要器是一次独立的 LLM 调用 — 您可以将其指向任何 provider 或端点。⁴

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 处理涉及大量工具调用的复杂任务时,可能在毫无察觉的情况下耗尽其迭代预算(默认:90 轮)。预算压力机制会自动向模型发出提示:⁴

流式超时

LLM 流式连接有两层超时机制,会针对本地 provider(localhost、局域网 IP)自动调整:⁴

之所以将本地端点的套接字读取超时提升到 30 分钟,是因为本地 LLM 在大上下文场景下,可能需要数分钟完成 prefill,才能产出第一个 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 现已具备完整的后台进程可观测性层。¹⁵

可插拔 Context Engine(v0.9.0+)

上下文管理现在通过 hermes plugins 成为可插拔的槽位。可换入自定义 context engine,以控制 agent 每轮所见的内容 — 过滤、摘要,或注入特定领域的上下文。¹⁶ 这将上下文策略与核心 agent 循环解耦,从而允许按项目或按领域进行上下文定制。

备份与恢复(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 安全问题,并将一项默认设置调整为对用户更有利的方向。¹⁸

如果您在维护 Hermes 部署,请将 v0.13.0 视为一次与安全相关的升级,而非单纯的功能更新。Discord 跨服务器绕过及两处 TOCTOU 窗口在更早版本上均可被利用。

面向实践者的架构

本节面向那些希望了解底层运作机制的读者，以便他们能够调试、扩展或推理性能。本节是上游架构文档的综合。³

入口点 → 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” 是上游仓库的 tool 注册表总数——即 Hermes 附带源代码的所有 tool，涵盖每一个 toolset。您实际运行的 CLI 在启动横幅中会显示一个较小的数字（我用来验证本指南的安装报告为 28 tools / 89 skills）。这并非缺陷。许多 toolset 都是可选启用的，必须在 config.yaml 的 toolsets: 下显式启用——例如消息平台适配器、浏览器自动化、较重的爬取工具等。注册表总数代表”可用范围”，横幅中的数字代表”当前 profile 中已启用的范围”。可使用 hermes tools --list 查看哪些 toolset 处于活动状态，并通过 ~/.hermes/config.yaml 中的 toolsets: 块（或在运行的会话中使用 /tools list / /tools enable <name> / /tools disable <name>——移除 tool 会触发会话重置，让 agent 重建其 tool 清单）启用或禁用各个 toolset。

三种 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. 面向 tool 的行为指引
3. 记忆/用户上下文（MEMORY.md、USER.md）
4. skill 指引
5. 上下文文件（AGENTS.md、.cursorrules）
6. 时间戳
7. 平台特定的格式提示
8. 可选的系统提示叠加层，例如 /personality

SOUL.md 是基础——其他一切都建立在它之上。¹³

会话存储

基于 SQLite 的会话存储，配合 FTS5 全文搜索。会话具备血缘追踪（跨压缩的父子关系）、按平台隔离，以及具有争用处理的原子写入。³

插件系统

三种发现来源：~/.hermes/plugins/（用户）、.hermes/plugins/（项目）以及 pip 入口点。插件通过上下文 API 注册 tool、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 个源目录的 skill、默认模型、自定义 provider、MCP 服务器、消息平台令牌与白名单（Telegram、Discord、Slack、WhatsApp、Signal、Matrix、Mattermost）、agent 默认设置（推理强度、压缩、人类延迟、时区、沙箱）、会话重置策略、审批规则、TTS 配置、浏览器设置、tool 设置、exec 超时、命令白名单、gateway 配置以及来自 3 个来源的 API 密钥。⁶

已归档以供手动审阅： cron 任务、插件、hook/webhook、memory 后端（QMD）、skill 注册表配置、UI/身份标识、日志、多 agent 配置、通道绑定、IDENTITY.md、TOOLS.md、HEARTBEAT.md、BOOTSTRAP.md。⁶

API 密钥解析按优先级顺序检查三个来源：config 值 → ~/.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

更新日志

参考资料