Z.AI Provider

기준일: 2026-07-26
난이도: 중급
공식 기준: Z.AI

개요

이 페이지는 OpenClaw Z.AI provider의 인증, 모델 ref, 온보딩 플래그, 설정 키를 공식 문서 기준으로 정리합니다.

공식 요약: Use Z.AI (GLM models) with OpenClaw

model ref는 보통 provider/model 형식입니다. API key·endpoint·model id는 아래 원문 값을 그대로 쓰세요. 임의로 키나 엔드포인트를 만들지 마세요.

빠른 참조

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)

공식 문서 기반 상세

아래는 공식 providers/zai 문서를 Mintlify 컴포넌트만 정리하고 공통 제목을 한국어로 맞춘 내용입니다. 설정 키, env, model ref, CLI 플래그는 원문 그대로 유지합니다.

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.

시작하기

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.

Run onboarding

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

Verify the model is listed

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






**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 API
    openclaw 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`

Z.AI also publishes 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 for clients that speak Anthropic Messages directly.

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.

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

openclaw models list --all --provider zai
openclaw 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.

설정 예시

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`

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.

GLM models are available as zai/<model> (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.

고급 설정

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.

검증 체크리스트

openclaw models list --provider zai 로 모델이 보이는지 확인
기본 model alias를 agents.defaults.model.primary에 설정했는지 확인
API key / OAuth / 로컬 런타임 인증 경로를 공식 문서와 대조했는지 확인
failover 시 데이터가 다른 provider로 이동할 수 있는지 검토

Z.AI Provider

기준일: 2026-07-26
난이도: 중급
공식 기준: Z.AI

개요

이 페이지는 OpenClaw Z.AI provider의 인증, 모델 ref, 온보딩 플래그, 설정 키를 공식 문서 기준으로 정리합니다.

공식 요약: Use Z.AI (GLM models) with OpenClaw

model ref는 보통 provider/model 형식입니다. API key·endpoint·model id는 아래 원문 값을 그대로 쓰세요. 임의로 키나 엔드포인트를 만들지 마세요.

빠른 참조

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)

공식 문서 기반 상세

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.

시작하기

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.

Run onboarding

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

Verify the model is listed

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






**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 API
    openclaw 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`

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

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

설정 예시

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/<model> (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.

고급 설정

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.

검증 체크리스트

openclaw models list --provider zai 로 모델이 보이는지 확인
기본 model alias를 agents.defaults.model.primary에 설정했는지 확인
API key / OAuth / 로컬 런타임 인증 경로를 공식 문서와 대조했는지 확인
failover 시 데이터가 다른 provider로 이동할 수 있는지 검토

Z.AI Provider

개요

빠른 참조

공식 문서 기반 상세

GLM models

시작하기

Run onboarding

Verify the model is listed

Pick the right onboarding choice

Verify the model is listed

Endpoints

Rate limits and overloads

설정 예시

Built-in catalog

Thinking levels

고급 설정

Forward-resolving unknown GLM-5 models

Tool-call streaming

Preserved thinking

Image understanding

Auth details

관련 문서

검증 체크리스트

관련

관련 가이드

Z.AI Provider

개요

빠른 참조

공식 문서 기반 상세

GLM models

시작하기

Run onboarding

Verify the model is listed

Pick the right onboarding choice

Verify the model is listed

Endpoints

Rate limits and overloads

설정 예시

Built-in catalog

Thinking levels

고급 설정

Forward-resolving unknown GLM-5 models

Tool-call streaming

Preserved thinking

Image understanding

Auth details

관련 문서

검증 체크리스트

관련

관련 가이드