Перейти до основного вмісту

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

Відмова моделі та перемикання

Ротація профілів автентифікації, періоди очікування та їхня взаємодія з резервними варіантами.

Провайдери моделей

Короткий огляд провайдерів і приклади.

Середовища виконання агентів

PI, Codex та інші середовища виконання циклу агента.

Довідник конфігурації

Ключі конфігурації моделі.
Посилання на моделі вибирають провайдера й модель. Зазвичай вони не вибирають низькорівневе середовище виконання агента. Посилання на агенти OpenAI є головним винятком: openai/gpt-5.5 за замовчуванням працює через середовище виконання app-server Codex в офіційного провайдера OpenAI. Явні перевизначення середовища виконання мають належати до політики провайдера/моделі, а не до всього агента чи сеансу. У режимі середовища виконання Codex посилання openai/gpt-* не означає оплату через API-ключ; автентифікація може походити з облікового запису Codex або профілю автентифікації openai-codex. Див. Середовища виконання агентів.

​
Як працює вибір моделі

OpenClaw вибирає моделі в такому порядку:
1

Основна модель

agents.defaults.model.primary (або agents.defaults.model).
2

Резервні варіанти

agents.defaults.model.fallbacks (за порядком).
3

Перемикання автентифікації провайдера

Перемикання автентифікації відбувається всередині провайдера перед переходом до наступної моделі.
  • 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 разом із прив’язками (див. Маршрутизація кількох агентів).

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

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

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

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

​
Початкове налаштування (рекомендовано)

Якщо ви не хочете редагувати конфігурацію вручну, запустіть початкове налаштування: 
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.

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

Використовуйте адитивні записи, коли оновлюєте agents.defaults.models вручну: 
openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json --merge
openclaw config set захищає мапи моделей/провайдерів від випадкового перезапису. Звичайне присвоєння об’єкта до agents.defaults.models, models.providers або models.providers.<id>.models відхиляється, якщо воно видалило б наявні записи. Використовуйте --merge для адитивних змін; використовуйте --replace лише тоді, коли надане значення має стати повним цільовим значенням.Інтерактивне налаштування провайдера та openclaw configure --section model також об’єднують вибори на рівні провайдера з наявним allowlist, тому додавання Codex, Ollama або іншого провайдера не видаляє непов’язані записи моделей. Configure зберігає наявний agents.defaults.model.primary, коли автентифікацію провайдера застосовано повторно. Явні команди встановлення типового значення, як-от openclaw models auth login --provider <id> --set-default і openclaw models set <model>, усе ще замінюють 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 <provider> 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 <provider>. Самих локальних імен файлів або відображуваних назв недостатньо, коли allowlist активний. Якщо ви хочете обмежити провайдерів без ручного перелічення кожної моделі, додайте записи provider/* до agents.defaults.models: 
{
  agents: {
    defaults: {
      models: {
        "openai-codex/*": {},
        "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 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 <ref>.
  • Якщо сам ID моделі містить / (у стилі OpenRouter), потрібно додати префікс провайдера (приклад: /model openrouter/moonshotai/kimi-k2).
  • Якщо ви не вказуєте провайдера, OpenClaw розв’язує введення в такому порядку:
    1. збіг з псевдонімом
    2. унікальний збіг налаштованого провайдера для цього точного ID моделі без префікса
    3. застарілий fallback до налаштованого провайдера за замовчуванням — якщо цей провайдер більше не надає налаштовану модель за замовчуванням, OpenClaw натомість fallback до першої налаштованої пари провайдер/модель, щоб не показувати застаріле значення за замовчуванням для видаленого провайдера.
Повна поведінка команди/конфігурація: Команди зі скісною рискою.

​
Команди CLI

openclaw models list
openclaw models status
openclaw models set <provider/model>
openclaw models set-image <provider/model>

openclaw models aliases list
openclaw models aliases add <alias> <provider/model>
openclaw models aliases remove <alias>

openclaw models fallbacks list
openclaw models fallbacks add <provider/model>
openclaw models fallbacks remove <provider/model>
openclaw models fallbacks clear

openclaw models image-fallbacks list
openclaw models image-fallbacks add <provider/model>
openclaw models image-fallbacks remove <provider/model>
openclaw models image-fallbacks clear
openclaw models (без підкоманди) — це скорочення для models status.

​
models list

За замовчуванням показує налаштовані/доступні за автентифікацією моделі. Корисні прапорці:
​
--all
boolean
Повний каталог. Містить рядки статичного каталогу, що належать вбудованому провайдеру, ще до налаштування автентифікації, тож подання лише для виявлення можуть показувати моделі, які недоступні, доки ви не додасте відповідні облікові дані провайдера.
​
--local
boolean
Лише локальні провайдери.
​
--provider <id>
string
Фільтр за ID провайдера, наприклад moonshot. Відображувані назви з інтерактивних вибірників не приймаються.
​
--plain
boolean
Одна модель на рядок.
​
--json
boolean
Машинозчитуваний вивід.

​
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.<provider> пропускає збережений профіль, перевірка повідомляє excluded_by_auth_order замість спроби використати його. Якщо автентифікація існує, але для цього провайдера не можна розв’язати модель, придатну для перевірки, перевірка повідомляє status: no_model.
Вибір автентифікації залежить від провайдера/облікового запису. Для постійно ввімкнених хостів Gateway ключі API зазвичай найпередбачуваніші; також підтримуються повторне використання Claude CLI і наявні профілі Anthropic OAuth/токенів.
Приклад (Claude CLI): 
claude auth login
openclaw models status

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

openclaw models scan перевіряє каталог безкоштовних моделей OpenRouter і може за потреби перевіряти моделі на підтримку інструментів і зображень.
​
--no-probe
boolean
Пропустити живі перевірки (лише метадані).
​
--min-params <b>
number
Мінімальний розмір параметрів (мільярди).
​
--max-age-days <days>
number
Пропустити старіші моделі.
​
--provider <name>
string
Фільтр за префіксом провайдера.
​
--max-candidates <n>
number
Розмір списку fallback.
​
--set-default
boolean
Установити agents.defaults.model.primary на перший вибір.
​
--set-image
boolean
Установити 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 (див. Змінні середовища)
  • Необов’язкові фільтри: --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/<agentId>/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.

​
Пов’язане