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. Apus uses the zai provider with a Z.AI API key.

GLM models

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

Getting started

Install the provider plugin first:

apus plugins install @openclaw/zai-provider

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

    ```bash
    apus onboard --auth-choice zai-api-key
    ```

    ```bash
    apus models list --all --provider zai
    ```

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

    ```bash
    # Coding Plan Global (recommended for Coding Plan users)
    apus onboard --auth-choice zai-coding-global

    # Coding Plan CN (China region)
    apus onboard --auth-choice zai-coding-cn

    # General API
    apus onboard --auth-choice zai-global

    # General API CN (China region)
    apus onboard --auth-choice zai-cn
    ```

    ```bash
    apus models list --all --provider zai
    ```

Endpoints

Z.AI also publishes the Anthropic-compatible Coding Plan base URL https://api.z.ai/api/anthropic. Apus's Z.AI choices use the documented OpenAI Chat Completions endpoints above; the Anthropic URL is for clients that speak Anthropic Messages directly.

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

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 Apus, are served on a best-effort basis. During high inference load, typically around 2-6 PM Singapore time, some requests may face temporary rate limits.
• Coding Plan rate and concurrency limits are tied to the plan tier and can be adjusted dynamically based on resource availability. Off-peak hours may have 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 see a temporary 429 or 1305 response during a busy period, wait and retry the request. If failures are repeatable outside peak periods, or only occur for one endpoint, model, or request shape, check the configured endpoint and model first:

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

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

Config example

{
  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 zai provider plugin ships its catalog in the plugin manifest, so read-only listing can show known GLM rows without loading provider runtime:

apus models list --all --provider zai

The manifest-backed catalog includes:

Pay-as-you-go catalog rows follow Z.AI's current API pricing. GLM-5.3 Flash uses its pay-as-you-go list prices even when temporary discounts are available. GLM-5.3 is currently a Coding Plan model, so its local catalog cost is zero; Coding Plan subscriptions use plan quota instead of per-token billing. See the live subscription page for plan pricing and availability.

Video generation

The same plugin and ZAI_API_KEY (or Z_AI_API_KEY) support the video generation tool with zai/cogvideox-3. It accepts text prompts or one PNG/JPEG image, including local files sent as data URIs (maximum 5 MB). Video references are unsupported.

Durations normalize to 5 or 10 seconds. Size and aspect-ratio hints map to the nearest supported size: 1280x720, 720x1280, 1024x1024, 1920x1080, 1080x1920, 2048x1080, or 3840x2160. Output defaults to 720P landscape without audio; audio: true enables sound. Use providerOptions.quality (speed or quality) and providerOptions.fps (30 or 60) for further control.

Video uses the configured global or China region's general /api/paas/v4 endpoint. Coding Plan chat endpoints map to the general video endpoint in the same region; video requires API access and billing for that endpoint.

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

Thinking levels

Levels: `low`, `high`, and `max` (default `max`). Apus maps these to
Z.AI's `reasoning_effort` request field. An explicit `off` setting maps to
`reasoning_effort: "low"` because GLM-5.3 models do not support disabling
reasoning entirely.

Full range: `off`, `low`, `high`, `max` (default `off`). Apus 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.3": {
          params: { preserveThinking: true },
        },
      },
    },
  },
}
```

When enabled and thinking is on, Apus 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 checking 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; Apus copies it to `ZAI_API_KEY` at startup if `ZAI_API_KEY` is unset.

Related

Choosing providers, model refs, and failover behavior.

Full Apus config schema, including provider and model settings.