---
read_when:
- Добавление или изменение CLI для моделей (models list/set/scan/aliases/fallbacks)
- Изменение поведения резервного выбора модели или UX выбора модели
- Обновление проб сканирования моделей (инструменты/изображения)
sidebarTitle: Models CLI
summary: 'CLI моделей: список, установка, псевдонимы, резервные варианты, сканирование, статус'
title: CLI моделей
x-i18n:
generated_at: "2026-06-28T22:51:09Z"
model: gpt-5.5
postprocess_version: locale-links-v1
provider: openai
source_hash: 8c7d4cbe1e0854a281f57f39dac9ac5f54c65f50da08cf37dfd298f8f1dd5536
source_path: concepts/models.md
workflow: 16
---
Ротация профилей аутентификации, периоды охлаждения и их взаимодействие с резервными вариантами.
Краткий обзор провайдеров и примеры.
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`. См. [Среды выполнения агентов](/ru/concepts/agent-runtimes) и [Среда выполнения агента GitHub Copilot](/ru/plugins/copilot).
## Как работает выбор модели
OpenClaw выбирает модели в таком порядке:
`agents.defaults.model.primary` (или `agents.defaults.model`).
`agents.defaults.model.fallbacks` (по порядку).
Отказоустойчивое переключение аутентификации происходит внутри провайдера перед переходом к следующей модели.
- `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` плюс привязки (см. [Маршрутизация нескольких агентов](/ru/concepts/multi-agent)).
## Источник выбора и поведение резервного переключения
Одна и та же ссылка `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`.
## Краткая политика моделей
- Задайте в качестве основной самую сильную модель последнего поколения, доступную вам.
- Используйте резервные варианты для задач, чувствительных к стоимости/задержке, и для чата с низкими рисками.
- Для агентов с включенными инструментами или недоверенных входных данных избегайте старых/более слабых уровней моделей.
## Онбординг (рекомендуется)
Если вы не хотите редактировать конфигурацию вручную, запустите онбординг:
```bash
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](/ru/providers/opencode).
### Безопасное редактирование allowlist
Используйте добавляющие записи при ручном обновлении `agents.defaults.models`:
```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` отклоняется, если оно удалило бы существующие записи. Используйте `--merge` для добавляющих изменений; используйте `--replace` только когда переданное значение должно стать полным целевым значением.
Интерактивная настройка провайдера и `openclaw configure --section model` также объединяют выборы в области провайдера с существующим allowlist, поэтому добавление Codex, Ollama или другого провайдера не удаляет несвязанные записи моделей. Configure сохраняет существующий `agents.defaults.model.primary`, когда аутентификация провайдера применяется повторно. Явные команды установки значения по умолчанию, такие как `openclaw models auth login --provider --set-default` и `openclaw models set `, все равно заменяют `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 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 `.
Одних локальных имен файлов или отображаемых имен недостаточно, когда allowlist
активен.
Если вы хотите ограничить провайдеров без ручного перечисления каждой модели, добавьте
записи `provider/*` в `agents.defaults.models`:
```json5
{
agents: {
defaults: {
models: {
"openai/*": {},
"vllm/*": {},
},
},
},
}
```
При такой политике `/model`, `/models` и средства выбора моделей показывают обнаруженный
каталог только для этих провайдеров. Новые модели от выбранных провайдеров могут
появляться без редактирования allowlist. Точные записи `provider/model` можно смешивать
с записями `provider/*`, когда вам нужна одна конкретная модель от другого провайдера.
Пример конфигурации allowlist:
```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" },
},
},
},
}
```
## Переключение моделей в чате (`/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 [`.
- Если сам ID модели содержит `/` (в стиле OpenRouter), необходимо указать префикс провайдера (пример: `/model openrouter/moonshotai/kimi-k2`).
- Если провайдер не указан, OpenClaw разрешает ввод в таком порядке:
1. совпадение с псевдонимом
2. уникальное совпадение настроенного провайдера для точного ID модели без префикса
3. устаревший fallback к настроенному провайдеру по умолчанию — если этот провайдер больше не предоставляет настроенную модель по умолчанию, OpenClaw вместо этого возвращается к первому настроенному провайдеру/модели, чтобы не показывать устаревшее значение по умолчанию для удаленного провайдера.
]
Полное поведение команд/конфигурация: [Слэш-команды](/ru/tools/slash-commands).
## Команды CLI
```bash
openclaw models list
openclaw models status
openclaw models set
openclaw models set-image
openclaw models aliases list
openclaw models aliases add
openclaw models aliases remove
openclaw models fallbacks list
openclaw models fallbacks add
openclaw models fallbacks remove
openclaw models fallbacks clear
openclaw models image-fallbacks list
openclaw models image-fallbacks add
openclaw models image-fallbacks remove
openclaw models image-fallbacks clear
```
`openclaw models` (без подкоманды) — это сокращение для `models status`.
### `models list`
По умолчанию показывает настроенные/доступные по аутентификации модели. Полезные флаги:
Полный каталог. Включает встроенные статические строки каталога, принадлежащие провайдерам, до настройки аутентификации, поэтому представления только для обнаружения могут показывать модели, недоступные до добавления соответствующих учетных данных провайдера.
Только локальные провайдеры.
Фильтр по ID провайдера, например `moonshot`. Отображаемые метки из интерактивных средств выбора не принимаются.
Одна модель на строку.
Машиночитаемый вывод.
### `models status`
Показывает разрешенную основную модель, резервные модели, модель изображений и обзор аутентификации настроенных провайдеров. Также показывает статус истечения OAuth для профилей, найденных в хранилище аутентификации (по умолчанию предупреждает за 24 ч). `--plain` печатает только разрешенную основную модель.
- Статус OAuth отображается всегда (и включается в вывод `--json`). Если у настроенного провайдера нет учетных данных, `models status` печатает раздел **Отсутствует аутентификация**.
- JSON включает `auth.oauth` (окно предупреждения + профили) и `auth.providers` (эффективная аутентификация по провайдерам, включая учетные данные из окружения). `auth.oauth` отражает только состояние профилей в хранилище аутентификации; провайдеры только из окружения там не отображаются.
- Используйте `--check` для автоматизации (код выхода `1` при отсутствии/истечении, `2` при скором истечении).
- Используйте `--probe` для живых проверок аутентификации; строки проб могут поступать из профилей аутентификации, учетных данных окружения или `models.json`.
- Если явный `auth.order.` пропускает сохраненный профиль, проба сообщает `excluded_by_auth_order` вместо попытки использовать его. Если аутентификация есть, но для этого провайдера нельзя разрешить модель, пригодную для пробы, проба сообщает `status: no_model`.
Выбор аутентификации зависит от провайдера/учетной записи. Для постоянно работающих хостов Gateway ключи API обычно наиболее предсказуемы; повторное использование Claude CLI и существующие профили Anthropic OAuth/токенов также поддерживаются.
Пример (Claude CLI):
```bash
claude auth login
openclaw models status
```
## Сканирование (бесплатные модели OpenRouter)
`openclaw models scan` проверяет **каталог бесплатных моделей** OpenRouter и при необходимости может выполнять пробы моделей на поддержку инструментов и изображений.
Пропустить живые пробы (только метаданные).
Минимальный размер параметров (в миллиардах).
Пропускать более старые модели.
Фильтр по префиксу провайдера.
Размер списка fallback.
Установить `agents.defaults.model.primary` в первый выбранный вариант.
Установить `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` (см. [Переменные окружения](/ru/help/environment))
- Необязательные фильтры: `--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//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`.
## Связанные материалы
- [Среды выполнения агентов](/ru/concepts/agent-runtimes) — OpenClaw, Codex и другие среды выполнения циклов агентов
- [Справочник конфигурации](/ru/gateway/config-agents#agent-defaults) — ключи конфигурации моделей
- [Генерация изображений](/ru/tools/image-generation) — конфигурация модели изображений
- [Отказоустойчивость моделей](/ru/concepts/model-failover) — резервные цепочки
- [Провайдеры моделей](/ru/concepts/model-providers) — маршрутизация провайдеров и аутентификация
- [Генерация музыки](/ru/tools/music-generation) — конфигурация модели музыки
- [Генерация видео](/ru/tools/video-generation) — конфигурация модели видео