Model yük devri

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

1. Geçerli sağlayıcı içinde auth profili rotasyonu.
2. agents.defaults.model.fallbacks içindeki sonraki modele model fallback.

Bu belge, runtime kurallarını ve bunları destekleyen verileri açıklar.

Runtime akışı

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

Bu, kasıtlı olarak "tüm oturumu kaydet ve geri yükle" yaklaşımından daha dardır. Yanıt runner'ı yalnızca fallback için sahibi 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 fallback yeniden denemesinin, deneme çalışırken gerçekleşen manuel /model değişiklikleri veya oturum rotasyonu güncellemeleri gibi daha yeni ve alakasız 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, fallback 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, bu agent model nesnesi kendi fallbacks listesini içermediği sürece katıdır. Katı davranışı açık yapmak için fallbacks: [] kullanın veya bu agent'ı model fallback'e dahil etmek için boş olmayan bir liste sağlayın.
• Otomatik fallback override'ı: runtime fallback, yeniden denemeden önce providerOverride, modelOverride, modelOverrideSource: "auto" ve seçilen kaynak modeli yazar. Bu otomatik override, her mesajda birincili denemeden yapılandırılmış fallback zincirinde ilerlemeye devam edebilir; ancak OpenClaw yapılandırılmış kaynağı periyodik olarak tekrar yoklar ve toparlandığında otomatik override'ı temizler. /new, /reset ve sessions.reset de otomatik kaynaklı override'ları temizler. Açık bir heartbeat.model olmadan çalışan Heartbeat, kaynakları artık geçerli yapılandırılmış varsayılanla eşleşmediğinde doğrudan otomatik override'ları temizler.
• Kullanıcı oturumu override'ı: /model, model seçici, session_status(model=...) ve sessions.patch, modelOverrideSource: "user" yazar. Bu, kesin bir oturum seçimidir. Seçilen sağlayıcı/model yanıt üretmeden önce başarısız olursa OpenClaw, alakasız bir yapılandırılmış fallback'ten yanıt vermek yerine hatayı bildirir.
• Eski oturum override'ı: eski oturum girdilerinde modelOverrideSource olmadan modelOverride olabilir. OpenClaw bunları kullanıcı override'ı olarak ele alır; böylece açık bir eski seçim sessizce fallback davranışına dönüştürülmez.
• Cron payload modeli: bir cron işi payload.model / --model, kullanıcı oturumu override'ı değil, iş birincilidir. İş payload.fallbacks sağlamadığı sürece yapılandırılmış fallback'leri kullanır; payload.fallbacks: [] cron çalıştırmasını katı yapar.

Otomatik fallback birincil yoklama aralığı beş dakikadır ve yapılandırılamaz. OpenClaw, başarısız olan bir birincilin her turda yeniden denenmemesi için son yoklamaları oturum ve birincil model bazında hatırlar. OpenClaw, bir oturum fallback'e geçtiğinde görünür bir bildirim ve seçilen birincile döndüğünde başka bir bildirim gönderir; yapışkan fallback'in her turunda bildirimi tekrarlamaz.

Auth hatası atlama önbelleği

Varsayılan olarak her yeni tur mevcut fallback yeniden deneme davranışını korur: OpenClaw yakın zamanda auth veya auth_permanent ile başarısız olmuş birincil olmayan adaylar dahil olmak üzere, yapılandırılmış her fallback adayını yeniden dener.

Bu tekrarlanan auth hatalarını bastırmayı tercih eden operatörler şununla etkinleştirebilir:

OPENCLAW_FALLBACK_SKIP_TTL_MS=60000

Etkinleştirildiğinde OpenClaw, auth sınıfı bir hatadan sonra birincil olmayan fallback adayı için bellek içi, oturum kapsamlı bir atlama işareti kaydeder. İşaret, oturum id'si, sağlayıcı ve modele göre anahtarlanır. Birincil adaylar asla atlanmaz; böylece açık bir kullanıcı model seçimi gerçek auth hatasını yine gösterir. Önbellek süreç yereldir ve Gateway yeniden başlatıldığında temizlenir.

Değer, milisaniye cinsinden bir TTL'dir. 0 veya ayarlanmamış değer önbelleği devre dışı bırakır. Pozitif değerler 1 saniye ile 10 dakika arasında sınırlandırılır.

Kullanıcıya görünür fallback bildirimleri

Bir oturum otomatik seçilmiş bir fallback'e geçtiğinde OpenClaw aynı yanıt yüzeyinde bir durum bildirimi gönderir:

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

Daha sonraki bir yoklama başarılı olduğunda ve oturum seçilen birincile döndüğünde OpenClaw şunu gönderir:

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

Bu bildirimler operasyonel mesajlardır, assistant içeriği değildir. Uygun olduğunda yalnızca yan etkili turlar dahil olmak üzere durum değişikliği başına bir kez iletilirler; ancak yapışkan fallback turları bunları tekrarlamaz. İletim normal kaynak-yanıt bastırmasını atlar, bildirim thread'li kanallar için ilk assistant yanıt slotunu tüketmez ve text-to-speech ile commitment extraction kapsamı dışında tutulur.

Auth depolama (anahtarlar + OAuth)

OpenClaw hem API anahtarları hem OAuth token'ları için auth profilleri kullanır.

• Gizli bilgiler ve runtime auth yönlendirme durumu ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite içinde yaşar.
• auth.profiles / auth.order yapılandırması yalnızca metadata + yönlendirme içindir (gizli bilgi içermez).
• Eski yalnızca içe aktarma OAuth dosyası: ~/.openclaw/credentials/oauth.json (ilk kullanımda agent başına auth deposuna içe aktarılır).
• Eski auth-profiles.json, auth-state.json ve agent başına auth.json dosyaları openclaw doctor --fix tarafından içe 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 ayrıca projectId/enterpriseUrl)

Profil ID'leri

OAuth girişleri, birden fazla hesabın birlikte var olabilmesi için ayrı profiller oluşturur.

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

Profiller, agent başına openclaw-agent.sqlite auth profil deposunda yaşar.

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ıra kullanır:

• 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 yakın bitiş zamanına göre sıralanarak sona taşınır.

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

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

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

/model …@<profileId> ile manuel seçim, o oturum için bir kullanıcı override'ı ayarlar ve yeni bir oturum başlayana kadar otomatik olarak döndürülmez.

OpenAI Codex aboneliği ve API anahtarı yedeği

OpenAI agent modelleri için auth ve runtime ayrıdır. openai/gpt-*, auth bir Codex abonelik profili ile bir OpenAI API anahtarı yedeği arasında dönebilirken Codex harness üzerinde kalır.

Kullanıcıya dönük sıra için auth.order.openai kullanın:

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

Hem ChatGPT/Codex OAuth profilleri hem OpenAI API anahtarı profilleri için openai:* kullanın. Abonelik bir Codex kullanım limitine ulaştığında, OpenClaw Codex bir zaman sağlıyorsa kesin sıfırlanma zamanını kaydeder, sıradaki auth profilini dener ve çalıştırmayı Codex harness içinde tutar. Sıfırlanma zamanı geçtikten sonra abonelik profili yeniden uygun olur ve sonraki otomatik seçim ona dönebilir.

Yalnızca o oturum için tek bir hesabı/anahtarı zorlamak istediğinizde kullanıcı tarafından sabitlenmiş profil kullanın. Kullanıcı tarafından sabitlenmiş profiller kasıtlı olarak katıdır ve sessizce başka bir profile atlamaz.

Cooldown'lar

Bir profil auth/hız limiti hataları (veya hız limiti gibi görünen bir zaman aşımı) nedeniyle başarısız olduğunda OpenClaw onu cooldown'a işaretler ve sonraki profile geçer.

Bekleme süreleri üstel geri çekilme kullanır:

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

Durum, ajan başına SQLite kimlik doğrulama durumunda 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") yük devrine değer kabul edilir, ancak genellikle geçici değildir. Kısa bir bekleme süresi yerine OpenClaw profili devre dışı olarak işaretler (daha uzun bir geri çekilmeyle) ve bir sonraki profile/sağlayıcıya geçer.

Durum, ajan başına SQLite kimlik doğrulama durumunda saklanır:

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

Varsayılanlar:

• Faturalandırma geri çekilmesi 5 saatte başlar, her faturalandırma hatasında ikiye katlanır ve 24 saatte üst sınıra ulaşır.
• 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üklü yeniden denemeler, model geri dönüşünden önce 1 aynı sağlayıcı profil dönüşüne izin verir.
• Aşırı yüklü yeniden denemeler varsayılan olarak 0 ms geri çekilme kullanır.

Model geri dönüşü

Bir sağlayıcı için tüm profiller başarısız olursa OpenClaw, agents.defaults.model.fallbacks içindeki bir sonraki modele geçer. Bu, profil dönüşünü tüketen kimlik doğrulama hataları, hız sınırları ve zaman aşımı durumları için geçerlidir (diğer hatalar geri dönüşü ilerletmez). Yeterli ayrıntı sunmayan sağlayıcı hataları yine de geri dönüş durumunda kesin şekilde 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 onunla eşleşmediği anlamına gelir.

Aşırı yüklü ve hız sınırı hataları, faturalandırma bekleme sürelerinden daha agresif ele alınır. OpenClaw varsayılan olarak bir aynı sağlayıcı kimlik doğrulama profili yeniden denemesine izin verir, ardından beklemeden bir sonraki yapılandırılmış model geri dönüşüne geçer. ModelNotReadyException gibi sağlayıcı meşgul sinyalleri bu aşırı yüklü kovaya düşer. 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 ajan 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 ajan 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 yanıt üretmeden önce başarısız olursa OpenClaw, ilgisiz bir geri dönüşten yanıt vermek yerine hatayı bildirir.

Aday zinciri kuralları

OpenClaw, aday listesini şu anda istenen provider/model ve 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ı için her kimlik doğrulama profili zaten bekleme süresindeyken OpenClaw o sağlayıcıyı otomatik olarak sonsuza dek 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ştirmeyle koordine olması gerektiği anlamına gelir:

• Yalnızca açık kullanıcı güdümlü model değişiklikleri bekleyen bir canlı değiştirmeyi işaretler. Buna /model, session_status(model=...) ve sessions.patch dahildir.
• Geri dönüş dönüşü, Heartbeat geçersiz kılmaları veya Compaction gibi sistem güdümlü model değişiklikleri kendi başlarına bekleyen canlı değiştirmeyi asla işaretlemez.
• Kullanıcı güdümlü model geçersiz kılmaları, geri dönüş politikası için kesin seçimler olarak ele alınır; bu nedenle erişilemeyen seçilmiş bir sağlayıcı, agents.defaults.model.fallbacks tarafından maskelenmek 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 bilinen kötü birincili her iletide yoklamaz. OpenClaw yapılandırılmış kaynağı periyodik olarak yeniden yoklar ve toparlandığında otomatik geçersiz kılmayı temizler; /new, /reset ve sessions.reset otomatik kaynaklı geçersiz kılmaları hemen temizler.
• Kullanıcı yanıtları, geri dönüş geçişlerini ve geri dönüş temizlenmiş toparlanmayı durum değişikliği başına bir kez duyurur. Yapışkan geri dönüş turları bildirimi yinelemez.
• /status seçilen modeli ve geri dönüş durumu farklı olduğunda etkin geri dönüş modelini ve nedeni gösterir.
• Canlı oturum uzlaştırması, eski runtime model alanları yerine kalıcı oturum geçersiz kılmalarını tercih eder.
• Bir canlı değiştirme hatası etkin geri dönüş zincirindeki daha sonraki bir adayı işaret ediyorsa OpenClaw önce ilgisiz adaylar arasında yürümek yerine doğrudan o seçili 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â o başarısız adayla eşleşiyorlarsa geri alır.

Bu klasik yarışı önler:

Kalıcı geri dönüş geçersiz kılması bu pencereyi kapatır ve dar geri alma, daha yeni manuel veya runtime oturum değişikliklerini olduğu gibi tutar.

Gözlemlenebilirlik ve hata özetleri

runWithModelFallback(...), günlükleri ve kullanıcıya dönük bekleme süresi mesajlaşması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 devri 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, "tüm modeller geçici olarak hız sınırında" gibi daha belirli bir ileti oluşturmak ve biliniyorsa en yakın bekleme süresi bitimini eklemek için kullanabilir.

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

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

İlgili yapılandırma

Şunun için bkz. Gateway yapılandırması:

• 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 kapsamlı model seçimi ve yedek davranışı özeti için Modeller bölümüne bakın.