Hermes Agent 入门（二）：接入 OpenRouter、第三方 API 与本地模型

上一篇我们已经完成了 Hermes Agent 的安装，并且简单了解了 Memory、Skills、Tools 和 Gateway。

但 Hermes 本身并不是一个大模型。

真正负责思考的是背后的 LLM，因此 Hermes 能不能用得舒服，很大程度取决于：

你接了什么模型
+
这个模型的 API 是否兼容
+
模型是否支持 Tool Calling
+
上下文是否足够大

这一篇就专门解决 Hermes 最基础、同时也是最容易踩坑的问题：

怎么给 Hermes 接模型？

本文主要介绍三种比较常见的方案：

Hermes
├── OpenRouter
├── 第三方 OpenAI Compatible API
└── 本地模型
    ├── Ollama
    ├── vLLM
    ├── llama.cpp
    └── LM Studio

内容基于 2026 年 9 月 Hermes Agent 当前版本整理。

---

一、先理解 Hermes 的 Provider

Hermes 并不负责真正生成回答。

完整链路实际上是：

你
 ↓
Hermes Agent
 ↓
Provider
 ↓
LLM
 ↓
返回结果
 ↓
Hermes 判断是否需要调用 Tool
 ↓
继续请求 LLM
 ↓
最终完成任务

例如使用 OpenRouter：

Hermes
 ↓
OpenRouter
 ↓
Claude / GPT / Gemini / DeepSeek / Qwen ...

使用自己搭建的 API：

Hermes
 ↓
https://api.example.com/v1
 ↓
你的模型

使用本地 Ollama：

Hermes
 ↓
http://127.0.0.1:11434/v1
 ↓
Ollama
 ↓
Qwen / Llama / DeepSeek ...

Hermes 官方目前内置了大量 Provider，包括 OpenRouter、Nous Portal、OpenAI Codex、Anthropic、Gemini、DeepSeek、Kimi、MiniMax、NVIDIA NIM、Azure、AWS Bedrock、LM Studio 等。

对于没有官方适配的服务，只要它提供标准 OpenAI Compatible API，一般也可以通过 custom Provider 使用。

---

二、最简单的方式：hermes model

Hermes 已经提供交互式模型配置。

直接运行：

hermes model

然后按照菜单选择 Provider。

例如：

OpenRouter
Custom Endpoint
Anthropic
DeepSeek
Gemini
...

这是目前最推荐的新手配置方式。

因为 Hermes 会帮你正确处理：

Provider
API Base URL
API Key
Model ID
Context Length

而不是自己去修改一堆配置文件。

而且以后想换模型，也不需要重新安装：

hermes model

重新选即可。

Hermes 官方明确支持随时切换 Provider。

---

三、方案一：OpenRouter

如果不想分别注册十几个模型厂商的 API，我个人认为 OpenRouter 是目前比较方便的一种方案。

它的逻辑相当于：

              ┌── Claude
              ├── GPT
Hermes → OpenRouter ── Gemini
              ├── DeepSeek
              ├── Qwen
              └── ...

只需要一个 OpenRouter API Key，就可以切换大量模型。

---

四、配置 OpenRouter

最简单：

hermes model

选择：

OpenRouter

然后按照提示输入 API Key。

OpenRouter 的 API Key 通常类似：

sk-or-v1-xxxxxxxxxxxxxxxx

Hermes 会把 Key 保存到：

~/.hermes/.env

普通模型配置则保存到：

~/.hermes/config.yaml

Hermes 有意把“秘密”和“普通配置”分开保存，避免 API Key 混在普通配置中。

也可以直接运行：

hermes config set OPENROUTER_API_KEY sk-or-xxxxxxxx

Hermes 会自动把它放到正确的位置。

---

五、OpenRouter 的模型名字怎么填？

这是很多人第一次使用时容易弄错的地方。

OpenRouter 通常使用：

厂商/模型

这样的 Model ID。

例如概念上会类似：

anthropic/xxx
openai/xxx
google/xxx
deepseek/xxx

不要只凭模型的显示名称猜。

最保险的方法是直接使用 OpenRouter 提供的真实 Model ID，再在：

hermes model

里面选择对应模型。

如果 Hermes 提示：

model not found

或者：

404

第一件事就是确认 Model ID，而不是先怀疑 Hermes。

---

六、测试 OpenRouter 是否成功

配置完成：

hermes

然后先不要测试复杂 Agent。

先问一个非常简单的问题：

你好，只回复 OK。

如果正常返回：

OK

证明：

Hermes
 ↓
OpenRouter
 ↓
模型

这条最基础的链路已经通了。

接下来再测试 Agent 能力：

帮我查看一下当前系统信息。

或者：

列出当前目录中的文件。

这一步非常重要。

因为：

能聊天

和：

能作为 Agent 正确调用工具

其实是两个不同的问题。

---

七、为什么“聊天正常”不代表 Hermes 能正常用？

比如你接入某个便宜模型。

普通问答：

用户：1+1 等于多少？

模型：2

完全正常。

但是 Hermes 让它调用工具：

请查看当前目录。

模型可能直接输出：

{
  "name": "terminal",
  "arguments": {
    "command": "ls"
  }
}

然后……

没有任何事情发生。

它只是把 Tool Call 当成普通文字输出了。

正常情况应该是：

模型
 ↓
产生标准 Tool Call
 ↓
Hermes 识别
 ↓
执行工具
 ↓
结果重新交给模型

因此，用于 Hermes 的模型最好具备可靠的 Tool Calling 能力。

---

八、Hermes 对上下文有一个非常重要的要求

目前 Hermes Agent 对 Agent 模型要求：

至少 64,000 Token 上下文。

低于这个长度的模型可能直接在启动阶段被拒绝。

原因很好理解。

普通聊天可能只有：

System Prompt
+
你的问题

但 Agent 模式实际上可能是：

System Prompt
+
几十个 Tool Schema
+
Memory
+
聊天历史
+
工具执行结果
+
网页内容
+
文件内容
+
Agent 中间状态

光 Hermes 自身的系统 Prompt 和工具定义，就可能消耗数千 Token。

因此官方把 Agent 模式最低上下文要求设成了约 64K。

这一点尤其影响：

Ollama
llama.cpp
vLLM
LM Studio

这类本地部署。

云 API 通常不用太担心。

---

九、方案二：接第三方 OpenAI Compatible API

这是我认为 Hermes 非常实用的地方。

如果你的 API 支持：

POST /v1/chat/completions

基本就可以尝试直接接入 Hermes。

例如：

API 中转
自建 LiteLLM
vLLM
Ollama
llama.cpp
SGLang
各种第三方模型 API

Hermes 官方直接把这种模式作为一等 Provider 支持：

provider: custom

而不是某种临时兼容方案。

---

十、最推荐的 Custom Endpoint 配置方法

运行：

hermes model

选择：

Custom endpoint

或者类似：

Custom endpoint (self-hosted / VLLM / etc.)

接下来一般需要填写四个东西：

API Base URL
API Key
Model Name
Context Length

例如：

API Base URL:
https://api.example.com/v1

API Key:
sk-xxxxxxxx

Model:
your-model-name

Context:
128000

然后 Hermes 就会保存配置。

---

十一、API 地址一定要注意 /v1

非常经典的错误：

假设服务地址是：

https://api.example.com

OpenAI Compatible API 实际入口却是：

https://api.example.com/v1

那么 Hermes 的 Base URL 应该填：

https://api.example.com/v1

而不是：

https://api.example.com

否则经常出现：

404 Not Found

---

十二、先别急着怪 Hermes，用 curl 测 API

第三方 API 接不上时，我非常推荐先绕过 Hermes。

测试：

curl https://api.example.com/v1/models \
  -H "Authorization: Bearer sk-xxxxxxxx"

如果正常，应该能看到类似：

{
  "data": [
    {
      "id": "model-name"
    }
  ]
}

然后再直接测试 Chat Completions：

curl https://api.example.com/v1/chat/completions \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "model-name",
    "messages": [
      {
        "role": "user",
        "content": "Hello"
      }
    ]
  }'

如果这个请求本身都失败：

Hermes 大概率也不会成功。

这样可以快速判断问题究竟在：

Hermes

还是：

API 服务

---

十三、手动修改 config.yaml

如果比较熟悉 Hermes，也可以直接修改：

~/.hermes/config.yaml

最基础的 Custom Provider 形式类似：

model:
  default: your-model-name
  provider: custom
  base_url: https://api.example.com/v1
  api_key: your-api-key

官方目前也支持这样的 Custom Endpoint 配置方式。

不过这里我还是建议：

新手：
hermes model

熟悉以后：
config.yaml

因为手动修改最容易犯 YAML 缩进错误。

---

十四、API Key 最好不要直接写 config.yaml

虽然 Custom Provider 可以内联 api_key，但长期使用时更建议：

配置
→ config.yaml

密钥
→ .env

例如：

hermes config set OPENAI_API_KEY sk-xxxxxxxx

或者让 hermes model 帮你配置。

这样以后：

备份 config.yaml
上传 Git
复制配置
截图排障

时，不容易顺手把 API Key 泄露出去。

---

十五、多个第三方 API 怎么办？

如果你同时拥有：

本地 Ollama
公司 GPU Server
一个 API 中转
另一台远程 vLLM

不需要每次覆盖同一套 Custom 配置。

Hermes 现在支持：

providers:

定义多个自定义 Provider。

例如：

providers:

  local:
    api: http://127.0.0.1:11434/v1

  gpu:
    api: https://gpu.example.com/v1
    key_env: GPU_API_KEY

  proxy:
    api: https://api.example.com/v1
    key_env: PROXY_API_KEY

这样你的结构就可以变成：

Hermes
├── local
│   └── Ollama
│
├── gpu
│   └── 自建 GPU Server
│
└── proxy
    └── API 中转

这比不停修改 OPENAI_BASE_URL 要干净很多。

---

十六、方案三：使用 Ollama

如果想完全在本机运行：

Hermes
+
Ollama

是比较容易上手的一种组合。

Ollama 默认提供 OpenAI Compatible API：

http://127.0.0.1:11434/v1

因此：

hermes model

选择：

Custom Endpoint

然后填写：

URL:
http://127.0.0.1:11434/v1

模型则填写 Ollama 中真实存在的模型：

ollama list

例如：

qwen...
deepseek...
llama...

---

十七、Ollama 最大的坑：Context

这是使用 Hermes + Ollama 最容易遇到的问题之一。

Hermes 需要：

>= 64000 tokens

但 Ollama 为了节省显存，并不保证默认直接把模型的完整上下文开出来。

因此即使一个模型理论上支持：

128K

Ollama 实际运行时也可能只给它：

4096

或者：

32768

Hermes 官方把这列为本地模型接入最常见的问题之一。

检查：

ollama ps

重点看：

CONTEXT

至少应该达到：

64000

---

十八、给 Ollama 设置 64K Context

一种方法：

OLLAMA_CONTEXT_LENGTH=64000 ollama serve

如果 Ollama 通过 systemd 运行：

sudo systemctl edit ollama.service

加入：

[Service]
Environment="OLLAMA_CONTEXT_LENGTH=64000"

然后：

sudo systemctl daemon-reload
sudo systemctl restart ollama

再检查：

ollama ps

Hermes 官方目前推荐 Agent 模式至少保持 64K 上下文。

---

十九、64K Context 为什么这么吃显存？

Context 并不是免费的。

模型运行时需要保存 KV Cache。

上下文越大：

Context ↑
   ↓
KV Cache ↑
   ↓
显存 / 内存占用 ↑

所以：

4K

能够跑起来的模型，不代表：

64K

也能舒服地运行。

如果显存不够，相比把 Context 降到 8K，我更建议：

换更小模型

因为 Context 小于 Hermes 的需求以后，即使勉强绕过去，Agent 多步骤任务的体验也会变得很差。

---

二十、使用 vLLM

如果有 NVIDIA GPU Server，vLLM 通常更适合作为正式推理服务器。

例如：

vllm serve MODEL_NAME \
  --max-model-len 64000 \
  --enable-auto-tool-choice \
  --tool-call-parser hermes

然后 Hermes：

http://127.0.0.1:8000/v1

官方特别提醒：

如果 Tool Call 只以 JSON 文本形式出现，而没有真正执行，vLLM 需要正确启用 Tool Calling Parser。

也就是说，出现：

{"name":"web_search","arguments":{}}

但没有实际执行时，不一定是模型坏了。

可能只是：

推理服务器没有正确解析 Tool Call。

---

二十一、llama.cpp 也可以

llama.cpp 同样提供 OpenAI Compatible Server。

启动后例如：

http://127.0.0.1:8080/v1

Hermes 直接连接即可。

但要注意 Tool Calling。

官方目前建议 llama.cpp 启动时使用：

--jinja

否则服务器可能完全忽略 API 中的：

"tools": [...]

最终你就会看到模型把 Tool Call 当成普通 JSON 输出。

同时 Context 至少设为：

64000

---

二十二、LM Studio 也能接

如果不想折腾命令行服务器，Windows 或 macOS 用户也可以使用：

LM Studio

开启 API Server 后，一般类似：

http://127.0.0.1:1234/v1

然后 Hermes：

hermes model

选择 Custom Endpoint，填入：

http://127.0.0.1:1234/v1

即可。

LM Studio 从较新的版本已经支持模型 Tool Calling，不过还是建议选择本身经过 Function Calling / Tool Calling 训练的模型。

同时记得在 LM Studio 中把：

Context Length

设置到至少：

64000

---

二十三、WSL 用户注意 localhost

有一种非常经典的环境：

Windows
├── LM Studio / Ollama
│
└── WSL
    └── Hermes

这时：

Hermes 在 WSL
模型服务器在 Windows

不要想当然认为：

127.0.0.1

一定能够连接。

因为传统 WSL2 NAT 网络模式下：

WSL 的 localhost

指的是 WSL 自己，而不是 Windows Host。

所以如果：

curl http://127.0.0.1:11434

显示：

Connection refused

但 Windows 本机明明可以访问 Ollama，那么应该先检查 WSL 与 Windows Host 的网络，而不是 Hermes。

Hermes 官方文档也单独列出了 WSL2 连接 Windows 本地模型服务器的问题。

---

二十四、Hermes 认为 Context 只有 2048 怎么办？

有一些第三方 API：

/v1/models

返回的信息不完整。

Hermes 无法正确识别上下文长度。

于是启动时可能显示：

Context limit: 2048 tokens

但你明明知道模型支持：

128K

这时可以手动指定：

model:
  default: your-model
  provider: custom
  base_url: https://api.example.com/v1
  context_length: 128000

Hermes 的 Context Detection 会优先使用你手动配置的：

model.context_length

然后才会继续尝试 API /models、OpenRouter metadata 等其他来源。

注意：

这里填写的数字必须和服务器真实 Context 一致。

不要模型实际上只有 32K，却骗 Hermes 写成：

128000

这样只会让问题变得更加隐蔽。

---

二十五、出现 401 Unauthorized

这是最好排查的一类问题。

通常就是：

API Key 错误

检查：

hermes config

以及：

~/.hermes/.env

当然：

不要把完整 API Key 发到公开群里。

如果直接 curl API 同样返回：

401 Unauthorized

那么基本就和 Hermes 无关了。

---

二十六、出现 404 Not Found

优先检查三件事：

① Base URL 是否漏了 /v1

② Model ID 是否写错

③ API 是否真的兼容 /v1/chat/completions

比如：

错误：

https://api.example.com


可能正确：

https://api.example.com/v1

其次测试：

curl https://api.example.com/v1/models

---

二十七、出现 429

429 Too Many Requests

一般代表：

限速
额度耗尽
并发过多
Provider 拒绝请求

Agent 和普通聊天相比，会产生更多请求。

一次你以为只是：

帮我查一下服务器问题

实际可能发生：

LLM Request 1
 ↓
Tool Call
 ↓
LLM Request 2
 ↓
Tool Call
 ↓
LLM Request 3
 ↓
Tool Call
 ↓
LLM Request 4

所以便宜但 Rate Limit 特别严格的 API，不一定适合跑 Agent。

---

二十八、模型一直说要调用工具，但就是不调用

表现：

我将查看当前目录。

然后没了。

或者输出：

{
  "tool": "terminal",
  "command": "ls"
}

但 Hermes 完全没有执行。

这通常优先考虑：

模型 Tool Calling 能力

或者：

推理服务器 Tool Parser

而不是 Terminal 权限。

Hermes 官方对几个常见服务器给出的排查方向包括：llama.cpp 检查 --jinja，vLLM 检查自动工具选择和 Tool Call Parser，SGLang 检查对应 Parser，Ollama 则确认所使用模型本身支持 Tool Calling。

---

二十九、怎么判断这个模型适不适合 Hermes？

我通常会做四组测试。

第一组：

只回复“测试成功”。

测试普通 API。

第二组：

查看当前目录有哪些文件。

测试 Tool Calling。

第三组：

查看系统 CPU、内存和磁盘情况，
根据结果告诉我有没有异常。

测试：

Tool
→ Result
→ 再推理

第四组：

调查当前目录里的项目，
判断它是什么项目，
找到启动方式，
但暂时不要修改任何文件。

测试多步骤 Agent。

如果第四组也能比较稳定完成，这个模型才比较适合拿来长期跑 Hermes。

---

三十、不要只看模型跑分

Agent 模型和普通聊天模型的评判方式并不完全一样。

一个模型可能：

写作很好
知识很多
聊天很聪明

但：

Tool Calling 一塌糊涂

那么作为 Hermes 主模型体验还是会很差。

Hermes 更看重：

指令遵循
Tool Calling
上下文
多步骤任务稳定性
代码能力
错误恢复能力

而不仅仅是：

聊天看起来聪不聪明。

---

三十一、我的建议配置

如果只是第一次体验：

Hermes
+
OpenRouter
+
一个主流 Tool Calling 模型

最省事。

如果有自己的 API：

Hermes
+
Custom Endpoint
+
OpenAI Compatible API

性价比通常更好。

如果想完全本地：

Hermes
+
Ollama / llama.cpp / LM Studio
+
支持 Tool Calling 的模型
+
>= 64K Context

如果是服务器长期部署：

Hermes
+
vLLM / SGLang
+
GPU

更适合生产式使用。

---

三十二、推荐的排障顺序

以后 Hermes 模型出现问题，不要乱试配置。

按照下面这个顺序判断：

① API 能不能访问？

↓ curl /v1/models

② API 能不能聊天？

↓ curl /v1/chat/completions

③ Hermes 能不能普通聊天？

↓ hermes

④ Context 是否 >= 64K？

↓

⑤ Tool Calling 正不正常？

↓

⑥ 多轮 Tool Calling 正不正常？

↓

⑦ 最后才测试复杂 Agent

这个顺序非常重要。

否则一个：

API Key 写错

的问题，你可能一路折腾：

Tool
Prompt
Hermes
Docker
模型
网络

折腾几个小时。

---

三十三、Hermes 自己也有诊断工具

如果配置完感觉哪里不正常：

hermes status --all

查看整体配置状态。

进一步检查：

hermes status --deep

目前官方 CLI 已经支持 --all 与 --deep 两种状态诊断方式。

也可以：

hermes doctor

再结合日志判断。

---

三十四、最后总结

Hermes 接模型其实可以浓缩成三个方案。

最省事：

Hermes
 ↓
OpenRouter
 ↓
云端模型

最灵活：

Hermes
 ↓
Custom Endpoint
 ↓
任意 OpenAI Compatible API

最折腾但也最自由：

Hermes
 ↓
Ollama / vLLM / llama.cpp
 ↓
本地模型

无论使用哪一种，记住 Hermes Agent 最重要的三个要求：

API 正常
+
Tool Calling 正常
+
Context >= 64K

满足这三个条件以后，Hermes 才算真正有了一个合格的“大脑”。

如果你只是刚开始玩，我建议：

hermes model

先接 OpenRouter 跑通。

等 Hermes 的：

聊天
工具调用
多步骤任务

全部工作正常以后，再研究本地模型和各种中转 API。

因为对于 Agent 来说：

先保证稳定，再考虑省钱。

一个响应很便宜、但工具调用经常出错的模型，最后往往比一个贵一点但一次能把任务完成的模型更浪费时间和 Token。

---

下一篇

下一篇我们就可以开始进入 Hermes 真正有意思的部分：

《Hermes Agent 入门（三）：Memory、Skills 与“越用越懂你”是怎么实现的》

届时会实际看看：

Memory 保存在哪里？
Hermes 怎么记住用户信息？
什么时候应该写 Memory？
什么时候应该做成 Skill？
Skill 文件是什么结构？
能不能自己写 Skill？
Hermes 所谓“自我改进”到底是怎么回事？

也会做一个实际例子：

第一次：
教 Hermes 如何维护一台服务器

↓

保存成 Memory + Skill

↓

下一次：
只告诉它“检查服务器”

↓

Hermes 自动按照之前总结的流程工作

这样就正式从“会调用工具的 AI”进入“能逐渐积累工作经验的 Agent”。