CLI моделей

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

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

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

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

Те саме provider/model може означати різні речі залежно від того, звідки воно взялося:

• Налаштовані типові значення (agents.defaults.model.primary і основні моделі конкретних агентів) є звичайною відправною точкою та використовують agents.defaults.model.fallbacks.
• Автоматичні резервні вибори — це тимчасовий стан відновлення. Вони зберігаються з modelOverrideSource: "auto", щоб наступні ходи могли продовжувати використовувати ланцюг резервних варіантів без попередньої перевірки відомо несправної основної моделі.
• Вибори користувача в сеансі є точними. /model, вибирач моделі, session_status(model=...) і sessions.patch зберігають modelOverrideSource: "user"; якщо вибраний провайдер/модель недоступний, OpenClaw явно завершується з помилкою, а не переходить до іншої налаштованої моделі.
• Cron --model / корисне навантаження model — це основна модель для окремого завдання. Вона все одно використовує налаштовані резервні варіанти, якщо завдання не надає явне корисне навантаження fallbacks (використовуйте fallbacks: [] для строгого запуску cron).
• Вибирачі типової моделі CLI та allowlist поважають models.mode: "replace", показуючи явні models.providers.*.models замість завантаження повного вбудованого каталогу.
• Вибирач моделей Control UI запитує в Gateway налаштований вигляд моделей: agents.defaults.models, якщо присутній, інакше явні 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 + псевдоніми + параметри провайдера)
• models.providers (власні провайдери, записані в models.json)

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

Використовуйте додавальні записи, коли оновлюєте agents.defaults.models вручну:

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

# "Модель не дозволена" (і чому відповіді зупиняються)

Якщо 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

Коли відхилена команда містила перевизначення середовища виконання, як-от /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 активний.

Приклад конфігурації allowlist:

{
  agent: {
    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

Повна поведінка команд/конфігурація: Slash-команди.

# Команди 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

Показує налаштовані/доступні для автентифікації моделі за замовчуванням. Корисні прапорці:

--allboolean

Повний каталог. Містить вбудовані статичні рядки каталогу, що належать провайдеру, ще до налаштування автентифікації, тож подання лише для виявлення можуть показувати моделі, недоступні, доки ви не додасте відповідні облікові дані провайдера.

--localboolean

Лише локальні провайдери.

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tcHJvdmlkZXIgPGlk " type="string"> Фільтрувати за id провайдера, наприклад moonshot. Відображувані мітки з інтерактивних засобів вибору не приймаються.

--plainboolean

Одна модель на рядок.

--jsonboolean

Машиночитаний вивід.

# models status

Показує розв’язану основну модель, резервні варіанти, модель зображень і огляд автентифікації налаштованих провайдерів. Також показує стан завершення терміну дії OAuth для профілів, знайдених у сховищі автентифікації (за замовчуванням попереджає в межах 24 годин). --plain друкує лише розв’язану основну модель.

Приклад (Claude CLI):

claude auth login
openclaw models status

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

openclaw models scan перевіряє каталог безкоштовних моделей OpenRouter і може додатково перевіряти моделі на підтримку інструментів і зображень.

--no-probeboolean

Пропустити живі перевірки (лише метадані).

"--min-params

"--max-age-days

"--provider

"--max-candidates

--set-defaultboolean

Установити agents.defaults.model.primary на перший вибір.

--set-imageboolean

Установити agents.defaults.imageModel.primary на перший вибір зображення.

Результати сканування ранжуються за:

1. Підтримкою зображень
2. Затримкою інструментів
3. Розміром контексту
4. Кількістю параметрів

Вхідні дані:

• Список OpenRouter /models (фільтр :free)
• Живі перевірки потребують ключа API OpenRouter з профілів автентифікації або OPENROUTER_API_KEY (див. Змінні середовища)
• Необов’язкові фільтри: --max-age-days, --min-params, --provider, --max-candidates
• Елементи керування запитами/перевірками: --timeout, --concurrency

Коли живі перевірки виконуються в TTY, ви можете інтерактивно вибрати резервні варіанти. У неінтерактивному режимі передайте --yes, щоб прийняти типові значення. Результати лише метаданих мають інформаційний характер; --set-default і --set-image потребують живих перевірок, щоб OpenClaw не налаштував непридатну для використання модель OpenRouter без ключа.

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

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

# Пов’язане

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