Model yük devri

OpenClaw hataları iki aşamada ele alır:

1. Geçerli sağlayıcı içinde kimlik doğrulama profili rotasyonu.
2. agents.defaults.model.fallbacks içindeki sonraki modele model yedek geçişi.

Bu belge, çalışma zamanı kurallarını ve bunları destekleyen verileri açıklar.

# Çalışma zamanı akışı

Normal bir metin çalıştırması için OpenClaw adayları şu sırayla değerlendirir:

Bu, bilinçli olarak "tüm oturumu kaydet ve geri yükle" yaklaşımından daha dardır. Yanıt çalıştırıcısı yalnızca yedek geçiş için sahip olduğu model seçimi alanlarını kalıcılaştırır:

• providerOverride
• modelOverride
• modelOverrideSource
• authProfileOverride
• authProfileOverrideSource
• authProfileOverrideCompactionCount

Bu, başarısız bir yedek geçiş yeniden denemesinin, deneme çalışırken gerçekleşen manuel /model değişiklikleri veya oturum rotasyonu güncellemeleri gibi daha yeni ve ilgisiz oturum mutasyonlarının üzerine yazmasını önler.

# Seçim kaynağı politikası

OpenClaw, seçilen sağlayıcı/model ile bunun neden seçildiğini birbirinden ayırır. Bu kaynak, yedek geçiş zincirine izin verilip verilmediğini kontrol eder:

• Yapılandırılmış varsayılan: agents.defaults.model.primary, agents.defaults.model.fallbacks kullanır.
• Agent birincili: agents.list[].model, ilgili agent model nesnesi kendi fallbacks değerini içermedikçe katıdır. Katı davranışı açık yapmak için fallbacks: [] kullanın veya bu agent için model yedek geçişini etkinleştirmek üzere boş olmayan bir liste sağlayın.
• Otomatik yedek geçiş geçersiz kılması: çalışma zamanı yedek geçişi, yeniden denemeden önce providerOverride, modelOverride ve modelOverrideSource: "auto" yazar. Bu otomatik geçersiz kılma, yapılandırılmış yedek geçiş zincirinde ilerlemeye devam edebilir ve /new, /reset ve sessions.reset tarafından temizlenir.
• Kullanıcı oturumu geçersiz kılması: /model, model seçici, session_status(model=...) ve sessions.patch, modelOverrideSource: "user" yazar. Bu, tam bir oturum seçimidir. Seçilen sağlayıcı/model yanıt üretmeden önce başarısız olursa OpenClaw ilgisiz bir yapılandırılmış yedekten yanıt vermek yerine hatayı bildirir.
• Eski oturum geçersiz kılması: eski oturum girdilerinde modelOverrideSource olmadan modelOverride bulunabilir. OpenClaw bunları kullanıcı geçersiz kılmaları olarak değerlendirir; böylece açık eski bir seçim sessizce yedek geçiş davranışına dönüştürülmez.
• Cron yük modeli: bir cron işi payload.model / --model, kullanıcı oturumu geçersiz kılması değil, iş birincilidir. İş payload.fallbacks sağlamadıkça yapılandırılmış yedekleri kullanır; payload.fallbacks: [] cron çalıştırmasını katı yapar.

# Kimlik doğrulama depolaması (anahtarlar + OAuth)

OpenClaw hem API anahtarları hem de OAuth token'ları için kimlik doğrulama profilleri kullanır.

• Gizli bilgiler ~/.openclaw/agents/<agentId>/agent/auth-profiles.json içinde tutulur (eski: ~/.openclaw/agent/auth-profiles.json).
• Çalışma zamanı kimlik doğrulama yönlendirme durumu ~/.openclaw/agents/<agentId>/agent/auth-state.json içinde tutulur.
• Config auth.profiles / auth.order yalnızca metadata + routing içindir (gizli bilgi yoktur).
• Yalnızca eski içe aktarma OAuth dosyası: ~/.openclaw/credentials/oauth.json (ilk kullanımda auth-profiles.json içine aktarılır).

Daha fazla ayrıntı: OAuth

Kimlik bilgisi türleri:

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

# Profil kimlikleri

OAuth oturum açmaları, birden fazla hesabın birlikte var olabilmesi için ayrı profiller oluşturur.

• Varsayılan: e-posta yoksa provider:default.
• E-posta ile OAuth: provider:<email> (örneğin google-antigravity:[email protected]).

Profiller ~/.openclaw/agents/<agentId>/agent/auth-profiles.json içinde profiles altında tutulur.

# Rotasyon sırası

Bir sağlayıcının birden fazla profili olduğunda OpenClaw şu şekilde bir sıra seçer:

Açık bir sıra yapılandırılmamışsa OpenClaw round-robin sırası kullanır:

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

# Oturum yapışkanlığı (cache dostu)

OpenClaw, sağlayıcı önbelleklerini sıcak tutmak için seçilen kimlik doğrulama profilini oturum başına sabitler. Her istekte rotasyon yapmaz. Sabitlenen profil şu durumlara kadar yeniden kullanılır:

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

/model …@<profileId> ile manuel seçim, o oturum için bir kullanıcı geçersiz kılması ayarlar ve yeni bir oturum başlayana kadar otomatik rotasyona sokulmaz.

# OAuth neden "kaybolmuş gibi görünebilir"

Aynı sağlayıcı için hem OAuth profili hem de API anahtarı profili varsa round-robin, sabitlenmedikçe iletiler arasında bunlar arasında geçiş yapabilir. Tek bir profili zorlamak için:

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

# Cooldown'lar

Bir profil kimlik doğrulama/hız sınırı hataları nedeniyle (veya hız sınırlaması gibi görünen bir zaman aşımıyla) başarısız olduğunda OpenClaw onu cooldown'a alır ve sonraki profile geçer.

Cooldown'lar üstel backoff kullanır:

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

Durum auth-state.json içinde usageStats altında saklanır:

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

# Faturalandırma devre dışı bırakmaları

Faturalandırma/kredi hataları (örneğin "insufficient credits" / "credit balance too low") devretmeye uygun kabul edilir, ancak genellikle geçici değildir. Kısa bir cooldown yerine OpenClaw profili devre dışı olarak işaretler (daha uzun bir backoff ile) ve sonraki profile/sağlayıcıya döner.

Durum auth-state.json içinde saklanır:

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

Varsayılanlar:

• Faturalandırma backoff'u 5 saat ile başlar, her faturalandırma hatasında ikiye katlanır ve 24 saat ile sınırlanır.
• Profil 24 saat boyunca başarısız olmadıysa backoff sayaçları sıfırlanır (yapılandırılabilir).
• Aşırı yüklenmiş yeniden denemeler, model yedek geçişinden önce 1 aynı sağlayıcı profil rotasyonuna izin verir.
• Aşırı yüklenmiş yeniden denemeler varsayılan olarak 0 ms backoff kullanır.

# Model yedek geçişi

Bir sağlayıcının tüm profilleri başarısız olursa OpenClaw agents.defaults.model.fallbacks içindeki sonraki modele geçer. Bu, profil rotasyonunu tüketen kimlik doğrulama hataları, hız sınırları ve zaman aşımları için geçerlidir (diğer hatalar yedek geçişi ilerletmez). Yeterli ayrıntı göstermeyen sağlayıcı hataları yine de yedek geçiş durumunda kesin biçimde etiketlenir: empty_response, sağlayıcının kullanılabilir ileti veya durum döndürmediği anlamına gelir; no_error_details, sağlayıcının açıkça Unknown error (no error details in response) döndürdüğü anlamına gelir; unclassified ise OpenClaw'ın ham önizlemeyi koruduğu ancak henüz hiçbir sınıflandırıcının bununla eşleşmediği anlamına gelir.

Aşırı yük ve oran sınırı hataları, faturalandırma bekleme sürelerinden daha agresif şekilde ele alınır. Varsayılan olarak OpenClaw, aynı sağlayıcı için bir kimlik doğrulama profili yeniden denemesine izin verir, ardından beklemeden yapılandırılmış bir sonraki model geri dönüşüne geçer. ModelNotReadyException gibi sağlayıcı meşgul sinyalleri bu aşırı yük kovasına girer. Bunu auth.cooldowns.overloadedProfileRotations, auth.cooldowns.overloadedBackoffMs ve auth.cooldowns.rateLimitedProfileRotations ile ayarlayın.

Bir çalıştırma yapılandırılmış varsayılan birincilden, bir cron işi birincilinden, açık geri dönüşleri olan bir aracı birincilinden veya otomatik seçilmiş bir geri dönüş geçersiz kılmasından başladığında, OpenClaw eşleşen yapılandırılmış geri dönüş zincirini izleyebilir. Açık geri dönüşleri olmayan aracı birincilleri ve açık kullanıcı seçimleri (örneğin /model ollama/qwen3.5:27b, model seçici, sessions.patch veya tek seferlik CLI sağlayıcı/model geçersiz kılmaları) katıdır: bu sağlayıcı/model erişilemezse veya bir yanıt üretmeden önce başarısız olursa, OpenClaw ilgisiz bir geri dönüşten yanıtlamak yerine hatayı bildirir.

# Aday zincir kuralları

OpenClaw, aday listesini o anda istenen provider/model ile yapılandırılmış geri dönüşlerden oluşturur.

# Hangi hatalar geri dönüşü ilerletir

# Bekleme süresi atlama ve yoklama davranışı

Bir sağlayıcının tüm kimlik doğrulama profilleri zaten bekleme süresindeyken, OpenClaw bu sağlayıcıyı otomatik olarak sonsuza kadar atlamaz. Aday başına karar verir:

# Oturum geçersiz kılmaları ve canlı model değiştirme

Oturum model değişiklikleri paylaşılan durumdur. Etkin çalıştırıcı, /model komutu, compaction/oturum güncellemeleri ve canlı oturum uzlaştırması aynı oturum girdisinin parçalarını okur veya yazar.

Bu, geri dönüş yeniden denemelerinin canlı model değiştirme ile koordine edilmesi gerektiği anlamına gelir:

• Yalnızca açık kullanıcı güdümlü model değişiklikleri bekleyen bir canlı geçişi işaretler. Buna /model, session_status(model=...) ve sessions.patch dahildir.
• Geri dönüş rotasyonu, heartbeat geçersiz kılmaları veya compaction gibi sistem güdümlü model değişiklikleri kendi başlarına hiçbir zaman bekleyen bir canlı geçiş işaretlemez.
• Kullanıcı güdümlü model geçersiz kılmaları, geri dönüş politikası için tam seçimler olarak ele alınır; bu nedenle erişilemeyen seçili bir sağlayıcı, agents.defaults.model.fallbacks tarafından gizlenmek yerine hata olarak yüzeye çıkar.
• Bir geri dönüş yeniden denemesi başlamadan önce, yanıt çalıştırıcısı seçilen geri dönüş geçersiz kılma alanlarını oturum girdisine kalıcı olarak yazar.
• Otomatik geri dönüş geçersiz kılmaları sonraki turlarda seçili kalır; böylece OpenClaw her mesajda bilinen bozuk bir birincili yoklamaz. /new, /reset ve sessions.reset, otomatik kaynaklı geçersiz kılmaları temizler ve oturumu yapılandırılmış varsayılana döndürür.
• /status seçilen modeli ve geri dönüş durumu farklı olduğunda etkin geri dönüş modelini ve nedenini gösterir.
• Canlı oturum uzlaştırması, eski çalışma zamanı model alanları yerine kalıcı oturum geçersiz kılmalarını tercih eder.
• Bir canlı geçiş hatası etkin geri dönüş zincirindeki daha sonraki bir adayı işaret ederse, OpenClaw önce ilgisiz adayları yürümek yerine doğrudan seçilen modele atlar.
• Geri dönüş denemesi başarısız olursa, çalıştırıcı yalnızca yazdığı geçersiz kılma alanlarını ve yalnızca hâlâ başarısız adayla eşleşiyorlarsa geri alır.

Bu klasik yarış durumunu önler:

Kalıcı geri dönüş geçersiz kılması bu pencereyi kapatır ve dar geri alma daha yeni manuel veya çalışma zamanı oturum değişikliklerini korur.

# Gözlemlenebilirlik ve hata özetleri

runWithModelFallback(...), günlükleri ve kullanıcıya yönelik bekleme süresi mesajlarını besleyen deneme başına ayrıntıları kaydeder:

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

Yapılandırılmış model_fallback_decision günlükleri, bir aday başarısız olduğunda, atlandığında veya daha sonraki bir geri dönüş başarılı olduğunda düz fallbackStep* alanlarını da içerir. Bu alanlar denenen geçişi açık hale getirir (fallbackStepFromModel, fallbackStepToModel, fallbackStepFromFailureReason, fallbackStepFromFailureDetail, fallbackStepFinalOutcome); böylece günlük ve tanılama dışa aktarıcıları, son geri dönüş de başarısız olsa bile birincil hatayı yeniden oluşturabilir.

Her aday başarısız olduğunda, OpenClaw FallbackSummaryError fırlatır. Dış yanıt çalıştırıcısı bunu kullanarak "tüm modeller geçici olarak oran sınırına takıldı" gibi daha özel bir mesaj oluşturabilir ve biliniyorsa en yakın bekleme süresi bitişini dahil edebilir.

Bu bekleme süresi özeti model farkındadır:

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

# İlgili yapılandırma

Şunlar için Gateway yapılandırmasına bakın:

• 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

Daha geniş model seçimi ve geri dönüş genel bakışı için Modeller bölümüne bakın.