跳转至

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 plugins install @openclaw/zai-provider
**最适合:** 大多数用户。OpenClaw 会使用您的 API 密钥检查受支持的 Z.AI 端点,并自动应用正确的 base URL。

1. 运行入门配置

openclaw onboard --auth-choice zai-api-key

2. 验证模型已列出

openclaw models list --all --provider zai
**最适合:** 希望强制使用特定 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. 验证模型已列出

openclaw models list --all --provider zai

端点

入门配置项 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 响应,请等待并 重试请求。如果失败在高峰时段之外可重复出现,或仅 出现在某个端点、模型或请求形态中,请先检查已配置的端点 和模型:

openclaw models list --all --provider zai
openclaw config get models.providers.zai.baseUrl

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 行:

openclaw models list --all --provider zai

由清单支持的目录包括:

模型引用 说明
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 访问权限和计费。

{
  agents: {
    defaults: {
      mediaModels: {
        video: { primary: "zai/cogvideox-3" },
      },
    },
  },
}

思考级别

级别: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 工具调用流式传输中启用。要禁用它:

{
  agents: {
    defaults: {
      models: {
        "zai/<model>": {
          params: { tool_stream: false },
        },
      },
    },
  },
}
保留思考

保留思考是选择性启用的,因为 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