Hermes 的使用

Nous Research 的 Hermes Agent 部署与配置实践。内容依据官方文档整理,核对日期:2026-09-27。。

一、Hermes Agent 架构

Hermes 是以大语言模型为推理核心、可以调用工具并在本地保存会话状态的 Agent。它不是一个模型本身:模型由云端 API 或本地推理服务提供,Hermes 负责提示词组装、模型请求、工具调用、上下文维护和多种交互入口。[1][2]

flowchart LR
    U[用户] --> E[交互入口:CLI / TUI / 消息网关 / ACP]
    E --> A[Agent 主循环]
    A --> P[模型提供方解析]
    P --> L[云端 LLM 或本地 OpenAI 兼容服务]
    L --> A
    A --> T[工具注册表与工具集]
    T --> B[内置工具 / MCP 服务 / 终端后端]
    B --> A
    A <--> S[SQLite 会话状态与 FTS5 搜索]
    A <--> M[MEMORY.md、USER.md 与可选外部记忆插件]
    A <--> K[Skills:按需加载的操作流程]
子系统 作用
入口层 CLI/TUI 适合交互;Gateway 连接 Telegram、Discord 等平台;ACP 用于 IDE 集成。
Agent 主循环 构建系统提示词、请求模型、执行工具调用、接收结果,再决定继续调用还是回答。
Provider 统一解析服务商、模型标识、API 协议、端点和凭证;可切换云端模型或自托管模型。
工具与执行环境 工具注册表提供文件、网页、终端等能力;MCP 用于连接外部工具;终端可在本机、Docker 或远端运行。
状态与记忆 SQLite 保存会话并支持 FTS5 全文检索;MEMORY.md/USER.md 保存有限的长期记忆;外部 Memory Provider 可添加语义检索或知识图谱能力。
Skills 与插件 Skills 为按需调用的流程说明;插件可扩展工具、记忆提供方、上下文引擎等。

一次 Agent 工具调用:用户提出目标 → 模型决定是否调用工具 → Hermes 分发工具请求 → 工具结果返回模型 → 模型继续执行或给出结论。Hermes 提供执行框架,但能否可靠使用工具仍取决于模型及推理服务对 tool calling 的支持。[2][3]

二、部署方案:WSL2 与 Docker

2.1 方案选择

不要让两个 Hermes Gateway 同时写同一个 HERMES_HOME。个人使用可选 WSL2 或 Docker 其中一种持有该数据目录;如需迁移,先停止旧实例并备份。[4]

2.2 在 WSL2 中安装并启动

在 WSL2 的 Linux 发行版终端中执行:

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
source ~/.bashrc
hermes --version
hermes setup

安装程序会准备 Hermes 所需运行环境。首次运行 hermes setup 完成模型、工具等配置;以后可分别用 hermes model、hermes tools 修改。启动交互会话:

hermes

如要运行消息网关,WSL 场景优先使用前台进程:

hermes gateway run

需要关闭终端后继续运行时,可在 WSL 中用 tmux:

tmux new -s hermes 'hermes gateway run'
# 重新连接:tmux attach -t hermes

官方 FAQ 提醒,WSL 的 systemd 服务可能无法在休眠、发行版重启或 Windows 空闲关闭后可靠存活;稳定自启动可用 Windows 任务计划程序启动 WSL 命令。[4]

2.3 Docker 部署 Hermes Gateway

先确认 Docker Engine/Docker Desktop 正常运行。在 WSL2 中使用 Docker Desktop 时,建议把 Hermes 数据放在 Docker named volume,避免 SQLite 数据库跨 Windows 文件系统挂载时的文件锁/WAL 兼容问题。

首次交互配置:

docker volume create hermes-data
docker run -it --rm \
  -v hermes-data:/opt/data \
  nousresearch/hermes-agent:latest setup

按提示配置提供方和 Gateway。长期运行:

docker run -d \
  --name hermes \
  --restart unless-stopped \
  -v hermes-data:/opt/data \
  nousresearch/hermes-agent:latest gateway run

只通过 Telegram/Discord 等消息平台使用时,通常不必向宿主机发布端口。若确实需要 OpenAI 兼容 API,必须在 Hermes 配置中显式启用 API Server,并配置认证密钥;再只绑定所需网络接口。API Server 默认关闭。不要把未认证的 API 或 Dashboard 直接暴露到公网。[5]

需要在运行容器中调整配置时:

docker exec -it hermes hermes model
docker exec hermes hermes tools
docker logs -f hermes

官方容器把可变数据放在 /opt/data,程序安装树则是镜像内容;升级应拉取新镜像并重建容器,而不是在容器内修改 Hermes 源码。[5]

Docker 数据目录注意事项:state.db 默认使用 SQLite WAL。Docker Desktop/Windows 文件挂载有跨 VM 文件系统语义差异;使用 named volume 可避免常见的 9p/virtiofs WAL 风险。若必须把 Windows 文件夹 bind mount 到 /opt/data,停止所有 Hermes 进程后备份,并确认 Hermes 的数据库日志模式/hermes doctor 状态;不要同时启动多个 Gateway 写同一目录。[5]

2.4 云端模型接入

可使用 OpenRouter、OpenAI、Anthropic 等提供方。最简单、也最不易写错的方式是在安装环境中运行交互式配置向导:

hermes model

选择服务商、完成 API Key/OAuth 认证,再从模型列表中选定模型。Hermes 把非秘密的模型和端点设置保存到 ~/.hermes/config.yaml,API Key 等秘密保存在 ~/.hermes/.env 或对应凭据存储。也可首次使用完整向导:

hermes setup

以 OpenRouter 为例,命令行设置密钥(将占位内容替换为用户自己的 Key):

hermes config set OPENROUTER_API_KEY "YOUR_OPENROUTER_API_KEY"
hermes model

模型 ID 取决于服务商及其当前模型目录,不要照抄已经过期的模型名。配置后先用短问题验证:

hermes chat -q "只回复:模型接入正常"

在 Docker 部署中,上述命令需要在容器内执行,且必须使用与 Gateway 相同的 /opt/data 持久化卷。密钥切勿写入文档、Git 仓库或明文 shell 历史。[3][5]

2.5 Windows LM Studio 接入 WSL2 Hermes

LM Studio(Windows):在 Developer 页面加载模型并启动本地 Server,默认 OpenAI 兼容 API 端点为 http://localhost:1234/v1。模型应支持工具调用;否则 Hermes 可能只收到模型输出的伪 JSON 文本,而不会真正执行工具。Hermes Agent 的工具使用建议上下文长度至少约 64K tokens;应在 LM Studio 中为实际模型设置可用的 context length,不能只在 Hermes 中填写一个服务端没有实现的值。[3][6]

网络模式 A:WSL2 mirrored networking(推荐)

Windows 11 22H2 及更高版本可在 Windows 用户目录的 .wslconfig 中启用 mirrored networking:

[wsl2]
networkingMode=mirrored

从 PowerShell 重启 WSL:

wsl --shutdown

重新打开 WSL 后测试:

curl http://localhost:1234/v1/models

如本机 Hyper-V 防火墙阻止连接,需按最小端口范围检查防火墙规则。不要为了方便而把模型 Server 无保护地监听在公网网卡上。[3]

网络模式 B:WSL2 NAT / Windows 10

在 WSL 中取得 Windows 主机的默认网关地址:

ip route show | awk '/default/ {print $3}'

假设输出 172.29.192.1,则在 LM Studio 的 Developer/Server 设置中启用 Serve on Network,必要时配置 Windows 防火墙允许 WSL 子网访问 TCP 1234。从 WSL 测试:

curl http://172.29.192.1:1234/v1/models

使用当前机器实际的网关 IP,不能假定示例 IP 固定不变。NAT 模式下仅监听 Windows 的 127.0.0.1 通常无法从 WSL 访问。[3]

将 LM Studio 配置为 Hermes 的模型提供方:

hermes model

选择 LM Studio,确认 API 地址(mirrored 模式用 http://localhost:1234/v1;NAT 模式用 http://<Windows主机IP>:1234/v1),并选中已加载模型。若 LM Studio 开启了 Server Authentication,按向导输入 Key。等价的配置结构如下(模型名必须与 LM Studio 的模型标识相符):

model:
  provider: lmstudio
  base_url: http://localhost:1234/v1
  default: <LM_STUDIO_MODEL_ID>

检查服务端可达和模型目录:

curl http://localhost:1234/v1/models
hermes doctor
hermes chat -q "请调用一个只读工具列出当前目录文件,并概括结果。"

NAT 模式的 base_url 换成 Windows 主机网关 IP。若网络检查成功但工具不执行,应检查模型的 tool-calling 支持、LM Studio 版本、上下文长度与 Hermes 启动日志。LM Studio 支持 OpenAI 兼容 Chat Completions;其 API Key 只有在服务端认证开启时才需要。[3][6]

Hermes 本身运行在 Docker、LM Studio 运行在 Windows 时:模型 URL 一般改为 http://host.docker.internal:1234/v1,并在容器内验证 curl http://host.docker.internal:1234/v1/models。Hermes 在容器中访问 localhost 指容器自身,不是 Windows 主机。[5]

三、RAG 与 GraphRAG 配置

3.1 先区分三类“记忆/检索”

  1. Hermes 内置记忆:MEMORY.md、USER.md 存储少量长期事实;session_search 查询 Hermes 自己的历史对话。它们不是对任意 PDF、网页或企业知识库自动切块、建向量索引的通用文档 RAG。[7]
  2. 外部 Memory Provider:通过 hermes memory setup 配置语义记忆、自动抽取、跨会话检索等能力。当前文档列出的提供方包括 OpenViking、Mem0、Hindsight、Holographic、RetainDB、ByteRover、Supermemory 等;通常只有一个外部提供方同时启用,但它与内置记忆并存。[8]
  3. 文档 RAG / GraphRAG:由独立知识库负责文档接入、切分、embedding、向量/图索引、检索及来源追踪;Hermes 通过 MCP 工具调用它。GraphRAG 是检索/索引方案,不是 Hermes 的配置选项或内置模型能力。[5][9]

架构关系:

flowchart LR
    D[PDF / Markdown / 网页 / 数据库] --> I[独立索引管线]
    I --> V[向量索引:语义/关键词混合检索]
    I --> G[知识图谱:实体、关系、社区摘要]
    H[Hermes Agent] -->|MCP: search_documents| V
    H -->|MCP: search_local / search_global| G
    V --> R[带来源的片段与元数据]
    G --> R
    R --> H
    H --> L[最终回答与引用]

3.2 普通文档 RAG:通过 MCP 接入

一种可维护的部署方式是让 RAG 服务独立提供 MCP endpoint,然后在 Hermes 的 config.yaml 注册它。服务端工具名称是示意;必须替换为你部署的 MCP 服务真实 URL 和真实工具名:

mcp_servers:
  knowledge_rag:
    url: "http://rag-service:8000/mcp"
    tools:
      include:
        - search_documents
        - get_document
      resources: false
      prompts: false

HTTPS 远程服务可使用 OAuth 或由环境变量注入的授权头;避免在配置中硬编码生产凭证。修改后从正在运行的会话执行 /reload-mcp,或重新启动 Hermes。终端中也可检查连接:

hermes mcp list
hermes mcp test knowledge_rag

RAG 服务负责提供稳定的数据管线:文档解析 → 清理/分块 → embedding → 向量或混合索引 → 查询重排 → 返回相关片段。MCP 查询结果建议至少包括 text、文档标题、稳定来源 URI、页码/段落定位和片段 ID;要求模型基于这些证据作答,检索不到时明确表示没有找到,而不是补写事实。

若使用 Hermes 外部记忆提供方做跨会话语义记忆,可运行:

hermes memory setup
hermes memory status

例如 Hindsight 提供知识图谱式记忆与多策略召回,安装步骤为:

hermes plugins install hindsight
hermes memory setup

这适合检索 Agent 学到的事实、实体关系及会话记忆;它与索引整个业务文档库的 RAG 不是同一工作流。[8]

3.3 GraphRAG:索引独立部署,MCP 暴露查询

Microsoft GraphRAG 的处理重点是从非结构化文本中抽取结构化实体/关系、构造知识图谱并建立检索数据。索引过程可能需要大量模型调用,成本高,应先选少量代表性文档试跑并评估结果。Microsoft 将其定位为研究项目/方法,不是正式支持的 Microsoft 产品。[9]

部署流程:

  1. 在独立 Python 环境或容器中安装并初始化 GraphRAG 项目,配置输入目录、LLM、embedding 模型和索引输出目录;遵循所选版本的官方 Quickstart,不要复用 Hermes 管理的 Python 虚拟环境。
  2. 先对小样本生成索引,核对实体、关系、社区摘要及 source mapping,再估算扩大范围后的调用量和费用。
  3. 将 GraphRAG 的查询接口包装成独立 MCP server(或在已有 MCP 服务中增加工具)。普通检索建议分开暴露:
    • search_local(query):围绕具体实体/局部关系回答细节问题;
    • search_global(query):利用社区摘要汇总全局主题;
    • get_sources(result_id):返回引用片段、文件、页码或原文位置。
  4. 在 Hermes 仅启用必要的只读工具:
mcp_servers:
  graphrag:
    url: "http://graphrag-mcp:8001/mcp"
    tools:
      include:
        - search_local
        - search_global
        - get_sources
      resources: false
      prompts: false
  1. 用 hermes mcp test graphrag 检查发现结果;在会话中测试一个局部实体问题和一个跨文档全局问题,并检查答案引用能否回溯到原文。

Hermes 并不会因为 endpoint 名称叫 GraphRAG 就自动生成知识图谱。MCP 服务必须实现上述工具契约,并自行调用 GraphRAG API/查询引擎;这是需要开发或选型完成的集成层。[5][9][10]

四、MCP 配置与安全注意点

4.1 基本配置

MCP 让 Hermes 作为 Host/Client 连接外部 MCP Server。Hermes 在启动或重载时发现工具,并将它们注册为普通工具;常见传输为本机子进程 stdio 和远端 HTTP。[10]

stdio 示例:只允许一个项目目录,避免给文件系统 Server 开整个用户主目录权限。

mcp_servers:
  project_files:
    command: "npx"
    args:
      - "-y"
      - "@modelcontextprotocol/server-filesystem"
      - "${workspaceFolder}"
    tools:
      include: [read_file, list_directory, search_files]

远程 HTTP 示例:优先使用服务商支持的 OAuth;如确实使用 Bearer Key,通过环境变量引用秘密。

mcp_servers:
  internal_docs:
    url: "https://mcp.example.org/mcp"
    headers:
      Authorization: "Bearer ${INTERNAL_MCP_TOKEN}"
    tools:
      include: [search_docs, fetch_doc]
      resources: false
      prompts: false

把密钥写入 ~/.hermes/.env:

INTERNAL_MCP_TOKEN=replace-with-your-token

之后执行 hermes mcp test internal_docs 检查连接,必要时运行 hermes mcp configure internal_docs,在当前对话内使用 /reload-mcp 加载改动。[10]

4.2 安全检查清单

参考来源

[1] Hermes Agent 官方仓库与项目介绍:https://github.com/NousResearch/hermes-agent

[2] Hermes Agent 官方架构说明:https://hermes-agent.nousresearch.com/docs/developer-guide/architecture

[3] Hermes Agent 官方模型提供方与本地推理说明(LM Studio、OpenAI 兼容接口、WSL2 网络、工具调用):https://hermes-agent.nousresearch.com/docs/integrations/providers

[4] Hermes Agent 官方安装、平台与 WSL Gateway FAQ:https://hermes-agent.nousresearch.com/docs/getting-started/installation;https://hermes-agent.nousresearch.com/docs/reference/faq#wsl-gateway-keeps-disconnecting-or-hermes-gateway-start-fails

[5] Hermes Agent 官方 Docker 部署:https://hermes-agent.nousresearch.com/docs/user-guide/docker

[6] LM Studio 官方 OpenAI 兼容 API:https://lmstudio.ai/docs/app/api/endpoints/openai;工具调用:https://lmstudio.ai/docs/developer/openai-compat/tools

[7] Hermes Agent 官方记忆说明:https://hermes-agent.nousresearch.com/docs/user-guide/features/memory

[8] Hermes Agent 官方 Memory Providers:https://hermes-agent.nousresearch.com/docs/user-guide/features/memory-providers

[9] Microsoft GraphRAG 官方仓库与 Quickstart:https://github.com/microsoft/graphrag;https://microsoft.github.io/graphrag/get_started/

[10] Hermes Agent 官方 MCP 使用与配置参考:https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp;https://hermes-agent.nousresearch.com/docs/reference/mcp-config-reference

[11] Model Context Protocol 官方规范(安全与信任原则):https://modelcontextprotocol.io/specification/2025-11-25