接入智谱 GLM：Z.AI 双端点与 Coding Plan

OpenClaw 接入 GLM（智谱）是国产模型专页的第三站。前两课 DeepSeek 一个环境变量就通了、Qwen 做了三选一；GLM 的选择题更简单——General API 还是 Coding Plan，再乘一次国际站 api.z.ai 还是国内站 open.bigmodel.cn。选错端点，Key 会被拒、默认模型也对不上号。全程约 8 分钟（Z.AI 注册另计）。

先给你一张速览表，本课所有配置都从它出发（属性与值为官方文档原样摘录）：

属性	值
Provider id	`zai`
认证环境变量	`ZAI_API_KEY`（旧别名 `Z_AI_API_KEY` 仍接受，启动时自动拷贝）
API 形态	Z.AI Chat Completions（Bearer 认证）
官方插件	`@openclaw/zai-provider`（外部插件，需安装）
默认模型	Coding Plan：`zai/glm-5.3`；General API：`zai/glm-5.2`
Key 管理控制台	`https://z.ai/manage-apikey/apikey-list`

一件必须先知道的事：GLM 是模型家族，不是独立 provider（官方原话："GLM is a model family, not a separate provider"）。模型引用一律 zai/ 开头，如 zai/glm-5.3——provider 是 zai，模型 id 是 glm-5.3。

四个端点，全课就靠这张表（auth-choice 与端点为官方文档原样摘录）：

用途	auth-choice	Base URL	默认模型
General API · 国际站	`zai-global`	`https://api.z.ai/api/paas/v4`	`glm-5.2`
General API · 国内站	`zai-cn`	`https://open.bigmodel.cn/api/paas/v4`	`glm-5.2`
Coding Plan · 国际站	`zai-coding-global`	`https://api.z.ai/api/coding/paas/v4`	`glm-5.3`
Coding Plan · 国内站	`zai-coding-cn`	`https://open.bigmodel.cn/api/coding/paas/v4`	`glm-5.3`

怎么选，三句话：

你的情况	选它
订阅了 GLM Coding Plan（包月写代码）	`zai-coding-global` / `zai-coding-cn`，默认模型直接是 `glm-5.3`
按量付费（pay-as-you-go）	`zai-global` / `zai-cn`，默认模型 `glm-5.2`
拿不准这把 Key 能用哪个端点	`zai-api-key`：OpenClaw 拿 Key 逐个试端点，第一个接受就用

两个补充事实，后面排障会用到：

Z.AI 另有一个 Anthropic 兼容的 Coding Plan 端点 https://api.z.ai/api/anthropic——那是给直接讲 Anthropic Messages 的客户端用的；OpenClaw 的 zai 选项不用它，走的是上表的 OpenAI Chat Completions 端点。
Coding Plan 端点上，GLM-5.2 / GLM-5.1 的请求会被 Z.AI 路由到 GLM-5.3。

💡 从「智谱清言」搜进来的朋友

「智谱清言」是智谱面向普通用户的对话产品；OpenClaw 要的不是那个聊天入口，而是 GLM 模型的 API Key——从 Z.AI 控制台（国际站）或 open.bigmodel.cn（中国区）拿。本页只讲 API 接入。

本教程基于 OpenClaw v2026.10.9。

学完你能做什么

装上 GLM 官方插件 @openclaw/zai-provider，把 ZAI_API_KEY 配进 OpenClaw——自动探测、显式端点、手动配置三条路任选
分清 General API 与 Coding Plan 双端点 × 国内 / 国际两套区域，按自己的 Key 选对 auth-choice
看懂 GLM 内置目录：glm-5.3、glm-5.3-flash、glm-5.2 各自的位置，以及 glm-5.1 为什么别再用
高峰期遇到 429 / 1302 / 1305 不慌：分清「临时限流」和「端点配错」
用上 GLM 专属能力：/think 推理档位、cogvideox-3 视频生成、glm-4.6v 图像理解

🎒 开始前的准备

完成了连接模型总览：provider 体系与模型切换：「装插件 → 配凭据 → 选模型」三步和 provider/model 引用规则心里有数
OpenClaw 已安装、Gateway 在运行：openclaw gateway status 有输出（插件对运行中的 Gateway 自动生效；没在跑则下次启动生效）
知道自己的 Key 是 Coding Plan 还是按量付费、国内站还是国际站发的
走服务器 / 守护进程部署的话，知道 ~/.openclaw/.env 在哪——Key 最终要住那里

跟我做

第 1 步：在 Z.AI 控制台创建 API Key

为什么：OpenClaw 只负责调用，Key 得先从 Z.AI 侧拿——而且你的账号类型（订阅 / 按量）决定了第 2 步选哪个端点。

浏览器打开 Z.AI 控制台 https://z.ai/manage-apikey/apikey-list，注册 / 登录
创建一把 API Key，复制后粘贴到安全的地方
国内用户：中国区平台是 open.bigmodel.cn，国内账号在它自己的控制台里管理 Key（OpenClaw 文档只给了国际站控制台直链，国内站入口进 open.bigmodel.cn 官网找 API Key 管理页）

你应该看到：一把可复制的 API Key。拿不准账号类型？去订阅页 https://z.ai/subscribe 看一眼当前套餐。

第 2 步：OpenClaw 接入 GLM——先装插件，再配 ZAI_API_KEY

为什么：zai 和 DeepSeek、Qwen 一样是外部官方插件（不随核心内置），比内置插件多一步「安装」；装完后，auth-choice 决定走哪个端点。

先装插件（两条方式共用的第一步）：

bash

openclaw plugins install @openclaw/zai-provider

你应该看到：安装成功。对运行中的 Gateway 自动生效；Gateway 没在跑则下次启动时生效。

方式 A（推荐）：onboarding 引导

最省事的是自动探测——OpenClaw 拿你的 Key 逐个试端点：

bash

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

探测顺序（官方文档原样）：先试 General 端点（zai-global → zai-cn），再试 Coding Plan 端点（zai-coding-global → zai-coding-cn），第一个接受请求的就用。

要强制指定端点（Coding Plan 用户推荐显式选，原因见踩坑提醒）：

bash

# Coding Plan · 国际站 / 国内站（Coding Plan 用户推荐）
openclaw onboard --auth-choice zai-coding-global
openclaw onboard --auth-choice zai-coding-cn

# General API · 国际站 / 国内站
openclaw onboard --auth-choice zai-global
openclaw onboard --auth-choice zai-cn

你应该看到：先提示输入 API Key，验证通过后保存凭据；默认模型按端点落位——Coding Plan 是 zai/glm-5.3，General API 是 zai/glm-5.2。

三个定心丸（官方文档明确写了）：

onboarding 保留你已有的模型条目——重跑不会清掉其他 provider 的配置
加新 provider 凭据不会改你已有的默认模型——要换默认，用第 3 步的 openclaw models set
旧环境变量 Z_AI_API_KEY 仍然有效：启动时若 ZAI_API_KEY 未设，OpenClaw 会自动把它拷贝过来

方式 B：手动改配置文件

官方插件本来不需要写 models.providers 条目——装插件、设 auth、选模型即可；只有要覆盖默认 baseUrl（比如手动钉死 Coding Plan 或国内站端点）才写。官方配置示例（原样）：

json5

{
  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" } } },
}

按需替换 baseUrl（对照上面的四端点表）：

想走哪个端点	baseUrl 写什么
Coding Plan · 国际站	`https://api.z.ai/api/coding/paas/v4`
Coding Plan · 国内站	`https://open.bigmodel.cn/api/coding/paas/v4`
General API · 国际站	`https://api.z.ai/api/paas/v4`
General API · 国内站	`https://open.bigmodel.cn/api/paas/v4`

Key 放哪：交互 shell 里 export ZAI_API_KEY="<你的 API Key>"，或写进 ~/.openclaw/.env（守护进程部署必须走这里，见下方警告）。

⚠️ Gateway 跑成守护进程？Key 别放交互 shell

Gateway 作为 launchd / systemd 服务运行时，看不到你终端里 export 的环境变量。把 ZAI_API_KEY 写进 ~/.openclaw/.env，或经配置里的 env.shellEnv 提供给那个进程。

openclaw models status 的凭据概览里，zai 一行能看到 ZAI_API_KEY 的来源

第 3 步：选择 GLM 模型并验证

为什么：默认模型按端点落位（Coding Plan → glm-5.3，General → glm-5.2），够用就先跑通；但目录里六个模型分工不同，看一眼再决定。

先看目录：

bash

openclaw models list --all --provider zai

你应该看到：插件清单内置的 GLM 目录（官方文档原样摘录；这套目录随插件 manifest 走，只读列表不用加载 provider 运行时）：

模型引用	上下文	备注
`zai/glm-5.3`	1,048,576	Coding Plan 默认
`zai/glm-5.3-flash`	1,048,576	多模态（文本 + 图像）
`zai/glm-5.2`	1M	General API 默认
`zai/glm-5-turbo`	200K	OpenClaw 优化的文本模型
`zai/glm-5v-turbo`	200K	多模态 coding 模型
`zai/glm-5.1`	—	已弃用；不配置不显示；官方建议改用 GLM-5.2

三个目录行为，官方 Note 写得明白：

全新 Coding Plan 配置默认 zai/glm-5.3；General API 配置停在 zai/glm-5.2
Coding Plan 端点上，Key 或区域端点不直接暴露 GLM-5.3 时，自动探测会顺着 glm-5.1、glm-4.7 回落
Coding Plan 收到 GLM-5.2 / GLM-5.1 的请求，Z.AI 会路由到 GLM-5.3

怎么选，三句话：

你的需求	选它	依据
Coding Plan 用户，不知道选啥	`zai/glm-5.3`	官方默认，1M 上下文
要模型看图	`zai/glm-5.3-flash`（1M）/ `zai/glm-5v-turbo`（200K）	目录里标了多模态
按量付费、要能完全关掉思考	`zai/glm-5.2`	thinking 默认 `off` 且支持 `off` 档（GLM-5.3 关不掉，见专属能力）

换默认模型：

bash

openclaw models set zai/glm-5.3

聊天里临时切也行：/model zai/glm-5.2 只影响当前会话，命令族详见聊天命令速成。

最后验证——发一句测试消息：

bash

openclaw agent --agent main --model zai/glm-5.3 --message "用一句话介绍你自己"

（openclaw agent 要求至少给一个会话选择器，--agent main 指向默认 agent——完成过 onboarding 的安装里默认就有 main；或者 openclaw dashboard 打开 Control UI，在聊天框直接发。）

你应该看到：模型正常回复，没有凭据缺失或模型不存在的报错。到这里，OpenClaw 接入 GLM 就通了。

价格一句话：GLM-5.3 目前是 Coding Plan 模型，本地目录 cost 为零——订阅用套餐额度，不按 token 计费；按量付费目录跟随 Z.AI 当前 API 定价，GLM-5.3 Flash 用按量目录价（临时折扣不影响目录价）。套餐价格与可用性以 Z.AI 订阅页 https://z.ai/subscribe 为准。

测试消息收到了来自 GLM 的回复

检查点 ✅

openclaw plugins install @openclaw/zai-provider 已执行，插件在列
auth-choice（或 baseUrl）与你的 Key 类型、区域配套：Coding Plan Key 走 coding 端点，按量 Key 走 general 端点
openclaw models status 的凭据概览里能看到 zai 的 ZAI_API_KEY
openclaw models list --all --provider zai 列出 GLM 系模型
测试消息发出后收到了 GLM 的回复
没有把 zai/glm-5.1 设为默认（已弃用）

踩坑提醒

❌ Coding Plan 的 Key 配到了 General 端点（或反过来）

原因：官方排障指引写得很直白——Coding Plan Key 应该用 Coding Plan 端点（如 https://api.z.ai/api/coding/paas/v4），General API Key 用 General 端点（如 https://api.z.ai/api/paas/v4）。同一把 Key + 同一端点持续失败，更可能是 provider 侧拒绝或套餐限制，不是普通高峰限流。

正确做法：先查端点再查别的：

bash

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

端点不对就重跑 onboard 显式选 auth-choice，或手动改 models.providers.zai.baseUrl。

❌ Key 两边都能用，自动探测却落到了 General

原因：zai-api-key 的探测顺序是先 General（zai-global → zai-cn）后 Coding Plan（zai-coding-global → zai-coding-cn），第一个接受就用。Key 在两类端点都有效时，会被分到 General——默认模型就成了 glm-5.2 而不是 glm-5.3。

正确做法：官方同一句指引——Key 两边都能用时，想走 Coding Plan 就显式指定：

bash

openclaw onboard --auth-choice zai-coding-global   # 国际站
openclaw onboard --auth-choice zai-coding-cn       # 国内站

❌ 高峰期 429 / 1305 报错，以为是配置坏了

原因：Z.AI 官方把通用 agent 工具（含 OpenClaw）列为容量托管、best-effort 服务——高推理负载时段（官方说法：约新加坡时间下午 2–6 点）部分请求会临时限流；Coding Plan 的限速与并发额度跟套餐档位挂钩、按资源动态调整，非高峰并发可能更高。

错误码含义见官方 API code 文档：1302 = 请求达到限速；1305 = 服务临时过载，请稍后再试。

正确做法：高峰期的临时 429 / 1305，等待重试就好。只有非高峰期仍持续失败、或失败只集中在某一个端点 / 模型 / 请求形态时，才回头查配置（上一坑的两条命令）。

❌ `/think off` 关不掉 GLM-5.3 的思考

原因：GLM-5.3 / GLM-5.3-flash 只支持 low / high / max 三档（默认 max），不支持完全关闭——显式 /think off 会被映射成 reasoning_effort: "low"。

正确做法：需要彻底关思考（省输出预算）就换 zai/glm-5.2——它支持完整 off / low / high / max，默认就是 off。详见下方专属能力。

❌ 还在用 zai/glm-5.1

原因：glm-5.1 已弃用，目录里不配置就不显示；官方建议改用 GLM-5.2。Coding Plan 端点上 5.2 / 5.1 的请求还会被 Z.AI 路由到 GLM-5.3——你以为在用的模型和实际跑的模型不是同一个。

正确做法：General API 换 zai/glm-5.2；Coding Plan 直接 zai/glm-5.3。

❌ Gateway 装成守护进程后，export 的 Key「不生效」

原因：launchd / systemd 服务看不到交互 shell 的环境变量——各 provider 文档反复强调这一点。

正确做法：ZAI_API_KEY 写进 ~/.openclaw/.env，或经配置里的 env.shellEnv 提供；换 Key 后重启 Gateway 服务。

🔧 GLM 专属能力（可选）

插件装好之后，四件 GLM 专属的能力跟着来。

thinking 档位：三套映射

模型	支持档位	默认	映射细节
GLM-5.3 / 5.3-flash	`low` / `high` / `max`	`max`	映射到 Z.AI 的 `reasoning_effort` 字段；显式 `off` 映射为 `low`（不能全关）
GLM-5.2	`off` / `low` / `high` / `max`	`off`	`low` / `high` 映射到 Z.AI 的 `high`，`max` 映射到 `max`，经 `reasoning_effort` 发送
其他 GLM 模型	`off` / `low`（选择器里显示 `on`）	`off`	`off` 发 `thinking: { type: "disabled" }`；其余档位不动请求体，按 Z.AI 默认推理行为

聊天里直接用：

text

/think max   # GLM-5.3 默认档
/think off   # GLM-5.3 上实际是 low；GLM-5.2 上才是真关

官方给的理由：把思考设为 off，可以避免回复把输出预算先花在 reasoning_content 上、可见正文反而变短。

视频生成：zai/cogvideox-3

同一个插件、同一把 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）

设为默认视频 provider（官方配置示例，原样）：

json5

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

⚠️ 视频走 General 端点，Coding Plan 订阅不能直接抵

视频生成用的是你配置区域（国际 / 国内）的 General /api/paas/v4 端点；Coding Plan 聊天端点会映射到同区域的 General 视频端点——视频需要该端点的 API 访问与计费，不是 Coding Plan 包月额度里自带的。

想系统玩配图、语音、视频，见图片与语音：给内容配图、把文章转语音。

图像理解：glm-4.6v

Z.AI 插件注册了图像理解能力，模型 glm-4.6v——自动从你配置的 Z.AI 凭据解析，无需额外配置。

进阶：tool_stream、preserveThinking 与未知 GLM-5 id

工具调用流式：tool_stream 默认开启。要关，把下面配置里的参数换成 tool_stream: false、模型键换成对应 zai/<模型>
保留思考（preserveThinking）：默认不开——Z.AI 要求回放完整历史 reasoning_content，会增加 prompt token。按模型开启（官方示例，原样）：

json5

{
  agents: {
    defaults: {
      models: {
        "zai/glm-5.3": {
          params: { preserveThinking: true },
        },
      },
    },
  },
}

开启后思考时发 thinking: { type: "enabled", clear_thinking: false }，并回放同一条 OpenAI 兼容 transcript 的历史 reasoning_content（snake_case 的 preserve_thinking 是别名）。进阶用户可用 params.extra_body.thinking 精确覆盖 provider payload。

未知 GLM-5 id 前向解析：目录里没有的 glm-5* id，只要匹配当前 GLM-5 家族形态，provider 会用 glm-4.7 模板合成元数据完成解析

下一步

OpenClaw 智谱 GLM 配置到此通关。国产模型专页继续走：

下一课接入 Kimi：Moonshot 与 Kimi Coding 两个插件：Moonshot 和 Kimi Coding 为什么是两个插件、两把 Key
其他模型专页（MiniMax、豆包、混元 / 千帆、中转与本地模型）从连接模型总览的课程表进
模型配好了？日常使用从日常使用：和你的 Claw 高效相处开始——Control UI、聊天命令、记忆系统都在那一章

接入智谱 GLM：Z.AI 双端点与 Coding Plan ​

学完你能做什么 ​

🎒 开始前的准备 ​

跟我做 ​

第 1 步：在 Z.AI 控制台创建 API Key ​

第 2 步：OpenClaw 接入 GLM——先装插件，再配 ZAI_API_KEY ​

方式 A（推荐）：onboarding 引导 ​

方式 B：手动改配置文件 ​

第 3 步：选择 GLM 模型并验证 ​

检查点 ✅ ​

踩坑提醒 ​

❌ Coding Plan 的 Key 配到了 General 端点（或反过来） ​

❌ Key 两边都能用，自动探测却落到了 General ​

❌ 高峰期 429 / 1305 报错，以为是配置坏了 ​

❌ /think off 关不掉 GLM-5.3 的思考 ​

❌ 还在用 zai/glm-5.1 ​

❌ Gateway 装成守护进程后，export 的 Key「不生效」 ​

🔧 GLM 专属能力（可选） ​

thinking 档位：三套映射 ​

视频生成：zai/cogvideox-3 ​

图像理解：glm-4.6v ​

下一步 ​

相关教程 ​

接入智谱 GLM：Z.AI 双端点与 Coding Plan

学完你能做什么

🎒 开始前的准备

跟我做

第 1 步：在 Z.AI 控制台创建 API Key

第 2 步：OpenClaw 接入 GLM——先装插件，再配 ZAI_API_KEY

方式 A（推荐）：onboarding 引导

方式 B：手动改配置文件

第 3 步：选择 GLM 模型并验证

检查点 ✅

踩坑提醒

❌ Coding Plan 的 Key 配到了 General 端点（或反过来）

❌ Key 两边都能用，自动探测却落到了 General

❌ 高峰期 429 / 1305 报错，以为是配置坏了

❌ `/think off` 关不掉 GLM-5.3 的思考

❌ 还在用 zai/glm-5.1

❌ Gateway 装成守护进程后，export 的 Key「不生效」

🔧 GLM 专属能力（可选）

thinking 档位：三套映射

视频生成：zai/cogvideox-3

图像理解：glm-4.6v

下一步

相关教程