Hermes Agent 接入智谱 GLM：GLM_API_KEY、国内端点自动探测、Coding Plan 与模型选择

为什么智谱 GLM 适合国内用户

智谱开放平台 bigmodel.cn 国内直连，不需要梯子。Hermes 上游把它做成 Z.AI / GLM 这一个选项，背后其实有四个端点：海外普通、国内普通、海外 Coding Plan、国内 Coding Plan。Hermes 拿你的 Key 自动探测该走哪一个，所以不用像 MiniMax 和 Kimi 那样手动区分国内站选项。接口走 OpenAI 兼容的 chat completions 协议，工具调用和流式输出都正常。

其他国内 Provider 的选项名和环境变量汇总在 国内安装与使用指南，MiniMax 的配置见 接入 MiniMax 国内站。

一个选项，四个端点：自动探测怎么工作

Hermes 内置的四个 GLM 端点和优先级如下：

1. 海外普通：https://api.z.ai/api/paas/v4
2. 国内普通：https://open.bigmodel.cn/api/paas/v4
3. 海外 Coding Plan：https://api.z.ai/api/coding/paas/v4
4. 国内 Coding Plan：https://open.bigmodel.cn/api/coding/paas/v4

第一次用这个 Key 启动时，Hermes 对四个端点并发各发一条只要 1 个 token 的测试请求，按上面的顺序取第一个返回 200 的端点，费用可以忽略。结果按 Key 的哈希缓存在 ~/.hermes/auth.json，之后启动不再探测；换了 Key 会自动重探。四个全失败时退回海外普通端点，并在 5 分钟内不再重试，表现就是国内 Key 一直 401。

探测的意义在于智谱对普通套餐和 Coding Plan、海外和国内是分开计费的，Key 打到错误的端点会报 Insufficient balance，哪怕账户里有钱。想跳过探测、锁死某个端点，设 GLM_BASE_URL，它永远优先：

# 国内普通按量
GLM_BASE_URL=https://open.bigmodel.cn/api/paas/v4
# 国内 Coding Plan
GLM_BASE_URL=https://open.bigmodel.cn/api/coding/paas/v4

申请 Key

普通按量账号在 bigmodel.cn 开放平台创建 API Key。Coding Plan 是单独订阅的套餐，Key 在套餐页面，和普通 Key 不通用，套餐里开放的模型也以套餐页列表为准。平台菜单会变，以当前界面为准；Key 只粘到 Hermes 里，不要进聊天记录、截图或代码仓库。

配置方式一：hermes model 向导

hermes model
# → 选 "Z.AI / GLM"，国内海外、普通和 Coding Plan 都选这一项
# → 粘贴 Key，Hermes 写进 ~/.hermes/.env 的 GLM_API_KEY
# → 模型选 glm-5（按量账号）或套餐页列出的型号（Coding Plan）

Hermes 也认 ZAI_API_KEY 和 Z_AI_API_KEY 这两个名字。配置文件里的 Provider ID 是 zai，别名 glm、z-ai、z.ai、zhipu 都能识别。

配置方式二：直接写 .env 和 config.yaml

echo 'GLM_API_KEY=你的Key' >> ~/.hermes/.env
hermes config set model.provider zai
hermes config set model.default glm-5

• ~/.hermes/.env 的优先级高于 shell 里 export 的同名变量，重启后以文件为准。
• 多数情况不要设 GLM_BASE_URL，让 Hermes 自动探测；只有探测结果不对、或者想锁死某个端点时再设。
• 只想临时试一次，用 hermes chat --provider zai --model glm-5，这是官方文档的示例写法。

验收：三条命令确认链路

hermes doctor
hermes -z "用一句话确认你能正常回复"
hermes gateway restart

注意 hermes doctor 的连通性检查那一行默认探的是海外站 api.z.ai 的模型列表，国内 Key 在这一行可能显示失败，但不代表链路不通；设了 GLM_BASE_URL 之后它才探你指定的端点。以 hermes -z 的短问答为准，能回复就是通了。Gateway 已经在跑的话，最后一条让它重新加载 Key。

选哪个模型

• glm-5：新旧版本 Hermes 的列表都有，普通按量账号从它开始。
• glm-4.7、glm-5.1：两版都有。Coding Plan 的老账号常常只开了 glm-4.7，新账号开的是 glm-5.x，以套餐页为准。
• glm-5.3、glm-5.3-flash、glm-5.2：只在较新版本 Hermes 的目录里，hermes update 之后出现。
• glm-4.5-flash：便宜、快，适合摘要和分类这类高频任务。

上下文长度 Hermes 记录为：glm-5 和 glm-5.1 是 204,800，glm-5.2 约 100 万，glm-5.3 约 131 万。价格方面，Hermes 内置的计价表里没有智谱官方价目，用量统计不会显示费用，成本要自己从控制台抄到 成本记录模板 里。

常见报错

1. Insufficient balance 但账户明明有钱：Key 被路由到了错误的端点，普通和 Coding Plan、海外和国内任何一组错位都会这样。用 grep -A4 detected_endpoint ~/.hermes/auth.json 看探测结果，不对就设 GLM_BASE_URL 锁定正确端点。
2. 一直 401：四个端点都探测失败后 Hermes 退回了海外站。确认 Key 没复制错、账号已开通 API 权限，然后重启 Hermes 让它重探；还不行就直接设 GLM_BASE_URL。
3. 429 带 1305 或 temporarily overloaded：这是 Coding Plan 端点过载，不是额度用完，等一会儿再试。较新版本的 Hermes 对 glm-5.2 的这类 429 会自动退避重试。
4. 换了 Key 还连旧端点：缓存绑定 Key 的哈希，换 Key 本身会触发重探；如果之前设过 GLM_BASE_URL，它永远优先，记得一起改。
5. CLI 正常、群里还是旧模型：hermes gateway restart。

更多排查思路见 Hermes Agent 故障排查清单。

顺手：把 GLM 设成兜底模型

zai 在上游 fallback_model 的官方支持列表里。主模型遇到 429、503、529 或连接失败时自动切过来：

fallback_model:
  provider: zai
  model: glm-5

核对说明

本文的端点列表、探测逻辑、环境变量名、模型目录和上下文数值对照上游 v2026.9.24（v0.21.5）的 hermes_cli/auth.py、auth_zai_kimi.py、models_catalog_static.py、doctor_connectivity.py、agent/model_metadata.py 和官方 Providers 文档核对，命令参数在本地 v0.15.1 验证过。编辑组没有用智谱账号做真实计费测试，价格和套餐内容以你的控制台为准。

下一步

国内 Provider 不止这一家，Kimi 和 小米 MiMo 各有单独教程。链路通了以后按 setup 输出验收清单 把 Memory、Skills 和 Gateway 逐项过一遍，再回到 模型接入指南 看按任务分层选模型的思路。

还没有真实场景？可以先领取 Free Starter 模板包，从低风险只读任务开始试跑。