Z.AI Provider: GLM Models via OpenClaw

Z.AI is the API platform for GLM models. It exposes REST APIs for GLM and authenticates with API keys. Generate your API key inside the Z.AI console. OpenClaw uses the zai provider together with a Z.AI API key.

GLM models

GLM is a model family, not a separate provider. In OpenClaw, GLM models use refs such as zai/glm-5.2: provider zai, model id glm-5.2.

Getting started

Start by installing the provider plugin:

openclaw plugins install @openclaw/zai-provider

Auto-detect endpoint

Best for: most users. OpenClaw checks supported Z.AI endpoints with your API key and picks the correct base URL automatically.

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 specific 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 also provides the Anthropic-compatible Coding Plan base URL https://api.z.ai/api/anthropic. OpenClaw's Z.AI choices use the documented OpenAI Chat Completions endpoints above; the Anthropic URL is meant for clients that directly speak Anthropic Messages.

zai-api-key auto-detects one of these four by testing your key against each endpoint's chat-completions API, checking general endpoints (zai-global, then zai-cn) before Coding Plan endpoints (zai-coding-global, then zai-coding-cn), and stops at the first endpoint that accepts a request. Use an explicit --auth-choice to force a Coding Plan endpoint if your key works on both.

Rate limits and overloads

Z.AI documents the Coding Plan and general-purpose agent tools as capacity managed services. In Z.AI's own docs:

• General-purpose agent tools, including OpenClaw, run on a best-effort basis. During high inference load, typically 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 can be adjusted dynamically based on resource availability. Off-peak hours may allow higher concurrency.
• 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".

If you get a temporary 429 or 1305 response during a busy period, wait and retry the request. If failures happen consistently outside peak periods, or only for one endpoint, model, or request shape, check the configured endpoint and model first:

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

Coding Plan keys should target a Coding Plan endpoint such as https://api.z.ai/api/coding/paas/v4; general API keys should target a general API endpoint such as https://api.z.ai/api/paas/v4. Persistent failures with the same key and endpoint may indicate a provider-side rejection or plan limitation, not ordinary peak-load throttling.

Config example

Tip

zai-api-key lets OpenClaw detect the matching Z.AI endpoint from the key and apply the correct base URL automatically. Use the explicit regional choices when you want to force a specific Coding Plan or general API surface.

{
  env: { ZAI_API_KEY: "sk-..." },
  models: {
    providers: {
      zai: {
        // GLM-5.2 uses the Coding Plan endpoint.
        baseUrl: "https://api.z.ai/api/coding/paas/v4",
      },
    },
  },
  agents: { defaults: { model: { primary: "zai/glm-5.2" } } },
}

Built-in catalog

The zai provider plugin ships its catalog in the plugin manifest, so read-only listing can show known GLM rows without loading provider runtime:

openclaw models list --all --provider zai

The manifest-backed catalog currently includes:

Catalog token-cost metadata follows Z.AI's current pay-as-you-go pricing. Coding Plan subscriptions use plan quota instead of per-token billing; see the live subscription page for plan pricing and availability.

Tip

GLM models are available as zai/<model> (example: zai/glm-5).

Note

Coding Plan setup defaults to zai/glm-5.2; general API setup keeps zai/glm-5.1. On the Coding Plan endpoints, auto-detection falls back to glm-5.1 and then glm-4.7 when the key/plan does not expose GLM-5.2. GLM versions and availability can change; run openclaw models list --all --provider zai to see the catalog known to your installed version.

Thinking levels

GLM-5.2

Full range: off, low, high, max (default off). OpenClaw maps low and high to Z.AI's high reasoning effort, and max to Z.AI's max effort, via reasoning_effort on the request payload.

Other GLM models

Binary toggle only: off and low (shown as on in pickers), default off. Setting thinking to off sends thinking: { type: "disabled" }; any other level leaves the request payload untouched (Z.AI's own default reasoning behavior applies).

Setting thinking to off avoids responses that spend the output budget on reasoning_content before visible text.

Advanced configuration

Forward-resolving unknown GLM-5 models

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

Tool-call streaming

tool_stream is enabled by default for Z.AI tool-call streaming. To disable it:

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

Preserved thinking

Preserved thinking is opt-in because Z.AI requires the full historical reasoning_content to be replayed, which increases prompt tokens. Enable it per model:

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

When enabled and thinking is on, 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.

Advanced users can still override the exact provider payload with params.extra_body.thinking.

Image understanding

The Z.AI plugin registers image understanding.

Image understanding is auto-resolved from the configured Z.AI auth, no additional config is needed.

Auth details

• Z.AI uses Bearer auth with your API key.
• The zai-api-key onboarding choice auto-detects the matching Z.AI endpoint by probing supported endpoints with your key.
• Use the explicit regional choices (zai-coding-global, zai-coding-cn, zai-global, zai-cn) when you want to force a specific API surface.
• The legacy env var Z_AI_API_KEY is still accepted; OpenClaw copies it to ZAI_API_KEY at startup if ZAI_API_KEY is unset.

Related

• Model selection, Choosing providers, model refs, and failover behavior.

• Configuration reference, Full OpenClaw config schema, including provider and model settings.