Перейти к основному содержанию

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

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

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

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

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

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 выбирает модели в таком порядке:
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 все равно может вывести резервное значение провайдера с настроенной аутентификацией. Сначала пробуется текущий провайдер по умолчанию, затем оставшиеся зарегистрированные провайдеры генерации изображений в порядке 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.

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

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

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

Если вы не хотите редактировать конфигурацию вручную, запустите онбординг: 
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)
Ссылки на модели нормализуются к нижнему регистру. Идентификаторы провайдеров в остальном точные; используйте идентификатор провайдера, объявленный plugin.Примеры конфигурации провайдеров (включая 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/*": {},
        "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 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

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

Показывает разрешенную основную модель, резервные модели, модель изображений и обзор аутентификации настроенных провайдеров. Также показывает статус истечения 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.
Выбор аутентификации зависит от провайдера/учетной записи. Для постоянно работающих хостов 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 публичен, поэтому сканирование только метаданных может перечислять бесплатных кандидатов без ключа. Пробы и инференс по-прежнему требуют API-ключ OpenRouter (из профилей аутентификации или OPENROUTER_API_KEY). Если ключ недоступен, openclaw models scan возвращается к выводу только метаданных и оставляет конфигурацию без изменений. Используйте --no-probe, чтобы явно запросить режим только метаданных.
Результаты сканирования ранжируются по:
  1. Поддержке изображений
  2. Задержке инструментов
  3. Размеру контекста
  4. Количеству параметров
Ввод:
  • Список 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 записывает маркеры из активного снимка конфигурации источника (до разрешения), а не из разрешенных значений секретов времени выполнения. Это применяется всякий раз, когда OpenClaw повторно генерирует models.json, включая пути, управляемые командами, такие как openclaw agent.

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