openclaw models

Обнаружение, сканирование и настройка моделей (модель по умолчанию, резервные модели, профили аутентификации).

См. также:

• Провайдеры и модели: Модели
• Основные понятия выбора модели и слеш-команда /models: Основные понятия моделей
• Настройка аутентификации провайдера: Начало работы

Основные команды

openclaw models statusopenclaw models listopenclaw models set <model-or-alias>openclaw models set-image <model-or-alias>openclaw models scan

Подкоманды status и auth принимают --agent <id> для выбора настроенного агента; list, scan, aliases, а также fallbacks/image-fallbacks всегда используют настроенного агента по умолчанию, а set/set-image безусловно отклоняют --agent. Если параметр опущен, команды с поддержкой --agent используют OPENCLAW_AGENT_DIR, если он задан, иначе — настроенного агента по умолчанию.

Состояние

openclaw models status показывает определённую модель по умолчанию, резервные модели и обзор аутентификации. Когда доступны снимки использования провайдеров, раздел состояния OAuth/API-ключей включает окна использования провайдеров и снимки квот. В настоящее время окна использования поддерживают следующие провайдеры: Anthropic, GitHub Copilot, Gemini CLI, OpenAI, MiniMax, Xiaomi и z.ai. Данные об использовании для аутентификации поступают из специализированных хуков провайдера, если они доступны; в противном случае OpenClaw использует соответствующие учётные данные OAuth/API-ключей из профилей аутентификации, переменных среды или конфигурации.

В выводе --json поле auth.providers содержит обзор провайдера с учётом переменных среды, конфигурации и хранилища, а auth.oauth — только состояние профилей в хранилище аутентификации.

Параметры:

Строки результатов проверки могут соответствовать профилям аутентификации, учётным данным из переменных среды или models.json. Категории состояния проверки: ok, auth, rate_limit, billing, timeout, format, unknown, no_model.

Коды сведений и причин, которые могут появиться, если проверка не доходит до вызова модели:

• excluded_by_auth_order: сохранённый профиль существует, но явно заданный auth.order.<provider> исключает его, поэтому вместо попытки его использования проверка сообщает об исключении.
• missing_credential, invalid_expires, expired, unresolved_ref: профиль существует, но не подходит или не может быть разрешён.
• ineligible_profile: профиль несовместим с конфигурацией провайдера по иной причине.
• no_model: аутентификация провайдера существует, но OpenClaw не удалось определить подходящую для проверки модель этого провайдера.

При устранении неполадок OAuth для OpenAI ChatGPT/Codex параметры openclaw models status, openclaw models auth list --provider openai и openclaw config get agents.defaults.model --json позволяют быстрее всего проверить, есть ли у агента пригодный профиль OAuth openai для openai/*, используемый через нативную среду выполнения Codex. См. Настройка провайдера OpenAI.

Список

openclaw models list работает только на чтение: команда читает конфигурацию, профили аутентификации, текущее состояние каталога и принадлежащие провайдерам строки каталога, но никогда не перезаписывает models.json.

Параметры: --all (полный каталог), --local (только локальные модели), --provider <id>, --json, --plain.

Примечания:

• Столбец Auth доступен только для чтения. Для принадлежащих провайдерам маршрутов моделей, например OpenAI, он сопоставляет маршрут API/базового URL каждой строки с подходящими профилями в действующей конфигурации auth.order, учётными данными из переменных среды или конфигурации и разрешёнными SecretRef в области текущей команды. Состояние конкретной строки OpenAI остаётся неизвестным, если политика её маршрута недоступна, вместо использования аутентификации на уровне провайдера; устаревшие проверки только на уровне провайдера и проверки других провайдеров сохраняют поведение на уровне провайдера. Метаданные синтетической аутентификации плагина лишь указывают на возможность среды выполнения, но не доказывают нативную аутентификацию учётной записи, поэтому состояние маршрутов, зависящих от учётной записи, остаётся неизвестным без положительных данных реестра. Команда не загружает среду выполнения провайдера, не читает секреты из связки ключей, не вызывает API провайдера и не подтверждает точную готовность к выполнению.
• models list --all --provider <id> может включать принадлежащие провайдерам статические строки каталога из манифестов плагинов или встроенных метаданных каталога провайдера, даже если вы ещё не прошли аутентификацию у этого провайдера. Эти строки всё равно отображаются как недоступные, пока не настроена соответствующая аутентификация.
• models list сохраняет отзывчивость плоскости управления, когда обнаружение каталога провайдера выполняется медленно. После короткого ожидания представления по умолчанию и настроенные представления используют настроенные или синтетические строки моделей и позволяют обнаружению завершиться в фоновом режиме. Используйте --all, если вам нужен точный полный обнаруженный каталог и вы готовы дождаться завершения обнаружения провайдера.
• Общий models list --all накладывает строки каталога манифеста поверх строк реестра без загрузки дополнительных хуков среды выполнения провайдера. Быстрые пути манифеста с фильтрацией по провайдеру используются только для провайдеров с отметкой static; провайдеры с отметкой refreshable по-прежнему используют реестр или кеш и добавляют строки манифеста как дополнение, а провайдеры с отметкой runtime продолжают использовать обнаружение через реестр или среду выполнения.
• models list разделяет нативные метаданные модели и ограничения среды выполнения. В табличном выводе Ctx показывает contextTokens/contextWindow, когда действующее ограничение среды выполнения отличается от нативного окна контекста; строки JSON включают contextTokens, если провайдер предоставляет это ограничение.
• Для принадлежащих провайдерам маршрутов models list проецирует одну логическую строку провайдера/модели на выбранный маршрут. Input и Ctx берутся только из строки каталога, точно соответствующей физическому маршруту, а явные настроенные логические переопределения применяются последними; если маршрут не удалось выбрать, поля возможностей отображаются как неизвестные вместо заимствования метаданных соседнего маршрута.
• models list --provider <id> фильтрует по идентификатору провайдера, например moonshot или openai. Параметр не принимает отображаемые названия из интерактивных средств выбора провайдера, например Moonshot AI.
• Ссылки на модели анализируются разделением по первому /. Если идентификатор модели содержит / (как в OpenRouter), укажите префикс провайдера (пример: openrouter/moonshotai/kimi-k2).
• Если провайдер не указан, OpenClaw сначала пытается разрешить введённое значение как псевдоним, затем как уникальное совпадение точного идентификатора модели среди настроенных провайдеров и только после этого использует настроенного провайдера по умолчанию, выводя предупреждение об устаревшем поведении. Если этот провайдер больше не предоставляет настроенную модель по умолчанию, OpenClaw использует первую настроенную пару провайдера и модели вместо ошибки из-за устаревшей модели по умолчанию от удалённого провайдера.
• models status может показывать marker(<value>) в выводе аутентификации для несекретных заполнителей (например, OPENAI_API_KEY, secretref-managed, minimax-oauth, oauth:chutes, ollama-local) вместо их маскирования как секретов.

Выбор модели по умолчанию или модели изображений

openclaw models set <model-or-alias>openclaw models set-image <model-or-alias>

set записывает agents.defaults.model.primary; set-image записывает agents.defaults.imageModel.primary. Обе команды принимают provider/model или настроенный псевдоним. set также восстанавливает установленные плагины среды выполнения Codex/Copilot, если они необходимы для новой выбранной модели; set-image этого не делает. Ни одна из команд не принимает --agent; они всегда записывают значения по умолчанию для агента.

Сканирование

models scan читает общедоступный каталог :free OpenRouter и ранжирует кандидатов для резервного использования. Сам каталог общедоступен, поэтому для сканирования только метаданных ключ OpenRouter не требуется.

По умолчанию OpenClaw пытается проверить поддержку инструментов и изображений с помощью реальных вызовов моделей. Если ключ OpenRouter не настроен, команда возвращает вывод только на основе метаданных и поясняет, что для проверки и инференса моделей :free по-прежнему требуется OPENROUTER_API_KEY.

Параметры:

• --no-probe (только метаданные; без чтения конфигурации и секретов)
• --min-params <b>
• --max-age-days <days>
• --provider <name>
• --max-candidates <n>
• --timeout <ms> (время ожидания запроса к каталогу и каждой проверки)
• --concurrency <n>
• --yes
• --no-input
• --set-default
• --set-image
• --json

--set-default и --set-image требуют реальных проверок; результаты сканирования только метаданных носят информационный характер и не применяются к конфигурации.

Псевдонимы

openclaw models aliases list [--json] [--plain]openclaw models aliases add <alias> <model-or-alias>openclaw models aliases remove <alias>

Псевдонимы хранятся отдельно для каждой записи модели в виде agents.defaults.models.<key>.alias. add сначала разрешает <model-or-alias> в канонический ключ провайдера/модели, поэтому создание псевдонима для другого псевдонима перенаправляет его, а не создаёт цепочку.

Резервные модели

openclaw models fallbacks list [--json] [--plain]openclaw models fallbacks add <model-or-alias>openclaw models fallbacks remove <model-or-alias>openclaw models fallbacks clear

Управляет agents.defaults.model.fallbacks. openclaw models image-fallbacks list|add|remove|clear управляет параллельным списком agents.defaults.imageModel.fallbacks с таким же набором подкоманд.

Профили аутентификации

openclaw models auth addopenclaw models auth list [--provider <id>] [--json]openclaw models auth login --provider <id>openclaw models auth login --provider openai --profile-id openai:workopenclaw models auth login-github-copilotopenclaw models auth paste-api-key --provider <id>openclaw models auth setup-token --provider <id>openclaw models auth paste-token --provider <id>openclaw models auth order get --provider <id>openclaw models auth order set --provider <id> <profileIds...>openclaw models auth order clear --provider <id>

models auth add — интерактивный помощник по аутентификации. В зависимости от выбранного провайдера он может запустить процедуру аутентификации провайдера (OAuth/API-ключ) или помочь вручную вставить токен.

models auth list выводит список сохранённых профилей аутентификации для выбранного агента, не отображая токены, ключи API или секретные данные OAuth. Используйте --provider <id>, чтобы отфильтровать результаты по одному провайдеру, например openai, а --json — для использования в скриптах.

models auth login запускает процесс аутентификации плагина провайдера (OAuth/ключ API). Используйте openclaw plugins list, чтобы узнать, какие провайдеры установлены. login принимает --profile-id <id> для провайдеров, поддерживающих именованные профили при входе (используйте это, чтобы хранить отдельно несколько сеансов входа для одного провайдера), --method <id> — для выбора конкретного метода аутентификации, --device-code — как сокращение для --method device-code, --set-default — для применения рекомендуемой провайдером модели по умолчанию, а --force — чтобы сначала удалить существующие профили этого провайдера (используйте, если кэшированный профиль OAuth завис или требуется сменить учётную запись).

models auth login-github-copilot — сокращение для models auth login --provider github-copilot --method device (поток авторизации GitHub на устройстве); команда принимает --yes, чтобы перезаписать существующий профиль без запроса подтверждения.

Используйте openclaw models auth --agent <id> <subcommand>, чтобы записать результаты аутентификации в хранилище конкретного настроенного агента. Родительский флаг --agent учитывается командами add, list, login, paste-api-key, setup-token, paste-token, login-github-copilot, а также order get/set/clear.

Для моделей OpenAI команда --provider openai по умолчанию использует вход через учётную запись ChatGPT/Codex. Используйте --method api-key только для добавления профиля OpenAI с ключом API — обычно в качестве резервного варианта на случай ограничений подписки Codex. Выполните openclaw doctor --fix, чтобы перенести устаревшее состояние аутентификации и профилей со старым префиксом OpenAI Codex в openai.

Примеры:

openclaw models auth login --provider openai --set-defaultopenclaw models auth login --provider openai --method api-keyopenclaw models auth paste-api-key --provider openaiopenclaw models auth list --provider openai

Примечания:

• paste-api-key принимает ключи API, созданные в другом месте, запрашивает значение ключа и записывает его в профиль с идентификатором по умолчанию <provider>:manual, если не передан --profile-id. При автоматизации передавайте ключ через стандартный ввод, например printf "%s\n" "$OPENAI_API_KEY" | openclaw models auth paste-api-key --provider openai.
• setup-token и paste-token остаются универсальными командами для работы с токенами у провайдеров, предоставляющих методы аутентификации по токену.
• setup-token требует интерактивный TTY и запускает метод токенной аутентификации провайдера (по умолчанию используется метод setup-token этого провайдера, если он доступен).
• paste-token требует --provider, по умолчанию запрашивает значение токена и записывает его в профиль с идентификатором по умолчанию <provider>:manual, если не передан --profile-id. При автоматизации передавайте токен через стандартный ввод, а не как аргумент, чтобы учётные данные провайдера не появлялись в истории команд оболочки или списках процессов.
• paste-token --expires-in <duration> сохраняет абсолютный срок действия токена, вычисленный из относительной длительности, например 365d или 12h.
• Для openai ключи API OpenAI и данные токенов ChatGPT/OAuth имеют разные форматы аутентификации. Используйте paste-api-key для ключей API OpenAI sk-..., а paste-token — только для данных токенной аутентификации.
• Anthropic: setup-token/paste-token поддерживаются OpenClaw как способы аутентификации для anthropic, однако при наличии Claude CLI (claude -p) на хосте OpenClaw предпочитает использовать его повторно.
• auth order get/set/clear управляет переопределением порядка профилей аутентификации одного провайдера для конкретного агента; оно хранится в auth-state.json (отдельно от ключа конфигурации auth.order.<provider>). set принимает один или несколько идентификаторов профилей в порядке приоритета; clear возвращает порядок из конфигурации или циклического перебора.

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

• Справочник CLI
• Выбор модели
• Переключение на резервную модель