Поширені запитання: моделі та автентифікація

Типова модель OpenClaw — це те, що ви задаєте як:

agents.defaults.model.primary

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

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

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

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

Серйозне застереження: слабші або надмірно квантизовані моделі вразливіші до prompt injection і небезпечної поведінки. Див. безпека.

Додатковий контекст: моделі.

Використовуйте команди моделей або редагуйте лише поля 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>

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

Документація: 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-codex, коли хочете використовувати автентифікацію підписки ChatGPT/Codex.
• Прямі завдання OpenAI API поза циклом агента: налаштуйте OPENAI_API_KEY для зображень, embeddings, мовлення, realtime та інших поверхонь OpenAI API, що не належать агенту.
• Автентифікація OpenAI agent API-key: використовуйте /model openai/gpt-5.5 з упорядкованим профілем API-key openai-codex.
• Підагенти: маршрутизуйте завдання програмування до агента, орієнтованого на Codex, із власною моделлю openai/gpt-5.5.

Див. моделі і slash-команди.

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

• Для сеансу: надішліть /fast on, поки сеанс використовує openai/gpt-5.5.
• Типове значення для моделі: задайте agents.defaults.models["openai/gpt-5.5"].params.fastMode як true.

Приклад:

{  agents: {    defaults: {      models: {        "openai/gpt-5.5": {          params: {            fastMode: true,          },        },      },    },  },}

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

Див. thinking і швидкий режим та швидкий режим 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 або збережений MiniMax OAuth для minimax-portal).

3. Використовуйте точний ідентифікатор моделі (з урахуванням регістру) для вашого шляху автентифікації: minimax/MiniMax-M2.7 або minimax/MiniMax-M2.7-highspeed для налаштування API-key, або 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-M2.7" },      models: {        "minimax/MiniMax-M2.7": { 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-7
• 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-preview

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

Псевдоніми беруться з 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" },        "anthropic/claude-haiku-4-5": { alias: "haiku" },      },    },  },}

Потім /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 відхилено: потрібна сигнатура мислення (Google Antigravity)

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

Виправлення: OpenClaw тепер видаляє непідписані блоки мислення для 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 (поширено, коли немає email-ідентичності)
• 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 часто використовує доступ за підпискою (де застосовно).
• Ключі API використовують оплату за токени.

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