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

​
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 — це список дозволених моделей/каталог моделей, які OpenClaw може використовувати (разом із псевдонімами).
  • agents.defaults.imageModel використовується лише тоді, коли основна модель не може приймати зображення.
  • agents.defaults.pdfModel використовується інструментом pdf. Якщо не вказано, інструмент переходить на agents.defaults.imageModel, а потім на визначену для сесії/типову модель.
  • agents.defaults.imageGenerationModel використовується спільною можливістю генерації зображень. Якщо не вказано, image_generate усе одно може визначити типовий провайдер з автентифікацією. Спочатку він пробує поточного типового провайдера, а потім решту зареєстрованих провайдерів генерації зображень у порядку ідентифікаторів провайдерів. Якщо ви задаєте конкретний провайдер/модель, також налаштуйте автентифікацію/API-ключ цього провайдера.
  • agents.defaults.videoGenerationModel використовується спільною можливістю генерації відео. Якщо не вказано, video_generate усе одно може визначити типовий провайдер з автентифікацією. Спочатку він пробує поточного типового провайдера, а потім решту зареєстрованих провайдерів генерації відео в порядку ідентифікаторів провайдерів. Якщо ви задаєте конкретний провайдер/модель, також налаштуйте автентифікацію/API-ключ цього провайдера.
  • Типові значення для окремих агентів можуть перевизначати agents.defaults.model через agents.list[].model разом із прив’язками (див. /concepts/multi-agent).

​
Коротка політика щодо моделей

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

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

Якщо ви не хочете редагувати конфігурацію вручну, запустіть онбординг: 
openclaw onboard
Він може налаштувати модель + автентифікацію для поширених провайдерів, зокрема OpenAI Code (Codex) subscription (OAuth) і Anthropic (API-ключ або 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 (список дозволених + псевдоніми + параметри провайдера)
  • models.providers (власні провайдери, записані в models.json)
Посилання на моделі нормалізуються до нижнього регістру. Псевдоніми провайдерів, як-от z.ai/*, нормалізуються до zai/*. Приклади конфігурації провайдерів (зокрема OpenCode) наведено в /providers/opencode.

​
«Модель не дозволена» (і чому відповіді зупиняються)

Якщо задано agents.defaults.models, він стає списком дозволених для /model і для перевизначень у сесії. Коли користувач вибирає модель, якої немає в цьому списку, OpenClaw повертає: 
Model "provider/model" is not allowed. Use /model to list available models.
Це відбувається до генерації звичайної відповіді, тому може здаватися, ніби повідомлення «не отримало відповіді». Вирішити це можна так:
  • Додати модель до agents.defaults.models, або
  • Очистити список дозволених (видалити agents.defaults.models), або
  • Вибрати модель із /model list.
Приклад конфігурації списку дозволених: 
{
  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.
  • Якщо сам ідентифікатор моделі містить / (у стилі OpenRouter), ви повинні вказати префікс провайдера (приклад: /model openrouter/moonshotai/kimi-k2).
  • Якщо ви не вказуєте провайдера, OpenClaw визначає введення в такому порядку:
    1. збіг псевдоніма
    2. унікальний збіг налаштованого провайдера для цього точного ідентифікатора моделі без префікса
    3. застарілий резервний перехід до налаштованого типового провайдера Якщо цей провайдер більше не надає налаштовану типову модель, OpenClaw натомість переходить до першого налаштованого провайдера/моделі, щоб уникнути показу застарілого типового значення від видаленого провайдера.
Повна поведінка команди/конфігурація: Slash commands.

​
Команди 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 виводить розділ Відсутня автентифікація. 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-ключі зазвичай є найпередбачуванішими; також підтримуються повторне використання Claude CLI та наявні профілі Anthropic OAuth/токенів. Приклад (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 на перший вибраний елемент для зображень
Для перевірок потрібен API-ключ OpenRouter (із профілів автентифікації або OPENROUTER_API_KEY). Без ключа використовуйте --no-probe, щоб лише переглянути кандидатів. Результати сканування ранжуються за:
  1. Підтримкою зображень
  2. Затримкою інструментів
  3. Розміром контексту
  4. Кількістю параметрів
Вхідні дані
  • Список OpenRouter /models (фільтр :free)
  • Потрібен API-ключ OpenRouter із профілів автентифікації або 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. Пріоритети режиму об’єднання для однакових ідентифікаторів провайдерів:
  • Непорожній 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.

​
Пов’язане