--- read_when: - Зміна поведінки резервного вибору моделі або UX її вибору - Налагодження помилки «модель не дозволена» або застарілого резервного переходу до постачальника за замовчуванням - Робота над поведінкою об’єднання та обробки секретів у models.json sidebarTitle: Models CLI summary: Як OpenClaw визначає посилання на провайдерів/моделі, ключі конфігурації та команду чату `/model` title: CLI моделей x-i18n: generated_at: "2026-07-16T17:44:43Z" model: gpt-5.6 postprocess_version: locale-links-v1 prompt_version: 32 provider: openai source_hash: 20a5e4861bdafa1f5ff549fc54968051b653611f1ef05e836df855638a7aa967 source_path: concepts/models.md workflow: 16 --- Ротація профілів автентифікації, періоди очікування та їхня взаємодія з резервними варіантами. Короткий огляд провайдерів і приклади. Повний довідник команди `openclaw models` і прапорців. Ключі конфігурації моделей, типові значення та приклади. Посилання на модель (`provider/model`) вибирає провайдера й модель, а не низькорівневе середовище виконання агента. Якщо політику середовища виконання не задано або встановлено `auto`, політика маршрутизації, якою керує провайдер OpenAI, може вибрати Codex лише для точного офіційного HTTPS-маршруту Platform Responses або ChatGPT Responses без заданого автором перевизначення запиту; сам префікс `openai/*` ніколи не вибирає Codex. Адаптери Completions, власні кінцеві точки та задана автором поведінка запиту залишаються на OpenClaw. Офіційні HTTP-кінцеві точки з незашифрованим текстом відхиляються. Див. [Неявне середовище виконання агента OpenAI](/uk/providers/openai#implicit-agent-runtime). Для посилань на Copilot за передплатою (`github-copilot/*`) можна явно ввімкнути зовнішній плагін середовища виконання агента GitHub Copilot, але цей шлях завжди явний (його ніколи не вибирає `auto`). Перевизначення середовища виконання належать до політики провайдера/моделі, а не до всього агента чи сеансу. Вибір середовища виконання не визначає спосіб оплати: облікові дані ключа API OpenAI та передплати ChatGPT/Codex залишаються окремими. Див. [Середовища виконання агентів](/uk/concepts/agent-runtimes) і [Середовище виконання агента GitHub Copilot](/uk/plugins/copilot). ## Порядок вибору `agents.defaults.model.primary` (або `agents.defaults.model` як звичайний рядок). `agents.defaults.model.fallbacks`, які випробовуються по черзі. Ротація профілів автентифікації відбувається в межах провайдера, перш ніж OpenClaw перейде до наступної резервної моделі. Пов’язані поверхні конфігурації моделей: - `agents.defaults.models` — це список дозволених моделей, які може використовувати OpenClaw, разом із псевдонімами. Використовуйте записи `provider/*`, щоб дозволити всі виявлені моделі провайдера без окремого переліку кожної з них. - `agents.defaults.utilityModel` — необов’язкова дешевша модель для коротких внутрішніх завдань, як-от згенеровані назви сеансів панелі керування, назви підтримуваних гілок/тем каналів і опис перебігу виконання. Налаштування `agents.list[].utilityModel` для окремого агента має вищий пріоритет. Якщо значення не задано, OpenClaw використовує оголошену основним провайдером типову малу модель, якщо вона існує (OpenAI → `gpt-5.6-luna`, Anthropic → `claude-haiku-4-5`), інакше — основну модель агента; задайте порожній рядок, щоб вимкнути маршрутизацію службових завдань. Службові завдання є окремими викликами моделі й можуть надсилати обмежений вміст завдання вибраному провайдеру моделі. - `agents.defaults.imageModel` використовується лише тоді, коли основна модель не може приймати зображення. - `agents.defaults.pdfModel` використовується інструментом `pdf`. Якщо значення не задано, інструмент спочатку переходить до `imageModel`, а потім — до визначеної моделі сеансу або типової моделі. - `agents.defaults.imageGenerationModel`, `musicGenerationModel` і `videoGenerationModel` забезпечують роботу спільних інструментів створення медіавмісту. Якщо значення не задано, кожен інструмент визначає типовий провайдер із підтримкою автентифікації: спочатку поточний типовий провайдер, потім решта зареєстрованих провайдерів для цієї можливості в порядку ідентифікаторів провайдерів. Задайте `agents.defaults.mediaGenerationAutoProviderFallback: false`, щоб вимкнути таке міжпровайдерне визначення, зберігши явні резервні варіанти. - Налаштування `agents.list[].model` для окремого агента (разом із прив’язками) має вищий пріоритет за `agents.defaults.model` — див. [Маршрутизація між кількома агентами](/uk/concepts/multi-agent). Повний довідник ключів, типові значення та приклади JSON5: [Довідник із конфігурації](/uk/gateway/config-agents#agent-defaults). ## Джерело вибору та строгість резервного перемикання Те саме значення `provider/model` поводиться по-різному залежно від свого джерела: | Джерело | Поведінка | | ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Налаштоване типове значення (`agents.defaults.model.primary`, основна модель окремого агента) | Звичайна початкова точка; використовує `agents.defaults.model.fallbacks`. | | Автоматичний резервний варіант | Тимчасовий стан відновлення, збережений як `modelOverrideSource: "auto"`. OpenClaw періодично повторно перевіряє початкову основну модель, скидає автоматичний вибір після відновлення та один раз повідомляє про перехід до резервного варіанта або відновлення за кожної зміни стану. | | Вибір користувача для сеансу | Точний і строгий. `/model`, засіб вибору моделі, `session_status(model=...)` і `sessions.patch` зберігають `modelOverrideSource: "user"`. Якщо цей провайдер або модель стає недоступним, виконання завершується з видимою помилкою, а не переходить до іншої налаштованої моделі. | | Cron `--model` / корисне навантаження `model` | Основна модель для окремого завдання. Усе одно використовує налаштовані резервні варіанти, якщо завдання не надає власне значення `fallbacks` у корисному навантаженні (`fallbacks: []` примусово вмикає строгий режим виконання). | Інші правила вибору: - Зміна `agents.defaults.model.primary` не перезаписує наявні закріплення сеансів. Якщо стан повідомляє `This session is pinned to X; config primary Y will apply to new/unpinned sessions.`, виконайте `/model default`, щоб скинути закріплення. - Засоби CLI для вибору типової моделі та списку дозволених моделей враховують `models.mode: "replace"`, показуючи лише `models.providers.*.models`, а не повний вбудований каталог. - Засіб вибору моделі в Control UI запитує в Gateway його налаштоване подання моделей: `agents.defaults.models`, якщо це значення задано (включно із записами-символами узагальнення `provider/*`), інакше — `models.providers.*.models` разом із провайдерами, що мають придатну автентифікацію. Повний вбудований каталог призначений лише для явних режимів перегляду (`models.list` з `view: "all"` або `openclaw models list --all`). - Інтерфейси інвентаризації провайдерів використовують `models.list` з `view: "provider-config"`, щоб показувати створені джерелом рядки `models.providers.*.models` без застосування списків дозволених моделей із засобу вибору. Повний опис механіки: [Перемикання моделі в разі збою](/uk/concepts/model-failover). ## Коротка політика щодо моделей - Встановіть як основну найпотужнішу доступну вам модель останнього покоління. - Використовуйте резервні варіанти для завдань, чутливих до вартості або затримки, і менш критичних чатів. - Для агентів із підтримкою інструментів або недовірених вхідних даних уникайте старіших чи слабших рівнів моделей. ## Початкове налаштування ```bash openclaw onboard ``` Налаштовує модель і автентифікацію для поширених провайдерів без ручного редагування конфігурації, включно з OAuth передплати OpenAI Codex та Anthropic (ключ API або повторне використання Claude CLI). Якщо основну модель не налаштовано, нове налаштування ключа API OpenAI вибирає `openai/gpt-5.6`; базовий ідентифікатор прямого API відповідає рівню Sol. Нове налаштування OAuth ChatGPT/Codex вибирає точне посилання каталогу `openai/gpt-5.6-sol`. Повторна автентифікація зберігає наявну явно задану основну модель, включно з `openai/gpt-5.5`. Якщо GPT-5.6 недоступна для облікового запису, явно виберіть `openai/gpt-5.5`; OpenClaw не знижує її рівень без повідомлення. ## «Модель не дозволена» (і чому відповіді припиняються) Якщо задано `agents.defaults.models`, це значення стає списком дозволених моделей для `/model` і перевизначень сеансу. Вибір моделі поза цим списком повертає наведене нижче повідомлення ще до створення звичайної відповіді: ```text Модель "provider/model" не дозволена. Використовуйте /models, щоб переглянути список провайдерів, або /models , щоб переглянути список моделей. Додайте її за допомогою: openclaw config set agents.defaults.models '{"provider/model":{}}' --strict-json --merge ``` Щоб виправити це, додайте модель до `agents.defaults.models`, повністю очистьте список дозволених моделей (видаліть ключ) або виберіть модель із `/model list`. Якщо відхилена команда містила перевизначення середовища виконання, наприклад `/model openai/gpt-5.5 --runtime codex`, спочатку виправте список дозволених моделей, а потім повторіть ту саму команду `/model ... --runtime ...`. Для локальних моделей/GGUF список дозволених моделей має містити повне посилання з префіксом провайдера, наприклад `ollama/gemma4:26b` або `lmstudio/Gemma4-26b-a4-it-gguf` — перевірте точний рядок у `openclaw models list --provider `. Самих імен файлів або відображуваних назв недостатньо, коли список дозволених моделей активний. Щоб обмежити провайдерів без переліку кожної моделі, використовуйте записи-символи узагальнення `provider/*`: ```json5 { agents: { defaults: { models: { "openai/*": {}, "vllm/*": {}, }, }, }, } ``` Після цього `/model`, `/models` і засоби вибору моделей показують виявлений каталог лише для цих провайдерів, а нові моделі можуть з’являтися без редагування списку дозволених моделей. Поєднуйте точні записи `provider/model` із записами `provider/*`, щоб додати одну конкретну модель іншого провайдера. Приклад списку дозволених моделей із псевдонімами: ```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" }, }, }, }, } ``` Використовуйте `--merge` для додавальних змін: ```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`, якщо вони призведуть до втрати наявних записів; використовуйте `--replace` лише тоді, коли нове значення має стати повним цільовим значенням. Інтерактивне налаштування провайдера та `openclaw configure --section model` уже об’єднують вибір у межах провайдера зі списком дозволених моделей, тому додавання провайдера не видаляє непов’язані записи; налаштування зберігає наявне значення `agents.defaults.model.primary`. Явні команди, як-от `openclaw models auth login --provider --set-default` і `openclaw models set `, усе одно замінюють основну модель. ## `/model` у чаті ```text /model /model list /model 3 /model openai/gpt-5.4 /model default /model status ``` - `/model` і `/model list` показують компактний нумерований список вибору (сімейство моделей + доступні провайдери); `/model <#>` вибирає з нього. У Discord це відкриває розкривні списки провайдерів і моделей із кроком Submit; у Telegram вибір зі списку діє лише в межах сеансу й ніколи не перезаписує постійне типове значення агента в `openclaw.json`. `/models add` застаріла й повертає повідомлення замість реєстрації моделей із чату. - `/model` негайно зберігає новий вибір для сеансу. Якщо агент неактивний, наступний запуск одразу його використовує; якщо запуск уже активний, перемикання ставиться в чергу до наступної безпечної точки повторної спроби (або пізнішої, якщо вже почалася робота інструментів чи виведення відповіді). - `/model default` очищає вибір для сеансу, щоб він знову успадковував налаштовану основну модель. - Вибране користувачем посилання `/model` є строгим для цього сеансу: якщо воно стає недоступним, відповідь завершується з явною помилкою замість непомітного переходу ланцюжком резервних варіантів через `agents.defaults.model.fallbacks`. Налаштовані типові значення й основні моделі завдань cron і надалі використовують ланцюжки резервних варіантів. - `/model status` — це докладне подання: кандидати автентифікації для кожного провайдера, а також (якщо налаштовано) кінцева точка провайдера `baseUrl` і режим `api`. - Посилання на моделі розбираються поділом за першим `/`; введіть `provider/model`. Якщо сам ідентифікатор моделі містить `/` (у стилі OpenRouter), додайте префікс провайдера, наприклад `/model openrouter/moonshotai/kimi-k2`. Якщо провайдера не вказано, OpenClaw пробує: (1) збіг псевдоніма, (2) збіг унікального налаштованого провайдера для цього точного ідентифікатора моделі без префікса, (3) налаштованого типового провайдера (застарілий резервний варіант) — а якщо цей провайдер більше не надає налаштовану типову модель, натомість першу налаштовану пару провайдер/модель, щоб не показувати застаріле типове значення видаленого провайдера. - Посилання на моделі нормалізуються до нижнього регістру; ідентифікатори провайдерів в інших аспектах мають точно збігатися, тому використовуйте ідентифікатор, оголошений плагіном. Повна поведінка команд і конфігурація: [Команди зі скісною рискою](/uk/tools/slash-commands). ## CLI ```bash openclaw models status openclaw models list openclaw models set openclaw models set-image openclaw models scan openclaw models aliases list|add|remove openclaw models fallbacks list|add|remove|clear openclaw models image-fallbacks list|add|remove|clear openclaw models auth list|add|login|paste-api-key|paste-token|setup-token|order ``` `openclaw models` без підкоманди — це скорочення для `models status`, яка також показує завершення терміну дії OAuth для профілів сховища автентифікації (типово попереджає за 24 год). Повний перелік прапорців, структури JSON і підкоманди профілів автентифікації: [Довідник CLI моделей](/uk/cli/models). `openclaw models scan` перевіряє публічний каталог безплатних моделей OpenRouter і може наживо тестувати кандидатів на підтримку інструментів і зображень. Сам каталог є публічним, тому для сканування лише метаданих (`--no-probe`) ключ не потрібен; для живого тестування й `--set-default`/`--set-image` потрібен ключ API OpenRouter (профіль автентифікації або `OPENROUTER_API_KEY`), а без нього команда безпечно обмежується виведенням лише метаданих. Результати впорядковуються за такими критеріями: підтримка зображень, потім затримка інструментів, потім розмір контексту, потім кількість параметрів. У TTY для протестованих результатів з’являється інтерактивний запит вибору резервного варіанта; у неінтерактивному режимі для прийняття типових значень потрібен `--yes`. ## Реєстр моделей (`models.json`) Спеціальні провайдери, налаштовані в `models.providers`, записуються до `models.json` у каталозі агента (типово `~/.openclaw/agents//agent/models.json`). Каталоги плагінів провайдерів зберігаються окремо як згенеровані фрагменти каталогів, що належать плагінам, і завантажуються автоматично. Типово цей файл об’єднується з конфігурацією; задайте `models.mode: "replace"`, щоб використовувати лише налаштованих вами провайдерів. Для однакових ідентифікаторів провайдерів: - Непорожнє `baseUrl`, уже наявне в агентському `models.json`, має пріоритет. - Непорожнє `apiKey` у `models.json` має пріоритет, лише якщо цей провайдер не керується через SecretRef у поточному контексті конфігурації або профілю автентифікації. - Значення `apiKey`, керовані через SecretRef, оновлюються з маркерів джерела замість збереження розкритих секретів: ім’я змінної середовища для посилань на середовище, `secretref-managed` для посилань на файл або виконання. - Значення заголовків, керовані через SecretRef, оновлюються так само з використанням `secretref-env:ENV_VAR_NAME` для посилань на середовище. - Порожні або відсутні `apiKey`/`baseUrl` у `models.json` використовують резервні значення `models.providers` із конфігурації. - Інші поля провайдера оновлюються з конфігурації та нормалізованих даних каталогу. Збереження маркерів визначається джерелом: OpenClaw записує маркери з активного знімка конфігурації джерела (до розкриття), а не з розкритих значень секретів середовища виконання, щоразу, коли повторно генерує `models.json` — зокрема через керовані командами шляхи на кшталт `openclaw agent`. ## Пов’язане - [Середовища виконання агентів](/uk/concepts/agent-runtimes) — OpenClaw, Codex та інші середовища виконання циклу агента - [Довідник конфігурації](/uk/gateway/config-agents#agent-defaults) — ключі конфігурації моделей - [Генерування зображень](/uk/tools/image-generation) — конфігурація моделі зображень - [Перемикання моделей у разі збою](/uk/concepts/model-failover) — ланцюжки резервних варіантів - [Провайдери моделей](/uk/concepts/model-providers) — маршрутизація провайдерів і автентифікація - [Довідник CLI моделей](/uk/cli/models) — повний довідник команд і прапорців - [Генерування музики](/uk/tools/music-generation) — конфігурація музичної моделі - [Генерування відео](/uk/tools/video-generation) — конфігурація відеомоделі