在 Hermes Agent 里使用珂艾网关

能用。 Hermes 走标准 OpenAI 协议，改两个环境变量就能换到珂艾，三种配法按场景选。
整理日期：2026-10-18 ｜相关：按任务选模型 · 配置三要素

一、配置三要素

要素	填什么
Base URL	`https://turbo.apimax.host/v1`
API Key	珂艾控制台生成的 `sk-` 密钥
模型	网关模型 ID，如 `claude-sonnet-5-5`

Hermes 走 OpenAI 兼容协议，Base URL 必须带 /v1。

二、三种配法，按场景选

配法 A：改 `.env`（最简单，适合先跑通）

编辑 ~/.hermes/.env：

保存后启动 hermes。

优点：改动最小，两行搞定。
缺点：只能配一个默认模型，想多模型切换要改配置。

配法 B：`config.yaml` 的 model_aliases（推荐，支持快速切换）

适合「同一台机器上要在几个模型之间切」的场景。编辑 config.yaml：

配好后在会话里直接用：

/model keai-sonnet
/model keai-opus

配法 C：CNB 里用 imports 注入（跑在云端时）

如果在 CNB 云原生环境里跑 Hermes，密钥走密钥仓库，别写进文件：

envs.yml 内容：

三、验证是否真的通了

启动后：

判定标准：

✅ /model 列表里能看到你配的名字

✅ 问一句「你在用什么模型」，答的与配置一致

❌ 启动直接退出、退出码 -2 → provider 名对不上（见下方坑点）

❌ 401 → 密钥错或带空格

❌ 404 → Base URL 漏 /v1

四、两个实踩过的坑

坑 1：provider 名必须三处一致，否则启动失败

Hermes 的 provider 配置分散在三处，名字必须完全相同，否则进程直接以 -2 退出，且报错信息不明显：

位置	字段
顶层	`model.provider`
provider 定义	`providers.<key>`
自定义 provider 列表	`custom_providers[].name`

建议：别用数字 ID 或临时名，统一用 custom 或 keai 这种稳定字符串。

坑 2：改完 `config.yaml` 必须重启，不热加载

Hermes 的 gateway 不会重新读取配置文件。改完一定要完全退出再启动。

如果你用的是桌面版（Hermes One），退出不是关窗口，要真正结束进程。另外桌面版和 pip CLI 版是两套独立安装、配置不互通——在 A 里配好，B 里不会生效。

五、常见报错

现象	原因	解决
启动即退出，码 `-2`	provider 名三处不一致	统一成 `custom`
改了配置没变化	没重启 / 改错了那份配置	完全退出重启；确认改的是当前安装的 config
`401`	密钥错 / 带空格	重新复制核对
`404`	Base URL 漏 `/v1`	改成 `https://turbo.apimax.host/v1`
模型不存在	填了官网名	换网关 ID
`/model` 里没有新加的别名	YAML 缩进错了	检查 `model_aliases` 下两级缩进

六、计费与分组

项目	信息
计费方式	按量计费（按输入 / 输出 token 结算）
建议	Hermes 会跑定时任务和长会话，给它建独立令牌并设额度上限

实际单价以价格页为准。

七、进阶：多模型分场景

Hermes 的模型别名很适合做「分场景路由」：

别名	用在哪
`keai-haiku` → `claude-haiku-5-5`	定时任务、晨报生成、简单摘要
`keai-sonnet` → `claude-sonnet-5-5`	日常主力
`keai-opus` → `claude-opus-5-5`	复杂分析，手动切

定时任务（hermes cron）建议固定用便宜档——它每天自动跑，用贵的很烧钱。

八、相关阅读

不确定选哪个模型：按任务选模型

搞不清填什么：配置三要素

跑在 CNB 上：在 CNB 里使用珂艾网关

报错排查：配置报错对照表

九、更新记录

日期	改了什么
2026-10-18	首次发布。含三种配法、provider 名三处一致与必须重启两个实踩坑

在 Hermes Agent 里使用珂艾网关

一、配置三要素#

二、三种配法，按场景选#

配法 A：改 .env（最简单，适合先跑通）#

配法 B：config.yaml 的 model_aliases（推荐，支持快速切换）#

配法 C：CNB 里用 imports 注入（跑在云端时）#

三、验证是否真的通了#

四、两个实踩过的坑#

坑 1：provider 名必须三处一致，否则启动失败#

坑 2：改完 config.yaml 必须重启，不热加载#

五、常见报错#

六、计费与分组#

七、进阶：多模型分场景#

八、相关阅读#

九、更新记录#