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

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" і вибрану вихідну модель перед повторною спробою. Це автоматичне перевизначення може продовжувати рухатися налаштованим ланцюжком резервних моделей без перевірки основної моделі для кожного повідомлення, але OpenClaw періодично знову перевіряє налаштоване джерело й очищає автоматичне перевизначення після його відновлення. /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-запуск суворим.

​

Кеш пропуску збоїв автентифікації

OPENCLAW_FALLBACK_SKIP_TTL_MS=60000

​

Видимі для користувача сповіщення про резервний перехід

↪️ Model Fallback: <fallback> (selected <primary>; <reason>)

↪️ Model Fallback cleared: <primary> (was <fallback>)

​

Сховище автентифікації (ключі + OAuth)

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

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

​

Фіксація сесії (дружня до кешу)

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

​

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

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

​

Періоди очікування

• 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 мс.

​

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

​

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

​

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

​

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

​

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

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