---
read_when:
- Додавання або змінення CLI для моделей (models list/set/scan/aliases/fallbacks)
- Зміна поведінки резервного вибору моделі або UX вибору
- Оновлення проб сканування моделей (інструменти/зображення)
sidebarTitle: Models CLI
summary: 'CLI моделей: список, налаштування, псевдоніми, резервні варіанти, сканування, статус'
title: CLI моделей
x-i18n:
generated_at: "2026-06-27T17:27:08Z"
model: gpt-5.5
postprocess_version: locale-links-v1
provider: openai
source_hash: 8c7d4cbe1e0854a281f57f39dac9ac5f54c65f50da08cf37dfd298f8f1dd5536
source_path: concepts/models.md
workflow: 16
---
Ротація профілів автентифікації, періоди охолодження та як це взаємодіє з резервними варіантами.
Короткий огляд постачальників і приклади.
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`. Див. [Середовища виконання агентів](/uk/concepts/agent-runtimes) і [Середовище виконання агента GitHub Copilot](/uk/plugins/copilot).
## Як працює вибір моделі
OpenClaw вибирає моделі в такому порядку:
`agents.defaults.model.primary` (або `agents.defaults.model`).
`agents.defaults.model.fallbacks` (у порядку).
Відмовостійке перемикання автентифікації відбувається всередині постачальника перед переходом до наступної моделі.
- `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` плюс прив’язки (див. [Маршрутизація кількох агентів](/uk/concepts/multi-agent)).
## Джерело вибору й поведінка резервних варіантів
Один і той самий `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`.
## Коротка політика моделей
- Встановіть основною найпотужнішу модель останнього покоління, доступну вам.
- Використовуйте резервні варіанти для завдань, чутливих до вартості/затримки, і чатів із нижчими ризиками.
- Для агентів з увімкненими інструментами або ненадійних вхідних даних уникайте старіших/слабших рівнів моделей.
## Початкове налаштування (рекомендовано)
Якщо ви не хочете редагувати конфігурацію вручну, запустіть початкове налаштування:
```bash
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](/uk/providers/opencode).
### Безпечні редагування allowlist
Використовуйте додавальні записи, коли вручну оновлюєте `agents.defaults.models`:
```bash
openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json --merge
```
`openclaw config set` захищає мапи моделей/постачальників від випадкового перезапису. Просте присвоєння об’єкта до `agents.defaults.models`, `models.providers` або `models.providers..models` відхиляється, якщо воно видалило б наявні записи. Використовуйте `--merge` для додавальних змін; використовуйте `--replace` лише тоді, коли надане значення має стати повним цільовим значенням.
Інтерактивне налаштування постачальника та `openclaw configure --section model` також зливають вибори в межах постачальника з наявним allowlist, тому додавання Codex, Ollama або іншого постачальника не видаляє непов’язані записи моделей. Configure зберігає наявний `agents.defaults.model.primary`, коли автентифікація постачальника застосовується повторно. Явні команди встановлення типового значення, як-от `openclaw models auth login --provider --set-default` і `openclaw models set `, усе ще замінюють `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 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 `.
Самих локальних імен файлів або відображуваних назв недостатньо, коли allowlist
активний.
Якщо ви хочете обмежити постачальників без ручного перелічення кожної моделі, додайте
записи `provider/*` до `agents.defaults.models`:
```json5
{
agents: {
defaults: {
models: {
"openai/*": {},
"vllm/*": {},
},
},
},
}
```
За такої політики `/model`, `/models` і засоби вибору моделей показують виявлений
каталог лише для цих постачальників. Нові моделі від вибраних постачальників можуть
з’являтися без редагування allowlist. Точні записи `provider/model` можна поєднувати
із записами `provider/*`, коли потрібна одна конкретна модель від іншого постачальника.
Приклад конфігурації allowlist:
```json5
{
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 [`.
- Якщо сам ID моделі містить `/` (у стилі OpenRouter), потрібно додати префікс постачальника (приклад: `/model openrouter/moonshotai/kimi-k2`).
- Якщо постачальника опущено, OpenClaw розв’язує введення в такому порядку:
1. збіг alias
2. унікальний збіг налаштованого постачальника для саме цього ID моделі без префікса
3. застарілий fallback до налаштованого постачальника за замовчуванням — якщо цей постачальник більше не надає налаштовану модель за замовчуванням, OpenClaw натомість fallback до першого налаштованого постачальника/моделі, щоб уникнути показу застарілого вилученого постачальника за замовчуванням.
]
Повна поведінка команди/конфігурація: [Slash-команди](/uk/tools/slash-commands).
## Команди CLI
```bash
openclaw models list
openclaw models status
openclaw models set
openclaw models set-image
openclaw models aliases list
openclaw models aliases add
openclaw models aliases remove
openclaw models fallbacks list
openclaw models fallbacks add
openclaw models fallbacks remove
openclaw models fallbacks clear
openclaw models image-fallbacks list
openclaw models image-fallbacks add
openclaw models image-fallbacks remove
openclaw models image-fallbacks clear
```
`openclaw models` (без підкоманди) — це скорочення для `models status`.
### `models list`
За замовчуванням показує налаштовані/доступні через автентифікацію моделі. Корисні прапорці:
Повний каталог. Включає вбудовані статичні рядки каталогу, що належать постачальнику, ще до налаштування автентифікації, тому перегляди лише для виявлення можуть показувати моделі, недоступні, доки ви не додасте відповідні облікові дані постачальника.
Лише локальні постачальники.
Фільтр за ID постачальника, наприклад `moonshot`. Мітки відображення з інтерактивних вибирачів не приймаються.
Одна модель на рядок.
Машинозчитуваний вивід.
### `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.` пропускає збережений профіль, перевірка повідомляє `excluded_by_auth_order` замість спроби його використати. Якщо автентифікація існує, але для цього постачальника неможливо розв’язати модель, придатну для перевірки, перевірка повідомляє `status: no_model`.
Вибір автентифікації залежить від постачальника/облікового запису. Для постійно ввімкнених хостів Gateway API-ключі зазвичай найпередбачуваніші; повторне використання Claude CLI та наявні профілі Anthropic OAuth/токенів також підтримуються.
Приклад (Claude CLI):
```bash
claude auth login
openclaw models status
```
## Сканування (безкоштовні моделі OpenRouter)
`openclaw models scan` перевіряє **каталог безкоштовних моделей** OpenRouter і може додатково перевіряти моделі на підтримку інструментів і зображень.
Пропустити live-перевірки (лише метадані).
Мінімальний розмір параметрів (мільярди).
Пропустити старіші моделі.
Фільтр за префіксом постачальника.
Розмір списку резервних варіантів.
Встановити `agents.defaults.model.primary` на перший вибір.
Встановити `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` (див. [Змінні середовища](/uk/help/environment))
- Необов’язкові фільтри: `--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//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`.
## Пов’язане
- [Середовища виконання агентів](/uk/concepts/agent-runtimes) — OpenClaw, Codex та інші середовища виконання agent loop
- [Довідник конфігурації](/uk/gateway/config-agents#agent-defaults) — ключі конфігурації моделей
- [Генерація зображень](/uk/tools/image-generation) — конфігурація моделі для зображень
- [Model failover](/uk/concepts/model-failover) — ланцюжки резервних варіантів
- [Постачальники моделей](/uk/concepts/model-providers) — маршрутизація постачальників і автентифікація
- [Генерація музики](/uk/tools/music-generation) — конфігурація моделі для музики
- [Генерація відео](/uk/tools/video-generation) — конфігурація моделі для відео