openclaw-openclaw/docs/providers/zai.md

summary, read_when, title

summary	read_when	title
Use Z.AI (GLM models) with OpenClaw	You want Z.AI / GLM models in OpenClaw You need a simple ZAI_API_KEY setup	Z.AI

Z.AI is the API platform for GLM models. It provides REST APIs for GLM and uses API keys for authentication. Create your API key in the Z.AI console. OpenClaw uses the zai provider with a Z.AI API key.

Property	Value
Provider	zai
Package	@openclaw/zai-provider
Auth	ZAI_API_KEY (legacy alias: Z_AI_API_KEY)
API	Z.AI Chat Completions (Bearer auth)

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

Install the provider plugin first:

openclaw plugins install @openclaw/zai-provider

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

<Steps>
  <Step title="Run onboarding">
    ```bash
    openclaw onboard --auth-choice zai-api-key
    ```
  </Step>
  <Step title="Verify the model is listed">
    ```bash
    openclaw models list --all --provider zai
    ```
  </Step>
</Steps>

**Best for:** users who want to force a specific Coding Plan or general API surface.

<Steps>
  <Step title="Pick the right onboarding choice">
    ```bash
    # 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
    ```
  </Step>
  <Step title="Verify the model is listed">
    ```bash
    openclaw models list --all --provider zai
    ```
  </Step>
</Steps>

Endpoints

Onboarding choice	Base URL	Default model
zai-global	https://api.z.ai/api/paas/v4	glm-5.1
zai-cn	https://open.bigmodel.cn/api/paas/v4	glm-5.1
zai-coding-global	https://api.z.ai/api/coding/paas/v4	glm-5.2
zai-coding-cn	https://open.bigmodel.cn/api/coding/paas/v4	glm-5.2

zai-api-key auto-detects one of these four by probing 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 stopping 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.

Config example

`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:

Model ref	Notes
zai/glm-5.2	Coding Plan default; 1M context
zai/glm-5.1	General API default
zai/glm-5
zai/glm-5-turbo
zai/glm-5v-turbo
zai/glm-4.7
zai/glm-4.7-flash
zai/glm-4.7-flashx
zai/glm-4.6
zai/glm-4.6v
zai/glm-4.5
zai/glm-4.5-air
zai/glm-4.5-flash
zai/glm-4.5v

GLM models are available as `zai/` (example: `zai/glm-5`). 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

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. 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

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_stream` is enabled by default for Z.AI tool-call streaming. To disable it:

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

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:

```json5
{
  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`.

The Z.AI plugin registers image understanding.

| Property      | Value       |
| ------------- | ----------- |
| Model         | `glm-4.6v`  |

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

- 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

Choosing providers, model refs, and failover behavior. Full OpenClaw config schema, including provider and model settings.