OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Providers

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:

bash
openclaw plugins install @openclaw/zai-provider

Auto-detect endpoint

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

  • Run onboarding

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

  • Verify the model is listed

    bash
    openclaw models list --all --provider zai

    • Explicit regional endpoint

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

  • 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 APIopenclaw onboard --auth-choice zai-global # General API CN (China region)openclaw onboard --auth-choice zai-cn

  • Verify the model is listed

    bash
    openclaw models list --all --provider zai

    • 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

    json5
    {  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:

    bash
    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

    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:

    json5
    {  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:

    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.

    Image understanding

    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.

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

    Choosing providers, model refs, and failover behavior.
    Configuration reference

    Full OpenClaw config schema, including provider and model settings.
    Was this useful?
    On this page

    On this page