---
read_when:
- Изменение поведения резервного выбора модели или интерфейса выбора
- Отладка ошибки «модель не разрешена» или устаревшего резервного перехода к провайдеру по умолчанию
- Работа над поведением слияния и секретов в models.json
sidebarTitle: Models CLI
summary: Как OpenClaw разрешает ссылки на провайдеров и модели, ключи конфигурации и команду чата `/model`
title: CLI моделей
x-i18n:
generated_at: "2026-07-13T18:05:29Z"
model: gpt-5.6
postprocess_version: locale-links-v1
prompt_version: 24
provider: openai
source_hash: 20a5e4861bdafa1f5ff549fc54968051b653611f1ef05e836df855638a7aa967
source_path: concepts/models.md
workflow: 16
---
Ротация профилей аутентификации, периоды ожидания и их взаимодействие с резервными моделями.
Краткий обзор провайдеров и примеры.
Полный справочник по команде `openclaw models` и её флагам.
Ключи конфигурации моделей, значения по умолчанию и примеры.
Ссылка на модель (`provider/model`) выбирает провайдера и модель, а не низкоуровневую
среду выполнения агента. Если политика среды выполнения не задана или имеет значение `auto`, принадлежащая провайдеру OpenAI
политика маршрутизации может выбрать Codex только для точного официального HTTPS-маршрута Platform
Responses или ChatGPT Responses без явно заданного переопределения запроса; один лишь
префикс `openai/*` никогда не выбирает Codex. Адаптеры Completions, пользовательские
конечные точки и явно заданное поведение запросов остаются в OpenClaw. Официальные
HTTP-конечные точки с открытым текстом отклоняются. См. раздел [Неявная среда выполнения агента OpenAI](/ru/providers/openai#implicit-agent-runtime).
Для ссылок подписки Copilot (`github-copilot/*`) можно явно включить внешний
плагин среды выполнения агента GitHub Copilot, но этот путь всегда выбирается явно (и никогда
не выбирается через `auto`). Переопределения среды выполнения относятся к политике провайдера/модели, а не ко
всему агенту или сеансу. Выбор среды выполнения не определяет способ оплаты:
учётные данные API-ключа OpenAI и подписки ChatGPT/Codex остаются раздельными. См.
[Среды выполнения агентов](/ru/concepts/agent-runtimes) и
[Среда выполнения агента GitHub Copilot](/ru/plugins/copilot).
## Порядок выбора
`agents.defaults.model.primary` (или `agents.defaults.model` в виде простой строки).
`agents.defaults.model.fallbacks`, проверяются по порядку.
Ротация профилей аутентификации происходит внутри провайдера до того, как OpenClaw перейдёт к следующей резервной модели.
Связанные поверхности конфигурации моделей:
- `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` — см. [Маршрутизация между несколькими агентами](/ru/concepts/multi-agent).
Полный справочник ключей, значения по умолчанию и примеры JSON5: [Справочник по конфигурации](/ru/gateway/config-agents#agent-defaults).
## Источник выбора и строгость резервного переключения
Один и тот же `provider/model` ведёт себя по-разному в зависимости от источника:
| Источник | Поведение |
| ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Настроенное значение по умолчанию (`agents.defaults.model.primary`, основная модель отдельного агента) | Обычная отправная точка; использует `agents.defaults.model.fallbacks`. |
| Автоматическое резервное переключение | Временное состояние восстановления, хранящееся как `modelOverrideSource: "auto"`. OpenClaw периодически повторно проверяет исходную основную модель, очищает автоматический выбор после восстановления и один раз при каждом изменении состояния сообщает о переходах на резервную модель и обратно. |
| Пользовательский выбор для сеанса | Точный и строгий. `/model`, средство выбора модели, `session_status(model=...)` и `sessions.patch` сохраняют `modelOverrideSource: "user"`. Если этот провайдер или модель становятся недоступны, выполнение завершается с видимой ошибкой вместо перехода к другой настроенной модели. |
| Cron `--model` / полезная нагрузка `model` | Основная модель для отдельной задачи. Настроенные резервные модели по-прежнему используются, если задача не предоставляет собственную полезную нагрузку `fallbacks` (`fallbacks: []` принудительно включает строгое выполнение). |
Другие правила выбора:
- Изменение `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`, заданные источником, без применения списков разрешённых моделей средства выбора.
Подробное описание механизма: [Отказоустойчивость моделей](/ru/concepts/model-failover).
## Краткая политика выбора моделей
- Выберите в качестве основной самую мощную доступную вам модель последнего поколения.
- Используйте резервные модели для задач, чувствительных к стоимости или задержке, и для менее критичных бесед.
- Для агентов с инструментами или недоверенными входными данными избегайте старых и менее мощных уровней моделей.
## Первоначальная настройка
```bash
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` и переопределений сеанса. При выборе модели вне этого списка до создания обычного ответа возвращается:
```text
Модель "provider/model" не разрешена. Используйте /models для вывода списка провайдеров или /models для вывода списка моделей.
Добавьте её командой: 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/*`:
```json5
{
agents: {
defaults: {
models: {
"openai/*": {},
"vllm/*": {},
},
},
},
}
```
После этого `/model`, `/models` и средства выбора моделей отображают обнаруженный каталог только для этих провайдеров, а новые модели могут появляться без редактирования списка разрешённых моделей. Сочетайте точные записи `provider/model` с записями `provider/*`, чтобы добавить одну конкретную модель другого провайдера.
Пример списка разрешённых моделей с псевдонимами:
```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" },
},
},
},
}
```
Используйте `--merge` для добавочных изменений:
```bash
openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json --merge
```
`openclaw config set` отклоняет присваивание простых объектов параметрам `agents.defaults.models`, `models.providers` или `models.providers..models`, если это приведёт к удалению существующих записей; используйте `--replace` только тогда, когда новое значение должно стать полным целевым значением. Интерактивная настройка провайдера и `openclaw configure --section model` уже объединяют выбор для конкретного провайдера со списком разрешённых моделей, поэтому добавление провайдера не удаляет несвязанные записи; настройка сохраняет существующий `agents.defaults.model.primary`. Явные команды, такие как `openclaw models auth login --provider --set-default` и `openclaw models set `, по-прежнему заменяют основную модель.
## `/model` в чате
```text
/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) настроенного провайдера по умолчанию (устаревший резервный вариант), а если этот провайдер больше не предоставляет настроенную модель по умолчанию — первую настроенную пару провайдер/модель, чтобы не показывать устаревшее значение по умолчанию для удалённого провайдера.
- Ссылки на модели нормализуются в нижний регистр; в остальном идентификаторы провайдеров должны совпадать точно, поэтому используйте идентификатор, объявленный плагином.
Полное описание поведения команд и конфигурации: [Команды с косой чертой](/ru/tools/slash-commands).
## CLI
```bash
openclaw models status
openclaw models list
openclaw models set
openclaw models set-image
openclaw models scan
openclaw models aliases list|add|remove
openclaw models fallbacks list|add|remove|clear
openclaw models image-fallbacks list|add|remove|clear
openclaw models auth list|add|login|paste-api-key|paste-token|setup-token|order
```
`openclaw models` без подкоманды — сокращение для `models status`, которая также показывает срок действия OAuth для профилей хранилища аутентификации (по умолчанию предупреждает за 24 ч). Полное описание флагов, структур JSON и подкоманд профилей аутентификации: [Справочник CLI по моделям](/ru/cli/models).
`openclaw models scan` проверяет публичный каталог бесплатных моделей OpenRouter и может в реальном времени тестировать кандидатов на поддержку инструментов и изображений. Сам каталог общедоступен, поэтому для сканирования только метаданных (`--no-probe`) ключ не требуется; для тестирования в реальном времени и `--set-default`/`--set-image` необходим API-ключ OpenRouter (профиль аутентификации или `OPENROUTER_API_KEY`), а без него команда безопасно ограничивается выводом только метаданных.
Результаты ранжируются по следующим критериям: поддержка изображений, затем задержка инструментов, размер контекста и количество параметров. В TTY для протестированных результатов предлагается интерактивный выбор резервных вариантов; в неинтерактивном режиме для принятия значений по умолчанию требуется `--yes`.
## Реестр моделей (`models.json`)
Пользовательские провайдеры, настроенные в `models.providers`, записываются в `models.json` в каталоге агента (по умолчанию `~/.openclaw/agents//agent/models.json`). Каталоги плагинов провайдеров хранятся отдельно в виде созданных фрагментов каталога, принадлежащих плагинам, и загружаются автоматически. По умолчанию этот файл объединяется с конфигурацией; задайте `models.mode: "replace"`, чтобы использовать только настроенных вами провайдеров.
Для совпадающих идентификаторов провайдеров:
- Приоритет имеет непустое значение `baseUrl`, уже присутствующее в агентском `models.json`.
- Непустое значение `apiKey` в `models.json` имеет приоритет, только если этот провайдер не управляется через SecretRef в текущем контексте конфигурации или профиля аутентификации.
- Значения `apiKey`, управляемые через SecretRef, обновляются из маркеров источника вместо сохранения разрешённых секретов: имя переменной окружения для ссылок на окружение, `secretref-managed` для ссылок на файл или исполняемую команду.
- Значения заголовков, управляемые через SecretRef, обновляются аналогично с использованием `secretref-env:ENV_VAR_NAME` для ссылок на окружение.
- Пустые или отсутствующие значения `apiKey`/`baseUrl` в `models.json` заменяются значениями `models.providers` из конфигурации.
- Остальные поля провайдера обновляются из конфигурации и нормализованных данных каталога.
При сохранении маркеров источник является определяющим: при каждом повторном создании `models.json`, в том числе через команды наподобие `openclaw agent`, OpenClaw записывает маркеры из активного снимка исходной конфигурации (до разрешения), а не разрешённые значения секретов среды выполнения.
## Связанные материалы
- [Среды выполнения агентов](/ru/concepts/agent-runtimes) — OpenClaw, Codex и другие среды выполнения циклов агентов
- [Справочник по конфигурации](/ru/gateway/config-agents#agent-defaults) — ключи конфигурации моделей
- [Генерация изображений](/ru/tools/image-generation) — конфигурация модели изображений
- [Переключение моделей при сбое](/ru/concepts/model-failover) — цепочки резервных вариантов
- [Провайдеры моделей](/ru/concepts/model-providers) — маршрутизация провайдеров и аутентификация
- [Справочник CLI по моделям](/ru/cli/models) — полный справочник по командам и флагам
- [Генерация музыки](/ru/tools/music-generation) — конфигурация музыкальной модели
- [Генерация видео](/ru/tools/video-generation) — конфигурация видеомодели