​

Model yedekleme

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

​

Çalışma zamanı akışı

1. O anda seçili oturum modeli.
2. Sıralı şekilde yapılandırılmış agents.defaults.model.fallbacks.
3. Çalıştırma bir geçersiz kılma ile 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. Auth profili döndürme/cooldown kurallarıyla geçerli sağlayıcıyı dene.
4. Bu sağlayıcı yedeklemeye uygun bir hatayla tükenirse, bir sonraki model adayına geç.
5. Yeniden deneme başlamadan önce seçilen yedek geçersiz kılmayı kalıcı hale getir ki diğer oturum okuyucuları çalıştırıcının kullanmak üzere olduğu aynı sağlayıcıyı/modeli görsün.
6. Yedek aday başarısız olursa, yalnızca yedek adaya ait oturum geçersiz kılma alanlarını, hâlâ o başarısız adayla eşleşiyorlarsa 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 (eski: ~/.openclaw/agent/auth-profiles.json).
• Çalışma zamanı auth yönlendirme durumu ~/.openclaw/agents/<agentId>/agent/auth-state.json içinde bulunur.
• auth.profiles / auth.order yapılandırması yalnızca üst veri + yönlendirme içindir (gizli bilgi içermez).
• Eski yalnızca içe aktarma amaçlı 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 ile birlikte)

​

Profil kimlikleri

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

​

Döndürme sırası

1. Açık yapılandırma: auth.order[provider] (ayarlanmışsa).
2. Yapılandırılmış profiller: sağlayıcıya göre filtrelenmiş 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 en sona taşınır ve en yakın bitiş süresine göre sıralanır.

​

Oturum sabitleme (önbellek dostu)

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

​

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

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

​

Cooldown süreleri

• OpenClaw, başarısız model kimliği biliniyorsa hız sınırı hataları için cooldownModel kaydeder.
• Aynı sağlayıcıdaki kardeş bir model, cooldown farklı bir modele kapsamlanmışsa yine de denenebilir.
• Faturalama/devre dışı pencereleri ise modeller arasında tüm profili engellemeye devam eder.

• 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ırakmalar

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

• Faturalama geri çekilmesi 5 saatten başlar, her faturalama hatasında iki katına çıkar ve 24 saatte sınırlanır.
• Geri çekilme sayaçları, profil 24 saat boyunca başarısız olmamışsa sıfırlanır (yapılandırılabilir).
• Aşırı yük yeniden denemeleri, model yedeklemeden önce aynı sağlayıcı içinde 1 auth profili döndürmeye izin verir.
• Aşırı yük yeniden denemeleri varsayılan olarak 0 ms geri çekilme kullanır.

​

Model yedekleme

​

Aday zinciri kuralları

• İstenen model her zaman ilk sıradadır.
• Açıkça yapılandırılmış yedekler yinelenenlerden arındırılır ancak model izin listesinden filtrelenmez. Açık operatör niyeti olarak değerlendirilirler.
• Geçerli çalıştırma zaten aynı sağlayıcı ailesindeki yapılandırılmış bir yedek üzerindeyse, OpenClaw tüm yapılandırılmış zinciri kullanmaya devam eder.
• Geçerli çalıştırma yapılandırmadan farklı bir sağlayıcı üzerindeyse ve bu geçerli model zaten yapılandırılmış yedek zincirinin bir parçası değilse, OpenClaw başka bir sağlayıcıdan ilgisiz yapılandırılmış yedekleri eklemez.
• Çalıştırma bir geçersiz kılma ile başladıysa, daha önceki adaylar tükendiğinde zincirin yeniden normal varsayılana yerleşebilmesi için yapılandırılmış birincil en sona eklenir.

​

Hangi hatalar yedeklemeyi ilerletir

• auth hataları
• hız sınırları ve cooldown tükenmesi
• aşırı yük/sağlayıcı meşgul hataları
• zaman aşımı biçimli yedekleme hataları
• faturalama nedeniyle devre dışı bırakmalar
• LiveSessionModelSwitchError; bu, eski bir kalıcı modelin dış bir yeniden deneme döngüsü oluşturmaması için yedekleme yoluna normalize edilir
• başka tanınmayan hatalar, hâlâ kalan adaylar varsa

• zaman aşımı/yedekleme biçiminde olmayan açık iptaller
• sıkıştırma/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 bir bilinmeyen hata

​

Cooldown atlama ve yoklama davranışı

• Kalıcı auth hataları tüm sağlayıcıyı hemen atlar.
• Faturalama nedeniyle devre dışı bırakmalar genellikle atlanır, ancak kurtarma yeniden başlatmadan mümkün olsun diye birincil aday yine de bir sınırlama ile yoklanabilir.
• Birincil aday, sağlayıcı başına bir sınırlama ile cooldown bitimine yakın yoklanabilir.
• Aynı sağlayıcıdaki yedek kardeşler, hata geçici görünüyorsa (rate_limit, overloaded veya bilinmeyen), cooldown’a rağmen denenebilir. Bu, özellikle bir hız sınırı model kapsamlı olduğunda ve kardeş bir model hemen toparlanabilecekse önemlidir.
• Geçici cooldown yoklamaları, tek bir sağlayıcının sağlayıcılar arası yedeklemeyi durdurmaması için yedekleme çalıştırması başına sağlayıcı başına bir taneyle sınırlıdır.

​

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

• Yalnızca açık kullanıcı odaklı model değişiklikleri bekleyen bir canlı geçişi işaretler. Buna /model, session_status(model=...) ve sessions.patch dahildir.
• Yedek döndürme, heartbeat geçersiz kılmaları veya sıkıştırma gibi sistem odaklı model değişiklikleri kendi başına bekleyen bir canlı geçiş işaretlemez.
• Bir yedek yeniden deneme başlamadan önce yanıt çalıştırıcısı seçilen yedek 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.
• Yedek denemesi başarısız olursa çalıştırıcı, yalnızca yazdığı geçersiz kılma alanlarını ve yalnızca bunlar hâlâ o başarısız adayla eşleşiyorsa geri alır.

1. Birincil model başarısız olur.
2. Yedek 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, yedek deneme başlamadan önce eski modele geri çekilir.

​

Gözlemlenebilirlik ve hata özetleri

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

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

​

İlgili yapılandırma

• 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