CLI моделей

Посилання на модель (provider/model) вибирає провайдера й модель, а не низькорівневе середовище виконання агента. Якщо політику середовища виконання не задано або встановлено auto, політика маршрутизації, якою керує провайдер OpenAI, може вибрати Codex лише для точного офіційного HTTPS-маршруту Platform Responses або ChatGPT Responses без заданого автором перевизначення запиту; сам префікс openai/* ніколи не вибирає Codex. Адаптери Completions, власні кінцеві точки та задана автором поведінка запиту залишаються на OpenClaw. Офіційні HTTP-кінцеві точки з незашифрованим текстом відхиляються. Див. Неявне середовище виконання агента OpenAI.

Для посилань на Copilot за передплатою (github-copilot/*) можна явно ввімкнути зовнішній плагін середовища виконання агента GitHub Copilot, але цей шлях завжди явний (його ніколи не вибирає auto). Перевизначення середовища виконання належать до політики провайдера/моделі, а не до всього агента чи сеансу. Вибір середовища виконання не визначає спосіб оплати: облікові дані ключа API OpenAI та передплати ChatGPT/Codex залишаються окремими. Див. Середовища виконання агентів і Середовище виконання агента GitHub Copilot.

Порядок вибору

Пов’язані поверхні конфігурації моделей:

• 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 — див. Маршрутизація між кількома агентами.

Повний довідник ключів, типові значення та приклади JSON5: Довідник із конфігурації.

Джерело вибору та строгість резервного перемикання

Те саме значення provider/model поводиться по-різному залежно від свого джерела:

Інші правила вибору:

• Зміна 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 без застосування списків дозволених моделей із засобу вибору.

Повний опис механіки: Перемикання моделі в разі збою.

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

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

Початкове налаштування

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

Модель "provider/model" не дозволена. Використовуйте /models, щоб переглянути список провайдерів, або /models <provider>, щоб переглянути список моделей.Додайте її за допомогою: 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>. Самих імен файлів або відображуваних назв недостатньо, коли список дозволених моделей активний.

Щоб обмежити провайдерів без переліку кожної моделі, використовуйте записи-символи узагальнення provider/*:

{  agents: {    defaults: {      models: {        "openai/*": {},        "vllm/*": {},      },    },  },}

Після цього /model, /models і засоби вибору моделей показують виявлений каталог лише для цих провайдерів, а нові моделі можуть з’являтися без редагування списку дозволених моделей. Поєднуйте точні записи provider/model із записами provider/*, щоб додати одну конкретну модель іншого провайдера.

Приклад списку дозволених моделей із псевдонімами:

{  agents: {    defaults: {      model: { primary: "anthropic/claude-sonnet-4-6" },      models: {        "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },        "anthropic/claude-opus-4-6": { alias: "Opus" },      },    },  },}

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

/model у чаті

/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) налаштованого типового провайдера (застарілий резервний варіант) — а якщо цей провайдер більше не надає налаштовану типову модель, натомість першу налаштовану пару провайдер/модель, щоб не показувати застаріле типове значення видаленого провайдера.
• Посилання на моделі нормалізуються до нижнього регістру; ідентифікатори провайдерів в інших аспектах мають точно збігатися, тому використовуйте ідентифікатор, оголошений плагіном.

Повна поведінка команд і конфігурація: Команди зі скісною рискою.

CLI

openclaw models statusopenclaw models listopenclaw models set <provider/model>openclaw models set-image <provider/model>openclaw models scanopenclaw models aliases list|add|removeopenclaw models fallbacks list|add|remove|clearopenclaw models image-fallbacks list|add|remove|clearopenclaw models auth list|add|login|paste-api-key|paste-token|setup-token|order

openclaw models без підкоманди — це скорочення для models status, яка також показує завершення терміну дії OAuth для профілів сховища автентифікації (типово попереджає за 24 год). Повний перелік прапорців, структури JSON і підкоманди профілів автентифікації: Довідник CLI моделей.

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

Спеціальні провайдери, налаштовані в models.providers, записуються до models.json у каталозі агента (типово ~/.openclaw/agents/<agentId>/agent/models.json). Каталоги плагінів провайдерів зберігаються окремо як згенеровані фрагменти каталогів, що належать плагінам, і завантажуються автоматично. Типово цей файл об’єднується з конфігурацією; задайте models.mode: "replace", щоб використовувати лише налаштованих вами провайдерів.

Збереження маркерів визначається джерелом: OpenClaw записує маркери з активного знімка конфігурації джерела (до розкриття), а не з розкритих значень секретів середовища виконання, щоразу, коли повторно генерує models.json — зокрема через керовані командами шляхи на кшталт openclaw agent.

Пов’язане

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