Hermes Agent 接入智谱 GLM Coding Plan

智谱的 GLM Coding Plan 兼容 OpenAI 和 Anthropic 两套协议，Hermes Agent 作为开源自进化 AI 智能体，接入步骤清晰、仅需 3 步。本文手把手说明从获取 API Key 到在 Hermes 中配置、验证，再到多 Agent 场景下的限流应对策略。

为什么用 GLM Coding Plan

• 中文理解优异：GLM 系大模型对中文语境、代码注释、国内技术栈的理解能力强，和 Hermes 的技能（Skills）体系搭配后，中文任务的输出质量更稳。
• 国内直连、低延迟：无需代理，不需要科学上网，本地网络环境下调用顺畅。
• 价格实惠：按 token 计费，日常代码生成和文本处理成本显著低于同级国际模型。
• Coding Plan 专属额度：与普通平台 API Key 不同，Coding Plan 的 Key 能独立消耗编程套餐额度，适合高频代码任务。

第一步：获取 Coding Plan API Key

1. 打开 bigmodel.cn 并完成实名认证（个人或企业均可）。
2. 进入 编程套餐（Coding Plan） 页面，新建或获取 API Key。
3. 务必注意：Coding Plan 的 Key 与平台其他 API Key 不通用。要使用编码套餐额度，必须用 Coding Plan 专属 Key。
4. Key 只显示一次，立即保存到密码管理器或本地凭据。

第二步：确认 Hermes 版本

智谱原生适配器在 Hermes v0.9.5 以上可用。终端运行：

hermes --version

版本偏低就先 hermes update 升到最新。

第三步：配置 Hermes 使用 GLM Coding Plan

智谱 Coding Plan 提供两个协议接入端点，我们优先使用 OpenAI Chat Completion 兼容协议：

3.1 使用 Hermes 内置 zhipu provider（最简单）

Hermes 内置了 zhipu 适配器，直接走 OpenAI 兼容接口。

# 1. 切换默认 provider 到 zhipu
hermes config set provider zhipu

# 2. 写入 Coding Plan 的 API Key（注意双引号，Key 中可能带点号）
hermes config set provider.zhipu.api_key "你的_Coding_Plan_API_Key"

# 3. 设置模型
hermes config set provider.zhipu.model "glm-5.2"

配置完，Hermes 的 ~/.hermes/config.yaml（或 TOML 形式视版本而定）中就会有 [llm.zhipu] 节。重启 Hermes 或 gateway 后生效。

3.2 使用 custom provider（自定义 Base URL）

如果你希望显式指定 Coding Plan 的端点，而不使用 zhipu 内置默认地址：

hermes config set provider custom
hermes config set model.base_url "https://open.bigmodel.cn/api/coding/paas/v4"
hermes config set model.api_key "你的_Coding_Plan_API_Key"
hermes config set model.name "glm-5.2"

这种方式适合将来可能切换端点的场景，模型名和 base URL 都完全由你控制。

第四步：模型选择与推荐配置

根据任务性质选择模型：

• glm-5.2 / glm-5.1：当前最强编码模型，上下文窗口可达 100 万 token。适合复杂代码生成、代码库级重构、多步骤 Agent 任务。
• glm-4-plus：对标 GPT-4o 级别，上下文 128K。适合一般编码任务、日常 Agent 交互。
• glm-4-air：高性价比，适合大批量文本处理、简单代码编写。
• glm-4-flash：限额度内免费，速度快、适合原型验证和轻量任务。

上下文注意：GLM-4 128K 不等于可以无脑塞大文档。实测中 token 数超过 6 万时可能出现中段遗忘。如果你有长文档 RAG 场景，建议分段总结，或改用超长上下文模型。

第五步：验证连通性

hermes doctor --provider

运行后若在 5 秒内返回 ✅，表示 endpoint、key 和模型都通。之后直接启动 Hermes 做任何任务就会走 Coding Plan 额度。

也可以用一条短查询快速试：

hermes chat -q "用 Python 写一个 Fibonacci 生成器，带类型注释和 doctest"

第六步：多 Agent / 高并发场景的限流应对

这是实际部署中最容易踩的坑。

智谱免费层通常 RPM=5（每分钟 5 次请求），付费用户默认 RPM=60，可通过工单申请进一步提升。如果你在跑多个 Agent 并行（Telegram Bot 多实例、串行 pipeline 之外的并发任务），极易遇到 429。

应对手段：

1. 提升 RPM：到开放平台后台或通过工单申请，将并发上限调高。
2. 错峰调度：用 Hermes 的 cronjob 工具，定时任务之间间隔 10 分钟以上。
3. 串行 pipeline：多个 Agent 走流水线而非完全并行，一个完成再触发下一个。
4. 自动重试：在自定义工具或脚本里，对 429 做指数退避重试。
5. fallback 链：配置另一个 provider（例如 OpenRouter 或其他）的 fallback，高并发时自动切过去。

单 Agent 或串行任务场景下，GLM Coding Plan 完全够用；多 Agent 高频并发场景建议组合使用。

第七步：项目内的模型切换技巧

Hermes 支持模型别名和多 provider 共存。可以建一个别名专门指向 GLM Coding Plan：

model:
  aliases:
    glm-coder: zhipu/glm-5.2

在 Skills 或 Agent 会话里用 /model glm-coder 切换，针对编码任务固定走 GLM，而其他任务走别的 provider。

也可以在 ~/.hermes/config.yaml 里给 zhipu 节定义快慢两档模型，由 Skill 元数据里的标签触发：

llm:
  zhipu:
    model_fast: "glm-4-air"
    model_smart: "glm-5.2"

这样批量文本处理走 Air、代码生成走 glm-5.2，账单更可控。

常见问题

1. 配置后报 "Model not found" 到 bigmodel.cn 控制台的 API 管理页面，确认当前账号可用的模型 ID 列表，把准确的模型名填入 hermes config set provider.zhipu.model。GLM-4-Flash 有时需要在「开通服务」页手动开通后才可用。

2. 连通性超时或 429 先 hermes context summarize 压缩当前会话。长文档场景可以开启流式输出：

hermes config set llm.zhipu.stream true

仍然超时就考虑切到超长上下文模型，或者把文档分 chunk 处理。

3. API Key 写错了或泄露了 重新生成 Key，并用新的值覆盖配置：

hermes config set provider.zhipu.api_key "新 Key"

旧 Key 会停用，及时在开放平台吊销。

4. 为什么消耗额度很快 编码任务输出 token 较多， 점검 hermes doctor 和实际用量报告，必要时调整模型（例如用 air/flash 做非核心任务）、压缩上下文、或打开内存压缩。

最佳实践总结

• Coding Plan 任务走独立的 API Key 和正确的 Base URL，别混用普通平台 Key。
• 优先使用云端最强模型（如 glm-5.2）处理编码和复杂推理，便宜模型处理批量轻量任务。
• 温度方面，GLM-4 的最佳推理区间大约在 0.3~0.5，写代码或做决策任务可以调低。
• 搭配 Hermes 的 Memory 模块，把高频重复上下文压缩，减少重复 token 开销。
• 多代理部署时，先保证 RPM 足够，再考虑串行/重试/fallback。

结语

Hermes Agent 作为开源、自进化的 AI 智能体框架，天然支持 GLM Coding Plan。这套组合对国内用户特别友好：中文能力强、直连不卡、额度和价格都有优势。配置本身是标准的 OpenAI 兼容接入，三五分钟就能跑通。上线后根据是否多 Agent 并发，决定是否申请提升 RPM 和配置 fallback。

有了这个接入，Hermes 的 CLI、Desktop、Dashboard、Telegram/Discord/Slack 等各种网关场景都能用上 GLM Coding Plan 的额度和模型能力。