Перейти до основного вмісту

​
CLI моделей

Див. /concepts/model-failover щодо ротації профілів автентифікації, періодів охолодження та того, як це взаємодіє з резервними варіантами. Короткий огляд провайдерів + приклади: /concepts/model-providers.

​
Як працює вибір моделі

OpenClaw вибирає моделі в такому порядку:
  1. Основна модель (agents.defaults.model.primary або agents.defaults.model).
  2. Резервні варіанти в agents.defaults.model.fallbacks (за порядком).
  3. Резервне перемикання автентифікації провайдера відбувається всередині провайдера перед переходом до наступної моделі.
Пов’язане:
  • agents.defaults.models — це allowlist/каталог моделей, які може використовувати OpenClaw (разом із псевдонімами).
  • agents.defaults.imageModel використовується лише тоді, коли основна модель не може приймати зображення.
  • agents.defaults.pdfModel використовується інструментом pdf. Якщо його не вказано, інструмент переходить до agents.defaults.imageModel, а потім до підсумково визначеної моделі сесії/типової моделі.
  • agents.defaults.imageGenerationModel використовується спільною можливістю генерації зображень. Якщо його не вказано, image_generate усе одно може визначити типовий варіант провайдера з автентифікацією. Спочатку він пробує поточного типового провайдера, а потім решту зареєстрованих провайдерів генерації зображень у порядку ідентифікаторів провайдерів. Якщо ви задаєте конкретний провайдер/модель, також налаштуйте автентифікацію/API key цього провайдера.
  • agents.defaults.musicGenerationModel використовується спільною можливістю генерації музики. Якщо його не вказано, music_generate усе одно може визначити типовий варіант провайдера з автентифікацією. Спочатку він пробує поточного типового провайдера, а потім решту зареєстрованих провайдерів генерації музики у порядку ідентифікаторів провайдерів. Якщо ви задаєте конкретний провайдер/модель, також налаштуйте автентифікацію/API key цього провайдера.
  • agents.defaults.videoGenerationModel використовується спільною можливістю генерації відео. Якщо його не вказано, video_generate усе одно може визначити типовий варіант провайдера з автентифікацією. Спочатку він пробує поточного типового провайдера, а потім решту зареєстрованих провайдерів генерації відео у порядку ідентифікаторів провайдерів. Якщо ви задаєте конкретний провайдер/модель, також налаштуйте автентифікацію/API key цього провайдера.
  • Типові налаштування для окремих агентів можуть перевизначати agents.defaults.model через agents.list[].model разом із прив’язками (див. /concepts/multi-agent).

​
Швидка політика моделей

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

​
Онбординг (рекомендовано)

Якщо ви не хочете вручну редагувати конфігурацію, запустіть онбординг: 
openclaw onboard
Він може налаштувати модель + автентифікацію для поширених провайдерів, зокрема OpenAI Code (Codex) subscription (OAuth) і Anthropic (API key або Claude CLI).

​
Ключі конфігурації (огляд)

  • agents.defaults.model.primary і agents.defaults.model.fallbacks
  • agents.defaults.imageModel.primary і agents.defaults.imageModel.fallbacks
  • agents.defaults.pdfModel.primary і agents.defaults.pdfModel.fallbacks
  • agents.defaults.imageGenerationModel.primary і agents.defaults.imageGenerationModel.fallbacks
  • agents.defaults.videoGenerationModel.primary і agents.defaults.videoGenerationModel.fallbacks
  • agents.defaults.models (allowlist + псевдоніми + параметри провайдера)
  • models.providers (власні провайдери, записані до models.json)
Посилання на моделі нормалізуються до нижнього регістру. Псевдоніми провайдерів на кшталт z.ai/* нормалізуються до zai/*. Приклади конфігурації провайдерів (зокрема OpenCode) наведено в /providers/opencode.

​
”Model is not allowed” (і чому відповіді припиняються)

Якщо задано agents.defaults.models, він стає allowlist для /model і для перевизначень сесії. Коли користувач вибирає модель, якої немає в цьому allowlist, OpenClaw повертає: 
Model "provider/model" is not allowed. Use /model to list available models.
Це відбувається до генерації звичайної відповіді, тому може здаватися, ніби на повідомлення «не відповіли». Виправлення: або
  • додайте модель до agents.defaults.models, або
  • очистьте allowlist (видаліть agents.defaults.models), або
  • виберіть модель із /model list.
Приклад конфігурації allowlist: 
{
  agent: {
    model: { primary: "anthropic/claude-sonnet-4-6" },
    models: {
      "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },
      "anthropic/claude-opus-4-6": { alias: "Opus" },
    },
  },
}

​
Перемикання моделей у чаті (/model)

Ви можете перемикати моделі для поточної сесії без перезапуску: 
/model
/model list
/model 3
/model openai/gpt-5.4
/model status
Примітки:
  • /model (і /model list) — це компактний нумерований вибір (сімейство моделей + доступні провайдери).
  • У Discord /model і /models відкривають інтерактивний вибір із випадними списками провайдера та моделі, а також кроком Submit.
  • /model <#> вибирає елемент із цього списку.
  • /model одразу зберігає новий вибір сесії.
  • Якщо агент неактивний, наступний запуск одразу використовує нову модель.
  • Якщо виконання вже активне, OpenClaw позначає перемикання під час роботи як відкладене й перезапускає з новою моделлю лише в чистій точці повторної спроби.
  • Якщо активність інструментів або виведення відповіді вже почалися, відкладене перемикання може залишатися в черзі до наступної нагоди повторної спроби або до наступного ходу користувача.
  • /model status — це докладне подання (кандидати автентифікації і, якщо налаштовано, baseUrl кінцевої точки провайдера + режим api).
  • Посилання на моделі розбираються шляхом поділу за першим /. Під час введення /model <ref> використовуйте provider/model.
  • Якщо сам ID моделі містить / (у стилі OpenRouter), ви повинні вказати префікс провайдера (приклад: /model openrouter/moonshotai/kimi-k2).
  • Якщо ви не вказуєте провайдера, OpenClaw визначає введення в такому порядку:
    1. збіг псевдоніма
    2. унікальний збіг налаштованого провайдера для цього точного ID моделі без префікса
    3. застарілий резервний перехід до налаштованого типового провайдера Якщо цей провайдер більше не надає налаштовану типову модель, OpenClaw натомість переходить до першого налаштованого провайдера/моделі, щоб не показувати застарілий типовий варіант від видаленого провайдера.
Повна поведінка команди/конфігурація: Слеш-команди.

​
Команди CLI

openclaw models list
openclaw models status
openclaw models set <provider/model>
openclaw models set-image <provider/model>

openclaw models aliases list
openclaw models aliases add <alias> <provider/model>
openclaw models aliases remove <alias>

openclaw models fallbacks list
openclaw models fallbacks add <provider/model>
openclaw models fallbacks remove <provider/model>
openclaw models fallbacks clear

openclaw models image-fallbacks list
openclaw models image-fallbacks add <provider/model>
openclaw models image-fallbacks remove <provider/model>
openclaw models image-fallbacks clear
openclaw models (без підкоманди) — це скорочення для models status.

​
models list

Типово показує налаштовані моделі. Корисні прапорці:
  • --all: повний каталог
  • --local: лише локальні провайдери
  • --provider <name>: фільтр за провайдером
  • --plain: одна модель на рядок
  • --json: машинозчитуваний вивід

​
models status

Показує підсумково визначену основну модель, резервні варіанти, модель зображень і огляд автентифікації налаштованих провайдерів. Також показує статус завершення OAuth для профілів, знайдених у сховищі автентифікації (типово попереджає за 24 год). --plain виводить лише підсумково визначену основну модель. Статус OAuth показується завжди (і включається у вивід --json). Якщо налаштований провайдер не має облікових даних, models status виводить розділ Missing auth. JSON містить auth.oauth (вікно попередження + профілі) і auth.providers (ефективна автентифікація для кожного провайдера, включно з обліковими даними з env). auth.oauth — це лише стан профілів у сховищі автентифікації; провайдери лише з env там не з’являються. Використовуйте --check для автоматизації (код виходу 1 — якщо відсутні/прострочені, 2 — якщо скоро завершаться). Використовуйте --probe для живих перевірок автентифікації; рядки перевірок можуть надходити з профілів автентифікації, облікових даних env або models.json. Якщо явний auth.order.<provider> пропускає збережений профіль, перевірка повідомляє excluded_by_auth_order замість спроби його використати. Якщо автентифікація є, але для цього провайдера не вдається визначити модель для перевірки, перевірка повідомляє status: no_model. Вибір автентифікації залежить від провайдера/облікового запису. Для хостів шлюзу, які працюють постійно, API key зазвичай є найпередбачуванішим варіантом; також підтримується повторне використання Claude CLI та наявні профілі Anthropic OAuth/token. Приклад (Claude CLI): 
claude auth login
openclaw models status

​
Сканування (безкоштовні моделі OpenRouter)

openclaw models scan перевіряє каталог безкоштовних моделей OpenRouter і може за потреби перевіряти моделі на підтримку інструментів і зображень. Основні прапорці:
  • --no-probe: пропустити живі перевірки (лише метадані)
  • --min-params <b>: мінімальний розмір параметрів (мільярди)
  • --max-age-days <days>: пропускати старіші моделі
  • --provider <name>: фільтр за префіксом провайдера
  • --max-candidates <n>: розмір списку резервних варіантів
  • --set-default: встановити agents.defaults.model.primary на перший вибраний варіант
  • --set-image: встановити agents.defaults.imageModel.primary на перший вибраний варіант зображення
Перевірка потребує OpenRouter API key (із профілів автентифікації або OPENROUTER_API_KEY). Без ключа використовуйте --no-probe, щоб лише перелічити кандидатів. Результати сканування ранжуються за:
  1. Підтримкою зображень
  2. Затримкою інструментів
  3. Розміром контексту
  4. Кількістю параметрів
Вхідні дані
  • список OpenRouter /models (фільтр :free)
  • Потребує OpenRouter API key з профілів автентифікації або OPENROUTER_API_KEY (див. /environment)
  • Необов’язкові фільтри: --max-age-days, --min-params, --provider, --max-candidates
  • Керування перевірками: --timeout, --concurrency
Під час запуску в TTY ви можете інтерактивно вибирати резервні варіанти. У неінтерактивному режимі передайте --yes, щоб прийняти типові значення.

​
Реєстр моделей (models.json)

Власні провайдери в models.providers записуються до models.json у каталозі агента (типово ~/.openclaw/agents/<agentId>/agent/models.json). Цей файл типово об’єднується, якщо тільки models.mode не встановлено в replace. Пріоритет у режимі об’єднання для відповідних ID провайдерів:
  • Непорожній baseUrl, який уже є в models.json агента, має пріоритет.
  • Непорожній apiKey у models.json агента має пріоритет лише тоді, коли цей провайдер не керується SecretRef у поточному контексті конфігурації/профілю автентифікації.
  • Значення apiKey для провайдерів, керованих SecretRef, оновлюються з маркерів джерела (ENV_VAR_NAME для посилань env, secretref-managed для посилань file/exec) замість збереження підсумково визначених секретів.
  • Значення заголовків провайдерів, керованих SecretRef, оновлюються з маркерів джерела (secretref-env:ENV_VAR_NAME для посилань env, secretref-managed для посилань file/exec).
  • Порожні або відсутні apiKey/baseUrl агента переходять до конфігурації models.providers.
  • Інші поля провайдера оновлюються з конфігурації та нормалізованих даних каталогу.
Збереження маркерів є авторитетним щодо джерела: OpenClaw записує маркери з активного знімка конфігурації джерела (до підсумкового визначення), а не з підсумково визначених значень секретів часу виконання. Це застосовується щоразу, коли OpenClaw повторно генерує models.json, зокрема для шляхів, керованих командами, як-от openclaw agent.

​
Пов’язане