​

Резервне переключення моделей

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

​

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

1. Поточна вибрана модель сесії.
2. Налаштовані agents.defaults.model.fallbacks у заданому порядку.
3. Налаштована основна модель наприкінці, якщо запуск почався з перевизначення.

1. Визначити активну модель сесії та перевагу профілю автентифікації.
2. Побудувати ланцюжок моделей-кандидатів.
3. Спробувати поточного провайдера з правилами ротації/cooldown профілів автентифікації.
4. Якщо можливості цього провайдера вичерпано через помилку, що допускає резервний перехід, перейти до наступного кандидата моделі.
5. Зберегти вибране перевизначення резервної моделі до початку повторної спроби, щоб інші читачі сесії бачили того самого провайдера/модель, яких виконавець ось-ось використає.
6. Якщо кандидат резервної моделі не спрацює, відкотити лише поля перевизначення сесії, що належать резервному переходу, коли вони все ще відповідають цьому невдалому кандидату.
7. Якщо всі кандидати не спрацюють, згенерувати FallbackSummaryError із деталями по кожній спробі та найближчим часом завершення cooldown, якщо він відомий.

• providerOverride
• modelOverride
• authProfileOverride
• authProfileOverrideSource
• authProfileOverrideCompactionCount

​

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

• Секрети зберігаються в ~/.openclaw/agents/<agentId>/agent/auth-profiles.json (застаріле: ~/.openclaw/agent/auth-profiles.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).

​

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

1. Явна конфігурація: auth.order[provider] (якщо задано).
2. Налаштовані профілі: auth.profiles, відфільтровані за провайдером.
3. Збережені профілі: записи в auth-profiles.json для цього провайдера.

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

​

Прикріплення до сесії (дружнє до кешу)

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

​

Чому OAuth може «здаватися втраченим»

• Закріпіть через auth.order[provider] = ["provider:profileId"], або
• Використайте перевизначення для конкретної сесії через /model … із перевизначенням профілю (коли це підтримується вашим UI/поверхнею чату).

​

Cooldown

• OpenClaw записує cooldownModel для помилок rate limit, коли відомий ідентифікатор моделі, що не спрацювала.
• Сусідню модель у того самого провайдера все ще можна спробувати, коли cooldown прив’язано до іншої моделі.
• Billing/вікна вимкнення все одно блокують весь профіль у всіх моделях.

• 1 хвилина
• 5 хвилин
• 25 хвилин
• 1 година (максимум)

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

​

Billing-вимкнення

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

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

​

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

​

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

• Запитана модель завжди перша.
• Явно налаштовані резервні варіанти дедуплікуються, але не фільтруються за списком дозволу моделей. Вони вважаються явним наміром оператора.
• Якщо поточний запуск уже працює на налаштованому резервному варіанті в тій самій родині провайдера, OpenClaw продовжує використовувати весь налаштований ланцюжок.
• Якщо поточний запуск працює на іншому провайдері, ніж у конфігурації, і ця поточна модель ще не є частиною налаштованого ланцюжка резервного переходу, OpenClaw не додає непов’язані резервні варіанти з іншого провайдера.
• Коли запуск почався з перевизначення, налаштована основна модель додається в кінці, щоб ланцюжок міг повернутися до звичайного типового значення після вичерпання попередніх кандидатів.

​

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

• збої автентифікації
• rate limit і вичерпання cooldown
• помилки перевантаження/зайнятості провайдера
• помилки резервного переходу, схожі на тайм-аут
• вимкнення через billing
• LiveSessionModelSwitchError, який нормалізується в шлях резервного переходу, щоб застаріла збережена модель не створювала зовнішній цикл повторних спроб
• інші нерозпізнані помилки, коли ще залишилися кандидати

• явне переривання, яке не схоже на тайм-аут/помилку резервного переходу
• помилки переповнення контексту, які мають залишатися в логіці compaction/повторних спроб (наприклад, request_too_large, INVALID_ARGUMENT: input exceeds the maximum number of tokens, input token count exceeds the maximum number of input tokens, The input is too long for the model або ollama error: context length exceeded)
• фінальна невідома помилка, коли кандидатів більше немає

​

Поведінка пропуску cooldown проти probe

• Стійкі збої автентифікації негайно пропускають увесь провайдер.
• Вимкнення через billing зазвичай пропускаються, але основного кандидата все ще можна probe з throttling, щоб відновлення було можливе без перезапуску.
• Основного кандидата можна probe ближче до завершення cooldown із throttling для кожного провайдера.
• Сусідні резервні моделі того самого провайдера можна спробувати попри cooldown, якщо збій виглядає тимчасовим (rate_limit, overloaded або unknown). Це особливо важливо, коли rate limit прив’язано до моделі і сусідня модель може одразу відновитися.
• Тимчасові cooldown probe обмежуються однією спробою на провайдера в межах одного резервного запуску, щоб один провайдер не затримував міжпровайдерний резервний перехід.

​

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

• Лише явні зміни моделі, ініційовані користувачем, позначають очікуване живе перемикання. Це включає /model, session_status(model=...) і sessions.patch.
• Зміни моделі, ініційовані системою, такі як ротація резервного переходу, перевизначення heartbeat або compaction, самі по собі ніколи не позначають очікуване живе перемикання.
• Перед початком повторної спроби резервного переходу виконавець відповіді зберігає вибрані поля перевизначення резервного переходу в запис сесії.
• Узгодження живої сесії надає перевагу збереженим перевизначенням сесії над застарілими полями моделі під час виконання.
• Якщо спроба резервного переходу не спрацює, виконавець відкочує лише ті поля перевизначення, які він записав, і лише якщо вони все ще відповідають невдалому кандидату.

1. Основна модель не спрацьовує.
2. Кандидат резервної моделі вибирається в пам’яті.
3. У сховищі сесії все ще вказано стару основну модель.
4. Узгодження живої сесії читає застарілий стан сесії.
5. Повторну спробу відкидає назад на стару модель до початку спроби резервного переходу.

​

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

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

• непов’язані rate limit, прив’язані до інших моделей, ігноруються для ланцюжка спроб provider/model
• якщо блокування, що залишилося, є відповідним rate limit, прив’язаним до моделі, 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