Настроить OpenClaw с Zukko — выбор провайдера и конфиг

OpenClaw подключается к Zukko как собственный (custom) провайдер моделей: вы указываете адрес, ключ fetch_..., тип API и список моделей. Ошибиться проще всего в двух местах — в суффиксе /v1 и в описании моделей. Ниже — оба варианта подключения, готовые конфиги и разбор ошибок.

Что такое OpenClaw

OpenClaw↗ — открытый персональный AI-ассистент, который работает на вашей машине. Его ядро — Gateway: он хранит настройки, вызывает модели и связывает агента с интерфейсами — терминальным TUI, веб-панелью и мессенджерами. Модель для агента задаётся через провайдеров; кроме встроенных, можно описать свой — так и подключается Zukko.

Два варианта подключения

Шлюз Zukko понимает оба формата и любую модель каталога может обслужить через любой из них. Выбирайте тот, что привычнее, или тот, что лучше поддерживает нужные вам функции OpenClaw.

Быстрая настройка через onboard (OpenAI)

Установите OpenClaw (официальный установщик описан в документации, есть и npm-пакет):

npm install -g openclaw

Затем запустите настройку без интерактивных вопросов. Флаги ниже взяты из справочника openclaw onboard в документации OpenClaw:

openclaw onboard --non-interactive --accept-risk \
  --auth-choice custom-api-key \
  --custom-base-url "https://api.zukko.pro/v1" \
  --custom-model-id "claude-sonnet-5" \
  --custom-api-key "fetch_..." \
  --secret-input-mode plaintext \
  --custom-compatibility openai

Замените fetch_... на ключ со страницы API-ключей↗. Флаг --accept-risk обязателен для неинтерактивного режима: им вы подтверждаете, что понимаете риски агента с доступом к системе. Названия флагов меняются от версии к версии — если команда не принимается, сверьтесь с openclaw onboard --help или настройте вручную, как описано ниже.

Ручная настройка: OpenAI Compatible

Конфиг OpenClaw — файл ~/.openclaw/openclaw.json в формате JSON5:

{
  models: {
    mode: "merge",
    providers: {
      zukko: {
        baseUrl: "https://api.zukko.pro/v1",
        apiKey: "fetch_...",
        api: "openai-completions",
        models: [
          {
            id: "claude-sonnet-5",
            name: "Claude Sonnet 5",
            input: ["text"],
            contextWindow: 1000000,

Что здесь важно:

• baseUrl — https://api.zukko.pro/v1, с /v1.
• apiKey — ваш ключ fetch_....
• api — openai-completions.
• models — модели провайдера; id должен совпадать с id в каталоге Zukko.
• agents.defaults.model.primary — модель по умолчанию в формате провайдер/модель.
• agents.defaults.models — алиасы и настройки моделей для агента. Документация Zukko рекомендует добавлять сюда каждую подключённую модель.

mode: "merge" оставляет встроенных провайдеров OpenClaw и добавляет к ним Zukko.

Ручная настройка: Anthropic Messages

Тот же файл, но другой тип API и адрес:

{
  models: {
    mode: "merge",
    providers: {
      zukko: {
        baseUrl: "https://api.zukko.pro",
        apiKey: "fetch_...",
        api: "anthropic-messages",
        models: [
          {
            id: "claude-sonnet-5",
            name: "Claude Sonnet 5",
            input: ["text"],
            contextWindow: 1000000,

Отличия от OpenAI-варианта:

• baseUrl — https://api.zukko.pro, без /v1.
• api — anthropic-messages.

Применение и проверка

По документации OpenClaw, Gateway следит за файлом конфига и подхватывает большинство изменений сам. После правки:

openclaw config validate
openclaw models list

Первая команда проверит синтаксис и схему, вторая покажет, видит ли OpenClaw модели zukko/.... Для полной замены конфига существует RPC-метод config.apply, но он перезаписывает весь файл целиком — для добавления провайдера достаточно отредактировать openclaw.json.

Дальше запустите терминальный интерфейс командой openclaw или откройте веб-панель через openclaw dashboard и задайте вопрос. Запрос должен появиться в разделе «Использование» в кабинете Zukko. Сменить модель в чате можно командой /model, например /model sonnet или /model zukko/claude-sonnet-5.

Добавить больше моделей

Чтобы переключаться между моделями Zukko, добавьте их в массив models провайдера:

models: [
  { id: "claude-sonnet-5", name: "Claude Sonnet 5", input: ["text"], contextWindow: 1000000, maxTokens: 8192 },
  { id: "claude-opus-5-5", name: "Claude Opus 5.5", input: ["text"], contextWindow: 1000000, maxTokens: 8192 },
  { id: "gpt-5.6-sol", name: "GPT-5.6 Sol", input: ["text"], contextWindow: 1000000, maxTokens: 8192 },
  { id: "glm-5.3-flash", name: "GLM 5.3 Flash", input: ["text"], contextWindow: 128000, maxTokens: 8192 },
]

И алиасы в agents.defaults.models:

models: {
  "zukko/claude-sonnet-5": { alias: "sonnet" },
  "zukko/claude-opus-5-5": { alias: "opus" },
  "zukko/gpt-5.6-sol": { alias: "sol" },
  "zukko/glm-5.3-flash": { alias: "flash" },
}

Цены Zukko за 1M токенов (вход/выход): Claude Sonnet 5, Claude Opus 5.5 и GPT-5.6 Sol — $0,30/$0,30, GLM 5.3 Flash — $0,04/$0,04. Актуальный список — GET https://api.zukko.pro/v1/models или страница «Модели»↗ в кабинете. Если модель принимает изображения и вы хотите отправлять их из чатов, по документации OpenClaw укажите для неё input: ["text", "image"].

Если не работает

Модель не видна в openclaw models list или в /model

1. Модель описана в models.providers.zukko.models и её id совпадает с каталогом Zukko.
2. Ссылка на модель записана как zukko/<id>.
3. openclaw config validate не показывает ошибок — невалидный файл Gateway не применит.

Ошибка вида «not allowed by agents.defaults.modelPolicy.allow»

В конфиге задан список разрешённых моделей agents.defaults.modelPolicy.allow. Добавьте в него zukko/<id> или уберите ограничение.

401 unauthorized

Проверьте apiKey: точное значение fetch_... со страницы ключей↗, без пробелов.

402

Закончился баланс — пополните↗ и повторите.

404

Почти всегда это перепутанный /v1:

• для openai-completions — https://api.zukko.pro/v1;
• для anthropic-messages — https://api.zukko.pro.

Частые вопросы

Какой вариант API выбрать?

Если вы привыкли к OpenAI SDK, берите openai-completions, если к Anthropic SDK — anthropic-messages. Набор доступных моделей одинаковый. Если какая-то функция OpenClaw работает в одном варианте и не работает в другом, просто переключите api и baseUrl.

Можно ли держать оба варианта в одном конфиге?

Да, опишите двух провайдеров с разными именами:

providers: {
  zukko_openai: { baseUrl: "https://api.zukko.pro/v1", apiKey: "fetch_...", api: "openai-completions", models: [/* ... */] },
  zukko_anthropic: { baseUrl: "https://api.zukko.pro", apiKey: "fetch_...", api: "anthropic-messages", models: [/* ... */] },
}

Ссылки на модели тогда будут zukko_openai/claude-sonnet-5 и zukko_anthropic/claude-sonnet-5.

Как узнать, какие модели доступны в Zukko?

Запросом GET https://api.zukko.pro/v1/models с ключом или на странице «Модели»↗ в кабинете. Подробнее — в справке по моделям↗.

Сколько стоит работа агента и влияет ли кэш?

Агент отправляет в модель большой повторяющийся контекст, поэтому основная часть расхода — входные токены. У вендоров чтение из кэша промптов стоит около 10% входной цены, а в Zukko кэшированные токены оплачиваются по обычной входной цене. Поэтому для длинных агентных сессий реальная разница с официальным прайсом меньше, чем при прямом сравнении цен. Следите за расходом в кабинете и ставьте на ключ дневной лимит.

Краткая шпаргалка — в документации Zukko по OpenClaw↗.