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 залишається невідомим, якщо політика його маршруту недоступна, замість використання автентифікації на рівні провайдера; застарілі перевірки лише на рівні провайдера та інші провайдери зберігають поведінку на рівні провайдера. Метадані синтетичної автентифікації Plugin є лише підказкою щодо можливостей середовища виконання, а не доказом нативної автентифікації облікового запису, тому стан маршрутів, що залежать від облікового запису, залишається невідомим без позитивного підтвердження з реєстру. Команда не завантажує середовище виконання провайдера, не читає секрети зі сховища ключів, не викликає API провайдера й не підтверджує точну готовність до виконання.
• models list --all --provider <id> може містити статичні рядки каталогу, якими керують провайдери, із маніфестів Plugin або вбудованих метаданих каталогу провайдера, навіть якщо автентифікацію для цього провайдера ще не виконано. Ці рядки й надалі відображаються як недоступні, доки не буде налаштовано відповідну автентифікацію.
• 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 також відновлює встановлення Plugin середовища виконання 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 запускає потік автентифікації Plugin провайдера (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 лише тоді, коли потрібно додати профіль API-ключа OpenAI, зазвичай як резервний варіант на випадок обмежень передплати 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, але OpenClaw надає перевагу повторному використанню Claude CLI (claude -p) на хості, коли він доступний.
• auth order get/set/clear керує перевизначенням порядку профілів автентифікації одного провайдера для кожного агента, що зберігається в auth-state.json (окремо від ключа конфігурації auth.order.<provider>). set приймає один або кілька ідентифікаторів профілів у порядку пріоритету; clear повертається до порядку з конфігурації або циклічного перебору.

Пов’язане

• Довідник CLI
• Вибір моделі
• Перемикання на резервну модель