CLI моделей

Ссылка на модель (provider/model) выбирает провайдера и модель, а не низкоуровневую среду выполнения агента. Если политика среды выполнения не задана или имеет значение auto, принадлежащая провайдеру OpenAI политика маршрутизации может выбрать Codex только для точного официального HTTPS-маршрута Platform Responses или ChatGPT Responses без явно заданного переопределения запроса; один лишь префикс openai/* никогда не выбирает Codex. Адаптеры Completions, пользовательские конечные точки и явно заданное поведение запросов остаются в OpenClaw. Официальные HTTP-конечные точки с открытым текстом отклоняются. См. раздел Неявная среда выполнения агента OpenAI.

Для ссылок подписки Copilot (github-copilot/*) можно явно включить внешний плагин среды выполнения агента GitHub Copilot, но этот путь всегда выбирается явно (и никогда не выбирается через auto). Переопределения среды выполнения относятся к политике провайдера/модели, а не ко всему агенту или сеансу. Выбор среды выполнения не определяет способ оплаты: учётные данные API-ключа OpenAI и подписки ChatGPT/Codex остаются раздельными. См. Среды выполнения агентов и Среда выполнения агента GitHub Copilot.

Порядок выбора

Связанные поверхности конфигурации моделей:

• agents.defaults.models — список разрешённых моделей и каталог моделей, которые может использовать OpenClaw, а также их псевдонимы. Используйте записи provider/*, чтобы разрешить все обнаруженные модели провайдера без перечисления каждой из них.
• agents.defaults.utilityModel — необязательная менее затратная модель для коротких внутренних задач, таких как создание заголовков сеансов панели управления, заголовков веток/тем поддерживаемых каналов и описаний хода выполнения. Параметр agents.list[].utilityModel отдельного агента переопределяет её. Если параметр не задан, OpenClaw использует объявленную основным провайдером малую модель по умолчанию, если она существует (OpenAI → gpt-5.6-luna, Anthropic → claude-haiku-4-5), а иначе — основную модель агента; задайте пустую строку, чтобы отключить маршрутизацию служебных задач. Служебные задачи выполняются отдельными вызовами модели и могут отправлять ограниченное содержимое задачи выбранному провайдеру модели.
• agents.defaults.imageModel используется только тогда, когда основная модель не может принимать изображения.
• agents.defaults.pdfModel используется инструментом pdf. Если параметр не задан, инструмент сначала использует imageModel, а затем разрешённую модель сеанса или модель по умолчанию.
• agents.defaults.imageGenerationModel, musicGenerationModel и videoGenerationModel обеспечивают работу общих инструментов генерации мультимедиа. Если они не заданы, каждый инструмент определяет модель провайдера с доступной аутентификацией по умолчанию: сначала текущий провайдер по умолчанию, затем остальные зарегистрированные провайдеры этой возможности в порядке идентификаторов провайдеров. Задайте agents.defaults.mediaGenerationAutoProviderFallback: false, чтобы отключить такое определение между провайдерами, сохранив явные резервные варианты.
• Параметр agents.list[].model отдельного агента (вместе с привязками) переопределяет agents.defaults.model — см. Маршрутизация между несколькими агентами.

Полный справочник ключей, значения по умолчанию и примеры JSON5: Справочник по конфигурации.

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

Один и тот же provider/model ведёт себя по-разному в зависимости от источника:

Другие правила выбора:

• Изменение agents.defaults.model.primary не перезаписывает существующие закрепления сеансов. Если в статусе указано This session is pinned to X; config primary Y will apply to new/unpinned sessions., выполните /model default, чтобы удалить закрепление.
• Средства выбора модели по умолчанию и списка разрешённых моделей в CLI учитывают models.mode: "replace", отображая только models.providers.*.models вместо полного встроенного каталога.
• Средство выбора модели в Control UI запрашивает у Gateway настроенное представление моделей: agents.defaults.models, если оно задано (включая записи с подстановочными знаками provider/*), а иначе — models.providers.*.models и провайдеров с пригодной аутентификацией. Полный встроенный каталог предназначен для явных представлений просмотра (models.list с view: "all" или openclaw models list --all).
• Интерфейсы инвентаризации провайдеров используют models.list с view: "provider-config", чтобы отображать строки models.providers.*.models, заданные источником, без применения списков разрешённых моделей средства выбора.

Подробное описание механизма: Отказоустойчивость моделей.

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

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

Первоначальная настройка

openclaw onboard

Настраивает модель и аутентификацию для распространённых провайдеров без ручного редактирования конфигурации, включая OAuth подписки OpenAI Codex и Anthropic (API-ключ или повторное использование Claude CLI).

Если основная модель не настроена, новая настройка API-ключа OpenAI выбирает openai/gpt-5.6; простой идентификатор прямого API разрешается в уровень Sol. Новая настройка OAuth ChatGPT/Codex выбирает точную ссылку каталога openai/gpt-5.6-sol. Повторная аутентификация сохраняет существующую явно заданную основную модель, включая openai/gpt-5.5. Если GPT-5.6 недоступна для учётной записи, явно выберите openai/gpt-5.5; OpenClaw не выполняет незаметный переход на более раннюю модель.

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

Если задан agents.defaults.models, он становится списком разрешённых моделей для /model и переопределений сеанса. При выборе модели вне этого списка до создания обычного ответа возвращается:

Модель "provider/model" не разрешена. Используйте /models для вывода списка провайдеров или /models <provider> для вывода списка моделей.Добавьте её командой: openclaw config set agents.defaults.models '{"provider/model":{}}' --strict-json --merge

Исправьте это, добавив модель в agents.defaults.models, полностью очистив список разрешённых моделей (удалив ключ) или выбрав модель из /model list. Если отклонённая команда содержала переопределение среды выполнения, например /model openai/gpt-5.5 --runtime codex, сначала исправьте список разрешённых моделей, а затем повторите ту же команду /model ... --runtime ....

Для локальных моделей/GGUF список разрешённых моделей должен содержать полную ссылку с префиксом провайдера, например ollama/gemma4:26b или lmstudio/Gemma4-26b-a4-it-gguf — точную строку можно узнать через openclaw models list --provider <provider>. После включения списка разрешённых моделей одних имён файлов или отображаемых имён недостаточно.

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

{  agents: {    defaults: {      models: {        "openai/*": {},        "vllm/*": {},      },    },  },}

После этого /model, /models и средства выбора моделей отображают обнаруженный каталог только для этих провайдеров, а новые модели могут появляться без редактирования списка разрешённых моделей. Сочетайте точные записи provider/model с записями provider/*, чтобы добавить одну конкретную модель другого провайдера.

Пример списка разрешённых моделей с псевдонимами:

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

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

/model в чате

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

• /model и /model list показывают компактный нумерованный список выбора (семейство моделей + доступные провайдеры); /model <#> выбирает из него. В Discord при этом открываются раскрывающиеся списки провайдеров и моделей с шагом Submit; в Telegram выбор в списке действует только в рамках сеанса и никогда не перезаписывает постоянное значение агента по умолчанию в openclaw.json. Команда /models add устарела и вместо регистрации моделей из чата возвращает сообщение.
• /model немедленно сохраняет новый выбор для сеанса. Если агент бездействует, следующий запуск сразу использует его; если запуск уже активен, переключение ставится в очередь до следующей безопасной точки повторной попытки (или более поздней, если уже началась работа инструментов или вывод ответа).
• /model default очищает выбор для сеанса, чтобы снова наследовалась настроенная основная модель.
• Выбранная пользователем ссылка /model строго применяется в этом сеансе: если она становится недоступной, ответ завершается с явно видимой ошибкой вместо незаметного перехода по цепочке agents.defaults.model.fallbacks. Для настроенных значений по умолчанию и основных моделей заданий cron по-прежнему используются цепочки резервных вариантов.
• /model status предоставляет подробное представление: кандидаты аутентификации для каждого провайдера, а также, если настроено, конечная точка провайдера baseUrl и режим api.
• Ссылки на модели разбираются разделением по первому /; введите provider/model. Если сам идентификатор модели содержит / (в стиле OpenRouter), укажите префикс провайдера, например /model openrouter/moonshotai/kimi-k2. Если провайдер не указан, OpenClaw пытается использовать: (1) совпадение псевдонима, (2) уникальное совпадение настроенного провайдера для этого точного идентификатора модели без префикса, (3) настроенного провайдера по умолчанию (устаревший резервный вариант), а если этот провайдер больше не предоставляет настроенную модель по умолчанию — первую настроенную пару провайдер/модель, чтобы не показывать устаревшее значение по умолчанию для удалённого провайдера.
• Ссылки на модели нормализуются в нижний регистр; в остальном идентификаторы провайдеров должны совпадать точно, поэтому используйте идентификатор, объявленный плагином.

Полное описание поведения команд и конфигурации: Команды с косой чертой.

CLI

openclaw models statusopenclaw models listopenclaw models set <provider/model>openclaw models set-image <provider/model>openclaw models scanopenclaw models aliases list|add|removeopenclaw models fallbacks list|add|remove|clearopenclaw models image-fallbacks list|add|remove|clearopenclaw models auth list|add|login|paste-api-key|paste-token|setup-token|order

openclaw models без подкоманды — сокращение для models status, которая также показывает срок действия OAuth для профилей хранилища аутентификации (по умолчанию предупреждает за 24 ч). Полное описание флагов, структур JSON и подкоманд профилей аутентификации: Справочник CLI по моделям.

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

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

При сохранении маркеров источник является определяющим: при каждом повторном создании models.json, в том числе через команды наподобие openclaw agent, OpenClaw записывает маркеры из активного снимка исходной конфигурации (до разрешения), а не разрешённые значения секретов среды выполнения.

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

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