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

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

Ротація профілів автентифікації, періоди охолодження та як це взаємодіє з резервними варіантами.

Постачальники моделей

Короткий огляд постачальників і приклади.

Середовища виконання агентів

OpenClaw, Codex та інші середовища виконання циклу агента.

Довідник конфігурації

Ключі конфігурації моделей.
Посилання на моделі вибирають постачальника й модель. Зазвичай вони не вибирають низькорівневе середовище виконання агента. Посилання на агенти OpenAI є головним винятком: openai/gpt-5.5 типово виконується через середовище виконання app-server Codex в офіційного постачальника OpenAI. Посилання на підписку Copilot (github-copilot/*) також можна явно перевести на зовнішній Plugin середовища виконання агента GitHub Copilot — цей шлях залишається явним (без резервного auto). Явні перевизначення середовища виконання належать до політики постачальника/моделі, а не до всього агента чи сеансу. У режимі середовища виконання Codex посилання openai/gpt-* не означає білінг за API-ключем; автентифікація може надходити з облікового запису Codex або OAuth-профілю openai. Див. Середовища виконання агентів і Середовище виконання агента GitHub Copilot.

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

OpenClaw вибирає моделі в такому порядку:
1

Основна модель

agents.defaults.model.primary (або agents.defaults.model).
2

Резервні варіанти

agents.defaults.model.fallbacks (у порядку).
3

Відмовостійке перемикання автентифікації постачальника

Відмовостійке перемикання автентифікації відбувається всередині постачальника перед переходом до наступної моделі.
  • agents.defaults.models — це allowlist/каталог моделей, які OpenClaw може використовувати (плюс псевдоніми). Використовуйте записи provider/*, щоб обмежити видимих постачальників, зберігаючи динамічне виявлення постачальників.
  • agents.defaults.imageModel використовується лише тоді, коли основна модель не може приймати зображення.
  • agents.defaults.pdfModel використовується інструментом pdf. Якщо не вказано, інструмент переходить до agents.defaults.imageModel, а потім до розв’язаної сеансової/типової моделі.
  • agents.defaults.imageGenerationModel використовується спільною можливістю генерації зображень. Якщо не вказано, image_generate усе одно може вивести типовий параметр постачальника, підкріплений автентифікацією. Спочатку він пробує поточного типового постачальника, потім решту зареєстрованих постачальників генерації зображень у порядку provider-id. Якщо ви задаєте конкретного постачальника/модель, також налаштуйте автентифікацію/API-ключ цього постачальника.
  • agents.defaults.musicGenerationModel використовується спільною можливістю генерації музики. Якщо не вказано, music_generate усе одно може вивести типовий параметр постачальника, підкріплений автентифікацією. Спочатку він пробує поточного типового постачальника, потім решту зареєстрованих постачальників генерації музики в порядку provider-id. Якщо ви задаєте конкретного постачальника/модель, також налаштуйте автентифікацію/API-ключ цього постачальника.
  • agents.defaults.videoGenerationModel використовується спільною можливістю генерації відео. Якщо не вказано, video_generate усе одно може вивести типовий параметр постачальника, підкріплений автентифікацією. Спочатку він пробує поточного типового постачальника, потім решту зареєстрованих постачальників генерації відео в порядку provider-id. Якщо ви задаєте конкретного постачальника/модель, також налаштуйте автентифікацію/API-ключ цього постачальника.
  • Типові параметри окремого агента можуть перевизначати agents.defaults.model через agents.list[].model плюс прив’язки (див. Маршрутизація кількох агентів).

​
Джерело вибору й поведінка резервних варіантів

Один і той самий provider/model може означати різні речі залежно від того, звідки він узявся:
  • Налаштовані типові значення (agents.defaults.model.primary і специфічні для агента основні моделі) є звичайною початковою точкою та використовують agents.defaults.model.fallbacks.
  • Автоматичні резервні вибори — це тимчасовий стан відновлення. Вони зберігаються з modelOverrideSource: "auto", щоб наступні ходи могли продовжувати використовувати резервний ланцюжок без перевірки відомо несправної основної моделі щоразу; OpenClaw періодично знову перевіряє початкову основну модель, очищає автоматичний вибір після її відновлення та оголошує переходи до резервного варіанта/відновлення один раз на зміну стану.
  • Вибори сеансу користувача є точними. /model, засіб вибору моделі, session_status(model=...) і sessions.patch зберігають modelOverrideSource: "user"; якщо вибраний постачальник/модель недосяжні, OpenClaw явно завершується з помилкою замість переходу до іншої налаштованої моделі.
  • Зміна agents.defaults.model.primary не переписує наявні вибори сеансів. Якщо статус каже This session is pinned to X; config primary Y will apply to new/unpinned sessions., очистьте поточний вибір сеансу за допомогою /model default, щоб він знову успадковував налаштовану основну модель.
  • Cron --model / payload model — це основна модель для окремого завдання. Вона все ще використовує налаштовані резервні варіанти, якщо завдання не надає явний payload fallbacks (використовуйте fallbacks: [] для строгого запуску cron).
  • Засоби вибору типової моделі CLI та allowlist поважають models.mode: "replace", перелічуючи явні models.providers.*.models замість завантаження повного вбудованого каталогу.
  • Засіб вибору моделі Control UI запитує в Gateway налаштований перегляд моделей: agents.defaults.models, якщо він є, включно із записами на рівні всього постачальника provider/*; інакше — явні models.providers.*.models плюс постачальники з придатною автентифікацією. Повний вбудований каталог зарезервовано для явних переглядів, як-от models.list з view: "all" або openclaw models list --all.

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

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

​
Початкове налаштування (рекомендовано)

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

​
Безпечні редагування allowlist

Використовуйте додавальні записи, коли вручну оновлюєте agents.defaults.models: 
openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json --merge
openclaw config set захищає мапи моделей/постачальників від випадкового перезапису. Просте присвоєння об’єкта до agents.defaults.models, models.providers або models.providers.<id>.models відхиляється, якщо воно видалило б наявні записи. Використовуйте --merge для додавальних змін; використовуйте --replace лише тоді, коли надане значення має стати повним цільовим значенням.Інтерактивне налаштування постачальника та openclaw configure --section model також зливають вибори в межах постачальника з наявним allowlist, тому додавання Codex, Ollama або іншого постачальника не видаляє непов’язані записи моделей. Configure зберігає наявний agents.defaults.model.primary, коли автентифікація постачальника застосовується повторно. Явні команди встановлення типового значення, як-от openclaw models auth login --provider <id> --set-default і openclaw models set <model>, усе ще замінюють agents.defaults.model.primary.

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

Якщо agents.defaults.models встановлено, він стає allowlist для /model і перевизначень сеансу. Коли користувач вибирає модель, якої немає в цьому allowlist, OpenClaw повертає: 
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, або
  • Очистьте allowlist (видаліть agents.defaults.models), або
  • Виберіть модель із /model list.
Коли відхилена команда містила перевизначення середовища виконання, наприклад /model openai/gpt-5.5 --runtime codex, спочатку виправте allowlist, а потім повторіть ту саму команду /model ... --runtime .... Для нативного виконання Codex вибрана модель усе ще openai/gpt-5.5; середовище виконання codex вибирає harness і використовує автентифікацію Codex окремо. Для локальних/GGUF-моделей зберігайте повне посилання з префіксом постачальника в allowlist, наприклад ollama/gemma4:26b, lmstudio/Gemma4-26b-a4-it-gguf або точний provider/model, показаний openclaw models list --provider <provider>. Самих локальних імен файлів або відображуваних назв недостатньо, коли allowlist активний. Якщо ви хочете обмежити постачальників без ручного перелічення кожної моделі, додайте записи provider/* до agents.defaults.models: 
{
  agents: {
    defaults: {
      models: {
        "openai/*": {},
        "vllm/*": {},
      },
    },
  },
}
За такої політики /model, /models і засоби вибору моделей показують виявлений каталог лише для цих постачальників. Нові моделі від вибраних постачальників можуть з’являтися без редагування allowlist. Точні записи provider/model можна поєднувати із записами provider/*, коли потрібна одна конкретна модель від іншого постачальника. Приклад конфігурації allowlist: 
{
  agents: {
    defaults: {
      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 default
/model status
  • /model (і /model list) — це компактний нумерований засіб вибору (сімейство моделей + доступні постачальники).
  • У Discord /model і /models відкривають інтерактивний засіб вибору з випадаючими списками постачальника й моделі плюс крок Submit.
  • У Telegram вибори в засобі /models прив’язані до сеансу; вони не змінюють постійне типове значення агента в openclaw.json.
  • /models add застаріло й тепер повертає повідомлення про застарілість замість реєстрації моделей із чату.
  • /model <#> вибирає з цього засобу вибору.
  • /model негайно зберігає новий вибір для сеансу.
  • Якщо агент простоює, наступний запуск одразу використовує нову модель.
  • Якщо запуск уже активний, OpenClaw позначає перемикання наживо як очікуване й перезапускає в нову модель лише в чистій точці повторної спроби.
  • Якщо активність інструментів або виведення відповіді вже почалися, очікуване перемикання може залишатися в черзі до пізнішої можливості повторної спроби або наступного ходу користувача.
  • /model default очищає вибір сеансу й повертає сеанс до налаштованої моделі за замовчуванням.
  • Вибраний користувачем ref /model є строгим для цього сеансу: якщо вибраний постачальник/модель недоступні, відповідь явно завершується помилкою замість тихого формування відповіді з agents.defaults.model.fallbacks. Це відрізняється від налаштованих значень за замовчуванням і основних моделей cron-завдань, які все ще можуть використовувати ланцюжки резервних варіантів.
  • /model status — це докладний перегляд (кандидати автентифікації та, якщо налаштовано, endpoint постачальника baseUrl + режим api).
  • Model refs розбираються поділом за першим /. Використовуйте provider/model, коли вводите /model <ref>.
  • Якщо сам ID моделі містить / (у стилі OpenRouter), потрібно додати префікс постачальника (приклад: /model openrouter/moonshotai/kimi-k2).
  • Якщо постачальника опущено, OpenClaw розв’язує введення в такому порядку:
    1. збіг alias
    2. унікальний збіг налаштованого постачальника для саме цього ID моделі без префікса
    3. застарілий fallback до налаштованого постачальника за замовчуванням — якщо цей постачальник більше не надає налаштовану модель за замовчуванням, OpenClaw натомість fallback до першого налаштованого постачальника/моделі, щоб уникнути показу застарілого вилученого постачальника за замовчуванням.
Повна поведінка команди/конфігурація: Slash-команди.

​
Команди 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
boolean
Повний каталог. Включає вбудовані статичні рядки каталогу, що належать постачальнику, ще до налаштування автентифікації, тому перегляди лише для виявлення можуть показувати моделі, недоступні, доки ви не додасте відповідні облікові дані постачальника.
​
--local
boolean
Лише локальні постачальники.
​
--provider <id>
string
Фільтр за ID постачальника, наприклад moonshot. Мітки відображення з інтерактивних вибирачів не приймаються.
​
--plain
boolean
Одна модель на рядок.
​
--json
boolean
Машинозчитуваний вивід.

​
models status

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

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

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

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

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

​
Пов’язане