FAQ: моделі та автентифікація

Модель OpenClaw за замовчуванням — це те, що ви задали як:

agents.defaults.model.primary

Моделі вказуються як provider/model (приклад: openai/gpt-5.5 або anthropic/claude-sonnet-4-6). Якщо провайдера не вказано, OpenClaw спочатку пробує псевдонім, потім унікальний збіг із налаштованим провайдером для цього точного ідентифікатора моделі, і лише після цього повертається до налаштованого провайдера за замовчуванням як застарілого шляху сумісності. Якщо цей провайдер більше не надає налаштовану модель за замовчуванням, OpenClaw повертається до першої налаштованої пари провайдер/модель замість того, щоб показувати застаріле значення за замовчуванням для видаленого провайдера. Вам усе одно слід явно задавати provider/model.

Рекомендовано за замовчуванням: використовуйте найсильнішу модель останнього покоління, доступну у вашому стеку провайдерів. Для агентів з увімкненими інструментами або недовіреним введенням: надавайте пріоритет потужності моделі, а не вартості. Для звичайного/низькоризикового чату: використовуйте дешевші резервні моделі й маршрутизуйте за роллю агента.

MiniMax має власну документацію: MiniMax і Локальні моделі.

Практичне правило: використовуйте найкращу модель, яку можете собі дозволити, для високоризикової роботи, а дешевшу модель — для звичайного чату або підсумків. Ви можете маршрутизувати моделі для кожного агента й використовувати під-агентів, щоб паралелізувати довгі завдання (кожен під-агент споживає токени). Див. Моделі і Під-агенти.

Суворе попередження: слабші/надмірно квантовані моделі вразливіші до ін'єкцій у промпт і небезпечної поведінки. Див. Безпека.

Більше контексту: Моделі.

Використовуйте команди моделей або редагуйте лише поля model. Уникайте повної заміни конфігурації.

Безпечні варіанти:

• /model у чаті (швидко, для окремого сеансу)
• openclaw models set ... (оновлює лише конфігурацію моделі)
• openclaw configure --section model (інтерактивно)
• редагуйте agents.defaults.model у ~/.openclaw/openclaw.json

Уникайте config.apply з частковим об'єктом, якщо не маєте наміру замінити всю конфігурацію. Для редагувань через RPC спочатку перевірте за допомогою config.schema.lookup і віддавайте перевагу config.patch. Корисне навантаження lookup дає нормалізований шлях, поверхневу документацію/обмеження схеми та короткі описи безпосередніх дочірніх елементів. для часткових оновлень. Якщо ви перезаписали конфігурацію, відновіть її з резервної копії або повторно запустіть openclaw doctor для виправлення.

Документація: Моделі, Налаштування, Конфігурація, Doctor.

Так. Ollama — найпростіший шлях для локальних моделей.

Найшвидше налаштування:

1. Установіть Ollama з https://ollama.com/download
2. Завантажте локальну модель, наприклад ollama pull gemma4
3. Якщо також хочете хмарні моделі, виконайте ollama signin
4. Запустіть openclaw onboard і виберіть Ollama
5. Виберіть Local або Cloud + Local

Примітки:

• Cloud + Local дає вам хмарні моделі плюс ваші локальні моделі Ollama
• хмарні моделі, як-от kimi-k2.5:cloud, не потребують локального завантаження
• для ручного перемикання використовуйте openclaw models list і openclaw models set ollama/<model>

Примітка щодо безпеки: менші або сильно квантовані моделі вразливіші до ін'єкцій у промпт. Ми наполегливо рекомендуємо великі моделі для будь-якого бота, який може використовувати інструменти. Якщо ви все ж хочете малі моделі, увімкніть ізоляцію в пісочниці та суворі списки дозволених інструментів.

Документація: Ollama, Локальні моделі, Провайдери моделей, Безпека, Ізоляція в пісочниці.

• Ці розгортання можуть відрізнятися й змінюватися з часом; фіксованої рекомендації щодо провайдера немає.
• Перевірте поточне налаштування середовища виконання на кожному Gateway за допомогою openclaw models status.
• Для чутливих до безпеки агентів або агентів з увімкненими інструментами використовуйте найсильнішу модель останнього покоління, доступну вам.

Використовуйте команду /model як окреме повідомлення:

/model sonnet/model opus/model gpt/model gpt-mini/model gemini/model gemini-flash/model gemini-flash-lite

Це вбудовані псевдоніми. Користувацькі псевдоніми можна додати через agents.defaults.models.

Ви можете переглянути доступні моделі за допомогою /model, /model list або /model status.

/model (і /model list) показує компактний нумерований вибір. Виберіть за номером:

/model 3

Ви також можете примусово задати конкретний профіль автентифікації для провайдера (для окремого сеансу):

/model opus@anthropic:default/model opus@anthropic:work

Порада: /model status показує, який агент активний, який файл auth-profiles.json використовується і який профіль автентифікації буде випробувано наступним. Він також показує налаштовану кінцеву точку провайдера (baseUrl) і режим API (api), якщо вони доступні.

Як відкріпити профіль, який я задав через @profile?

Повторно запустіть /model без суфікса @profile:

/model anthropic/claude-opus-4-6

Якщо хочете повернутися до стандартного значення, виберіть його з /model (або надішліть /model <default provider/model>). Використайте /model status, щоб підтвердити, який профіль автентифікації активний.

/model provider/model вибирає точний маршрут провайдера для сеансу.

Наприклад, qianfan/deepseek-v4-flash і deepseek/deepseek-v4-flash — різні посилання на моделі, хоча обидва містять deepseek-v4-flash. OpenClaw не має мовчки перемикатися з одного провайдера на іншого лише тому, що збігається голий ідентифікатор моделі.

Вибране користувачем посилання /model також є суворим для політики резервного переходу. Якщо вибраний провайдер/модель недоступні, відповідь явно завершується помилкою замість відповіді з agents.defaults.model.fallbacks. Налаштовані ланцюжки резервного переходу все ще застосовуються до налаштованих стандартних значень, основних моделей завдань cron і автоматично вибраного резервного стану.

Якщо запуск, що почався з перевизначення не на рівні сеансу, може використовувати резервний перехід, OpenClaw спочатку пробує запитаний провайдер/модель, потім налаштовані резервні варіанти, і лише потім налаштовану основну модель. Це не дає дубльованим голим ідентифікаторам моделей одразу повертатися до провайдера за замовчуванням.

Див. Моделі і Резервний перехід моделей.

Так. Розглядайте вибір моделі й вибір середовища виконання окремо:

• Нативний агент кодування Codex: задайте agents.defaults.model.primary як openai/gpt-5.5. Увійдіть за допомогою openclaw models auth login --provider openai, коли хочете автентифікацію через підписку ChatGPT/Codex.
• Прямі завдання OpenAI API поза циклом агента: налаштуйте OPENAI_API_KEY для зображень, embeddings, мовлення, realtime та інших поверхонь OpenAI API не для агентів.
• Автентифікація агента OpenAI за API-ключем: використовуйте /model openai/gpt-5.5 з упорядкованим профілем API-ключа openai.
• Під-агенти: маршрутизуйте завдання кодування до агента, орієнтованого на Codex, із власною моделлю openai/gpt-5.5.

Див. Моделі і Команди зі скісною рискою.

Використовуйте або перемикач сеансу, або значення за замовчуванням у конфігурації:

• Для сеансу: надішліть /fast on, поки сеанс використовує openai/gpt-5.5.
• За замовчуванням для моделі: задайте agents.defaults.models["openai/gpt-5.5"].params.fastMode як true.
• Автоматичне відсікання: використовуйте /fast auto або params.fastMode: "auto", щоб починати нові виклики моделі у швидкому режимі до автоматичного відсікання, а пізніші повторні спроби, резервні переходи, виклики з результатами інструментів або продовження — без швидкого режиму. За замовчуванням відсікання становить 60 секунд; задайте params.fastAutoOnSeconds для активної моделі, щоб змінити його.

Приклад:

{  agents: {    defaults: {      models: {        "openai/gpt-5.5": {          params: {            fastMode: "auto",            fastAutoOnSeconds: 30,          },        },      },    },  },}

Для OpenAI швидкий режим відповідає service_tier = "priority" у підтримуваних нативних запитах Responses. Перевизначення сеансу /fast мають пріоритет над значеннями конфігурації за замовчуванням. Ходи сервера застосунку Codex можуть отримати рівень лише на початку ходу, тому auto застосовується під час наступного ходу моделі, запущеного OpenClaw, а не всередині вже запущеного ходу сервера застосунку.

Див. Мислення і швидкий режим і Швидкий режим OpenAI.

Якщо agents.defaults.models задано, він стає списком дозволених для /model і будь-яких перевизначень сеансу. Вибір моделі, якої немає в цьому списку, повертає:

Model "provider/model" is not allowed. Use /models to list providers, or /models <provider> to list models.Add it with: openclaw config set agents.defaults.models '{"provider/model":{}}' --strict-json --merge

Ця помилка повертається замість звичайної відповіді. Виправлення: додайте точну модель до agents.defaults.models, додайте wildcard провайдера, як-от "provider/*": {} для динамічних каталогів провайдерів, видаліть список дозволених або виберіть модель з /model list. Якщо команда також містила --runtime codex, спочатку оновіть список дозволених, а потім повторіть ту саму команду /model provider/model --runtime codex.

Це означає, що провайдера не налаштовано (не знайдено конфігурації провайдера MiniMax або профілю автентифікації), тому модель неможливо розв'язати.

Контрольний список виправлення:

1. Оновіть OpenClaw до поточного випуску (або запустіть із вихідного коду main), потім перезапустіть Gateway.

2. Переконайтеся, що MiniMax налаштовано (майстер або JSON), або що автентифікація MiniMax існує в env/профілях автентифікації, щоб відповідний провайдер міг бути інжектований (MINIMAX_API_KEY для minimax, MINIMAX_OAUTH_TOKEN або збережений OAuth MiniMax для minimax-portal).

3. Використовуйте точний ідентифікатор моделі (з урахуванням регістру) для вашого шляху автентифікації: minimax/MiniMax-M3, minimax/MiniMax-M2.7 або minimax/MiniMax-M2.7-highspeed для налаштування з API-ключем, або minimax-portal/MiniMax-M3, minimax-portal/MiniMax-M2.7 чи minimax-portal/MiniMax-M2.7-highspeed для налаштування OAuth.

4. Запустіть:

   openclaw models list

   і виберіть зі списку (або /model list у чаті).

Див. MiniMax і Моделі.

Так. Використовуйте MiniMax за замовчуванням і перемикайте моделі для кожного сеансу, коли потрібно. Резервні варіанти призначені для помилок, а не для "складних завдань", тому використовуйте /model або окремого агента.

Варіант A: перемикання для кожного сеансу

{  env: { MINIMAX_API_KEY: "sk-...", OPENAI_API_KEY: "sk-..." },  agents: {    defaults: {      model: { primary: "minimax/MiniMax-M3" },      models: {        "minimax/MiniMax-M3": { alias: "minimax" },        "openai/gpt-5.5": { alias: "gpt" },      },    },  },}

Потім:

/model gpt

Варіант B: окремі агенти

• Агент A за замовчуванням: MiniMax
• Агент B за замовчуванням: OpenAI
• Маршрутизуйте за агентом або використовуйте /agent для перемикання

Документація: Моделі, Маршрутизація між агентами, MiniMax, OpenAI.

Так. OpenClaw постачається з кількома стандартними скороченнями (застосовуються лише тоді, коли модель існує в agents.defaults.models):

• opus → anthropic/claude-opus-4-8
• sonnet → anthropic/claude-sonnet-4-6
• gpt → openai/gpt-5.4
• gpt-mini → openai/gpt-5.4-mini
• gpt-nano → openai/gpt-5.4-nano
• gemini → google/gemini-3.1-pro-preview
• gemini-flash → google/gemini-3-flash-preview
• gemini-flash-lite → google/gemini-3.1-flash-lite

Якщо ви задасте власний псевдонім із такою самою назвою, використовуватиметься ваше значення.

Псевдоніми беруться з agents.defaults.models.<modelId>.alias. Приклад:

{  agents: {    defaults: {      model: { primary: "anthropic/claude-opus-4-6" },      models: {        "anthropic/claude-opus-4-6": { alias: "opus" },        "anthropic/claude-sonnet-4-6": { alias: "sonnet" },      },    },  },}

Потім /model sonnet (або /<alias>, якщо підтримується) розв’язується в цей ID моделі.

OpenRouter (оплата за токени; багато моделей):

{  agents: {    defaults: {      model: { primary: "openrouter/anthropic/claude-sonnet-4-6" },      models: { "openrouter/anthropic/claude-sonnet-4-6": {} },    },  },  env: { OPENROUTER_API_KEY: "sk-or-..." },}

Z.AI (моделі GLM):

{  agents: {    defaults: {      model: { primary: "zai/glm-5" },      models: { "zai/glm-5": {} },    },  },  env: { ZAI_API_KEY: "..." },}

Якщо ви посилаєтеся на провайдера/модель, але потрібний ключ провайдера відсутній, ви отримаєте помилку автентифікації під час виконання (наприклад, No API key found for provider "zai").

Після додавання нового агента не знайдено ключ API для провайдера

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

~/.openclaw/agents/<agentId>/agent/auth-profiles.json

Варіанти виправлення:

• Запустіть openclaw agents add <id> і налаштуйте автентифікацію в майстрі.
• Або скопіюйте лише переносні статичні профілі api_key / token з основного сховища автентифікації агента до сховища автентифікації нового агента.
• Для профілів OAuth увійдіть із нового агента, коли йому потрібен власний обліковий запис; інакше OpenClaw може читати дані через стандартного/основного агента без клонування токенів оновлення.

Не використовуйте agentDir повторно для кількох агентів; це спричиняє конфлікти автентифікації/сесій.

Відмовостійке перемикання відбувається у два етапи:

1. Ротація профілів автентифікації в межах того самого провайдера.
2. Резервна модель — перехід до наступної моделі в agents.defaults.model.fallbacks.

До профілів із помилками застосовуються періоди охолодження (експоненційна затримка), тож OpenClaw може продовжувати відповідати, навіть коли провайдер обмежує частоту запитів або тимчасово не працює.

Кошик обмеження частоти містить не лише звичайні відповіді 429. OpenClaw також розглядає повідомлення на кшталт Too many concurrent requests, ThrottlingException, concurrency limit reached, workers_ai ... quota limit exceeded, resource exhausted і періодичні обмеження вікна використання (weekly/monthly limit reached) як обмеження частоти, що варті відмовостійкого перемикання.

Деякі відповіді, схожі на білінгові, не є 402, а деякі HTTP-відповіді 402 також залишаються в цьому тимчасовому кошику. Якщо провайдер повертає явний білінговий текст у 401 або 403, OpenClaw усе ще може тримати це в білінговій смузі, але провайдер-специфічні зіставлячі тексту залишаються обмеженими провайдером, якому вони належать (наприклад, OpenRouter Key limit exceeded). Якщо повідомлення 402 натомість схоже на повторюване вікно використання або ліміт витрат організації/робочого простору (daily limit reached, resets tomorrow, organization spending limit exceeded), OpenClaw трактує його як rate_limit, а не як тривале білінгове вимкнення.

Помилки переповнення контексту відрізняються: сигнатури на кшталт request_too_large, input exceeds the maximum number of tokens, input token count exceeds the maximum number of input tokens, input is too long for the model або ollama error: context length exceeded залишаються на шляху Compaction/повторної спроби, а не просувають резервне перемикання моделі.

Загальний текст серверної помилки навмисно вужчий, ніж «будь-що з unknown/error у ньому». OpenClaw справді розглядає обмежені провайдером тимчасові форми, як-от Anthropic без додаткового контексту An unknown error occurred, OpenRouter без додаткового контексту Provider returned error, помилки причин зупинки на кшталт Unhandled stop reason: error, JSON-навантаження api_error із тимчасовим серверним текстом (internal server error, unknown error, 520, upstream error, backend error) і помилки зайнятості провайдера на кшталт ModelNotReadyException як сигнали тайм-ауту/перевантаження, що варті відмовостійкого перемикання, коли контекст провайдера збігається. Загальний внутрішній текст резервної помилки, як-от LLM request failed with an unknown error., залишається консервативним і сам по собі не запускає резервне перемикання моделі.

Це означає, що система спробувала використати ID профілю автентифікації anthropic:default, але не змогла знайти для нього облікові дані в очікуваному сховищі автентифікації.

Контрольний список виправлення:

• Підтвердьте, де зберігаються профілі автентифікації (нові чи застарілі шляхи)
  • Поточний: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
  • Застарілий: ~/.openclaw/agent/* (мігрується через openclaw doctor)
• Підтвердьте, що вашу змінну середовища завантажує Gateway
  • Якщо ви встановили ANTHROPIC_API_KEY у своїй оболонці, але запускаєте Gateway через systemd/launchd, він може її не успадкувати. Помістіть її в ~/.openclaw/.env або ввімкніть env.shellEnv.
• Переконайтеся, що редагуєте правильного агента
  • Налаштування з кількома агентами означають, що може існувати кілька файлів auth-profiles.json.
• Перевірте стан моделі/автентифікації
  • Використайте openclaw models status, щоб побачити налаштовані моделі та чи автентифіковані провайдери.

Контрольний список виправлення для "No credentials found for profile anthropic"

Це означає, що запуск прив’язано до профілю автентифікації Anthropic, але Gateway не може знайти його у своєму сховищі автентифікації.

• Використайте Claude CLI

  • Запустіть openclaw models auth login --provider anthropic --method cli --set-default на хості Gateway.

• Якщо натомість хочете використовувати ключ API

  • Помістіть ANTHROPIC_API_KEY у ~/.openclaw/.env на хості Gateway.

  • Очистьте будь-який закріплений порядок, який примушує використовувати відсутній профіль:

    openclaw models auth order clear --provider anthropic

• Підтвердьте, що виконуєте команди на хості Gateway

  • У віддаленому режимі профілі автентифікації зберігаються на машині Gateway, а не на вашому ноутбуці.

Якщо ваша конфігурація моделей містить Google Gemini як резервний варіант (або ви перемкнулися на скорочення Gemini), OpenClaw спробує його під час резервного перемикання моделі. Якщо ви не налаштували облікові дані Google, ви побачите No API key found for provider "google".

Виправлення: або надайте автентифікацію Google, або вилучіть/уникайте моделей Google у agents.defaults.model.fallbacks / псевдонімах, щоб резервне перемикання не спрямовувалося туди.

Запит LLM відхилено: потрібна сигнатура thinking (Google Antigravity)

Причина: історія сесії містить блоки thinking без сигнатур (часто через перерваний/частковий потік). Google Antigravity вимагає сигнатури для блоків thinking.

Виправлення: OpenClaw тепер видаляє непідписані блоки thinking для Google Antigravity Claude. Якщо це все ще з’являється, почніть нову сесію або встановіть /thinking off для цього агента.

Профіль автентифікації — це іменований запис облікових даних (OAuth або ключ API), прив’язаний до провайдера. Профілі зберігаються в:

~/.openclaw/agents/<agentId>/agent/auth-profiles.json

Щоб переглянути збережені профілі без виведення секретів, запустіть openclaw models auth list (за бажанням із --provider <id> або --json). Докладніше див. CLI моделей.

OpenClaw використовує ID з префіксом провайдера, як-от:

• anthropic:default (поширено, коли ідентичності електронної пошти немає)
• anthropic:<email> для ідентичностей OAuth
• користувацькі ID, які ви обираєте (наприклад, anthropic:work)

Так. Конфігурація підтримує необов’язкові метадані для профілів і порядок для кожного провайдера (auth.order.<provider>). Це не зберігає секрети; воно зіставляє ID з провайдером/режимом і задає порядок ротації.

OpenClaw може тимчасово пропустити профіль, якщо він перебуває в короткому періоді охолодження (обмеження частоти/тайм-аути/збої автентифікації) або в довшому стані вимкнено (білінг/недостатньо кредитів). Щоб це перевірити, запустіть openclaw models status --json і перегляньте auth.unusableProfiles. Налаштування: auth.cooldowns.billingBackoffHours*.

Періоди охолодження через обмеження частоти можуть бути прив’язані до моделі. Профіль, який охолоджується для однієї моделі, усе ще може бути придатним для спорідненої моделі в того самого провайдера, тоді як білінгові/вимкнені вікна все ще блокують увесь профіль.

Ви також можете встановити перевизначення порядку для кожного агента (зберігається в auth-state.json цього агента) через CLI:

# Defaults to the configured default agent (omit --agent)openclaw models auth order get --provider anthropic # Lock rotation to a single profile (only try this one)openclaw models auth order set --provider anthropic anthropic:default # Or set an explicit order (fallback within provider)openclaw models auth order set --provider anthropic anthropic:work anthropic:default # Clear override (fall back to config auth.order / round-robin)openclaw models auth order clear --provider anthropic

Щоб націлитися на конкретного агента:

openclaw models auth order set --provider anthropic --agent main anthropic:default

Щоб перевірити, що фактично буде спробувано, використайте:

openclaw models status --probe

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

OpenClaw підтримує обидва варіанти:

• OAuth / вхід через CLI часто використовує доступ за підпискою там, де провайдер це підтримує. Для Anthropic бекенд Claude CLI в OpenClaw використовує Claude Code claude -p; Anthropic наразі розглядає це як використання Agent SDK/програмне використання. Anthropic призупинила окрему зміну кредитів Agent SDK від 15 червня 2026 року, тож наразі це все ще витрачає ліміти використання підписки. Див. статтю про план Agent SDK Anthropic для поточного повідомлення про паузу.
• Ключі API використовують оплату за токени.

Майстер явно підтримує Anthropic Claude CLI, OpenAI Codex OAuth і ключі API.