Integrating Zhipu GLM: Z.AI Dual Endpoints and the Coding Plan
OpenClaw Integration with GLM (Zhipu) is the third stop on the domestic-models track. In the previous two lessons, DeepSeek worked with a single environment variable, and Qwen did a pick-one-of-three; GLM's multiple-choice question is simpler — General API or Coding Plan, multiplied once more by the international site api.z.ai or the domestic site open.bigmodel.cn. Pick the wrong endpoint and your Key will be rejected and the default model won't match. The whole process takes about 8 minutes (Z.AI registration not included).
Here's a quick-reference table first — every configuration in this lesson starts from it (properties and values are quoted verbatim from the official documentation):
| Property | Value |
|---|---|
| Provider id | zai |
| Authentication environment variable | ZAI_API_KEY (the old alias Z_AI_API_KEY is still accepted and copied automatically at startup) |
| API style | Z.AI Chat Completions (Bearer authentication) |
| Official plugin | @openclaw/zai-provider (external plugin, needs to be installed) |
| Default model | Coding Plan: zai/glm-5.3; General API: zai/glm-5.2 |
| Key management console | https://z.ai/manage-apikey/apikey-list |
One thing you must know first: GLM is a model family, not a standalone provider (official wording: "GLM is a model family, not a separate provider"). Model references always start with zai/, e.g. zai/glm-5.3 — the provider is zai and the model id is glm-5.3.
Four endpoints — this table carries the whole lesson (auth-choice and endpoints are quoted verbatim from the official documentation):
| Purpose | auth-choice | Base URL | Default model |
|---|---|---|---|
| General API · International site | zai-global | https://api.z.ai/api/paas/v4 | glm-5.2 |
| General API · Domestic site | zai-cn | https://open.bigmodel.cn/api/paas/v4 | glm-5.2 |
| Coding Plan · International site | zai-coding-global | https://api.z.ai/api/coding/paas/v4 | glm-5.3 |
| Coding Plan · Domestic site | zai-coding-cn | https://open.bigmodel.cn/api/coding/paas/v4 | glm-5.3 |
How to choose, in three sentences:
| Your situation | Choose this |
|---|---|
| You subscribed to the GLM Coding Plan (monthly coding plan) | zai-coding-global / zai-coding-cn, with the default model being glm-5.3 |
| Pay-as-you-go billing | zai-global / zai-cn, with the default model glm-5.2 |
| Not sure which endpoint this Key works with | zai-api-key: OpenClaw tries the endpoints one by one with the Key; use the first one that accepts it |
Two additional facts, which will come in handy for troubleshooting later:
- Z.AI also has an Anthropic-compatible Coding Plan endpoint
https://api.z.ai/api/anthropic— that's for clients that speak the Anthropic Messages API directly; OpenClaw's zai option doesn't use it, it goes through the OpenAI Chat Completions endpoints in the table above. - On the Coding Plan endpoints, requests for GLM-5.2 / GLM-5.1 are routed by Z.AI to GLM-5.3.
💡 For those who arrived here by searching "Zhipu Qingyan"
"Zhipu Qingyan" is Zhipu's conversational product for general users; OpenClaw is not after that chat entry point, but an API Key for the GLM models—obtained from the Z.AI console (international site) or open.bigmodel.cn (China region). This page only covers API integration.
This tutorial is based on OpenClaw v2026.10.9.
What you'll be able to do after finishing this course
- Install the GLM official plugin
@openclaw/zai-providerand configureZAI_API_KEYinto OpenClaw—choose any of three paths: auto-detection, explicit endpoint, or manual configuration - Distinguish the General API and Coding Plan dual endpoints × the domestic / international two regions, and pick the right auth-choice for your Key
- Understand the GLM built-in catalog: where
glm-5.3,glm-5.3-flash, andglm-5.2each sit, and why you should stop usingglm-5.1 - Don't panic when you hit
429/1302/1305at peak hours: tell apart "temporary rate limiting" from "wrong endpoint" - Use GLM-exclusive capabilities:
/thinkreasoning tiers,cogvideox-3video generation,glm-4.6vimage understanding
🎒 Preparation before starting
- You have completed Model Connection Overview: the provider system and model switching: you have a clear grasp of the three steps "install plugin → configure credentials → pick a model" and the
provider/modelreference rules - OpenClaw is installed and the Gateway is running:
openclaw gateway statusproduces output (the plugin takes effect automatically on a running Gateway; if it isn't running, it takes effect on next startup) - You know whether your Key is from a Coding Plan or pay-as-you-go, and whether it was issued on the domestic site or the international site
- If you deploy via a server / daemon, you know where
~/.openclaw/.envis—that's where the Key will ultimately live
Follow along with me
Step 1: Create an API Key in the Z.AI console
Why: OpenClaw only handles the calling; the Key must first be obtained from the Z.AI side—and your account type (subscription / pay-as-you-go) determines which endpoint to choose in step 2.
- Open the Z.AI console
https://z.ai/manage-apikey/apikey-listin a browser, register / log in - Create an API Key, copy it, and paste it somewhere safe
- Domestic users: the China-region platform is
open.bigmodel.cn; domestic accounts manage Keys in its own console (the OpenClaw documentation only gives a direct link to the international-site console; for the domestic site, go to theopen.bigmodel.cnofficial website and find the API Key management page)
You should see: a copyable API Key. Unsure about your account type? Check your current plan on the subscription page https://z.ai/subscribe.
Step 2: Connect OpenClaw to GLM—install the plugin first, then configure ZAI_API_KEY
Why: Like DeepSeek and Qwen, zai is an external official plugin (not bundled with the core), which adds one extra "install" step compared to built-in plugins; once installed, auth-choice decides which endpoint is used.
Install the plugin first (the shared first step for both paths):
openclaw plugins install @openclaw/zai-providerYou should see: successful installation. It takes effect automatically on a running Gateway; if the Gateway isn't running, it takes effect at next startup.
Path A (recommended): onboarding wizard
The easiest way is auto-detection—OpenClaw tries the endpoints one by one with your Key:
openclaw onboard --auth-choice zai-api-keyDetection order (verbatim from the official documentation): try the General endpoints first (zai-global → zai-cn), then the Coding Plan endpoints (zai-coding-global → zai-coding-cn); the first one that accepts the request is used.
To force a specific endpoint (Coding Plan users are advised to choose explicitly—see the pitfall notes for why):
# 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-cnYou should see: first a prompt to enter the API Key, then the credential is saved after validation passes; the default model lands according to the endpoint—zai/glm-5.3 for Coding Plan, zai/glm-5.2 for General API.
Three reassurances (explicitly stated in the official documentation):
- The onboarding preserves your existing model entries—re-running it won't wipe out other providers' configuration
- Adding new provider credentials will not change your existing default model—to change the default, use Step 3's
openclaw models set - The legacy environment variable
Z_AI_API_KEYstill works: ifZAI_API_KEYis unset at startup, OpenClaw automatically copies it over
Path B: manually edit the configuration file
The official plugin normally does not require writing a models.providers entry—just install the plugin, set the auth, and pick a model; you only write one when overriding the default baseUrl (e.g., manually pinning the Coding Plan or domestic-site endpoint). Official configuration example (verbatim):
{
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" } } },
}Replace the baseUrl as needed (refer to the four-endpoint table above):
| Which endpoint you want | What to write as baseUrl |
|---|---|
| Coding Plan · international site | https://api.z.ai/api/coding/paas/v4 |
| Coding Plan · domestic site | https://open.bigmodel.cn/api/coding/paas/v4 |
| General API · international site | https://api.z.ai/api/paas/v4 |
| General API · domestic site | https://open.bigmodel.cn/api/paas/v4 |
Where to put the Key: in an interactive shell use export ZAI_API_KEY="<你的 API Key>", or write it into ~/.openclaw/.env (daemon deployments must go through the latter—see the warning below).
⚠️ Running the Gateway as a daemon? Don't put the Key in an interactive shell
When the Gateway runs as a launchd / systemd service, it cannot see the environment variables from export in your terminal. Write ZAI_API_KEY into ~/.openclaw/.env, or provide it to that process via env.shellEnv in the configuration.
- In
openclaw models status's credentials overview, the zai line shows whereZAI_API_KEYcomes from
Step 3: Pick a GLM model and verify
Why: the default model lands according to the endpoint (Coding Plan → glm-5.3, General → glm-5.2); if that's enough, just get it running first—but the six models in the catalog have different roles, so take a look before deciding.
First, look at the catalog:
openclaw models list --all --provider zaiYou should see: the GLM catalog built into the plugin manifest (excerpted verbatim from the official documentation; this catalog ships with the plugin manifest, a read-only list that doesn't require loading the provider runtime):
| Model reference | Context | Notes |
|---|---|---|
zai/glm-5.3 | 1,048,576 | Default for Coding Plan |
zai/glm-5.3-flash | 1,048,576 | Multimodal (text + images) |
zai/glm-5.2 | 1M | Default for General API |
zai/glm-5-turbo | 200K | OpenClaw optimized text model |
zai/glm-5v-turbo | 200K | multimodal coding model |
zai/glm-5.1 | — | deprecated; not shown if not configured; the official recommendation is to switch to GLM-5.2 |
The behavior of the three directories is spelled out clearly in the official Note:
- A fresh Coding Plan configuration defaults to
zai/glm-5.3; a General API configuration stays onzai/glm-5.2 - On Coding Plan endpoints, when the Key or a regional endpoint does not directly expose GLM-5.3, automatic probing falls back through
glm-5.1andglm-4.7 - When Coding Plan receives a request for GLM-5.2 / GLM-5.1, Z.AI routes it to GLM-5.3
How to choose, in three sentences:
| Your need | Pick it | Basis |
|---|---|---|
| Coding Plan users who don't know what to pick | zai/glm-5.3 | Official default, 1M context |
| Want the model to see images | zai/glm-5.3-flash (1M) / zai/glm-5v-turbo (200K) | Marked as multimodal in the directory |
| Pay-as-you-go and need to be able to fully turn off thinking | zai/glm-5.2 | thinking defaults to off and supports the off level (GLM-5.3 can't be turned off, see dedicated capabilities) |
To change the default model:
openclaw models set zai/glm-5.3You can also switch temporarily within a chat: /model zai/glm-5.2 only affects the current session; see Chat Commands Crash Course for the full command family.
Finally, verify — send a test message:
openclaw agent --agent main --model zai/glm-5.3 --message "用一句话介绍你自己"(openclaw agent requires at least one session selector; --agent main points to the default agent — installations that have completed onboarding have main by default; alternatively, run openclaw dashboard to open the Control UI and send directly in the chat box.)
You should see: the model replies normally, with no errors about missing credentials or a nonexistent model. At this point, OpenClaw is successfully connected to GLM.
Pricing in one sentence: GLM-5.3 is currently a Coding Plan model, so the local directory cost is zero — subscriptions use the plan quota and are not billed by token; pay-as-you-go directories follow Z.AI's current API pricing, and GLM-5.3 Flash uses the pay-as-you-go directory price (temporary discounts don't affect the directory price). Plan prices and availability are subject to the Z.AI subscription page https://z.ai/subscribe.
- The test message received a reply from GLM
Checkpoint ✅
openclaw plugins install @openclaw/zai-providerexecuted, plugin listed- auth-choice (or baseUrl) matches your Key type and region: Coding Plan Keys go to the coding endpoint, pay-as-you-go Keys go to the general endpoint
- zai's
ZAI_API_KEYis visible in the credentials overview ofopenclaw models status openclaw models list --all --provider zailists the GLM family of models- After sending the test message, a reply from GLM was received
- did not set
zai/glm-5.1as the default (deprecated)
Pitfall Reminders
❌ A Coding Plan Key configured against the General endpoint (or vice versa)
Cause: the official troubleshooting guide is very direct — Coding Plan Keys should use Coding Plan endpoints (e.g. https://api.z.ai/api/coding/paas/v4), and General API Keys should use General endpoints (e.g. https://api.z.ai/api/paas/v4). If the same Key + same endpoint keeps failing, it's more likely a provider-side rejection or a plan restriction, not ordinary peak-hour rate limiting.
The right fix: check the endpoint first, then everything else:
openclaw models list --all --provider zai
openclaw config get models.providers.zai.baseUrlIf the endpoint is wrong, rerun onboard and explicitly choose auth-choice, or manually edit models.providers.zai.baseUrl.
❌ The Key works on both sides, but auto-detection landed on General
Cause: zai-api-key probes General first (zai-global → zai-cn) then Coding Plan (zai-coding-global → zai-coding-cn), and uses the first one that accepts. When the Key is valid on both endpoint types, it gets assigned to General — so the default model becomes glm-5.2 instead of glm-5.3.
The right fix: the same official guidance — when the Key works on both sides and you want to use Coding Plan, explicitly specify it:
openclaw onboard --auth-choice zai-coding-global # 国际站
openclaw onboard --auth-choice zai-coding-cn # 国内站❌ Peak-hour 429 / 1305 errors, assumed to be a broken configuration
Cause: Z.AI officially lists the general agent tools (including OpenClaw) as capacity-hosted, best-effort services — during periods of high inference load (per the official wording: roughly Singapore time from 2–6 PM), some requests are temporarily rate-limited; Coding Plan rate limits and concurrency quotas are tied to the plan tier and adjusted dynamically based on resources, and off-peak concurrency may be higher.
For error code meanings, see the official API code documentation: 1302 = request rate limit reached; 1305 = service temporarily overloaded, please try again later.
The right fix: for temporary peak-hour 429 / 1305, just wait and retry. Only go back and check your configuration (the two commands from the previous pitfall) if failures persist even off-peak, or if they are concentrated on a single endpoint / model / request pattern.
❌ /think off can't turn off GLM-5.3's thinking
Cause: GLM-5.3 / GLM-5.3-flash only supports the three levels low / high / max (default max); fully turning it off is not supported—an explicit /think off gets mapped to reasoning_effort: "low".
Correct approach: if you need to fully turn off thinking (to save output budget), switch to zai/glm-5.2—it supports the full off / low / high / max, with off as the default. See the dedicated capabilities below for details.
❌ Still using zai/glm-5.1
Cause: glm-5.1 is deprecated; if it is not configured in the catalog it will not show up; the official recommendation is to switch to GLM-5.2. On the Coding Plan endpoint, requests for 5.2 / 5.1 are still routed by Z.AI to GLM-5.3—the model you think you are using and the model actually running are not the same.
Correct approach: switch to zai/glm-5.2 on the General API; use zai/glm-5.3 directly on the Coding Plan.
❌ After installing the Gateway as a daemon, the exported Key "doesn't take effect"
Cause: launchd / systemd services cannot see environment variables from an interactive shell—each provider's documentation stresses this repeatedly.
Correct approach: write ZAI_API_KEY into ~/.openclaw/.env, or provide it via env.shellEnv in the configuration; restart the Gateway service after changing the Key.
🔧 GLM dedicated capabilities (optional)
Once the plugin is installed, four GLM-dedicated capabilities come along with it.
thinking levels: three sets of mappings
| Model | Supported levels | Default | Mapping details |
|---|---|---|---|
| GLM-5.3 / 5.3-flash | low / high / max | max | mapped to Z.AI's reasoning_effort field; explicit off mapped to low (cannot be fully turned off) |
| GLM-5.2 | off / low / high / max | off | low / high mapped to Z.AI's high, max mapped to max, sent via reasoning_effort |
| Other GLM models | off / low (shown as on in the selector) | off | off sends thinking: { type: "disabled" }; other levels leave the request body untouched, following Z.AI's default reasoning behavior |
Use it directly in chat:
/think max # GLM-5.3 default level
/think off # on GLM-5.3 this is actually low; only on GLM-5.2 is it truly offThe official rationale: setting thinking to off avoids the reply spending its output budget first on reasoning_content, which would otherwise shorten the visible body.
Video generation: zai/cogvideox-3
The same plugin and the same ZAI_API_KEY (or Z_AI_API_KEY) can also drive the video generation tool, with the model zai/cogvideox-3:
- Input: a text prompt, or one PNG / JPEG image (local files sent as data URIs, up to 5 MB); video references are not supported
- Duration: normalized to 5 or 10 seconds
- Size: mapped to the nearest supported size—
1280x720,720x1280,1024x1024,1920x1080,1080x1920,2048x1080,3840x2160 - Default 720P landscape, no audio;
audio: trueenables sound - Advanced:
providerOptions.quality(speed/quality),providerOptions.fps(30/60)
Set as the default video provider (official configuration example, verbatim):
{
agents: {
defaults: {
mediaModels: {
video: { primary: "zai/cogvideox-3" },
},
},
},
}⚠️ Video goes through the General endpoint and cannot be charged directly against a Coding Plan subscription
Video generation uses the General /api/paas/v4 endpoint of the region you configured (international / China); the Coding Plan chat endpoint is mapped to the General video endpoint of the same region—video requires that endpoint's API access and billing, which is not included in the Coding Plan monthly quota.
To systematically work with images, voice, and video, see Images and voice: adding images to content, converting articles to speech.
Image understanding: glm-4.6v
The Z.AI plugin registers an image understanding capability, with the model glm-4.6v—automatically resolved from your configured Z.AI credentials, no extra configuration needed.
advanced: tool_stream, preserveThinking, and unknown GLM-5 ids
- Tool-call streaming:
tool_streamis on by default. To turn it off, replace the parameter in the configuration below withtool_stream: falseand the model key with the correspondingzai/<模型> - Preserve thinking (preserveThinking): off by default—Z.AI requires replaying the full history
reasoning_content, which increases prompt tokens. Enable per model (official example, verbatim):
{
agents: {
defaults: {
models: {
"zai/glm-5.3": {
params: { preserveThinking: true },
},
},
},
},
}Once enabled, during thinking it sends thinking: { type: "enabled", clear_thinking: false } and replays the history of the same OpenAI-compatible transcript reasoning_content (the snake_case preserve_thinking is an alias). Advanced users can use params.extra_body.thinking to precisely override the provider payload.
- Forward resolution of unknown GLM-5 ids: for
glm-5*ids not in the catalog, as long as they match the current GLM-5 family pattern, the provider synthesizes metadata using theglm-4.7template to complete resolution
Next steps
OpenClaw GLM configuration is complete at this point. Continue on the domestic models page:
- Next lesson Connecting to Kimi: the Moonshot and Kimi Coding plugins: why Moonshot and Kimi Coding are two plugins with two Keys
- Other model pages (MiniMax, Doubao, Hunyuan / Qianfan, relay and local models) are reachable from the course schedule in Model connection overview
- Model all set up? For everyday use, start with Daily Use: Working Efficiently with Your Claw — the Control UI, chat commands, and memory system are all covered in that chapter