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 — це платформа 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

Автоматичне визначення кінцевої точки

Найкраще для: більшості користувачів. OpenClaw перевіряє підтримувані кінцеві точки Z.AI за допомогою вашого ключа API й автоматично застосовує правильну базову URL-адресу.

  • Запустіть початкове налаштування

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

  • Переконайтеся, що модель є у списку

    bash
    openclaw models list --all --provider zai

    • Явно вказана регіональна кінцева точка

    Найкраще для: користувачів, які хочуть примусово вибрати певний Coding Plan або загальне API.

  • Виберіть правильний варіант початкового налаштування

    bash
    # Coding Plan Global (рекомендовано для користувачів Coding Plan)openclaw onboard --auth-choice zai-coding-global # Coding Plan CN (регіон Китаю)openclaw onboard --auth-choice zai-coding-cn # Загальне APIopenclaw onboard --auth-choice zai-global # Загальне API CN (регіон Китаю)openclaw onboard --auth-choice zai-cn

  • Переконайтеся, що модель є у списку

    bash
    openclaw models list --all --provider zai

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

    Варіант початкового налаштування Базова 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:

    • Агентські інструменти загального призначення, зокрема OpenClaw, обслуговуються за принципом максимально можливих зусиль. Під час високого навантаження на інференс, зазвичай приблизно з 2 до 6 години вечора за сінгапурським часом, для деяких запитів можуть тимчасово застосовуватися обмеження частоти.
    • Обмеження частоти й паралельності Coding Plan залежать від рівня плану та можуть динамічно коригуватися залежно від доступності ресурсів. У години поза піковим навантаженням рівень паралельності може бути вищим.
    • Код помилки API 1302 означає «Досягнуто обмеження частоти запитів». Код помилки API 1305 означає «Сервіс може бути тимчасово перевантажений, повторіть спробу пізніше».

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

    bash
    openclaw models list --all --provider zaiopenclaw 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. Постійні збої з тим самим ключем і кінцевою точкою можуть свідчити про відхилення запиту на боці провайдера або обмеження плану, а не про звичайне обмеження через пікове навантаження.

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

    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

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

    GLM-5.2

    Повний діапазон: off, low, high, max (за замовчуванням off). OpenClaw зіставляє low та high із рівнем зусиль для міркування high у Z.AI, а max — із рівнем зусиль max у Z.AI через reasoning_effort у корисному навантаженні запиту.

    Інші моделі GLM

    Лише двійковий перемикач: off і low (у засобах вибору відображається як on), за замовчуванням off. Якщо для міркування встановити off, надсилається thinking: { type: "disabled" }; будь-який інший рівень залишає корисне навантаження запиту без змін (застосовується власна типова поведінка міркування Z.AI).

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

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

    Перспективне розпізнавання невідомих моделей GLM-5

    Невідомі ідентифікатори glm-5* усе одно перспективно розпізнаються на шляху провайдера шляхом синтезу метаданих, що належать провайдеру, із шаблону glm-4.7, коли ідентифікатор відповідає поточній формі сімейства GLM-5.

    Потокове передавання викликів інструментів

    tool_stream за замовчуванням увімкнено для потокового передавання викликів інструментів Z.AI. Щоб вимкнути його:

    json5
    {  agents: {    defaults: {      models: {        "zai/<model>": {          params: { tool_stream: false },        },      },    },  },}
    Збережене міркування

    Збережене міркування потрібно вмикати явно, оскільки 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.

    Розуміння зображень

    Плагін Z.AI реєструє розуміння зображень.

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

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

    Відомості про автентифікацію
    • 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 не задано.

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

    Вибір моделі

    Вибір провайдерів, посилань на моделі та поведінки перемикання після збою.
    Довідник із конфігурації

    Повна схема конфігурації OpenClaw, зокрема налаштування провайдерів і моделей.
    Was this useful?
    On this page

    On this page