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

Она задаётся с помощью:

agents.defaults.model.primary

Модели указываются как ссылки provider/model (например, openai/gpt-5.5, anthropic/claude-sonnet-4-6). Всегда указывайте provider/model явно. Если провайдер не указан, OpenClaw сначала пытается найти совпадение по псевдониму, затем — единственное совпадение идентификатора модели среди настроенных провайдеров, после чего использует настроенного провайдера по умолчанию (устаревший путь совместимости). Если у этого провайдера больше нет настроенной модели по умолчанию, OpenClaw вместо устаревшего значения по умолчанию использует первую настроенную пару «провайдер/модель».

Используйте наиболее мощную модель последнего поколения, доступную в вашем наборе провайдеров, особенно для агентов с доступом к инструментам или недоверенными входными данными: более слабые или чрезмерно квантованные модели уязвимее для инъекций в промпты и небезопасного поведения (см. раздел «Безопасность»). Направляйте рутинные диалоги с низкими рисками на более дешёвые модели в зависимости от роли агента.

Назначайте модели каждому агенту отдельно и используйте субагентов для параллельного выполнения длительных задач (каждый субагент расходует собственные токены). См. разделы «Модели», «Субагенты», MiniMax и «Локальные модели».

Изменяйте только поля модели — избегайте полной замены конфигурации.

• /model в чате (для отдельного сеанса; см. «Команды с косой чертой»)
• openclaw models set ... (обновляет только конфигурацию модели)
• openclaw configure --section model (интерактивный режим)
• измените agents.defaults.model непосредственно в ~/.openclaw/openclaw.json

При изменении через RPC сначала проверьте данные с помощью config.schema.lookup (нормализованный путь, краткая документация схемы и сводки дочерних элементов), затем предпочитайте config.patch вместо config.apply с частичным объектом. Если вы всё же перезаписали конфигурацию, восстановите её из резервной копии или выполните openclaw doctor для исправления.

Документация: «Модели», «Настройка», «Конфигурация», Doctor.

Да — проще всего использовать Ollama. Быстрая настройка:

1. Установите Ollama с https://ollama.com/download
2. Загрузите локальную модель, например ollama pull gemma4
3. Чтобы также использовать облачные модели, выполните ollama signin
4. Выполните openclaw onboard, выберите Ollama, затем Local или Cloud + Local

Cloud + Local предоставляет доступ как к облачным, так и к локальным моделям Ollama; облачные модели, такие как kimi-k2.5:cloud, не требуют локальной загрузки. Для ручного переключения выполните openclaw models list, затем openclaw models set ollama/<model>.

Небольшие или сильно квантованные модели уязвимее для инъекций в промпты. Используйте крупные модели для всех ботов с доступом к инструментам; если вы всё же используете небольшие модели, включите изоляцию в песочнице и строгие списки разрешённых инструментов.

Документация: Ollama, «Локальные модели», «Провайдеры моделей», «Безопасность», «Изоляция в песочнице».

Отправьте /model <name> отдельным сообщением. Полный список команд, включая нумерованный выбор (/model, /model list, /model 3), команду /model default для сброса переопределения сеанса и /model status для просмотра сведений о конечной точке и режиме API, см. в разделе «Команды с косой чертой».

Чтобы принудительно использовать определённый профиль аутентификации в текущем сеансе, укажите @profile:

/model opus@anthropic:default/model opus@anthropic:work

Чтобы открепить профиль, заданный с помощью @profile, повторно выполните /model без суффикса (например, /model anthropic/claude-opus-4-6) или выберите профиль по умолчанию в /model. Используйте /model status, чтобы проверить активный профиль аутентификации.

/model provider/model выбирает маршрут именно этого провайдера. Например, qianfan/deepseek-v4-flash и deepseek/deepseek-v4-flash — разные ссылки, даже если идентификаторы моделей совпадают: OpenClaw не переключает провайдеров неявно при совпадении только идентификатора.

Выбранная пользователем ссылка /model строго ограничивает резервное переключение: если эта пара «провайдер/модель» становится недоступной, ответ завершается явной ошибкой вместо переключения на agents.defaults.model.fallbacks. Настроенные цепочки резервного переключения по-прежнему применяются к настроенным значениям по умолчанию, основным моделям заданий Cron и автоматически выбранному резервному состоянию. Когда запуск без переопределения сеанса может использовать резервное переключение, OpenClaw сначала пробует запрошенную пару «провайдер/модель», затем настроенные резервные варианты и после этого настроенную основную модель, поэтому одинаковые идентификаторы моделей без провайдера никогда не приводят к немедленному возврату к провайдеру по умолчанию.

См. разделы «Модели» и «Резервное переключение моделей».

Да — выбор модели и выбор среды выполнения независимы:

• Нативный агент Codex для программирования: задайте для agents.defaults.model.primary значение openai/gpt-5.5. Выполните вход с помощью openclaw models auth login --provider openai для аутентификации по подписке ChatGPT/Codex.
• Прямые задачи OpenAI API вне цикла агента: настройте OPENAI_API_KEY для изображений, векторных представлений, речи, взаимодействия в реальном времени и других возможностей OpenAI API вне агента.
• Аутентификация агента OpenAI по ключу API: /model openai/gpt-5.5 с упорядоченным профилем ключа API openai.
• Субагенты: направляйте задачи программирования агенту, ориентированному на Codex, с его собственной моделью openai/gpt-5.5.

См. разделы «Модели» и «Команды с косой чертой».

• Для отдельного сеанса: отправьте /fast on при использовании openai/gpt-5.5.
• Значение по умолчанию для модели: задайте для agents.defaults.models["openai/gpt-5.5"].params.fastMode значение true.
• Автоматическое пороговое время: /fast auto или params.fastMode: "auto" выполняет новые вызовы модели в быстром режиме до достижения порогового времени, а последующие повторные попытки, резервные вызовы, вызовы после результатов инструментов или продолжения — без быстрого режима. По умолчанию пороговое время составляет 60 секунд; его можно переопределить для модели с помощью params.fastAutoOnSeconds.

{  agents: {    defaults: {      models: {        "openai/gpt-5.5": {          params: {            fastMode: "auto",            fastAutoOnSeconds: 30,          },        },      },    },  },}

Быстрый режим соответствует service_tier = "priority" в нативных запросах OpenAI Responses; существующие значения service_tier сохраняются, а быстрый режим не изменяет reasoning и text.verbosity. Переопределения сеанса /fast имеют приоритет над значениями конфигурации по умолчанию.

См. раздел «Рассуждение и быстрый режим», а также раздел о быстром режиме в расширенной конфигурации на странице провайдера OpenAI.

Если задано agents.defaults.models, оно становится списком разрешённых значений для /model и переопределений сеанса. При выборе модели вне этого списка вместо обычного ответа возвращается следующее:

Модель "provider/model" не разрешена. Используйте /models для вывода списка провайдеров или /models <provider> для вывода списка моделей.Добавьте её с помощью: openclaw config set agents.defaults.models '{"provider/model":{}}' --strict-json --merge

Исправление: добавьте точную модель в agents.defaults.models, добавьте шаблон провайдера, например "provider/*": {}, для динамических каталогов, удалите список разрешённых значений или выберите модель из /model list. Если команда также содержала --runtime codex, сначала обновите список разрешённых значений, затем повторите ту же команду /model provider/model --runtime codex.

Если вы используете старый выпуск OpenClaw, сначала обновите его (либо запустите из исходного кода main) и перезапустите Gateway — MiniMax-M3 может ещё отсутствовать в каталоге установленного выпуска. В противном случае провайдер MiniMax не настроен (не найдена запись провайдера или профиль аутентификации), поэтому модель невозможно разрешить. Полный список действий для исправления, таблицу идентификаторов провайдеров и моделей и пример блока конфигурации см. в разделе устранения неполадок на странице провайдера MiniMax.

Да. Используйте MiniMax по умолчанию и переключайте модели для отдельных сеансов — резервные варианты предназначены для ошибок, а не для «сложных задач», поэтому используйте /model или отдельного агента.

Вариант A: переключение для отдельного сеанса

{  env: { MINIMAX_API_KEY: "sk-...", OPENAI_API_KEY: "sk-..." },  agents: {    defaults: {      model: { primary: "minimax/MiniMax-M3" },      models: {        "minimax/MiniMax-M3": { alias: "minimax" },        "openai/gpt-5.5": { alias: "gpt" },      },    },  },}

Затем /model gpt.

Вариант B: отдельные агенты — агент A по умолчанию использует MiniMax, агент B по умолчанию использует OpenAI; направляйте задачи нужному агенту или используйте /agent для переключения.

Документация: «Модели», «Маршрутизация между несколькими агентами», MiniMax, OpenAI.

Да — это встроенные сокращения, которые применяются, только если целевая модель существует в agents.defaults.models:

Пользовательский псевдоним с таким же именем переопределяет встроенный.

Псевдонимы задаются в agents.defaults.models.<modelId>.alias:

{  agents: {    defaults: {      model: { primary: "anthropic/claude-opus-4-6" },      models: {        "anthropic/claude-opus-4-6": { alias: "opus" },        "anthropic/claude-sonnet-4-6": { alias: "sonnet" },      },    },  },}

После этого /model sonnet (или /<alias>, если поддерживается) разрешается в этот идентификатор модели.

OpenRouter (оплата за токены; множество моделей):

{  agents: {    defaults: {      model: { primary: "openrouter/anthropic/claude-sonnet-4-6" },      models: { "openrouter/anthropic/claude-sonnet-4-6": {} },    },  },  env: { OPENROUTER_API_KEY: "sk-or-..." },}

Z.AI (модели GLM):

{  agents: {    defaults: {      model: { primary: "zai/glm-5.1" },      models: { "zai/glm-5.1": {} },    },  },  env: { ZAI_API_KEY: "..." },}

Отсутствие ключа провайдера для указанной пары «провайдер/модель» вызывает во время выполнения ошибку аутентификации (например, No API key found for provider "zai").

После добавления нового агента не найден ключ API провайдера

У нового агента хранилище данных аутентификации пусто — данные аутентификации относятся к отдельному агенту и хранятся по адресу:

~/.openclaw/agents/<agentId>/agent/auth-profiles.json

Решение: запустите openclaw agents add <id> и настройте аутентификацию в мастере либо скопируйте из хранилища основного агента только переносимые статические профили api_key/token. Для OAuth войдите в систему из нового агента, когда ему потребуется собственная учётная запись. Полные правила повторного использования agentDir и совместного использования учётных данных см. в разделе Маршрутизация нескольких агентов — никогда не используйте agentDir повторно для разных агентов.

Два этапа:

1. Ротация профилей аутентификации в рамках одного провайдера.
2. Переход на резервную модель — следующую модель в agents.defaults.model.fallbacks.

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

Категория ограничений частоты охватывает не только обычный 429: Too many concurrent requests, ThrottlingException, concurrency limit reached, workers_ai ... quota limit exceeded, resource exhausted и периодические ограничения окна использования (weekly/monthly limit reached) также считаются ограничениями частоты, требующими переключения при сбое.

Ответы, связанные с оплатой, не всегда имеют статус 402, а некоторые 402 остаются в категории временных сбоев или ограничений частоты, а не переходят в категорию оплаты. Явный текст об оплате в 401/403 всё же может быть отнесён к категории оплаты; сопоставления текста, специфичные для провайдера (например, Key limit exceeded OpenRouter), применяются только к соответствующему провайдеру. 402, похожий на повторяемое ограничение окна использования или расходов организации/рабочего пространства (daily limit reached, resets tomorrow, organization spending limit exceeded), обрабатывается как rate_limit, а не как длительное отключение из-за оплаты.

Ошибки переполнения контекста полностью исключаются из пути перехода на резервную модель: сигнатуры вроде request_too_large, input exceeds the maximum number of tokens, input token count exceeds the maximum number of input tokens, input is too long for the model или ollama error: context length exceeded приводят к Compaction и повторной попытке, а не к переходу на следующую резервную модель.

Универсальное распознавание текста серверной ошибки уже, чем «всё, что содержит unknown/error». К специфичным для провайдера временным формам, которые считаются сигналами для переключения при сбое, относятся: отдельный An unknown error occurred Anthropic, отдельный Provider returned error OpenRouter, ошибки причины остановки вроде Unhandled stop reason: error, полезные нагрузки JSON api_error с текстом временной серверной ошибки (internal server error, unknown error, 520, upstream error, backend error) и ошибки занятости провайдера вроде ModelNotReadyException, если контекст провайдера совпадает. Универсальный внутренний текст резервного перехода вроде LLM request failed with an unknown error. обрабатывается консервативно и сам по себе не запускает переключение.

У профиля аутентификации с идентификатором anthropic:default отсутствуют учётные данные в ожидаемом хранилище аутентификации.

Порядок устранения:

• Проверьте расположение профилей: текущее — ~/.openclaw/agents/<agentId>/agent/auth-profiles.json; устаревшее — ~/.openclaw/agent/* (мигрирует с помощью openclaw doctor).
• Убедитесь, что Gateway загружает вашу переменную окружения. Значение ANTHROPIC_API_KEY, заданное только в оболочке, не попадёт в Gateway, запущенный через systemd/launchd, — поместите его в ~/.openclaw/.env или включите env.shellEnv.
• Убедитесь, что редактируете нужного агента: в конфигурациях с несколькими агентами имеется несколько файлов auth-profiles.json.
• Запустите openclaw models status, чтобы просмотреть настроенные модели и состояние аутентификации провайдера.

Для «No credentials found for profile anthropic» (без суффикса электронной почты):

Выполнение закреплено за профилем Anthropic, который Gateway не может найти.

• Используйте Claude CLI: запустите openclaw models auth login --provider anthropic --method cli --set-default на узле Gateway.

• Если предпочитаете ключ API: поместите ANTHROPIC_API_KEY в ~/.openclaw/.env на узле Gateway, затем сбросьте закреплённый порядок, принудительно использующий отсутствующий профиль:

  openclaw models auth order clear --provider anthropic

• Удалённый режим: профили аутентификации находятся на машине Gateway, а не на вашем ноутбуке, — убедитесь, что выполняете команды там.

Если конфигурация моделей содержит Google Gemini как резервный вариант (или вы переключились на сокращённое имя Gemini), OpenClaw пробует его при переключении после сбоя. При отсутствии настроенных учётных данных Google возникает No API key found for provider "google". Решение: добавьте аутентификацию Google или удалите модели Google из agents.defaults.model.fallbacks/псевдонимов.

Запрос LLM отклонён: требуется сигнатура рассуждений (Google Antigravity)

Причина: история сеанса содержит блоки рассуждений без сигнатур (часто из-за прерванного или неполного потока); Google Antigravity требует сигнатуры для блоков рассуждений. OpenClaw удаляет неподписанные блоки рассуждений для Google Antigravity Claude; если ошибка всё равно возникает, начните новый сеанс или задайте /thinking off для этого агента.

Именованная запись учётных данных (OAuth или ключ API), связанная с провайдером и хранящаяся по адресу:

~/.openclaw/agents/<agentId>/agent/auth-profiles.json

Просмотреть сохранённые профили без вывода секретов можно с помощью openclaw models auth list (необязательно с --provider <id> или --json). См. CLI моделей.

С префиксом провайдера: anthropic:default (часто используется, когда идентификатор электронной почты отсутствует), anthropic:<email> для идентификаторов OAuth или выбранный вами пользовательский идентификатор (например, anthropic:work).

Да. Конфигурация auth.order.<provider> задаёт порядок ротации для каждого провайдера (только метаданные — секреты не сохраняются).

OpenClaw может пропустить профиль, находящийся в кратковременном состоянии ожидания (ограничения частоты, тайм-ауты, ошибки аутентификации) или в более длительном состоянии отключения (оплата или недостаточно средств). Проверьте состояние с помощью openclaw models status --json и просмотрите auth.unusableProfiles. Настройте параметры с помощью auth.cooldowns.billingBackoffHours*. Периоды ожидания из-за ограничений частоты могут применяться к отдельным моделям: профиль, временно недоступный для одной модели, всё ещё может обслуживать другую модель того же провайдера; окна оплаты или отключения блокируют профиль целиком.

Задайте переопределение порядка для отдельного агента (оно сохраняется в auth-state.json этого агента):

# По умолчанию используется настроенный агент по умолчанию (не указывайте --agent)openclaw models auth order get --provider anthropic # Ограничить ротацию одним профилемopenclaw models auth order set --provider anthropic anthropic:default # Или задать явный порядок (резервирование в рамках провайдера)openclaw models auth order set --provider anthropic anthropic:work anthropic:default # Сбросить переопределение (вернуться к auth.order из конфигурации / циклическому перебору)openclaw models auth order clear --provider anthropic # Выбрать конкретного агентаopenclaw models auth order set --provider anthropic --agent main anthropic:default

Чтобы проверить, какие профили действительно будут испробованы, используйте openclaw models status --probe. Для сохранённого профиля, не включённого в явный порядок, вместо неявной попытки использования выводится excluded_by_auth_order.

• OAuth / вход через CLI часто использует доступ по подписке, если провайдер его поддерживает. Для Anthropic серверная часть Claude CLI в OpenClaw использует claude -p Claude Code, который Anthropic сейчас рассматривает как использование Agent SDK/программного доступа, расходующее лимиты подписки. Текущее состояние приостановки оплаты и ссылки на источники см. в разделе Anthropic.
• Ключи API используют оплату за количество токенов.

Мастер поддерживает Anthropic Claude CLI, OAuth OpenAI Codex и ключи API.