Z.AI Provider for GLM Models in OpenClaw

Z.AI serves as the API platform for the GLM model series. Authentication happens through API keys, with REST endpoints provided for GLM access. Head to the Z.AI console to generate your API key. Within OpenClaw, the zai provider is configured using a Z.AI API key.

GLM models

Rather than being a standalone provider, GLM is a model family. In OpenClaw, GLM models are referenced with identifiers like zai/glm-5.3: the provider is zai, and the model id is glm-5.3.

Getting started

Start by installing the provider plugin:

openclaw plugins install @openclaw/zai-provider

Auto-detect endpoint

Best for: most users. OpenClaw tests supported Z.AI endpoints using your API key and sets the proper base URL on its own.

Run onboarding

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

Verify the model is listed

openclaw models list --all --provider zai

Explicit regional endpoint

Best for: users who need to pin down a particular Coding Plan or general API surface.

Pick the right onboarding choice

# 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

Verify the model is listed

openclaw models list --all --provider zai

Endpoints

An Anthropic-compatible Coding Plan base URL, https://api.z.ai/api/anthropic, is also published by Z.AI. The Z.AI options in OpenClaw rely on the OpenAI Chat Completions endpoints listed above; the Anthropic URL exists for clients that communicate directly via Anthropic Messages.

By probing your key against each endpoint's chat-completions API, zai-api-key determines which of the four applies. General endpoints (zai-global, then zai-cn) are checked before Coding Plan endpoints (zai-coding-global, then zai-coding-cn), and the first endpoint that accepts a request wins. If your key works across both types, pick an explicit --auth-choice to force a Coding Plan endpoint.

Rate limits and overloads

Both the Coding Plan and general-purpose agent tools are documented by Z.AI as capacity managed services. From Z.AI's documentation:

• General-purpose agent tools, which cover OpenClaw, run on a best-effort basis. When inference load is high, usually from around 2-6 PM Singapore time, some requests might hit temporary rate limits.
• Coding Plan rate and concurrency limits depend on the plan tier and can shift dynamically with resource availability. Concurrency may be higher during off-peak hours.
• API error code 1302 signals "Rate limit reached for requests". API error code 1305 signals "The service may be temporarily overloaded, please try again later".

When you encounter a temporary 429 or 1305 response during peak times, pause and retry. If failures persist outside peak periods, or show up for just one endpoint, model, or request pattern, start by checking the configured endpoint and model:

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

Keys for the Coding Plan should point to a Coding Plan endpoint like https://api.z.ai/api/coding/paas/v4; general API keys should target a general API endpoint like https://api.z.ai/api/paas/v4. Repeated failures with the same key and endpoint may point to a provider-side rejection or plan limitation rather than standard peak-load throttling.

Config example

Tip

With zai-api-key, OpenClaw can match the right Z.AI endpoint from the key and apply the correct base URL automatically. Choose the explicit regional options when you want to lock in a specific Coding Plan or general API surface.

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

Built-in catalog

Because the zai provider plugin carries its catalog in the plugin manifest, read-only listing can display known GLM rows without needing to load the provider runtime:

openclaw models list --all --provider zai

The manifest-backed catalog currently includes:

The pay-as-you-go catalog entries reflect Z.AI's live API pricing. Even when temporary discounts apply, GLM-5.3 Flash still bills at its standard pay-as-you-go rates. Since GLM-5.3 is part of the Coding Plan, its local catalog cost sits at zero; Coding Plan subscriptions draw from plan quota rather than per-token charges. For current plan pricing and availability, check the subscription page directly.

Tip

GLM models come through as zai/<model> (for instance, zai/glm-5.3).

Note

A fresh Coding Plan setup picks zai/glm-5.3 by default; general API setup continues with zai/glm-5.2. On Coding Plan endpoints, auto-detection steps down through glm-5.1 and glm-4.7 when a key or regional endpoint doesn't expose GLM-5.3 directly. Z.AI currently directs Coding Plan traffic for GLM-5.2 and GLM-5.1 to GLM-5.3. Running openclaw models list --all --provider zai shows the catalog your installed version recognizes.

Thinking levels

GLM-5.3 and Flash

Available levels: low, high, and max (with max as the default). OpenClaw translates these into Z.AI's reasoning_effort request field. An explicit off setting gets mapped to reasoning_effort: "low", since GLM-5.3 models can't fully turn off reasoning.

GLM-5.2

The complete range: off, low, high, max (defaulting to off). OpenClaw converts low and high into Z.AI's high reasoning effort, and max into Z.AI's max effort, using reasoning_effort on the request payload.

Other GLM models

Only a binary switch exists: off and low (displayed as on in pickers), defaulting to off. Setting thinking to off transmits thinking: { type: "disabled" }; any other level leaves the request payload as-is (Z.AI's own default reasoning behavior then applies).

Choosing off for thinking prevents responses from burning the output budget on reasoning_content before any visible text appears.

Advanced configuration

Forward-resolving unknown GLM-5 models

Unrecognized glm-5* ids still resolve forward on the provider path by generating provider-owned metadata from the glm-4.7 template when the id matches the current GLM-5 family shape.

Tool-call streaming

For Z.AI tool-call streaming, tool_stream is turned on by default. To switch it off:

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

Preserved thinking

Thinking preservation is opt-in because Z.AI demands the complete historical reasoning_content be replayed, which raises prompt tokens. Activate it per model:

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

With it enabled and thinking active, OpenClaw sends thinking: { type: "enabled", clear_thinking: false } and replays prior reasoning_content for the same OpenAI-compatible transcript. The snake_case preserve_thinking param key works as an alias.

For precise control, advanced users can still override the provider payload with params.extra_body.thinking.

Image understanding

Image understanding gets registered by the Z.AI plugin.

Image understanding resolves automatically from the configured Z.AI auth, so no extra configuration is required.

Auth details

• Z.AI authenticates via Bearer tokens, which rely on your API key.
• The zai-api-key onboarding option identifies the correct Z.AI endpoint automatically by testing various endpoints with your key.
• To lock in a particular API surface, pick the explicit regional choices (zai-coding-global, zai-coding-cn, zai-global, zai-cn).
• The older environment variable Z_AI_API_KEY remains supported; if ZAI_API_KEY is not set, OpenClaw transfers its value to ZAI_API_KEY during startup.

Related

• Model selection, Details on provider choice, model references, and failover handling.

• Configuration reference, The complete OpenClaw configuration schema, covering provider and model options.