Concepts and configuration

CLI моделей

Отказоустойчивое переключение моделей

Ротация профилей аутентификации, периоды охлаждения и их взаимодействие с резервными вариантами.

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

Краткий обзор провайдеров и примеры.

Среды выполнения агентов

OpenClaw, Codex и другие среды выполнения агентного цикла.

Справочник по конфигурации

Ключи конфигурации моделей.

Ссылки на модели выбирают провайдера и модель. Обычно они не выбирают низкоуровневую среду выполнения агента. Основное исключение — ссылки на агентов OpenAI: openai/gpt-5.5 по умолчанию выполняется через среду выполнения Codex app-server у официального провайдера OpenAI. Для ссылок Subscription Copilot (github-copilot/*) дополнительно можно явно включить внешний Plugin среды выполнения агента GitHub Copilot — этот путь остается явным (без резервного auto). Явные переопределения среды выполнения относятся к политике провайдера/модели, а не ко всему агенту или сеансу. В режиме среды выполнения Codex ссылка openai/gpt-* не подразумевает оплату по API-ключу; аутентификация может выполняться через учетную запись Codex или профиль OAuth openai. См. Среды выполнения агентов и Среда выполнения агента GitHub Copilot.

Как работает выбор модели

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 все равно может вывести резервное значение провайдера с настроенной аутентификацией. Сначала пробуется текущий провайдер по умолчанию, затем оставшиеся зарегистрированные провайдеры генерации изображений в порядке provider-id. Если вы задаете конкретного провайдера/модель, также настройте аутентификацию/API-ключ этого провайдера.
agents.defaults.musicGenerationModel используется общей возможностью генерации музыки. Если он не указан, music_generate все равно может вывести резервное значение провайдера с настроенной аутентификацией. Сначала пробуется текущий провайдер по умолчанию, затем оставшиеся зарегистрированные провайдеры генерации музыки в порядке provider-id. Если вы задаете конкретного провайдера/модель, также настройте аутентификацию/API-ключ этого провайдера.
agents.defaults.videoGenerationModel используется общей возможностью генерации видео. Если он не указан, video_generate все равно может вывести резервное значение провайдера с настроенной аутентификацией. Сначала пробуется текущий провайдер по умолчанию, затем оставшиеся зарегистрированные провайдеры генерации видео в порядке provider-id. Если вы задаете конкретного провайдера/модель, также настройте аутентификацию/API-ключ этого провайдера.
Значения по умолчанию для отдельных агентов могут переопределять agents.defaults.model через agents.list[].model плюс привязки (см. Маршрутизация нескольких агентов).

Источник выбора и поведение резервного переключения

Одна и та же ссылка provider/model может означать разные вещи в зависимости от того, откуда она появилась:

Настроенные значения по умолчанию (agents.defaults.model.primary и основные модели конкретных агентов) являются обычной отправной точкой и используют agents.defaults.model.fallbacks.
Автоматические резервные выборы — это временное состояние восстановления. Они сохраняются с modelOverrideSource: "auto", чтобы последующие ходы могли продолжать использовать резервную цепочку без проверки заведомо неисправной основной модели каждый раз; OpenClaw периодически снова проверяет исходную основную модель, очищает автоматический выбор при восстановлении и объявляет переходы в резервный режим/обратно один раз на каждое изменение состояния.
Пользовательские выборы сеанса являются точными. /model, средство выбора модели, session_status(model=...) и sessions.patch сохраняют modelOverrideSource: "user"; если выбранный провайдер/модель недоступен, OpenClaw явно завершится ошибкой вместо перехода к другой настроенной модели.
Изменение agents.defaults.model.primary не перезаписывает существующие выборы сеанса. Если статус сообщает This session is pinned to X; config primary Y will apply to new/unpinned sessions., очистите текущий выбор сеанса с помощью /model default, чтобы он снова наследовал настроенную основную модель.
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)

Безопасное редактирование 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.<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 возвращает:

Code

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 активен.

Если вы хотите ограничить провайдеров без ручного перечисления каждой модели, добавьте записи provider/* в agents.defaults.models:

json5

{  agents: {    defaults: {      models: {        "openai/*": {},        "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`)

Вы можете переключать модели для текущего сеанса без перезапуска:

Code

/model/model list/model 3/model openai/gpt-5.4/model default/model status

Поведение средства выбора

/model (и /model list) — это компактное нумерованное средство выбора (семейство моделей + доступные провайдеры).
В Discord /model и /models открывают интерактивное средство выбора с выпадающими списками провайдера и модели, а также шагом Submit.
В Telegram выборы в средстве /models привязаны к сеансу; они не меняют постоянное значение агента по умолчанию в openclaw.json.
/models add устарел и теперь возвращает сообщение об устаревании вместо регистрации моделей из чата.
/model <#> выбирает из этого средства выбора.

Постоянство и переключение на лету

/model сразу сохраняет новый выбор для сеанса.
Если агент простаивает, следующий запуск сразу использует новую модель.
Если запуск уже активен, OpenClaw помечает переключение на лету как ожидающее и перезапускается с новой моделью только в чистой точке повторной попытки.
Если активность инструментов или вывод ответа уже начались, ожидающее переключение может оставаться в очереди до следующей возможности повторной попытки или следующего хода пользователя.
/model default очищает выбор для сеанса и возвращает сеанс к настроенной модели по умолчанию.
Выбранная пользователем ссылка /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 вместо этого возвращается к первому настроенному провайдеру/модели, чтобы не показывать устаревшее значение по умолчанию для удаленного провайдера.

Полное поведение команд/конфигурация: Слэш-команды.

Команды CLI

bash

openclaw models listopenclaw models statusopenclaw models set <provider/model>openclaw models set-image <provider/model> openclaw models aliases listopenclaw models aliases add <alias> <provider/model>openclaw models aliases remove <alias> openclaw models fallbacks listopenclaw models fallbacks add <provider/model>openclaw models fallbacks remove <provider/model>openclaw models fallbacks clear openclaw models image-fallbacks listopenclaw 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 печатает только разрешенную основную модель.

Поведение аутентификации и проб

Статус OAuth отображается всегда (и включается в вывод --json). Если у настроенного провайдера нет учетных данных, models status печатает раздел Отсутствует аутентификация.
JSON включает auth.oauth (окно предупреждения + профили) и auth.providers (эффективная аутентификация по провайдерам, включая учетные данные из окружения). auth.oauth отражает только состояние профилей в хранилище аутентификации; провайдеры только из окружения там не отображаются.
Используйте --check для автоматизации (код выхода 1 при отсутствии/истечении, 2 при скором истечении).
Используйте --probe для живых проверок аутентификации; строки проб могут поступать из профилей аутентификации, учетных данных окружения или models.json.
Если явный auth.order.<provider> пропускает сохраненный профиль, проба сообщает excluded_by_auth_order вместо попытки использовать его. Если аутентификация есть, но для этого провайдера нельзя разрешить модель, пригодную для пробы, проба сообщает status: no_model.

Пример (Claude CLI):

bash

claude auth loginopenclaw 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 в первый выбранный вариант изображения.

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

Поддержке изображений
Задержке инструментов
Размеру контекста
Количеству параметров

Ввод:

Список OpenRouter /models (фильтр :free)
Живые пробы требуют API-ключ OpenRouter из профилей аутентификации или OPENROUTER_API_KEY (см. Переменные окружения)
Необязательные фильтры: --max-age-days, --min-params, --provider, --max-candidates
Управление запросами/пробами: --timeout, --concurrency

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

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

Пользовательские провайдеры в models.providers записываются в models.json в каталоге агента (по умолчанию ~/.openclaw/agents/<agentId>/agent/models.json). Каталоги Plugin-провайдеров хранятся как сгенерированные фрагменты каталога, принадлежащие Plugin, в состоянии Plugin агента и загружаются автоматически. Этот файл по умолчанию объединяется, если models.mode не задан как replace.

Приоритет режима объединения

Приоритет режима объединения для совпадающих ID провайдеров:

Непустой baseUrl, уже присутствующий в models.json агента, имеет приоритет.
Непустой apiKey в models.json агента имеет приоритет только тогда, когда этот провайдер не управляется SecretRef в текущем контексте конфигурации/профиля аутентификации.
Значения apiKey провайдера, управляемого SecretRef, обновляются из маркеров источника (ENV_VAR_NAME для ссылок на окружение, secretref-managed для ссылок на файл/exec) вместо сохранения разрешенных секретов.
Значения заголовков провайдера, управляемого SecretRef, обновляются из маркеров источника (secretref-env:ENV_VAR_NAME для ссылок на окружение, secretref-managed для ссылок на файл/exec).
Пустые или отсутствующие apiKey/baseUrl агента возвращаются к models.providers из конфигурации.
Остальные поля провайдера обновляются из конфигурации и нормализованных данных каталога.

Связанные материалы

Среды выполнения агентов — OpenClaw, Codex и другие среды выполнения циклов агентов
Справочник конфигурации — ключи конфигурации моделей
Генерация изображений — конфигурация модели изображений
Отказоустойчивость моделей — резервные цепочки
Провайдеры моделей — маршрутизация провайдеров и аутентификация
Генерация музыки — конфигурация модели музыки
Генерация видео — конфигурация модели видео

Was this useful?

CLI моделей

Как работает выбор модели

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

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

Отказоустойчивое переключение аутентификации провайдера

Источник выбора и поведение резервного переключения

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

Онбординг (рекомендуется)

Ключи конфигурации (обзор)

Безопасное редактирование allowlist

"Model is not allowed" (и почему ответы останавливаются)

Переключение моделей в чате (`/model`)

Команды CLI

`models list`

`models status`

Сканирование (бесплатные модели OpenRouter)

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

Связанные материалы

On this page

Molty

Как работает выбор модели

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

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

Отказоустойчивое переключение аутентификации провайдера

Источник выбора и поведение резервного переключения

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

Онбординг (рекомендуется)

Ключи конфигурации (обзор)

Безопасное редактирование allowlist

"Model is not allowed" (и почему ответы останавливаются)

Переключение моделей в чате (/model)

Команды CLI

models list

models status

Сканирование (бесплатные модели OpenRouter)

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

Связанные материалы

On this page

Переключение моделей в чате (`/model`)

`models list`

`models status`

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