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

Запитання й відповіді про моделі та профілі автентифікації. Налаштування, сеанси, Gateway, канали й усунення несправностей описано в основному розділі поширених запитань.

Моделі: типові значення, вибір, псевдоніми, перемикання

Що таке «типова модель»?

Задається за допомогою:

agents.defaults.model.primary

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

Яку модель ви рекомендуєте?

Використовуйте найпотужнішу модель останнього покоління, яку пропонує ваш набір постачальників, особливо для агентів із доступом до інструментів або з недовіреними вхідними даними — слабші або надмірно квантовані моделі вразливіші до ін’єкцій у запити та небезпечної поведінки (див. Безпека). Спрямовуйте дешевші моделі на рутинні діалоги з низькими ризиками відповідно до ролі агента.Призначайте моделі для кожного агента й використовуйте підагентів для паралельного виконання тривалих завдань (кожен підагент споживає власні токени). Див. Моделі, Підагентів, MiniMax і Локальні моделі.

Як перемкнути модель без стирання конфігурації?

Змінюйте лише поля моделі — уникайте повної заміни конфігурації.

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

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

Чи можна використовувати моделі з власним хостингом (llama.cpp, vLLM, Ollama)?

Так — Ollama є найпростішим варіантом. Швидке налаштування:

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

Cloud + Local надає хмарні моделі разом із вашими локальними моделями Ollama; хмарні моделі на кшталт kimi-k2.5:cloud не потребують локального завантаження. Щоб перемкнутися вручну: openclaw models list, а потім openclaw models set ollama/<model>.Менші або сильно квантовані моделі вразливіші до ін’єкцій у запити. Використовуйте великі моделі для всіх ботів із доступом до інструментів; якщо ви все одно використовуєте малі моделі, увімкніть ізоляцію та суворі списки дозволених інструментів.Документація: Ollama, Локальні моделі, Постачальники моделей, Безпека, Ізоляція.

Як перемикати моделі під час роботи (без перезапуску)?

Надішліть /model <name> окремим повідомленням. Повний список команд наведено в розділі Команди з похилою рискою, зокрема нумерований засіб вибору (/model, /model list, /model 3), /model default для очищення перевизначення сеансу та /model status для перегляду подробиць кінцевої точки й режиму API.Щоб примусово застосувати певний профіль автентифікації до сеансу, використовуйте @profile:

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

Щоб відкріпити профіль, заданий через @profile, повторно виконайте /model без суфікса (наприклад, /model anthropic/claude-opus-4-6) або виберіть типовий варіант у /model. Використовуйте /model status, щоб перевірити активний профіль автентифікації.

Якщо два постачальники надають однаковий ідентифікатор моделі, якого з них використовує /model?

/model provider/model вибирає маршрут саме цього постачальника. Наприклад, qianfan/deepseek-v4-flash і deepseek/deepseek-v4-flash — це різні посилання, хоча ідентифікатор моделі збігається: OpenClaw не перемикає постачальників непомітно лише через збіг ідентифікатора.Вибране користувачем посилання /model має сувору поведінку щодо резервного перемикання: якщо ця пара постачальник/модель стає недоступною, відповідь завершується явною помилкою замість переходу до agents.defaults.model.fallbacks. Налаштовані ланцюжки резервного перемикання і надалі застосовуються до налаштованих типових значень, основних моделей завдань cron і автоматично вибраного стану резервного перемикання. Коли запуск без перевизначення сеансу може використовувати резервне перемикання, OpenClaw спочатку пробує запитану пару постачальник/модель, потім налаштовані резервні варіанти, а тоді налаштовану основну модель — тому однакові прості ідентифікатори моделей ніколи не перескакують одразу назад до типового постачальника.Див. Моделі і Резервне перемикання моделей.

Чи можна використовувати GPT 5.5 для щоденних завдань, а Codex 5.5 — для програмування?

Так — вибір моделі й вибір середовища виконання є окремими рішеннями:

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

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

Як налаштувати швидкий режим для 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,
          },
        },
      },
    },
  },
}

Швидкий режим відповідає service_tier = "priority" у нативних запитах OpenAI Responses; наявні значення service_tier зберігаються, а швидкий режим не переписує reasoning або text.verbosity. Перевизначення /fast у сеансі мають пріоритет над типовими значеннями конфігурації.Див. Міркування та швидкий режим і розділ про швидкий режим в додатковій конфігурації на сторінці постачальника OpenAI.

Чому я бачу «Model ... is not allowed», а потім не отримую відповіді?

Якщо задано 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, додайте шаблон постачальника, наприклад "provider/*": {}, для динамічних каталогів, видаліть список дозволених моделей або виберіть модель із /model list. Якщо команда також містила --runtime codex, спочатку оновіть список дозволених моделей, а потім повторіть ту саму команду /model provider/model --runtime codex.

Чому я бачу «Unknown model: minimax/MiniMax-M3»?

Якщо ви використовуєте старішу версію OpenClaw, спочатку оновіться (або запустіть із вихідного коду main) і перезапустіть Gateway — можливо, MiniMax-M3 ще немає в каталозі встановленої версії. В іншому разі постачальника MiniMax не налаштовано (не знайдено запису постачальника або профілю автентифікації), тому модель неможливо визначити. Повний перелік кроків для виправлення, таблицю ідентифікаторів постачальників і моделей та приклад блоку конфігурації наведено в розділі про усунення несправностей на сторінці постачальника MiniMax.

Чи можна використовувати MiniMax як типову модель, а OpenAI — для складних завдань?

Так. Використовуйте 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.

Чи є opus / sonnet / gpt вбудованими скороченнями?

Так — це вбудовані скорочення, які застосовуються лише тоді, коли цільова модель є в 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>, якщо підтримується) визначається як цей ідентифікатор моделі.

Як додати моделі інших постачальників, наприклад OpenRouter або Z.AI?

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.1" },
      models: { "zai/glm-5.1": {} },
    },
  },
  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 увійдіть у систему з нового агента, коли йому знадобиться власний обліковий запис. Повні правила повторного використання agentDir і спільного доступу до облікових даних див. у розділі Маршрутизація між кількома агентами — ніколи не використовуйте agentDir повторно для різних агентів.

Резервне перемикання моделей і «Усі моделі завершилися помилкою»

Як працює резервне перемикання?

Є два етапи:

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

До профілів із помилками застосовуються періоди очікування (експоненційна затримка), тому OpenClaw продовжує відповідати, коли постачальник обмежує частоту запитів або тимчасово працює з помилками.Категорія обмеження частоти охоплює не лише звичайну помилку 429: Too many concurrent requests, ThrottlingException, concurrency limit reached, workers_ai ... quota limit exceeded, resource exhausted і періодичні обмеження вікна використання (weekly/monthly limit reached) також вважаються обмеженнями частоти, що потребують резервного перемикання.Відповіді щодо оплати не завжди мають код 402, а деякі відповіді 402 залишаються в категорії тимчасових помилок або обмеження частоти, а не переходять до категорії оплати. Явний текст про оплату у відповідях 401/403 усе одно може спрямувати помилку до категорії оплати; засоби зіставлення тексту для окремих постачальників (наприклад, OpenRouter Key limit exceeded) застосовуються лише до відповідного постачальника. Відповідь 402, схожа на повторюване обмеження вікна використання або витрат організації чи робочого простору (daily limit reached, resets tomorrow, organization spending limit exceeded), обробляється як 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». До сигналів тимчасових помилок у межах конкретного постачальника, які враховуються для резервного перемикання, належать: окреме повідомлення 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. обробляється консервативно й сам по собі не запускає резервне перемикання.

Що означає "No credentials found for profile anthropic:default"?

Профіль автентифікації з ідентифікатором 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 на хості шлюзу.
Якщо натомість бажаєте використовувати ключ API, додайте ANTHROPIC_API_KEY до ~/.openclaw/.env на хості шлюзу, а потім очистьте будь-який закріплений порядок, що примусово використовує відсутній профіль:
openclaw models auth order clear --provider anthropic
Віддалений режим: профілі автентифікації зберігаються на машині шлюзу, а не на вашому ноутбуці — переконайтеся, що виконуєте команди саме там.

Чому система також спробувала Google Gemini й зазнала невдачі?

Якщо конфігурація моделі містить 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 для цього агента.

Профілі автентифікації: що це таке і як ними керувати

Пов’язаний матеріал: /concepts/oauth (потоки OAuth, зберігання токенів, схеми роботи з кількома обліковими записами)

Що таке профіль автентифікації?

Іменований запис облікових даних (OAuth або ключ API), пов’язаний із постачальником і збережений за адресою:

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

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

Які ідентифікатори профілів є типовими?

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

Чи можна керувати тим, який профіль автентифікації випробовується першим?

Так. Конфігурація auth.order.<provider> задає порядок ротації для кожного постачальника (лише метадані — секрети не зберігаються).OpenClaw може пропустити профіль під час короткого періоду очікування (обмеження частоти, перевищення часу очікування, помилки автентифікації) або тривалішого стану вимкнення (проблеми з оплатою або недостатньо коштів). Перевірте це за допомогою openclaw models status --json і перегляньте auth.unusableProfiles. Налаштуйте поведінку через auth.cooldowns.billingBackoffHours*. Періоди очікування через обмеження частоти можуть стосуватися окремої моделі — профіль, що перебуває в періоді очікування для однієї моделі, усе ще може обслуговувати споріднену модель того самого постачальника; вікна оплати або вимкнення блокують увесь профіль.Задайте для агента власний порядок (зберігається у файлі auth-state.json цього агента):

# Defaults to the configured default agent (omit --agent)
openclaw models auth order get --provider anthropic

# Lock rotation to a single profile
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

# Target a specific agent
openclaw models auth order set --provider anthropic --agent main anthropic:default

Перевірте, що саме буде випробувано: openclaw models status --probe. Збережений профіль, пропущений у явному порядку, повідомляє excluded_by_auth_order замість непомітної спроби його використання.

OAuth і ключ API — у чому різниця?

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

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

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

Поширені запитання — основний розділ поширених запитань
Поширені запитання — швидкий старт і початкове налаштування
Вибір моделі
Резервне перемикання моделей

Start here

FAQ

Testing

Diagnostics

Community and meta

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

Моделі: типові значення, вибір, псевдоніми, перемикання

Резервне перемикання моделей і «Усі моделі завершилися помилкою»

Профілі автентифікації: що це таке і як ними керувати

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

​Моделі: типові значення, вибір, псевдоніми, перемикання

​Резервне перемикання моделей і «Усі моделі завершилися помилкою»

​Профілі автентифікації: що це таке і як ними керувати

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

Моделі: типові значення, вибір, псевдоніми, перемикання

Резервне перемикання моделей і «Усі моделі завершилися помилкою»

Профілі автентифікації: що це таке і як ними керувати

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