​

Model failover

1. Geçerli sağlayıcı içinde auth profili döndürme.
2. agents.defaults.model.fallbacks içindeki bir sonraki modele model geri dönüşü.

​

Çalışma zamanı akışı

1. O anda seçili oturum modeli.
2. Sırayla yapılandırılmış agents.defaults.model.fallbacks.
3. Çalıştırma bir geçersiz kılmayla başladıysa, sonda yapılandırılmış birincil model.

1. Etkin oturum modelini ve auth profili tercihini çözümle.
2. Model aday zincirini oluştur.
3. Geçerli sağlayıcıyı auth profili döndürme/cooldown kurallarıyla dene.
4. Bu sağlayıcı failover’a değer bir hatayla tükenirse, bir sonraki model adayına geç.
5. Yeniden deneme başlamadan önce seçilen fallback geçersiz kılmasını kalıcı hale getir; böylece diğer oturum okuyucuları çalıştırıcının kullanmak üzere olduğu aynı sağlayıcıyı/modeli görür.
6. Fallback adayı başarısız olursa, yalnızca hâlâ bu başarısız adayla eşleşen fallback’e ait oturum geçersiz kılma alanlarını geri al.
7. Her aday başarısız olursa, deneme başına ayrıntı ve biliniyorsa en yakın cooldown bitiş zamanı ile bir FallbackSummaryError fırlat.

• providerOverride
• modelOverride
• authProfileOverride
• authProfileOverrideSource
• authProfileOverrideCompactionCount

​

Auth depolama (anahtarlar + OAuth)

• Gizli bilgiler ~/.openclaw/agents/<agentId>/agent/auth-profiles.json içinde bulunur (legacy: ~/.openclaw/agent/auth-profiles.json).
• Config auth.profiles / auth.order yalnızca meta veriler + yönlendirme içindir (gizli bilgi içermez).
• Yalnızca içe aktarma için legacy OAuth dosyası: ~/.openclaw/credentials/oauth.json (ilk kullanımda auth-profiles.json içine aktarılır).

• type: "api_key" → { provider, key }
• type: "oauth" → { provider, access, refresh, expires, email? } (+ bazı sağlayıcılar için projectId/enterpriseUrl)

​

Profil kimlikleri

• Varsayılan: e-posta yoksa provider:default.
• E-postalı OAuth: provider:<email> (örneğin google-antigravity:user@gmail.com).

​

Döndürme sırası

1. Açık config: auth.order[provider] (ayarlıysa).
2. Yapılandırılmış profiller: sağlayıcıya göre süzülmüş auth.profiles.
3. Depolanmış profiller: sağlayıcı için auth-profiles.json içindeki girdiler.

• Birincil anahtar: profil türü (API anahtarlarından önce OAuth).
• İkincil anahtar: usageStats.lastUsed (her tür içinde en eski önce).
• Cooldown/devre dışı profiller sona taşınır, en yakın bitiş zamanına göre sıralanır.

​

Oturum yapışkanlığı (önbellek dostu)

• oturum sıfırlanırsa (/new / /reset)
• bir compaction tamamlanırsa (compaction sayısı artar)
• profil cooldown/devre dışı durumundaysa

​

OAuth neden “kaybolmuş gibi” görünebilir?

• auth.order[provider] = ["provider:profileId"] ile sabitleyin veya
• Profil geçersiz kılması içeren /model … üzerinden oturum başına bir geçersiz kılma kullanın (UI/sohbet yüzeyiniz destekliyorsa).

​

Cooldown’lar

• OpenClaw, başarısız olan model kimliği bilindiğinde oran sınırı başarısızlıkları için cooldownModel kaydeder.
• Aynı sağlayıcıdaki kardeş bir model, cooldown farklı bir modele kapsamlandırılmışsa yine de denenebilir.
• Faturalama/devre dışı pencereleri, modeller arasında yine de tüm profili engeller.

• 1 dakika
• 5 dakika
• 25 dakika
• 1 saat (üst sınır)

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

​

Faturalama nedeniyle devre dışı bırakma

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

• Faturalama geri çekilmesi 5 saat ile başlar, her faturalama başarısızlığında iki katına çıkar ve 24 saat ile sınırlanır.
• Bir profil 24 saat boyunca başarısız olmadıysa geri çekilme sayaçları sıfırlanır (yapılandırılabilir).
• Aşırı yüklenmiş yeniden denemeler, model fallback’inden önce aynı sağlayıcı içinde 1 auth profili döndürmesine izin verir.
• Aşırı yüklenmiş yeniden denemeler varsayılan olarak 0 ms geri çekilme kullanır.

​

Model fallback

​

Aday zinciri kuralları

• İstenen model her zaman ilk sıradadır.
• Açıkça yapılandırılmış fallback’ler tekilleştirilir ancak model allowlist’i ile süzülmez. Bunlar açık operatör niyeti olarak değerlendirilir.
• Geçerli çalıştırma aynı sağlayıcı ailesindeki yapılandırılmış bir fallback üzerinde zaten bulunuyorsa, OpenClaw tam yapılandırılmış zinciri kullanmaya devam eder.
• Geçerli çalıştırma config’ten farklı bir sağlayıcı üzerindeyse ve bu geçerli model zaten yapılandırılmış fallback zincirinin parçası değilse, OpenClaw başka bir sağlayıcıdan ilgisiz yapılandırılmış fallback’leri eklemez.
• Çalıştırma bir geçersiz kılmayla başladıysa, zincir önceki adaylar tükendiğinde normal varsayılana geri oturabilsin diye yapılandırılmış birincil model sona eklenir.

​

Hangi hatalar fallback’i ilerletir

• auth başarısızlıkları
• oran sınırları ve cooldown tükenmesi
• aşırı yüklenme/sağlayıcı meşgul hataları
• zaman aşımı biçimli failover hataları
• faturalama nedeniyle devre dışı bırakmalar
• LiveSessionModelSwitchError; bu hata, eski kalıcı modelin dış yeniden deneme döngüsü oluşturmasını engellemek için bir failover yoluna normalize edilir
• kalan adaylar hâlâ varken diğer tanınmayan hatalar

• zaman aşımı/failover biçiminde olmayan açık iptaller
• compaction/yeniden deneme mantığı içinde kalması gereken bağlam taşması hataları (örneğin 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 veya ollama error: context length exceeded)
• aday kalmadığında son bilinmeyen hata

​

Cooldown atlama ve probe davranışı

• Kalıcı auth başarısızlıkları tüm sağlayıcıyı hemen atlar.
• Faturalama nedeniyle devre dışı bırakmalar genellikle atlanır, ancak kurtarma yeniden başlatma olmadan mümkün olsun diye birincil aday yine de throttled şekilde problanabilir.
• Birincil aday, cooldown bitişine yakın, sağlayıcı başına bir throttle ile problanabilir.
• Başarısızlık geçici görünüyorsa (rate_limit, overloaded veya bilinmeyen), aynı sağlayıcıdaki fallback kardeşleri cooldown’a rağmen denenebilir. Bu özellikle bir oran sınırı modele özgüyse ve kardeş bir model hâlâ hemen toparlanabilecekse önemlidir.
• Geçici cooldown probları, tek bir sağlayıcının sağlayıcılar arası fallback’i durdurmaması için fallback çalıştırması başına sağlayıcı başına bir tane ile sınırlıdır.

​

Oturum geçersiz kılmaları ve canlı model geçişi

• Bekleyen canlı geçişi yalnızca açık kullanıcı kaynaklı model değişiklikleri işaretler. Buna /model, session_status(model=...) ve sessions.patch dahildir.
• Fallback döndürmesi, heartbeat geçersiz kılmaları veya compaction gibi sistem kaynaklı model değişiklikleri kendi başına hiçbir zaman bekleyen canlı geçiş işaretlemez.
• Fallback yeniden denemesi başlamadan önce yanıt çalıştırıcısı seçilen fallback geçersiz kılma alanlarını oturum girdisine kalıcı hale getirir.
• Canlı oturum uzlaştırması, eski çalışma zamanı model alanları yerine kalıcı oturum geçersiz kılmalarını tercih eder.
• Fallback denemesi başarısız olursa çalıştırıcı yalnızca yazdığı geçersiz kılma alanlarını ve yalnızca hâlâ bu başarısız adayla eşleşiyorlarsa geri alır.

1. Birincil başarısız olur.
2. Fallback adayı bellekte seçilir.
3. Oturum deposu hâlâ eski birinciliği gösterir.
4. Canlı oturum uzlaştırması eski oturum durumunu okur.
5. Yeniden deneme, fallback denemesi başlamadan önce eski modele geri çekilir.

​

Gözlemlenebilirlik ve başarısızlık özetleri

• denenen sağlayıcı/model
• neden (rate_limit, overloaded, billing, auth, model_not_found ve benzer failover nedenleri)
• isteğe bağlı durum/kod
• insanlar tarafından okunabilir hata özeti

• ilgisiz modele özgü oran sınırları, denenmiş sağlayıcı/model zinciri için yok sayılır
• kalan engel eşleşen modele özgü bir oran sınırıysa, OpenClaw o modeli hâlâ engelleyen son eşleşen bitiş zamanını bildirir

​

İlgili config

• 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 yönlendirmesi