Z.AI
Z.AI 是 GLM 模型的 API 平台。它为 GLM 提供 REST API,并使用 API 密钥进行身份验证。请在 Z.AI 控制台 中创建您的 API 密钥。
OpenClaw 使用 zai 提供商和 Z.AI API 密钥。
| 属性 | 值 |
|---|---|
| 提供商 | zai |
| 包 | @openclaw/zai-provider |
| 身份验证 | ZAI_API_KEY(旧版别名:Z_AI_API_KEY) |
| API | Z.AI Chat Completions(Bearer 身份验证) |
GLM 模型¶
GLM 是模型系列,而不是单独的提供商。在 OpenClaw 中,GLM 模型使用
类似 zai/glm-5.3 的引用:提供商 zai,模型 ID glm-5.3。
快速开始¶
首先安装提供商插件:
**最适合:** 大多数用户。OpenClaw 会使用您的 API 密钥检查受支持的 Z.AI 端点,并自动应用正确的 base URL。
1. 运行入门配置
2. 验证模型已列出
**最适合:** 希望强制使用特定 Coding Plan 或通用 API 表面的用户。
1. 选择正确的入门配置项
# Coding Plan Global (recommended for Coding Plan users)
openclaw onboard --auth-choice zai-coding-global
# Coding Plan CN (China region)
openclaw onboard --auth-choice zai-coding-cn
# General API
openclaw onboard --auth-choice zai-global
# General API CN (China region)
openclaw onboard --auth-choice zai-cn
2. 验证模型已列出
端点¶
| 入门配置项 | Base URL | 默认模型 |
|---|---|---|
zai-global |
https://api.z.ai/api/paas/v4 |
glm-5.2 |
zai-cn |
https://open.bigmodel.cn/api/paas/v4 |
glm-5.2 |
zai-coding-global |
https://api.z.ai/api/coding/paas/v4 |
glm-5.3 |
zai-coding-cn |
https://open.bigmodel.cn/api/coding/paas/v4 |
glm-5.3 |
Z.AI 还发布了兼容 Anthropic 的 Coding Plan base URL
https://api.z.ai/api/anthropic。OpenClaw 的 Z.AI 选项使用上述文档中记录的
OpenAI Chat Completions 端点;Anthropic URL 适用于直接调用 Anthropic Messages 的客户端。
zai-api-key 会通过将您的密钥与每个端点的 chat-completions API 进行校验,自动检测这四个端点之一,先检查通用端点(zai-global,
然后 zai-cn),再检查 Coding Plan 端点(zai-coding-global,然后
zai-coding-cn),并在第一个接受请求的端点处停止。
如果您的密钥在两者上都能使用,请使用显式 --auth-choice 强制使用 Coding Plan 端点。
速率限制和过载¶
Z.AI 将 Coding Plan 和通用代理工具记录为容量 管理服务。在 Z.AI 自己的文档中:
- 通用代理工具, 包括 OpenClaw,以尽力而为的方式提供服务。在高推理 负载期间,通常在新加坡时间下午 2 点至 6 点左右,部分请求可能会遇到临时 速率限制。
- Coding Plan 速率和并发限制 与套餐层级绑定,并可根据资源 可用性动态调整。非高峰时段可能具有更高的并发。
- API 错误代码
1302表示“请求 已达到速率限制”。API 错误代码1305表示“服务可能暂时 过载,请稍后重试”。
如果在繁忙时段看到临时 429 或 1305 响应,请等待并
重试请求。如果失败在高峰时段之外可重复出现,或仅
出现在某个端点、模型或请求形态中,请先检查已配置的端点
和模型:
Coding Plan 密钥应使用 Coding Plan 端点,例如
https://api.z.ai/api/coding/paas/v4;通用 API 密钥应使用通用 API
端点,例如 https://api.z.ai/api/paas/v4。使用相同密钥和端点时持续失败可能表示提供商端拒绝或套餐限制,
而不是普通的高峰负载限流。
配置示例¶
Tip
zai-api-key 可让 OpenClaw 从密钥检测匹配的 Z.AI 端点,并
自动应用正确的 base URL。当您希望强制使用特定 Coding Plan 或通用 API 表面时,请使用显式区域选项。
{
env: { vars: { ZAI_API_KEY: "sk-..." } },
models: {
providers: {
zai: {
// GLM-5.3 uses the Coding Plan endpoint.
baseUrl: "https://api.z.ai/api/coding/paas/v4",
},
},
},
agents: { defaults: { model: { primary: "zai/glm-5.3" } } },
}
内置目录¶
zai 提供商插件将其目录打包在插件清单中,因此只读
列表可以在不加载提供商运行时的情况下显示已知的 GLM 行:
由清单支持的目录包括:
| 模型引用 | 说明 |
|---|---|
zai/glm-5.3 |
Coding Plan 默认值;1,048,576 个 token 的上下文 |
zai/glm-5.3-flash |
多模态文本和图像模型;1,048,576 上下文 |
zai/glm-5.2 |
通用 API 默认值;1M 上下文 |
zai/glm-5-turbo |
OpenClaw 优化的文本模型;200K 上下文 |
zai/glm-5v-turbo |
多模态编码模型;200K 上下文 |
zai/glm-5.1 |
已弃用;除非已配置,否则隐藏;请使用 GLM-5.2 |
按量付费目录行遵循 Z.AI 当前的 API 定价。GLM-5.3 Flash 使用 其按量付费的列表价格,即使有临时折扣也是如此。 GLM-5.3 目前是 Coding Plan 模型,因此其本地目录成本为零; Coding Plan 订阅使用计划配额,而不是按 token 计费。有关计划定价和可用性, 请参阅实时订阅页面。
Tip
GLM 模型可通过 zai/<model> 使用(示例:zai/glm-5.3)。
Note
新的 Coding Plan 设置默认使用 zai/glm-5.3;常规 API 设置仍保持
zai/glm-5.2。在 Coding Plan 端点上,当某个密钥或区域端点未直接暴露 GLM-5.3
时,自动检测会依次回退到 glm-5.1 和 glm-4.7。Z.AI 目前会将
针对 GLM-5.2 和 GLM-5.1 的 Coding Plan 请求路由到 GLM-5.3。运行
openclaw models list --all --provider zai 可查看已安装版本所知的目录。
视频生成¶
同一个插件和 ZAI_API_KEY(或 Z_AI_API_KEY)通过 zai/cogvideox-3
支持视频生成工具。它接受文本提示或
一张 PNG/JPEG 图片,包括以 data URI 形式发送的本地文件(最大 5 MB)。
不支持视频参考。
时长会归一化为 5 秒或 10 秒。尺寸和宽高比提示会映射到最接近的受支持尺寸:
1280x720、720x1280、1024x1024、1920x1080、1080x1920、
2048x1080 或 3840x2160。输出默认为无音频的 720P 横屏;audio: true
可启用声音。使用 providerOptions.quality(speed 或 quality)和
providerOptions.fps(30 或 60)进行进一步控制。
视频使用所配置的全球或中国区域通用 /api/paas/v4 端点。Coding Plan
聊天端点会映射到同一区域的通用视频端点;视频需要该端点的 API 访问权限和计费。
思考级别¶
级别:low、high 和 max(默认 max)。OpenClaw 会将这些映射到
Z.AI 的 reasoning_effort 请求字段。显式设置 off 会映射到
reasoning_effort: "low",因为 GLM-5.3 模型不支持完全禁用推理。
完整范围:off、low、high、max(默认 off)。OpenClaw
通过请求负载中的 reasoning_effort,将 low 和 high 映射到 Z.AI 的
high 推理强度,将 max 映射到 Z.AI 的 max 强度。
仅二元切换:off 和 low(在选择器中显示为 on),默认为 off。
将思考设置为 off 会发送 thinking: { type: "disabled" };任何其他级别
都会保持请求负载不变(应用 Z.AI 自身的默认推理行为)。
将思考设置为 off 可避免响应在可见文本之前把输出预算消耗在 reasoning_content 上。
高级配置¶
前向解析未知的 GLM-5 模型
当 id 与当前 GLM-5 系列形态匹配时,未知的 glm-5* id 仍会在提供商路径上
通过从 glm-4.7 模板合成提供商拥有的元数据进行前向解析。
工具调用流式传输
tool_stream 默认在 Z.AI 工具调用流式传输中启用。要禁用它:
保留思考
保留思考是选择性启用的,因为 Z.AI 要求重放完整的历史 reasoning_content,
这会增加提示词 token。请按模型启用它:
{
agents: {
defaults: {
models: {
"zai/glm-5.3": {
params: { preserveThinking: true },
},
},
},
},
}
启用后且思考开启时,OpenClaw 会发送
thinking: { type: "enabled", clear_thinking: false },并为同一个
OpenAI 兼容的对话记录重放先前的 reasoning_content。snake_case 的
preserve_thinking 参数键可作为别名使用。
高级用户仍可使用 params.extra_body.thinking 覆盖确切的提供商负载。
图像理解
Z.AI 插件注册了图像理解功能。
| 属性 | 值 |
|---|---|
| 模型 | glm-4.6v |
图像理解会根据所配置的 Z.AI 认证自动解析——无需额外配置。
认证详情
- Z.AI 使用 Bearer 认证与你的 API 密钥。
zai-api-key的初始设置选项会通过使用你的密钥检查受支持的端点,自动检测匹配的 Z.AI 端点。- 当你希望强制使用特定的 API 接口时,请使用显式区域选项(
zai-coding-global、zai-coding-cn、zai-global、zai-cn)。 - 旧的环境变量
Z_AI_API_KEY仍然被接受;如果ZAI_API_KEY未设置,OpenClaw 会在启动时将其复制为ZAI_API_KEY。
相关¶
选择提供商、模型引用和故障转移行为。
OpenClaw 完整配置结构,包括提供商和模型设置。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw