CLI моделей

Посилання на моделі вибирають постачальника й модель. Зазвичай вони не вибирають низькорівневе середовище виконання агента. Посилання на агенти 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 вибирає моделі в такому порядку:

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

Один і той самий 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)

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

Використовуйте додавальні записи, коли вручну оновлюєте agents.defaults.models:

openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json --merge

"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

Коли відхилена команда містила перевизначення середовища виконання, наприклад /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

Повна поведінка команди/конфігурація: Slash-команди.

Команди CLI

openclaw models listopenclaw models statusopenclaw models set <provider/model>openclaw models set-image <provider/model> openclaw models aliases listopenclaw models aliases add <alias> <provider/model>openclaw models aliases remove <alias> openclaw models fallbacks listopenclaw models fallbacks add <provider/model>openclaw models fallbacks remove <provider/model>openclaw models fallbacks clear openclaw models image-fallbacks listopenclaw models image-fallbacks add <provider/model>openclaw models image-fallbacks remove <provider/model>openclaw models image-fallbacks clear

openclaw models (без підкоманди) — це скорочення для models status.

models list

За замовчуванням показує налаштовані/доступні через автентифікацію моделі. Корисні прапорці:

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tcHJvdmlkZXIgPGlk " type="string"> Фільтр за ID постачальника, наприклад moonshot. Мітки відображення з інтерактивних вибирачів не приймаються.

models status

Показує розв’язану основну модель, резервні варіанти, модель для зображень і огляд автентифікації налаштованих постачальників. Також показує статус завершення строку дії OAuth для профілів, знайдених у сховищі автентифікації (за замовчуванням попереджає протягом 24 год). --plain друкує лише розв’язану основну модель.

Приклад (Claude CLI):

claude auth loginopenclaw models status

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

openclaw models scan перевіряє каталог безкоштовних моделей OpenRouter і може додатково перевіряти моделі на підтримку інструментів і зображень.

Результати сканування ранжуються за:

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.

Пов’язане

• Середовища виконання агентів — OpenClaw, Codex та інші середовища виконання agent loop
• Довідник конфігурації — ключі конфігурації моделей
• Генерація зображень — конфігурація моделі для зображень
• Model failover — ланцюжки резервних варіантів
• Постачальники моделей — маршрутизація постачальників і автентифікація
• Генерація музики — конфігурація моделі для музики
• Генерація відео — конфігурація моделі для відео