Z.AI Provider Setup: GLM Models in OpenClaw

Z.AI is the API platform that serves GLM models. It exposes REST APIs for GLM and authenticates callers with API keys. You create your API key in the Z.AI console. In OpenClaw, the zai provider is used together with a Z.AI API key.

GLM models

GLM is a model family rather than a provider of its own. Within OpenClaw, GLM models are addressed through refs like zai/glm-5.3: the provider is zai and the model id is glm-5.3.

Getting started

Begin by installing the provider plugin:

openclaw plugins install @openclaw/zai-provider

Auto-detect endpoint

Best for: most users. With your API key, OpenClaw probes the supported Z.AI endpoints and then sets the correct 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 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

Z.AI additionally publishes an Anthropic-compatible Coding Plan base URL, https://api.z.ai/api/anthropic. The Z.AI choices in OpenClaw rely on the documented OpenAI Chat Completions endpoints listed above; that Anthropic URL is meant for clients that speak Anthropic Messages directly.

zai-api-key works out which of the four applies by testing your key against each endpoint's chat-completions API. General endpoints are tried first (zai-global, then zai-cn), followed by Coding Plan endpoints (zai-coding-global, then zai-coding-cn), and the search stops as soon as one endpoint accepts the request. If your key works on both kinds, supply an explicit --auth-choice to force a Coding Plan endpoint.

Rate limits and overloads

Z.AI describes the Coding Plan and general-purpose agent tools as capacity managed services. Per Z.AI's own documentation:

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

Should a temporary 429 or 1305 response appear during a busy period, wait and retry the request. When failures repeat outside peak periods, or show up only for a single endpoint, model, or request shape, verify the configured endpoint and model first:

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

Coding Plan keys belong on a Coding Plan endpoint such as https://api.z.ai/api/coding/paas/v4; general API keys belong on a general API endpoint such as https://api.z.ai/api/paas/v4. Repeated failures with the same key and endpoint may point to a rejection or plan limitation on the provider side rather than ordinary peak-load throttling.

Config example

Tip

With zai-api-key, OpenClaw identifies the matching Z.AI endpoint from the key and applies the correct base URL automatically. Choose the explicit regional options when you need to pin 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

The catalog for the zai provider plugin is shipped in the plugin manifest, so a read-only listing can display the known GLM rows without loading the provider runtime:

openclaw models list --all --provider zai

The manifest-backed catalog includes:

Rows in the pay-as-you-go catalog track Z.AI's current API pricing. Even when temporary discounts apply, GLM-5.3 Flash is billed at its pay-as-you-go list prices. Because GLM-5.3 is a Coding Plan model at present, its cost in the local catalog is zero; Coding Plan subscriptions draw on plan quota rather than per-token billing. Plan pricing and availability are listed on the live subscription page.

Tip

You can use GLM models as zai/<model> (for example, zai/glm-5.3).

Note

A new Coding Plan setup starts on zai/glm-5.3 by default, while general API setup stays on zai/glm-5.2. When a key or regional endpoint does not expose GLM-5.3 directly, auto-detection on Coding Plan endpoints falls back via glm-5.1 and glm-4.7. Requests that Z.AI receives for GLM-5.2 and GLM-5.1 on the Coding Plan are currently routed to GLM-5.3. To inspect the catalog your installed version knows about, run openclaw models list --all --provider zai.

Video generation

The video generation tool is provided by the same plugin and ZAI_API_KEY (or Z_AI_API_KEY), with zai/cogvideox-3. It takes text prompts or a single PNG/JPEG image, and local files can be sent as data URIs (5 MB maximum). Video references are not supported.

Durations are normalized to 5 or 10 seconds. Any size or aspect-ratio hint is mapped to the closest supported size: 1280x720, 720x1280, 1024x1024, 1920x1080, 1080x1920, 2048x1080, or 3840x2160. By default the output is 720P landscape with no audio; set audio: true to turn sound on. For finer control, use providerOptions.quality (speed or quality) and providerOptions.fps (30 or 60).

Video goes through the general /api/paas/v4 endpoint of whichever region is configured, global or China. On Coding Plan chat endpoints, requests map to the general video endpoint in that same region; using video therefore requires API access and billing on that endpoint.

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

Thinking levels

GLM-5.3 and Flash

Options: low, high, and max (max is the default). OpenClaw sends these in Z.AI's reasoning_effort request field. Setting off explicitly maps to reasoning_effort: "low", since GLM-5.3 models cannot turn reasoning off completely.

GLM-5.2

The full set is off, low, high, max (default off). OpenClaw sends low and high as Z.AI's high reasoning effort, while max becomes Z.AI's max effort, both through reasoning_effort in the request payload.

Other GLM models

Only two values are accepted: off and low (displayed as on inside pickers), with off as the default. When thinking is set to off, thinking: { type: "disabled" } gets sent; at any other level the request payload is left unchanged, so Z.AI's own default reasoning behavior takes effect.

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

Advanced configuration

Forward-resolving unknown GLM-5 models

An unrecognized glm-5* id can still be resolved on the provider path: if the id fits the shape of the current GLM-5 family, provider-owned metadata is synthesized from the glm-4.7 template.

Tool-call streaming

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

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

Preserved thinking

Preserved thinking is opt-in, since Z.AI needs the whole historical reasoning_content replayed, which raises prompt token counts. Turn it on per model:

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

Once it is enabled and thinking is active, OpenClaw sends thinking: { type: "enabled", clear_thinking: false } and replays earlier reasoning_content for the same OpenAI-compatible transcript. The snake_case preserve_thinking parameter key serves as an alias.

Advanced users who need to override the exact provider payload can still do so with params.extra_body.thinking.

Image understanding

Image understanding is registered by the Z.AI plugin.

No extra configuration is required: image understanding is resolved automatically from the Z.AI auth you have configured.

Auth details

• Authentication for Z.AI is Bearer auth using your API key.
• The zai-api-key onboarding choice finds the matching Z.AI endpoint on its own by testing supported endpoints with your key.
• To force a particular API surface, pick one of the explicit regional options (zai-coding-global, zai-coding-cn, zai-global, zai-cn).
• The legacy environment variable Z_AI_API_KEY remains accepted; at startup OpenClaw copies it into ZAI_API_KEY when ZAI_API_KEY is not set.

Related

• Model selection, How to pick providers, model refs, and failover behavior.

• Configuration reference, The complete OpenClaw config schema, covering provider and model settings.