---
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
---

<CardGroup cols={2}>
  <Card title="Отказоустойчивость моделей" href="/ru/concepts/model-failover">
    Ротация профилей аутентификации, периоды ожидания и их взаимодействие с резервными моделями.
  </Card>
  <Card title="Провайдеры моделей" href="/ru/concepts/model-providers">
    Краткий обзор провайдеров и примеры.
  </Card>
  <Card title="Справочник CLI по моделям" href="/ru/cli/models">
    Полный справочник по команде `openclaw models` и её флагам.
  </Card>
  <Card title="Справочник по конфигурации" href="/ru/gateway/config-agents#agent-defaults">
    Ключи конфигурации моделей, значения по умолчанию и примеры.
  </Card>
</CardGroup>

Ссылка на модель (`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).

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

<Steps>
  <Step title="Основная модель">
    `agents.defaults.model.primary` (или `agents.defaults.model` в виде простой строки).
  </Step>
  <Step title="Резервные модели">
    `agents.defaults.model.fallbacks`, проверяются по порядку.
  </Step>
  <Step title="Переключение аутентификации">
    Ротация профилей аутентификации происходит внутри провайдера до того, как OpenClaw перейдёт к следующей резервной модели.
  </Step>
</Steps>

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

- `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 <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/*`:

```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" },
      },
    },
  },
}
```

<Accordion title="Безопасное редактирование списка разрешённых моделей через CLI">
Используйте `--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.<id>.models`, если это приведёт к удалению существующих записей; используйте `--replace` только тогда, когда новое значение должно стать полным целевым значением. Интерактивная настройка провайдера и `openclaw configure --section model` уже объединяют выбор для конкретного провайдера со списком разрешённых моделей, поэтому добавление провайдера не удаляет несвязанные записи; настройка сохраняет существующий `agents.defaults.model.primary`. Явные команды, такие как `openclaw models auth login --provider <id> --set-default` и `openclaw models set <model>`, по-прежнему заменяют основную модель.
</Accordion>

## `/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 <provider/model>
openclaw models set-image <provider/model>
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).

<AccordionGroup>
  <Accordion title="Сканирование (бесплатные модели OpenRouter)">
    `openclaw models scan` проверяет публичный каталог бесплатных моделей OpenRouter и может в реальном времени тестировать кандидатов на поддержку инструментов и изображений. Сам каталог общедоступен, поэтому для сканирования только метаданных (`--no-probe`) ключ не требуется; для тестирования в реальном времени и `--set-default`/`--set-image` необходим API-ключ OpenRouter (профиль аутентификации или `OPENROUTER_API_KEY`), а без него команда безопасно ограничивается выводом только метаданных.

    Результаты ранжируются по следующим критериям: поддержка изображений, затем задержка инструментов, размер контекста и количество параметров. В TTY для протестированных результатов предлагается интерактивный выбор резервных вариантов; в неинтерактивном режиме для принятия значений по умолчанию требуется `--yes`.

  </Accordion>
</AccordionGroup>

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

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

<AccordionGroup>
  <Accordion title="Приоритет в режиме объединения">
    Для совпадающих идентификаторов провайдеров:

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

  </Accordion>
</AccordionGroup>

При сохранении маркеров источник является определяющим: при каждом повторном создании `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) — конфигурация видеомодели
