Аварійне перемикання моделі

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

1. Ротація профілів автентифікації в межах поточного провайдера.
2. Резервне перемикання моделі на наступну модель у agents.defaults.model.fallbacks.

​

Потік виконання

• providerOverride
• modelOverride
• modelOverrideSource
• authProfileOverride
• authProfileOverrideSource
• authProfileOverrideCompactionCount

​

Політика джерела вибору

• Налаштоване значення за замовчуванням: agents.defaults.model.primary використовує agents.defaults.model.fallbacks.
• Основна модель агента: agents.list[].model є строгим, якщо об’єкт моделі цього агента не містить власних fallbacks. Використовуйте fallbacks: [], щоб зробити строгу поведінку явною, або надайте непорожній список, щоб увімкнути для цього агента резервне перемикання моделей.
• Автоматичне резервне перевизначення: під час виконання резервне перемикання записує providerOverride, modelOverride, modelOverrideSource: "auto" і вибрану початкову модель перед повторною спробою. Це автоматичне перевизначення може продовжувати проходити налаштований ланцюжок резервного перемикання та очищується командами /new, /reset і sessions.reset. Запуски Heartbeat без явного heartbeat.model також очищують пряме автоматичне перевизначення, коли його походження більше не відповідає поточному налаштованому значенню за замовчуванням.
• Користувацьке перевизначення сеансу: /model, вибір моделі, session_status(model=...) і sessions.patch записують modelOverrideSource: "user". Це точний вибір сеансу. Якщо вибраний провайдер/модель зазнає невдачі до створення відповіді, OpenClaw повідомляє про збій замість відповіді з непов’язаного налаштованого резервного варіанта.
• Застаріле перевизначення сеансу: старіші записи сеансу можуть мати modelOverride без modelOverrideSource. OpenClaw трактує їх як користувацькі перевизначення, щоб явний старий вибір не було непомітно перетворено на поведінку резервного перемикання.
• Модель у payload Cron: payload.model / --model завдання cron є основною моделлю завдання, а не користувацьким перевизначенням сеансу. Вона використовує налаштовані резервні варіанти, якщо завдання не надає payload.fallbacks; payload.fallbacks: [] робить запуск cron строгим.

​

Зберігання автентифікації (ключі + OAuth)

• Секрети зберігаються в ~/.openclaw/agents/<agentId>/agent/auth-profiles.json (застаріле: ~/.openclaw/agent/auth-profiles.json).
• Стан маршрутизації автентифікації під час виконання зберігається в ~/.openclaw/agents/<agentId>/agent/auth-state.json.
• Конфігурація auth.profiles / auth.order — це лише метадані + маршрутизація (без секретів).
• Застарілий файл OAuth лише для імпорту: ~/.openclaw/credentials/oauth.json (імпортується в auth-profiles.json під час першого використання).

• type: "api_key" → { provider, key }
• type: "oauth" → { provider, access, refresh, expires, email? } (+ projectId/enterpriseUrl для деяких провайдерів)

​

Ідентифікатори профілів

• За замовчуванням: provider:default, коли email недоступний.
• OAuth з email: provider:<email> (наприклад, google-antigravity:user@gmail.com).

​

Порядок ротації

• Основний ключ: тип профілю (OAuth перед ключами API).
• Вторинний ключ: usageStats.lastUsed (найстаріші першими, у межах кожного типу).
• Профілі в cooldown або вимкнені переміщуються в кінець, упорядковані за найранішим завершенням.

​

Закріплення сеансу (зручне для кешування)

• сеанс не буде скинуто (/new / /reset)
• не завершиться Compaction (лічильник Compaction збільшиться)
• профіль не перебуває в cooldown/вимкненому стані

​

Передплата OpenAI Codex плюс резервний API-ключ

{
  auth: {
    order: {
      openai: ["openai-codex:user@example.com", "openai:api-key-backup"],
    },
  },
}

​

Cooldown-и

• 1 хвилина
• 5 хвилин
• 25 хвилин
• 1 година (верхня межа)

{
  "usageStats": {
    "provider:profile": {
      "lastUsed": 1736160000000,
      "cooldownUntil": 1736160600000,
      "errorCount": 2
    }
  }
}

​

Вимкнення через billing

{
  "usageStats": {
    "provider:profile": {
      "disabledUntil": 1736178000000,
      "disabledReason": "billing"
    }
  }
}

• Відкладення через білінг починається з 5 годин, подвоюється після кожного збою білінгу й обмежується 24 годинами.
• Лічильники відкладення скидаються, якщо профіль не зазнавав збою протягом 24 годин (налаштовується).
• Повторні спроби при перевантаженні дозволяють 1 ротацію профілю того самого провайдера перед переходом до резервної моделі.
• Повторні спроби при перевантаженні типово використовують відкладення 0 мс.

​

Резервний перехід моделі

​

Правила ланцюга кандидатів

​

Які помилки просувають резервний перехід

​

Пропуск періоду очікування порівняно з поведінкою проби

​

Перевизначення сесії та живе перемикання моделі

• Лише явні зміни моделі, ініційовані користувачем, позначають очікуване live-перемикання. Це включає /model, session_status(model=...) і sessions.patch.
• Зміни моделі, ініційовані системою, як-от ротація резервних варіантів, перевизначення Heartbeat або Compaction, самі по собі ніколи не позначають очікуване live-перемикання.
• Перевизначення моделі, ініційовані користувачем, трактуються як точні вибори для політики резервного переходу, тому недоступний вибраний провайдер показується як збій, а не маскується agents.defaults.model.fallbacks.
• Перед початком повторної спроби резервного переходу reply runner зберігає вибрані поля перевизначення резервного варіанта в записі сесії.
• Автоматичні перевизначення резервного варіанта залишаються вибраними в наступних ходах, щоб OpenClaw не пробував завідомо несправну основну модель у кожному повідомленні. /new, /reset і sessions.reset очищають автоматично отримані перевизначення та повертають сесію до налаштованого типового варіанта.
• /status показує вибрану модель і, коли стан резервного переходу відрізняється, активну резервну модель і причину.
• Узгодження live-сесії надає перевагу збереженим перевизначенням сесії над застарілими runtime-полями моделі.
• Якщо помилка live-перемикання вказує на пізнішого кандидата в активному ланцюгу резервного переходу, OpenClaw переходить безпосередньо до цієї вибраної моделі, а не спершу обходить непов’язаних кандидатів.
• Якщо спроба резервного переходу зазнає збою, runner відкочує лише ті поля перевизначення, які він записав, і лише якщо вони все ще відповідають цьому невдалому кандидату.

​

Спостережуваність і підсумки збоїв

• провайдер/модель, які пробувалися
• причина (rate_limit, overloaded, billing, auth, model_not_found і подібні причини перемикання)
• необов’язковий статус/код
• зрозумілий для людини підсумок помилки

• непов’язані ліміти частоти на рівні моделі ігноруються для ланцюга провайдер/модель, який пробувався
• якщо залишкове блокування є відповідним лімітом частоти на рівні моделі, OpenClaw повідомляє останній відповідний час завершення, який усе ще блокує цю модель

​

Пов’язана конфігурація

• auth.profiles / auth.order
• auth.cooldowns.billingBackoffHours / auth.cooldowns.billingBackoffHoursByProvider
• auth.cooldowns.billingMaxHours / auth.cooldowns.failureWindowHours
• auth.cooldowns.overloadedProfileRotations / auth.cooldowns.overloadedBackoffMs
• auth.cooldowns.rateLimitedProfileRotations
• agents.defaults.model.primary / agents.defaults.model.fallbacks
• маршрутизації agents.defaults.imageModel