以本次接入智谱 GLM-4.5-Flash 为例。适用场景：某个模型已被服务商从"可枚举模型列表/官方下拉菜单"里下架，但接口本身没有真正封禁，其他客户端仍能正常调用。

---

0. 先弄清楚为什么绕不过 UI

在动手之前，理解这几个前提，能少走很多弯路：

1. 官方内置 Provider（比如 Z.AI / GLM）的模型列表是动态拉取的，下架的模型不会出现在下拉菜单里，UI 层面无法选中，也没有输入框可以手打。

2. Hermes Studio 的"添加模型"下拉菜单也是拉取列表，不是自由输入框，同样绕不开下架限制。

3. hermes model CLI 交互流程虽然允许手动输入模型名，但不保证真的写入配置文件——本次实测中，CLI 走完整个流程后，配置文件里根本没有对应记录，是"假成功"。

4. 真正的解法：跳过 UI 和 CLI，直接编辑配置文件 config.yaml，新增一个独立的自定义 Provider（custom_provider），一个 Provider 对应一个模型。

---

1. 确认目标模型接口本身没被真封禁

先在别的能正常调用这个模型的 App / 客户端里确认一次调用成功，确保只是"列表里被隐藏"，而不是接口层面真的下线了。如果接口真的 404，后面全部白做。

---

2. 确认模型的上下文长度（context length）

去官方文档或模型卡片查这个模型的真实上下文窗口（不要留空走 auto-detect，下架模型的自动探测大概率拿不到准确值）。

以 GLM-4.5-Flash 为例：官方标称 128K tokens，换算成精确 token 数填 131072。

同时注意：Hermes 有一个隐性门槛——低于 64K 上下文的模型会被拒绝接入，如果目标模型本身上下文 < 64K，这条路走不通。

---

3. 确认容器结构（一次性排查，后续可跳过）

Hermes 的 docker compose 通常包含两个关键容器：

两者共享的配置文件路径（容器内路径，两个容器里都一样）：

/opt/data/config.yaml

不需要关心宿主机上具体挂在哪个 volume 路径，直接在容器内操作即可。

---

4. 备份配置文件（务必先做，别省这一步）

docker exec hermes-webui cp /opt/data/config.yaml /opt/data/config.yaml.bak.$(date +%Y%m%d)

---

5. 用 Python 脚本追加自定义 Provider

不要手工改 YAML 缩进（容易改坏），用脚本安全追加：

docker exec hermes-webui python3 -c "
import yaml

path = '/opt/data/config.yaml'
with open(path) as f:
    data = yaml.safe_load(f)

data['custom_providers'].append({
    'name': 'zai-glm-4.5-flash',
    'base_url': 'https://open.bigmodel.cn/api/paas/v4',
    'api_key': '你的智谱APIKey',
    'model': 'glm-4.5-flash',
    'api_mode': 'chat_completions'
})

with open(path, 'w') as f:
    yaml.dump(data, f, allow_unicode=True, sort_keys=False)

print('done')
"

字段说明（下次配置其他模型，照这个表改就行）：

结构关键点：custom_providers 是一个列表，每一项是一个 Provider 对应一个模型（model 字段是单数，不是数组）。如果以后要加同一个服务商的另一个模型，需要再追加一条新记录，name 换个不重复的名字。

---

6. 重启容器让配置生效

docker compose restart hermes hermes-webui

---

7. 验证配置已写入

docker exec hermes-webui python3 -c "
import yaml, json
with open('/opt/data/config.yaml') as f:
    data = yaml.safe_load(f)
print(json.dumps(data['custom_providers'], indent=2, ensure_ascii=False))
"

确认输出里能看到新增的这一条记录。

---

8. Studio 里实际验证能用

1. 刷新 Studio 页面。

2. 在"模型"页面应该能看到一个新的自定义 Provider 卡片（比如本例的 zai-glm-4.5-flash）。

3. 选中里面的模型，发一条测试消息（比如"你好，你是谁"）。

4. 确认能正常返回内容，而不是报错。

   • 如果返回 404 / model not found：说明服务商这次是网关层彻底封禁，不只是隐藏，这条路走不通，需要找其他调用路径。

   • 如果正常返回：配置成功。

---

常见排查备忘（本次踩过的坑）

• 不要相信 hermes model CLI 的"配置成功"提示，务必用第 7 步的方式实际读一遍 config.yaml 确认真的写进去了。

• Studio 的"添加模型"下拉菜单是死路，改配置文件才是唯一可靠办法。

• 不要把 Context length 留空走 auto-detect，尤其对已下架/非标准接入的模型，自动探测大概率不准，容易导致长对话被截断或直接被 Hermes 判定不兼容而拒绝接入。

• 排查配置存在哪里时，如果不确定字段名，用以下命令直接看 config.yaml 顶层结构，比瞎猜字符串 grep 更快：

  docker exec hermes-webui python3 -c "import yamlwith open('/opt/data/config.yaml') as f:    data = yaml.safe_load(f)print(list(data.keys()))"