Концепции моделей

CLI моделей

См. /concepts/model-failover для информации о ротации профилей аутентификации, периодах охлаждения и их взаимодействии с резервными моделями. Краткий обзор провайдеров и примеры: /concepts/model-providers.

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

OpenClaw выбирает модели в следующем порядке:

Основная модель (agents.defaults.model.primary или agents.defaults.model).
Резервные модели в agents.defaults.model.fallbacks (по порядку).
Переключение при сбое аутентификации провайдера происходит внутри провайдера перед переходом к следующей модели.

Связанные настройки:

agents.defaults.models — это белый список/каталог моделей, которые может использовать OpenClaw (плюс псевдонимы).
agents.defaults.imageModel используется только тогда, когда основная модель не может принимать изображения.
Настройки по умолчанию для конкретного агента могут переопределить agents.defaults.model через agents.list[].model и привязки (см. /concepts/multi-agent).

Быстрая политика выбора моделей

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

Мастер настройки (рекомендуется)

Если вы не хотите редактировать конфигурацию вручную, запустите мастер начальной настройки:

openclaw onboard

Он может настроить модель и аутентификацию для распространённых провайдеров, включая подписку OpenAI Code (Codex) (OAuth) и Anthropic (API-ключ или claude setup-token).

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

agents.defaults.model.primary и agents.defaults.model.fallbacks
agents.defaults.imageModel.primary и agents.defaults.imageModel.fallbacks
agents.defaults.models (белый список + псевдонимы + параметры провайдера)
models.providers (пользовательские провайдеры, записанные в models.json)

Ссылки на модели нормализуются к нижнему регистру. Псевдонимы провайдеров, такие как z.ai/*, нормализуются к zai/*. Примеры конфигурации провайдеров (включая OpenCode Zen) находятся в /gateway/configuration.

“Модель не разрешена” (и почему ответы прекращаются)

Если задан agents.defaults.models, он становится белым списком для /model и для переопределений сессии. Когда пользователь выбирает модель, которой нет в этом белом списке, OpenClaw возвращает:

Model "provider/model" is not allowed. Use /model to list available models.

Это происходит до генерации обычного ответа, поэтому сообщение может показаться “неответившим”. Исправление заключается в том, чтобы:

Добавить модель в agents.defaults.models, или
Очистить белый список (удалить agents.defaults.models), или
Выбрать модель из /model list.

Пример конфигурации белого списка:

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

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

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

/model
/model list
/model 3
/model openai/gpt-5.2
/model status

Примечания:

/model (и /model list) — это компактный нумерованный выборщик (семейство моделей + доступные провайдеры).
В Discord /model и /models открывают интерактивный выборщик с выпадающими списками провайдеров и моделей, а также шаг подтверждения (Submit).
/model <#> выбирает из этого выборщика.
/model status — это подробное представление (кандидаты на аутентификацию и, при настройке, baseUrl конечной точки провайдера + режим api).
Ссылки на модели разбираются путём разделения по первому /. Используйте provider/model при вводе /model <ref>.
Если сам идентификатор модели содержит / (в стиле OpenRouter), вы должны указать префикс провайдера (пример: /model openrouter/moonshotai/kimi-k2).
Если вы опустите провайдера, OpenClaw будет рассматривать ввод как псевдоним или модель для провайдера по умолчанию (работает только тогда, когда в идентификаторе модели нет /).

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

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: полный каталог
--local: только локальные провайдеры
--provider <name>: фильтр по провайдеру
--plain: одна модель на строку
--json: машинно-читаемый вывод

models status

Показывает разрешённую основную модель, резервные модели, модель для изображений и обзор аутентификации настроенных провайдеров. Также отображает статус истечения срока действия OAuth для профилей, найденных в хранилище аутентификации (по умолчанию предупреждает за 24 часа). --plain выводит только разрешённую основную модель. Статус OAuth всегда отображается (и включается в вывод --json). Если у настроенного провайдера нет учётных данных, models status выводит раздел Missing auth. JSON включает auth.oauth (окно предупреждения + профили) и auth.providers (эффективная аутентификация на провайдера). Используйте --check для автоматизации (выход 1 при отсутствии/истечении срока, 2 при скором истечении). Выбор аутентификации зависит от провайдера/учётной записи. Для постоянно работающих шлюзов API-ключи обычно наиболее предсказуемы; также поддерживаются потоки токенов подписки. Пример (Anthropic setup-token):

claude setup-token
openclaw models status

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

openclaw models scan проверяет каталог бесплатных моделей OpenRouter и может дополнительно проверять модели на поддержку инструментов и изображений. Ключевые флаги:

--no-probe: пропустить живые проверки (только метаданные)
--min-params <b>: минимальный размер параметров (в миллиардах)
--max-age-days <days>: пропустить более старые модели
--provider <name>: фильтр по префиксу провайдера
--max-candidates <n>: размер списка резервных моделей
--set-default: установить agents.defaults.model.primary в первую выбранную модель
--set-image: установить agents.defaults.imageModel.primary в первую выбранную модель для изображений

Проверка требует API-ключа OpenRouter (из профилей аутентификации или OPENROUTER_API_KEY). Без ключа используйте --no-probe только для перечисления кандидатов. Результаты сканирования ранжируются по:

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

Входные данные

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

При запуске в TTY вы можете интерактивно выбирать резервные модели. В неинтерактивном режиме передайте --yes для принятия значений по умолчанию.

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

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

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

Этот маркерный механизм сохранения применяется всякий раз, когда OpenClaw заново генерирует models.json, включая пути, управляемые командами, такие как openclaw agent.

Быстрый старт провайдеров моделей Провайдеры моделей