​

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

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

​

Потік виконання під час роботи

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

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

• providerOverride
• modelOverride
• authProfileOverride
• authProfileOverrideSource
• authProfileOverrideCompactionCount

​

Сховище автентифікації (ключі + 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 для деяких провайдерів)

​

ID профілів

• За замовчуванням: 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 (найдавніші першими в межах кожного типу).
• Профілі в охолодженні/вимкнені профілі переміщуються в кінець, упорядковані за найближчим завершенням терміну дії.

​

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

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

​

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

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

​

Періоди охолодження

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

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

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

​

Вимкнення через білінг

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

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

​

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

​

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

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

​

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

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

• явні переривання, які не мають форми тайм-ауту/резервного переходу
• помилки переповнення контексту, які мають залишатися в межах логіки компакції/повторної спроби (наприклад, 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)
• фінальна невідома помилка, коли кандидатів більше не залишилося

​

Поведінка пропуску через охолодження та пробних спроб

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

​

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

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

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

​

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

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

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