Hermes Agent 接入 Nbility：把模型 API 换成更顺手的 OpenAI 兼容入口

这是「AI Agent 上手系列」第 2 篇。上一篇我们把 Hermes Agent 跑起来了，这一篇继续做一件真正会影响体验的事：把模型 API 接好，让 Agent 能稳定调用模型、用工具、写文件、查资料、跑命令。

封面：niku 正在帮用户配置 Hermes Agent 的 API 面板

摘要

很多人第一次玩 AI Agent，会卡在一个很现实的问题：

模型到底填哪个？
API Key 放哪里？
Base URL 是不是要带 /v1？
为什么普通聊天还好，一到 Agent 就 token 消耗明显变快？
配完之后怎么确认不是“看起来能用，实际跑任务就报错”？

这篇文章用 Hermes Agent 做例子，记录一次完整的模型 API 接入流程。为了让步骤更通用，我会按「OpenAI 兼容接口」来讲。只要你使用的服务提供了兼容 /v1/chat/completions 的接口，基本都能套这个思路。

如果你不想自己折腾多个模型渠道，也可以直接用我自己的 token 站点：

Nbility：https://nbility.dev

它适合作为 AI Agent 的统一模型入口：配置一个 API Key、一个 Base URL，然后在 Hermes 里按模型名调用。本文不会硬推充值，而是把它放在真正需要 API 的地方顺手用上。

为什么第二步要先接模型 API？

上一篇把 Hermes Agent 安装起来，只能算“车架子搭好了”。真正跑起来，还需要三件事：

模型：负责理解任务、规划步骤、调用工具。
工具权限：负责让 Agent 能读写文件、执行命令、访问网页。
稳定的 token 供给：负责支撑多轮上下文和工具调用。

普通 ChatBot 一问一答，通常是一条用户消息、一条模型回复。但 Agent 不一样，它可能会经历这样的链路：

AI Agent 一次任务中的 token 消耗链路

Hermes Agent 通过 OpenAI 兼容 API 调用模型和工具的流程示意

例如你让 Hermes：

帮我检查这个项目为什么启动失败，修好并跑一遍测试。

它可能会：

读取项目目录
打开配置文件
搜索报错关键字
执行安装或测试命令
根据输出继续修改代码
再次运行验证
最后给你总结

每一步都要把上下文、工具结果、错误日志、代码片段塞回模型里。也就是说，Agent 的 token 消耗不是“聊天消息数量”决定的，而是由“任务复杂度 × 工具调用次数 × 上下文长度”决定的。

所以第二篇我们先把模型入口接稳，这是后面部署 OpenClaw、小龙虾、Dify、LobeChat、NextChat 等应用的基础。

准备工作

你需要准备：

一台已经安装好 Hermes Agent 的电脑或服务器
一个可用的模型 API Key
一个 OpenAI 兼容的 Base URL
至少一个你准备调用的模型名

如果你用 Nbility，可以在后台拿到：

API Key: sk-xxxxxxxxxxxxxxxxxxxx
Base URL: https://api.nbility.dev/v1
Model: 你准备使用的模型名

注意：截图、教程、群聊里都不要暴露真实 API Key。本文所有 key 都会写成 [REDACTED] 或 sk-xxxx。

第一步：确认 Hermes 的配置文件位置

Hermes 的主要配置都在用户目录下：

~/.hermes/
├── config.yaml     # 模型、工具、终端、压缩等设置
├── .env            # API Key 等敏感信息
├── skills/         # 技能
├── sessions/       # 会话记录
└── logs/           # 日志

先看一下配置路径：

hermes config path
hermes config env-path

通常会输出类似：

/root/.hermes/config.yaml
/root/.hermes/.env

如果你是在普通用户下安装，路径可能是：

/home/你的用户名/.hermes/config.yaml
/home/你的用户名/.hermes/.env

第二步：把 API Key 放进 `.env`

敏感信息建议放到 .env，不要直接写进文章、截图或 Git 仓库。

如果你的 Hermes 支持 hermes config set 自动写入环境变量，可以这样做：

hermes config set NBILITY_API_KEY "sk-你的真实key"

也可以手动编辑：

nano ~/.hermes/.env

加入：

NBILITY_API_KEY=sk-你的真实key

保存后确认一下变量存在，但不要把真实值打印出来：

grep '^NBILITY_API_KEY=' ~/.hermes/.env | sed 's/=.*/=[REDACTED]/'

预期输出：

NBILITY_API_KEY=[REDACTED]

第三步：在 Hermes 里配置 OpenAI 兼容模型入口

Hermes 支持很多 provider。对于像 Nbility 这种 OpenAI 兼容接口，最通用的方式是配置成一个 custom_providers。

打开配置文件：

hermes config edit

加入类似配置：

model:
  provider: custom:nbility
  default: gpt-4.1-mini

custom_providers:
  - name: nbility
    base_url: https://api.nbility.dev/v1
    api_key: ${NBILITY_API_KEY}
    api_mode: chat_completions

这里解释一下：

provider: custom:nbility：告诉 Hermes 使用名为 nbility 的自定义 provider。
default: gpt-4.1-mini：默认模型名，按你的实际可用模型替换。
base_url：OpenAI 兼容接口地址，通常要带 /v1。
api_key：从 .env 读取，不要写死真实 key。
api_mode: chat_completions：表示走 OpenAI Chat Completions 风格接口。

如果你想临时指定模型，也可以在启动时加参数：

hermes chat -m gpt-4.1-mini

或者直接用单次问题测试：

hermes chat -q "用一句话介绍 Hermes Agent" -m gpt-4.1-mini

第四步：跑配置检查

改完配置后，先让 Hermes 自检：

hermes config check

如果配置没问题，再看状态：

hermes status --all

你要重点看三类信息：

当前 provider 是否是 custom:nbility
当前默认模型是否是你填写的模型
是否有缺失 API Key、配置项拼写错误之类的提示

Hermes 接入 Nbility 的配置检查流程

如果你是在 Telegram、Discord、微信这类 gateway 里使用 Hermes，改完 .env 或 config.yaml 后，记得重启 gateway：

hermes gateway restart

如果只是在命令行里用 Hermes，重新开一个终端会话通常就行。

第五步：用一个“小任务”验证 Agent 真的能跑

不要一上来就让 Agent 改大项目。第一次验证建议用一个小任务：

mkdir -p /tmp/hermes-api-test
cd /tmp/hermes-api-test
hermes chat -q "创建一个 hello.py，打印 hello nbility，然后运行它验证输出"

一个正常的 Agent 执行过程大概是：

理解你的任务
写入 hello.py
调用终端运行 Python
读取输出
返回验证结果

如果这一步顺利，说明至少三件事已经通了：

Hermes 能连接模型 API
模型能进行工具调用规划
本地终端工具能被 Agent 正常使用

这比只问一句“你是谁”更可靠。因为 Agent 真正有价值的地方，不是闲聊，而是能执行任务。

常见错误排查

1. 401 Unauthorized

通常是 API Key 不对，或者环境变量没有加载。

检查：

grep '^NBILITY_API_KEY=' ~/.hermes/.env | sed 's/=.*/=[REDACTED]/'

然后重启 Hermes 会话或 gateway。

2. 404 Not Found

常见原因是 Base URL 写错。

建议确认是不是：

https://api.nbility.dev/v1

不要漏掉 /v1，也不要多拼一层 /chat/completions。Hermes 会自己拼接具体接口路径。

3. Model not found

模型名不可用，或者当前账号没有该模型权限。

换一个后台明确显示可用的模型名，再测试：

model:
  default: 你的可用模型名

4. Agent 回答正常，但不会调用工具

这可能不是 API 问题，而是工具权限或当前运行环境的问题。

可以检查工具：

hermes tools list

如果是命令行开发场景，通常至少需要 terminal、file、web 等工具集可用。

5. 聊几轮以后变贵、变慢

这是 Agent 类应用的典型现象，不一定是异常。

原因通常是：

上下文越来越长
工具输出太多
读取了大量文件或日志
模型在多轮规划和验证

解决方法：

给任务更明确的范围
让 Agent 先列计划，再执行
对大日志只让它看关键片段
使用更便宜的模型处理简单任务
复杂任务再切更强模型

这也是我建议把 Nbility 当作统一入口的原因：不同模型可以按任务类型切换，不用每个应用都重新折腾一遍 key 和 base url。

一点真实感受：Agent 消耗 token，但省的是人的时间

我不太建议把 AI Agent 宣传成“无限免费生产力”。那样用户第一次看到账单就会失望。

更真实的说法是：

Agent 会消耗更多 token，因为它不只是在回答问题，而是在读文件、跑命令、看结果、修正方案。你花的 token，换的是少切窗口、少复制粘贴、少人工排查。

所以在推广 token 站点时，不如围绕真实场景来讲：

服务器上部署一个长期在线的 Agent
给 Telegram / QQ / 微信接一个能干活的助手
用 Agent 帮你维护小项目
用 Agent 自动生成文章、图片、摘要
用 Agent 做定时任务和监控

这些场景天然需要稳定的 API token，而不是为了卖 token 硬造需求。

本篇小结

这一篇我们完成了 Hermes Agent 的模型 API 接入：

找到 Hermes 配置目录
把 API Key 放进 .env
用 custom_providers 配置 Nbility
通过 hermes config check 做自检
用一个真实小任务验证 Agent 能调用模型和工具
解释了 Agent 为什么比普通聊天更容易消耗 token

如果你已经有 Hermes Agent，可以直接照着本文把模型入口换成你自己的 OpenAI 兼容服务。

如果你还没有稳定的 token 来源，可以试试：

https://nbility.dev

我的建议是：先少量充值，拿一个轻量任务跑通；确认自己的 Agent 工作流真的顺手，再决定要不要长期使用。

下一篇预告

下一篇我准备写：

《把 Hermes Agent 接到 Telegram：在手机上远程指挥服务器干活》

这个场景会更像真实生产力工具：你人在外面，只要给机器人发一句话，它就能帮你查服务器、改文件、跑脚本、生成日报。

配图提示词

封面图 Prompt

A polished tech blog cover illustration for an article about connecting Hermes Agent to an OpenAI-compatible API provider. Include niku, Nbility mascot: cute anime catgirl with long fluffy black hair with warm brown highlights, black cat ears with pink inner ears and white fur, fluffy black cat tail with orange bow, oversized black hoodie with orange drawstrings and orange lightning logo, black choker with golden bell. Use the support version: wearing black over-ear headset with orange paw-print icon, microphone near mouth, one hand pointing at a floating API configuration panel. Scene: dark server room, glowing terminal, API key field masked as [REDACTED], Base URL field showing https://api.nbility.dev/v1, model selector, token stream particles, Hermes Agent logo-like abstract wing icon. Black and orange brand palette, clean composition, leave empty space at top for Chinese title text, no real secrets, no messy small text, high quality anime tech illustration, 16:9 landscape.

正文配图 Prompt

A clean anime-tech illustration showing an AI Agent workflow: user sends task, Hermes Agent plans, calls tools, reads files, sends requests to OpenAI-compatible API, receives model response, writes result back. Include a small cute black catgirl mascot niku as a guide character, black hoodie with orange lightning logo, headset, pointing at the flow. Dark UI, orange highlights, no real API keys, no readable tiny text except [REDACTED], high-quality blog illustration.