Skip to main content

​
Z.AI 工作原理

Z.AI(由智谱 AI 开发)提供 GLM 系列模型。它是少数几家为 API 访问提供统一订阅费的主要提供商之一:GLM Coding Plan 以固定月费捆绑模型使用量,并通过 5 小时和每周的时间窗口(而非按 token 计费)来应用速率限制。 对于更大或波动较大的工作负载,Z.AI 也通过标准开发者 API 对同样的模型提供按 token 付费的访问。 两种方式都暴露 OpenAI 兼容端点,因此 Kodus 可以通过 OpenAI-compatible 提供商与之对接。Kodus 还提供专用的 Z.ai 提供商,它通过 Z.AI 的 Anthropic 兼容端点(https://api.z.ai/api/anthropic)进行连接。

​
方案概览

价格和配额经常变化。选择套餐前请务必在 z.ai/subscribe 和 docs.z.ai 查看最新数据。

​
GLM Coding Plan(订阅)

  • 配额按5 小时滚动窗口和每周窗口重置 — 这是需要规划的上限,而非月度总量。
  • 覆盖模型包括 GLM-5.1、GLM-5-Turbo、GLM-5、GLM-4.5 和 GLM-4.5-Air。
  • Coding Plan 端点:https://api.z.ai/api/anthropic(Anthropic 兼容 — Kodus 中的 Z.ai 提供商使用此端点)和 https://api.z.ai/api/coding/paas/v4(OpenAI 兼容)。标准的 /api/paas/v4/ 端点不消耗 Coding Plan 额度。

​
按 token 付费的开发者 API

标准端点:https://api.z.ai/api/paas/v4/(OpenAI 兼容)。

​
创建 API 密钥

创建 API 密钥需要 Z.AI 账号。
  1. 在 z.ai 登录。
  2. 在 z.ai/subscribe 购买 GLM Coding Plan 档位。
  3. 打开订阅的密钥管理页并创建 Coding Plan 密钥。
  4. 复制密钥 — 之后将无法再次看到。
Coding Plan 密钥绑定到 Coding Plan 端点(/api/anthropic 和 /api/coding/paas/v4)。发送到标准 /api/paas/v4/ 端点会返回 401。

​
在 Kodus 中配置 Z.AI

主流程是使用 Kodus Cloud 上的 AI providers 页面。希望在进程层级固定提供商的自托管用户可以改用环境变量。

​
方式 1 — Kodus Cloud 上的 Z.ai 提供商(推荐)

1

打开 AI providers 并选择 Z.ai

在侧边栏中打开 AI providers(app.kodus.io/byok)。在 Providers 选项卡上,点击 Z.ai 磁贴(位于 Connect your first provider 下;如果您已连接过提供商,则位于 Add another provider 下)。
2

粘贴您的 API 密钥并输入模型

在 API key 卡片中粘贴您的 Z.AI 密钥,然后在 Model 中输入模型 ID(例如 glm-5.1)。Kodus 会为您填入 https://api.z.ai/api/anthropic 端点 — 这是 Z.AI 为 GLM Coding Plan 文档化的 Anthropic 兼容端点 — 因此该磁贴没有方案选择器,也没有基础 URL 字段。如果要改用特定的 OpenAI 兼容端点,请使用下面的方式 2。
3

设置并发(Coding Plan)

Kodus 不会预填并发数。在 Coding Plan Lite/Pro 上,打开 Advanced (optional) 并将 Max concurrent requests 设置为 1;如果您使用 Max 档位,最多可上调到 30。
4

Test & save

点击 Test & save。Kodus 会测试连接,成功后保存配置。401 表示密钥与端点不匹配。

​
调优推理(可选)

Thinking / Reasoning 位于 Advanced (optional) 下。对于 GLM,除 Off 以外的任何级别都会发出 thinking: { type: "enabled" },对大多数工作负载而言够用。两种需要覆盖的情况:
  • 强制特定 token 预算 — 将 Thinking / Reasoning 切换到 Custom 并粘贴:
  • 禁用 thinking — 在小型 PR 上实现最快/最便宜的审查:
无需命名空间包装 — Kodus 在发送前会将选项包装在当前提供商的命名空间下。详见 主 BYOK 文档 → 自定义 JSON 覆盖。

​
调优并发

  • Coding Plan Lite / Pro:将 Max concurrent requests 设置为 1。更高会返回 429 Too much concurrency。
  • Coding Plan Max:先上调到 5,如果未见 429 可继续提高至 30。Max 档位允许最多 30 并发。
  • 开发者 API:保持为空(无上限)。如果看到速率限制错误,降到 5,然后再逐步调高。
在 Routing 选项卡上,将 GLM 5.1 设置为 Model for all tasks,并将一个 OpenAI 或 Anthropic 模型设置为 Fallback (optional),这样当 Coding Plan 的 5 小时窗口耗尽时审查仍可继续。Kodus 会自动故障转移。

​
方式 2 — OpenAI 兼容端点

如需通过 Z.AI 的某个 OpenAI 兼容端点连接,请打开 AI providers,在 Providers 选项卡上选择 Custom 下的 OpenAI-compatible,并填写:

​
方式 3 — 自托管(环境变量)

如果您以 Fixed Mode 运行 Kodus(单一全局提供商,无按组织 BYOK),在 API + worker 容器的 .env 中配置 Z.AI:
仅在有意禁用 BYOK 的自托管 Kodus 安装中才需要这条路径。如果您的自托管实例启用了 BYOK,请优先使用方式 1 — AI providers 页面的用法与 Cloud 上相同。
编辑 .env 后重启 API 和 worker 容器,然后验证集成:
完整的自托管设置(域名、安全密钥、数据库、webhook、反向代理)请参见通用 VM 部署指南,只需将 LLM 部分替换为上面的配置。

​
在 Coding Plan 和按 token 付费之间选择

  • 当您有稳定的审查团队并希望获得固定月度成本时,选择 Coding Plan。5 小时和每周配额大致相当于订阅费 15–30 倍的等价 API 开销。
  • 当您的流量波动大、偶尔需要最大上下文窗口,或希望成本随 PR 数量线性增长时,选择按 token 付费。
  • 组合使用:在 Routing 中,把 Coding Plan 设置为 Model for all tasks,把开发者 API 密钥(或完全不同的另一家提供商)设置为 Fallback (optional),以消化超出订阅窗口的突发流量。

​
故障排查

  • Coding Plan 密钥在 /api/anthropic 和 /api/coding/paas/v4 上工作,不能用于 /api/paas/v4/。开发者 API 密钥使用 /api/paas/v4/。
  • Z.ai 磁贴始终使用 https://api.z.ai/api/anthropic。如果您的密钥只在其他端点上有效,请通过 OpenAI-compatible 并配合该 Base URL 连接。
  • 使用 OpenAI-compatible 时,确认 Base URL 与密钥来源匹配。
  • Lite 和 Pro 的 Coding Plan 档位通常仅允许 1 个并发请求。请将 Max concurrent requests 设置为 1;仅在 Max 上才需上调。
  • 如果仍撞到 429,在高级设置中降低最大并发请求数。
  • 配额按5 小时滚动窗口和每周窗口执行。触发其一会返回 HTTP 429。
  • 在 Z.AI 控制台查看剩余配额。
  • 选项:等待下一个窗口、升级到更高档位,或在 Routing 中将一个开发者 API 密钥配置为 Fallback (optional) 模型来弥补空缺。
  • 确认模型 ID 与 Z.AI 目录匹配(glm-5.1、glm-5-turbo、glm-5、glm-4.5、glm-4.5-air)。
  • Coding Plan 目前仅覆盖 GLM 系列 — 非 GLM 模型名称会被拒绝。
  • 确认您的服务器可以访问 api.z.ai。
  • 查看 API 和 worker 日志获取具体的上游错误。
  • 如果您所在地区有出站流量限制,请通过基础设施允许的反向代理路由请求。

​
相关链接