---
read_when:
- Додавання або змінення моделей у CLI (models list/set/scan/aliases/fallbacks)
- Зміна поведінки резервного вибору моделі або UX вибору
- Оновлення перевірок сканування моделей (інструменти/зображення)
sidebarTitle: Models CLI
summary: 'CLI моделей: список, встановлення, псевдоніми, резервні варіанти, сканування, стан'
title: CLI для моделей
x-i18n:
generated_at: "2026-05-11T20:32:49Z"
model: gpt-5.5
provider: openai
source_hash: 346f0edaf0d821bc8e65b73bf1d2385fb343c4b93127e6a20e9dd783c5138c52
source_path: concepts/models.md
workflow: 16
---
Ротація профілів автентифікації, періоди очікування та їхня взаємодія з резервними варіантами.
Короткий огляд провайдерів і приклади.
PI, Codex та інші середовища виконання циклу агента.
Ключі конфігурації моделі.
Посилання на моделі вибирають провайдера й модель. Зазвичай вони не вибирають низькорівневе середовище виконання агента. Посилання на агенти OpenAI є головним винятком: `openai/gpt-5.5` за замовчуванням працює через середовище виконання app-server Codex в офіційного провайдера OpenAI. Явні перевизначення середовища виконання мають належати до політики провайдера/моделі, а не до всього агента чи сеансу. У режимі середовища виконання Codex посилання `openai/gpt-*` не означає оплату через API-ключ; автентифікація може походити з облікового запису Codex або профілю автентифікації `openai-codex`. Див. [Середовища виконання агентів](/uk/concepts/agent-runtimes).
## Як працює вибір моделі
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` все одно може визначити типове значення провайдера з автентифікацією. Спочатку він пробує поточного типового провайдера, потім решту зареєстрованих провайдерів генерації зображень у порядку ідентифікаторів провайдерів. Якщо ви задаєте конкретного провайдера/модель, також налаштуйте автентифікацію/API-ключ цього провайдера.
- `agents.defaults.musicGenerationModel` використовується спільною можливістю генерації музики. Якщо його не вказано, `music_generate` все одно може визначити типове значення провайдера з автентифікацією. Спочатку він пробує поточного типового провайдера, потім решту зареєстрованих провайдерів генерації музики в порядку ідентифікаторів провайдерів. Якщо ви задаєте конкретного провайдера/модель, також налаштуйте автентифікацію/API-ключ цього провайдера.
- `agents.defaults.videoGenerationModel` використовується спільною можливістю генерації відео. Якщо його не вказано, `video_generate` все одно може визначити типове значення провайдера з автентифікацією. Спочатку він пробує поточного типового провайдера, потім решту зареєстрованих провайдерів генерації відео в порядку ідентифікаторів провайдерів. Якщо ви задаєте конкретного провайдера/модель, також налаштуйте автентифікацію/API-ключ цього провайдера.
- Типові значення для окремого агента можуть перевизначати `agents.defaults.model` через `agents.list[].model` разом із прив’язками (див. [Маршрутизація кількох агентів](/uk/concepts/multi-agent)).
## Джерело вибору та поведінка резервного переходу
Один і той самий `provider/model` може означати різне залежно від того, звідки він походить:
- Налаштовані типові значення (`agents.defaults.model.primary` і основні моделі для конкретних агентів) є звичайною початковою точкою й використовують `agents.defaults.model.fallbacks`.
- Автоматичні резервні вибори — це тимчасовий стан відновлення. Вони зберігаються з `modelOverrideSource: "auto"`, щоб наступні ходи могли й далі використовувати ланцюжок резервних варіантів без попереднього зондування відомо проблемної основної моделі.
- Вибори користувача в сеансі є точними. `/model`, вибір моделі, `session_status(model=...)` і `sessions.patch` зберігають `modelOverrideSource: "user"`; якщо вибраний провайдер/модель недоступні, OpenClaw явно завершується помилкою замість переходу до іншої налаштованої моделі.
- 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`)
Посилання на моделі нормалізуються до нижнього регістру. Псевдоніми провайдерів на кшталт `z.ai/*` нормалізуються до `zai/*`.
Приклади конфігурації провайдерів (зокрема 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-codex/*": {},
"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 status
```
- `/model` (і `/model list`) — це компактний нумерований засіб вибору (сімейство моделей + доступні провайдери).
- У Discord `/model` і `/models` відкривають інтерактивний засіб вибору з розкривними списками провайдера й моделі та кроком Submit.
- У Telegram вибори в засобі `/models` мають область дії сеансу; вони не змінюють постійне типове значення агента в `openclaw.json`.
- `/models add` застарів і тепер повертає повідомлення про застарілість замість реєстрації моделей із чату.
- `/model <#>` вибирає з цього засобу вибору.
- `/model` негайно зберігає новий вибір сеансу.
- Якщо агент неактивний, наступний запуск одразу використовує нову модель.
- Якщо запуск уже активний, OpenClaw позначає живе перемикання як очікуване й перезапускає в нову модель лише в чистій точці повторної спроби.
- Якщо активність інструментів або виведення відповіді вже почалися, очікуване перемикання може залишатися в черзі до пізнішої можливості повтору або наступного ходу користувача.
- Вибране користувачем посилання `/model` є суворим для цього сеансу: якщо вибраний провайдер/модель недоступні, відповідь явно завершується помилкою замість мовчазної відповіді з `agents.defaults.model.fallbacks`. Це відрізняється від налаштованих типових значень і основних моделей cron-завдань, які все ще можуть використовувати ланцюжки резервних варіантів.
- `/model status` — це докладний вигляд (кандидати автентифікації та, коли налаштовано, endpoint провайдера `baseUrl` + режим `api`).
- Посилання на моделі аналізуються поділом за **першим** `/`. Використовуйте `provider/model`, коли вводите `/model [`.
- Якщо сам ID моделі містить `/` (у стилі OpenRouter), потрібно додати префікс провайдера (приклад: `/model openrouter/moonshotai/kimi-k2`).
- Якщо ви не вказуєте провайдера, OpenClaw розв’язує введення в такому порядку:
1. збіг з псевдонімом
2. унікальний збіг налаштованого провайдера для цього точного ID моделі без префікса
3. застарілий fallback до налаштованого провайдера за замовчуванням — якщо цей провайдер більше не надає налаштовану модель за замовчуванням, OpenClaw натомість fallback до першої налаштованої пари провайдер/модель, щоб не показувати застаріле значення за замовчуванням для видаленого провайдера.
]
Повна поведінка команди/конфігурація: [Команди зі скісною рискою](/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`
Показує розв’язану основну модель, fallbacks, модель зображень і огляд автентифікації налаштованих провайдерів. Також показує статус завершення терміну дії 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.` пропускає збережений профіль, перевірка повідомляє `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 і може за потреби перевіряти моделі на підтримку інструментів і зображень.
Пропустити живі перевірки (лише метадані).
Мінімальний розмір параметрів (мільярди).
Пропустити старіші моделі.
Фільтр за префіксом провайдера.
Розмір списку fallback.
Установити `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`)
- Для живих перевірок потрібен ключ API OpenRouter з профілів автентифікації або `OPENROUTER_API_KEY` (див. [Змінні середовища](/uk/help/environment))
- Необов’язкові фільтри: `--max-age-days`, `--min-params`, `--provider`, `--max-candidates`
- Керування запитами/перевірками: `--timeout`, `--concurrency`
Коли живі перевірки виконуються в TTY, ви можете інтерактивно вибрати fallbacks. У неінтерактивному режимі передайте `--yes`, щоб прийняти значення за замовчуванням. Результати лише метаданих мають інформаційний характер; `--set-default` і `--set-image` вимагають живих перевірок, щоб OpenClaw не налаштував непридатну до використання модель OpenRouter без ключа.
## Реєстр моделей (`models.json`)
Користувацькі провайдери в `models.providers` записуються в `models.json` у каталозі агента (за замовчуванням `~/.openclaw/agents//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` агента fallback до `models.providers` у конфігурації.
- Інші поля провайдера оновлюються з конфігурації та нормалізованих даних каталогу.
Збереження маркерів є джерельно-авторитетним: OpenClaw записує маркери з активного знімка конфігурації джерела (до розв’язання), а не з розв’язаних значень секретів під час виконання. Це застосовується щоразу, коли OpenClaw повторно генерує `models.json`, включно зі шляхами, керованими командами, як-от `openclaw agent`.
## Пов’язане
- [Середовища виконання агентів](/uk/concepts/agent-runtimes) — PI, Codex та інші середовища виконання циклу агента
- [Довідник конфігурації](/uk/gateway/config-agents#agent-defaults) — ключі конфігурації моделей
- [Генерація зображень](/uk/tools/image-generation) — конфігурація моделі зображень
- [Перемикання моделі після збою](/uk/concepts/model-failover) — fallback-ланцюжки
- [Провайдери моделей](/uk/concepts/model-providers) — маршрутизація провайдерів і автентифікація
- [Генерація музики](/uk/tools/music-generation) — конфігурація музичної моделі
- [Генерація відео](/uk/tools/video-generation) — конфігурація відеомоделі