---
read_when:
    - Ви хочете використовувати моделі Z.AI / GLM в OpenClaw
    - Вам потрібно просто налаштувати ZAI_API_KEY
summary: Використання Z.AI (моделей GLM) з OpenClaw
title: Z.AI
x-i18n:
    generated_at: "2026-07-16T18:31:56Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 32
    provider: openai
    source_hash: 7f7adf0e2f436f9081891013c0092ce4717bf302b2a4a2e997d9561d7d40211a
    source_path: providers/zai.md
    workflow: 16
---

Z.AI — це платформа API для моделей **GLM**. Вона надає REST API для GLM і
використовує ключі API для автентифікації. Створіть ключ API в консолі Z.AI.
OpenClaw використовує провайдера `zai` із ключем API Z.AI.

| Властивість | Значення                                     |
| -------- | -------------------------------------------- |
| Провайдер | `zai`                                        |
| Пакет  | `@openclaw/zai-provider`                     |
| Автентифікація     | `ZAI_API_KEY` (застарілий псевдонім: `Z_AI_API_KEY`) |
| API      | Z.AI Chat Completions (автентифікація Bearer)          |

## Моделі GLM

GLM — це сімейство моделей, а не окремий провайдер. В OpenClaw моделі GLM використовують
посилання на кшталт `zai/glm-5.2`: провайдер `zai`, ідентифікатор моделі `glm-5.2`.

## Початок роботи

Спочатку встановіть плагін провайдера:

```bash
openclaw plugins install @openclaw/zai-provider
```

<Tabs>
  <Tab title="Автоматичне визначення кінцевої точки">
    **Найкраще для:** більшості користувачів. OpenClaw перевіряє підтримувані кінцеві точки Z.AI за допомогою вашого ключа API й автоматично застосовує правильну базову URL-адресу.

    <Steps>
      <Step title="Запустіть початкове налаштування">
        ```bash
        openclaw onboard --auth-choice zai-api-key
        ```
      </Step>
      <Step title="Переконайтеся, що модель є у списку">
        ```bash
        openclaw models list --all --provider zai
        ```
      </Step>
    </Steps>

  </Tab>

  <Tab title="Явно вказана регіональна кінцева точка">
    **Найкраще для:** користувачів, які хочуть примусово вибрати певний Coding Plan або загальне API.

    <Steps>
      <Step title="Виберіть правильний варіант початкового налаштування">
        ```bash
        # Coding Plan Global (рекомендовано для користувачів Coding Plan)
        openclaw onboard --auth-choice zai-coding-global

        # Coding Plan CN (регіон Китаю)
        openclaw onboard --auth-choice zai-coding-cn

        # Загальне API
        openclaw onboard --auth-choice zai-global

        # Загальне API CN (регіон Китаю)
        openclaw onboard --auth-choice zai-cn
        ```
      </Step>
      <Step title="Переконайтеся, що модель є у списку">
        ```bash
        openclaw models list --all --provider zai
        ```
      </Step>
    </Steps>

  </Tab>
</Tabs>

### Кінцеві точки

| Варіант початкового налаштування   | Базова URL-адреса                              | Модель за замовчуванням |
| ------------------- | --------------------------------------------- | ------------- |
| `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` автоматично визначає одну з цих чотирьох кінцевих точок, перевіряючи ваш ключ через API
чат-завершень кожної кінцевої точки: спочатку перевіряються загальні кінцеві точки (`zai-global`,
потім `zai-cn`), а після них — кінцеві точки Coding Plan (`zai-coding-global`, потім
`zai-coding-cn`); перевірка припиняється на першій кінцевій точці, яка прийме запит.
Використовуйте явний варіант `--auth-choice`, щоб примусово вибрати кінцеву точку Coding Plan, якщо ваш ключ
працює з обома типами.

## Обмеження частоти запитів і перевантаження

Z.AI описує Coding Plan та агентські інструменти загального призначення як сервіси
з керованою пропускною здатністю. Згідно з документацією Z.AI:

- [Агентські інструменти загального призначення](https://docs.z.ai/devpack/tool/others),
  зокрема OpenClaw, обслуговуються за принципом максимально можливих зусиль. Під час високого навантаження
  на інференс, зазвичай приблизно з 2 до 6 години вечора за сінгапурським часом, для деяких запитів можуть тимчасово
  застосовуватися обмеження частоти.
- [Обмеження частоти й паралельності Coding Plan](https://docs.z.ai/devpack/usage-policy)
  залежать від рівня плану та можуть динамічно коригуватися залежно від доступності
  ресурсів. У години поза піковим навантаженням рівень паралельності може бути вищим.
- [Код помилки API `1302`](https://docs.z.ai/api-reference/api-code) означає «Досягнуто
  обмеження частоти запитів». Код помилки API `1305` означає «Сервіс може бути
  тимчасово перевантажений, повторіть спробу пізніше».

Якщо в період високого навантаження ви отримали тимчасову відповідь `429` або `1305`, зачекайте й
повторіть запит. Якщо збої регулярно повторюються поза піковими періодами або
виникають лише для однієї кінцевої точки, моделі чи форми запиту, спочатку перевірте налаштовані кінцеву точку
та модель:

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

Ключі Coding Plan мають використовувати кінцеву точку Coding Plan, наприклад
`https://api.z.ai/api/coding/paas/v4`; ключі загального API мають використовувати кінцеву точку
загального API, наприклад `https://api.z.ai/api/paas/v4`. Постійні збої з тим самим
ключем і кінцевою точкою можуть свідчити про відхилення запиту на боці провайдера або обмеження плану,
а не про звичайне обмеження через пікове навантаження.

## Приклад конфігурації

<Tip>
`zai-api-key` дає змогу OpenClaw визначити відповідну кінцеву точку Z.AI за ключем і
автоматично застосувати правильну базову URL-адресу. Використовуйте явні регіональні варіанти, коли
потрібно примусово вибрати певний Coding Plan або загальне API.
</Tip>

```json5
{
  env: { ZAI_API_KEY: "sk-..." },
  models: {
    providers: {
      zai: {
        // GLM-5.2 використовує кінцеву точку Coding Plan.
        baseUrl: "https://api.z.ai/api/coding/paas/v4",
      },
    },
  },
  agents: { defaults: { model: { primary: "zai/glm-5.2" } } },
}
```

## Вбудований каталог

Плагін провайдера `zai` постачається з каталогом у маніфесті плагіна, тому список лише для читання
може відображати відомі записи GLM без завантаження середовища виконання провайдера:

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

Каталог на основі маніфесту наразі містить:

| Посилання на модель  | Примітки                        |
| -------------------- | ------------------------------- |
| `zai/glm-5.2`        | Типова для Coding Plan; контекст 1M |
| `zai/glm-5.1`        | Типова для загального API       |
| `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`       |                                 |

<Tip>
Моделі GLM доступні як `zai/<model>` (приклад: `zai/glm-5`).
</Tip>

<Note>
Налаштування Coding Plan за замовчуванням використовує `zai/glm-5.2`; налаштування загального API зберігає
`zai/glm-5.1`. На кінцевих точках Coding Plan автоматичне визначення використовує як резерв
`glm-5.1`, а потім `glm-4.7`, коли ключ або план не надає доступу до GLM-5.2. Версії GLM
і їх доступність можуть змінюватися; виконайте `openclaw models list --all --provider zai`,
щоб переглянути каталог, відомий установленій версії.
</Note>

## Рівні міркування

<Tabs>
  <Tab title="GLM-5.2">
    Повний діапазон: `off`, `low`, `high`, `max` (за замовчуванням `off`). OpenClaw зіставляє
    `low` та `high` із рівнем зусиль для міркування `high` у Z.AI, а `max` — із
    рівнем зусиль `max` у Z.AI через `reasoning_effort` у корисному навантаженні запиту.
  </Tab>
  <Tab title="Інші моделі GLM">
    Лише двійковий перемикач: `off` і `low` (у засобах вибору відображається як `on`), за замовчуванням
    `off`. Якщо для міркування встановити `off`, надсилається `thinking: { type: "disabled" }`;
    будь-який інший рівень залишає корисне навантаження запиту без змін (застосовується власна типова
    поведінка міркування Z.AI).
  </Tab>
</Tabs>

Якщо для міркування встановити `off`, відповіді не витрачатимуть бюджет виведення на
`reasoning_content` перед видимим текстом.

## Розширена конфігурація

<AccordionGroup>
  <Accordion title="Перспективне розпізнавання невідомих моделей GLM-5">
    Невідомі ідентифікатори `glm-5*` усе одно перспективно розпізнаються на шляху провайдера
    шляхом синтезу метаданих, що належать провайдеру, із шаблону `glm-4.7`, коли ідентифікатор
    відповідає поточній формі сімейства GLM-5.
  </Accordion>

  <Accordion title="Потокове передавання викликів інструментів">
    `tool_stream` за замовчуванням увімкнено для потокового передавання викликів інструментів Z.AI. Щоб вимкнути його:

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

  </Accordion>

  <Accordion title="Збережене міркування">
    Збережене міркування потрібно вмикати явно, оскільки Z.AI вимагає повторного відтворення повного історичного
    `reasoning_content`, що збільшує кількість токенів запиту. Увімкніть його
    окремо для кожної моделі:

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

    Коли цю функцію ввімкнено й міркування активне, OpenClaw надсилає
    `thinking: { type: "enabled", clear_thinking: false }` і повторно відтворює попередній
    `reasoning_content` для тієї самої сумісної з OpenAI транскрипції. Ключ параметра у форматі snake_case
    `preserve_thinking` працює як псевдонім.

    Досвідчені користувачі все одно можуть перевизначити точне корисне навантаження провайдера за допомогою
    `params.extra_body.thinking`.

  </Accordion>

  <Accordion title="Розуміння зображень">
    Плагін Z.AI реєструє розуміння зображень.

    | Властивість  | Значення    |
    | ------------- | ----------- |
    | Модель        | `glm-4.6v`  |

    Розуміння зображень автоматично визначається на основі налаштованої автентифікації Z.AI —
    додаткова конфігурація не потрібна.

  </Accordion>

  <Accordion title="Відомості про автентифікацію">
    - Z.AI використовує автентифікацію Bearer із вашим ключем API.
    - Варіант початкового налаштування `zai-api-key` автоматично визначає відповідну кінцеву точку Z.AI, перевіряючи підтримувані кінцеві точки за допомогою вашого ключа.
    - Використовуйте явні регіональні варіанти (`zai-coding-global`, `zai-coding-cn`, `zai-global`, `zai-cn`), коли потрібно примусово вибрати певне API.
    - Застаріла змінна середовища `Z_AI_API_KEY` усе ще підтримується; OpenClaw копіює її до `ZAI_API_KEY` під час запуску, якщо `ZAI_API_KEY` не задано.

  </Accordion>
</AccordionGroup>

## Пов’язані матеріали

<CardGroup cols={2}>
  <Card title="Вибір моделі" href="/uk/concepts/model-providers" icon="layers">
    Вибір провайдерів, посилань на моделі та поведінки перемикання після збою.
  </Card>
  <Card title="Довідник із конфігурації" href="/uk/gateway/configuration-reference" icon="gear">
    Повна схема конфігурації OpenClaw, зокрема налаштування провайдерів і моделей.
  </Card>
</CardGroup>
