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 方案选择
- WSL2 安装 Hermes:适合个人开发机、需要直接访问 WSL 文件系统和 Windows 上 LM Studio 的场景。Hermes 在 WSL Linux 环境运行,配置与数据放在 WSL 用户目录的
~/.hermes/。 - Docker 运行 Hermes:适合常驻 Gateway、服务化部署和隔离运行。容器中的用户数据通过
/opt/data持久化;升级 Hermes 镜像不应丢失配置、密钥和会话。 - 本地模型跨边界访问:Hermes 在 WSL2、LM Studio 在 Windows 时,两者之间必须先有可达的 HTTP 网络路径;Hermes 在 Docker 时,Windows 主机通常通过
host.docker.internal访问。[4][5]
不要让两个 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 先区分三类“记忆/检索”
- Hermes 内置记忆:
MEMORY.md、USER.md存储少量长期事实;session_search查询 Hermes 自己的历史对话。它们不是对任意 PDF、网页或企业知识库自动切块、建向量索引的通用文档 RAG。[7] - 外部 Memory Provider:通过
hermes memory setup配置语义记忆、自动抽取、跨会话检索等能力。当前文档列出的提供方包括 OpenViking、Mem0、Hindsight、Holographic、RetainDB、ByteRover、Supermemory 等;通常只有一个外部提供方同时启用,但它与内置记忆并存。[8] - 文档 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]
部署流程:
- 在独立 Python 环境或容器中安装并初始化 GraphRAG 项目,配置输入目录、LLM、embedding 模型和索引输出目录;遵循所选版本的官方 Quickstart,不要复用 Hermes 管理的 Python 虚拟环境。
- 先对小样本生成索引,核对实体、关系、社区摘要及 source mapping,再估算扩大范围后的调用量和费用。
- 将 GraphRAG 的查询接口包装成独立 MCP server(或在已有 MCP 服务中增加工具)。普通检索建议分开暴露:
search_local(query):围绕具体实体/局部关系回答细节问题;search_global(query):利用社区摘要汇总全局主题;get_sources(result_id):返回引用片段、文件、页码或原文位置。
- 在 Hermes 仅启用必要的只读工具:
mcp_servers:
graphrag:
url: "http://graphrag-mcp:8001/mcp"
tools:
include:
- search_local
- search_global
- get_sources
resources: false
prompts: false
- 用
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 安全检查清单
- 先审核服务端,再连接:
stdio会在 Hermes 主机启动第三方可执行程序;检查仓库来源、依赖、启动参数、更新策略及权限。官方目录经过目录级审查不等于第三方代码绝对安全。 - 最小权限:文件 Server 限定到项目目录;金融、客户数据、写操作接口优先用
tools.include白名单;未使用时禁用resources、prompts和服务本身。 - 管理凭证:不要把 Token 写进公开 YAML、README 或版本库。使用
.env的环境变量占位符或 OAuth;只向 stdio server 传入它需要的env,不要无差别转发整个 Shell 环境。 - 把工具结果视为不可信输入:MCP 返回的文档/网页内容可能含提示词注入;Agent 不应仅凭工具结果执行高风险命令、审批密钥读取或改变安全配置。
- 区分读写工具:远端 Server 若不受自己控制,可设
trust: untrusted,让写操作经过审批;不要仅凭 Server 声称的readOnlyHint判断安全。只有确认同一服务内工具并发互不影响时,才启用supports_parallel_tool_calls: true。 - 网络与 TLS:HTTP Server URL 必须是实际 MCP endpoint,而非产品主页;不要用
ssl_verify: false绕过证书错误。容器部署时,服务间使用 Docker 网络中的服务名;Hermes 容器里的localhost只指向 Hermes 容器。 - 检查真实暴露范围:MCP Server 可执行任意自身权限范围内的操作。Hermes 的工具过滤是减少暴露面,不是沙箱;高风险工具还应由后端 ACL、只读账号和网络隔离约束。
- 诊断:
hermes mcp list查看配置,hermes mcp test <name>测试服务,/reload-mcp刷新会话;检查hermes logs中的连接错误、鉴权状态和启动日志。[10][11]
参考来源
[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