मॉडल फेलओवर

OpenClaw विफलताओं को दो चरणों में संभालता है:

1. मौजूदा प्रदाता के भीतर प्रमाणीकरण प्रोफ़ाइल रोटेशन।
2. agents.defaults.model.fallbacks में अगले मॉडल पर मॉडल फ़ॉलबैक।

यह दस्तावेज़ रनटाइम नियमों और उन्हें आधार देने वाले डेटा की व्याख्या करता है।

रनटाइम प्रवाह

सामान्य टेक्स्ट रन के लिए, OpenClaw उम्मीदवारों का मूल्यांकन इस क्रम में करता है:

यह जानबूझकर "पूरा सत्र सहेजें और बहाल करें" से अधिक संकीर्ण है। reply runner केवल उन मॉडल-चयन फ़ील्ड को कायम रखता है जिनका वह फ़ॉलबैक के लिए स्वामी है:

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

यह विफल फ़ॉलबैक पुनः प्रयास को नए, असंबंधित सत्र बदलावों को अधिलेखित करने से रोकता है, जैसे मैनुअल /model बदलाव या सत्र रोटेशन अपडेट जो प्रयास चलने के दौरान हुए थे।

चयन स्रोत नीति

OpenClaw चयनित प्रदाता/मॉडल को उससे अलग रखता है कि उसे क्यों चुना गया था। वही स्रोत नियंत्रित करता है कि फ़ॉलबैक श्रृंखला की अनुमति है या नहीं:

• कॉन्फ़िगर किया गया डिफ़ॉल्ट: agents.defaults.model.primary agents.defaults.model.fallbacks का उपयोग करता है।
• एजेंट प्राथमिक: agents.list[].model सख्त है, जब तक उस एजेंट मॉडल ऑब्जेक्ट में अपने fallbacks शामिल न हों। सख्त व्यवहार को स्पष्ट करने के लिए fallbacks: [] उपयोग करें, या उस एजेंट को मॉडल फ़ॉलबैक में शामिल करने के लिए गैर-रिक्त सूची दें।
• स्वतः फ़ॉलबैक ओवरराइड: रनटाइम फ़ॉलबैक पुनः प्रयास करने से पहले providerOverride, modelOverride, modelOverrideSource: "auto", और चयनित मूल मॉडल लिखता है। वह ऑटो ओवरराइड हर संदेश पर प्राथमिक को जांचे बिना कॉन्फ़िगर की गई फ़ॉलबैक श्रृंखला पर आगे बढ़ता रह सकता है, लेकिन OpenClaw समय-समय पर कॉन्फ़िगर किए गए मूल को फिर से जांचता है और उसके ठीक होने पर ऑटो ओवरराइड साफ़ कर देता है। /new, /reset, और sessions.reset भी ऑटो-स्रोत ओवरराइड साफ़ करते हैं। स्पष्ट heartbeat.model के बिना Heartbeat रन सीधे ऑटो ओवरराइड साफ़ करते हैं जब उनका मूल मौजूदा कॉन्फ़िगर किए गए डिफ़ॉल्ट से अब मेल नहीं खाता।
• उपयोगकर्ता सत्र ओवरराइड: /model, मॉडल पिकर, session_status(model=...), और sessions.patch modelOverrideSource: "user" लिखते हैं। यह एक सटीक सत्र चयन है। यदि चयनित प्रदाता/मॉडल उत्तर बनाने से पहले विफल होता है, तो OpenClaw किसी असंबंधित कॉन्फ़िगर किए गए फ़ॉलबैक से उत्तर देने के बजाय विफलता रिपोर्ट करता है।
• लेगेसी सत्र ओवरराइड: पुराने सत्र एंट्री में modelOverrideSource के बिना modelOverride हो सकता है। OpenClaw इन्हें उपयोगकर्ता ओवरराइड मानता है, ताकि कोई स्पष्ट पुराना चयन चुपचाप फ़ॉलबैक व्यवहार में परिवर्तित न हो।
• Cron पेलोड मॉडल: cron job payload.model / --model एक job primary है, उपयोगकर्ता सत्र ओवरराइड नहीं। यह कॉन्फ़िगर किए गए फ़ॉलबैक उपयोग करता है, जब तक job payload.fallbacks न दे; payload.fallbacks: [] cron रन को सख्त बनाता है।

ऑटो फ़ॉलबैक प्राथमिक-जांच अंतराल पांच मिनट है और कॉन्फ़िगर करने योग्य नहीं है। OpenClaw प्रति सत्र और प्राथमिक मॉडल हाल की जांचों को याद रखता है, ताकि विफल प्राथमिक को हर turn पर दोबारा न आज़माया जाए। जब कोई सत्र फ़ॉलबैक पर जाता है तो OpenClaw एक दृश्यमान सूचना भेजता है, और चयनित प्राथमिक पर लौटने पर दूसरी सूचना भेजता है; यह हर sticky fallback turn पर सूचना दोहराता नहीं है।

प्रमाणीकरण विफलता स्किप कैश

डिफ़ॉल्ट रूप से, हर नया turn मौजूदा फ़ॉलबैक पुनः प्रयास व्यवहार बनाए रखता है: OpenClaw हर कॉन्फ़िगर किए गए फ़ॉलबैक उम्मीदवार को फिर से आज़माएगा, जिसमें वे गैर-प्राथमिक उम्मीदवार भी शामिल हैं जो हाल ही में auth या auth_permanent के साथ विफल हुए थे।

जो ऑपरेटर इन दोहराई गई प्रमाणीकरण विफलताओं को दबाना पसंद करते हैं, वे इसके साथ opt in कर सकते हैं:

OPENCLAW_FALLBACK_SKIP_TTL_MS=60000

सक्षम होने पर, OpenClaw किसी प्रमाणीकरण-वर्ग विफलता के बाद गैर-प्राथमिक फ़ॉलबैक उम्मीदवार के लिए इन-मेमोरी, सत्र-स्कोप वाला स्किप मार्कर रिकॉर्ड करता है। मार्कर session id, प्रदाता, और मॉडल से keyed होता है। प्राथमिक उम्मीदवार कभी स्किप नहीं होते, इसलिए स्पष्ट उपयोगकर्ता मॉडल चयन फिर भी वास्तविक प्रमाणीकरण त्रुटि दिखाता है। कैश प्रक्रिया-स्थानीय है और Gateway restart पर साफ़ हो जाता है।

मान मिलीसेकंड में TTL है। 0 या unset मान कैश को अक्षम करता है। धनात्मक मान 1 सेकंड और 10 मिनट के बीच सीमित किए जाते हैं।

उपयोगकर्ता-दृश्य फ़ॉलबैक सूचनाएं

जब कोई सत्र स्वतः-चयनित फ़ॉलबैक पर जाता है, OpenClaw उसी reply surface में स्थिति सूचना भेजता है:

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

जब बाद की जांच सफल होती है और सत्र चयनित प्राथमिक पर लौटता है, OpenClaw भेजता है:

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

ये सूचनाएं संचालनात्मक संदेश हैं, assistant content नहीं। संभव होने पर इन्हें हर स्थिति बदलाव पर एक बार डिलीवर किया जाता है, जिसमें side-effect-only turns भी शामिल हैं, लेकिन sticky fallback turns इन्हें दोहराते नहीं हैं। डिलीवरी सामान्य source-reply suppression को बायपास करती है, सूचना threaded channels के लिए पहले assistant reply slot का उपभोग नहीं करती, और इसे text-to-speech तथा commitment extraction से बाहर रखा जाता है।

प्रमाणीकरण स्टोरेज (कुंजियां + OAuth)

OpenClaw API keys और OAuth tokens दोनों के लिए प्रमाणीकरण प्रोफ़ाइल उपयोग करता है।

• Secrets और रनटाइम auth-routing स्थिति ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite में रहती है।
• Config auth.profiles / auth.order केवल metadata + routing हैं (कोई secrets नहीं)।
• लेगेसी import-only OAuth फ़ाइल: ~/.openclaw/credentials/oauth.json (पहले उपयोग पर per-agent auth store में आयात की जाती है)।
• लेगेसी auth-profiles.json, auth-state.json, और per-agent auth.json फ़ाइलें openclaw doctor --fix द्वारा आयात की जाती हैं।

अधिक विवरण: OAuth

क्रेडेंशियल प्रकार:

• type: "api_key" → { provider, key }
• type: "oauth" → { provider, access, refresh, expires, email? } (कुछ प्रदाताओं के लिए + projectId/enterpriseUrl)

प्रोफ़ाइल ID

OAuth लॉगिन अलग-अलग प्रोफ़ाइल बनाते हैं ताकि कई खाते साथ-साथ रह सकें।

• डिफ़ॉल्ट: जब कोई ईमेल उपलब्ध न हो तो provider:default।
• ईमेल के साथ OAuth: provider:<email> (उदाहरण के लिए google-antigravity:user@gmail.com)।

प्रोफ़ाइल प्रति-एजेंट openclaw-agent.sqlite auth प्रोफ़ाइल स्टोर में रहती हैं।

रोटेशन क्रम

जब किसी प्रदाता के पास कई प्रोफ़ाइल हों, तो OpenClaw इस तरह का क्रम चुनता है:

यदि कोई स्पष्ट क्रम कॉन्फ़िगर नहीं है, तो OpenClaw राउंड-रॉबिन क्रम का उपयोग करता है:

• प्राथमिक कुंजी: प्रोफ़ाइल प्रकार (API keys से पहले OAuth)।
• द्वितीयक कुंजी: usageStats.lastUsed (प्रत्येक प्रकार के भीतर सबसे पुराना पहले)।
• Cooldown/disabled profiles को अंत में ले जाया जाता है, निकटतम समाप्ति के अनुसार क्रमबद्ध।

सेशन स्टिकिनेस (कैश-अनुकूल)

प्रदाता कैश को गर्म रखने के लिए OpenClaw चुनी गई auth प्रोफ़ाइल को प्रति सेशन पिन करता है। यह हर अनुरोध पर रोटेट नहीं करता। पिन की गई प्रोफ़ाइल तब तक पुनः उपयोग होती है जब तक:

• सेशन रीसेट हो (/new / /reset)
• कोई Compaction पूरी हो जाए (Compaction गणना बढ़ती है)
• प्रोफ़ाइल cooldown/disabled में हो

/model …@<profileId> के जरिए मैन्युअल चयन उस सेशन के लिए उपयोगकर्ता ओवरराइड सेट करता है और नया सेशन शुरू होने तक अपने आप रोटेट नहीं होता।

OpenAI Codex सब्सक्रिप्शन और API-key बैकअप

OpenAI एजेंट मॉडल के लिए, auth और रनटाइम अलग-अलग हैं। openai/gpt-* Codex harness पर रहता है, जबकि auth Codex सब्सक्रिप्शन प्रोफ़ाइल और OpenAI API-key बैकअप के बीच रोटेट कर सकता है।

उपयोगकर्ता-सामने आने वाले क्रम के लिए auth.order.openai का उपयोग करें:

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

ChatGPT/Codex OAuth प्रोफ़ाइल और OpenAI API-key प्रोफ़ाइल, दोनों के लिए openai:* का उपयोग करें। जब सब्सक्रिप्शन Codex उपयोग सीमा तक पहुँचता है, तो Codex द्वारा उपलब्ध कराए जाने पर OpenClaw सटीक रीसेट समय रिकॉर्ड करता है, अगली क्रमबद्ध auth प्रोफ़ाइल आज़माता है, और रन को Codex harness के भीतर रखता है। रीसेट समय बीत जाने के बाद, सब्सक्रिप्शन प्रोफ़ाइल फिर पात्र हो जाती है और अगला स्वचालित चयन उस पर लौट सकता है।

उपयोगकर्ता-पिन की गई प्रोफ़ाइल का उपयोग केवल तब करें जब आप उस सेशन के लिए एक खाते/key को बाध्य करना चाहते हों। उपयोगकर्ता-पिन की गई प्रोफ़ाइल जानबूझकर सख्त होती हैं और चुपचाप दूसरी प्रोफ़ाइल पर नहीं जातीं।

Cooldowns

जब कोई प्रोफ़ाइल auth/rate-limit त्रुटियों (या rate limiting जैसी दिखने वाली timeout) के कारण विफल होती है, तो OpenClaw उसे cooldown में चिह्नित करता है और अगली प्रोफ़ाइल पर चला जाता है।

कूलडाउन exponential backoff का उपयोग करते हैं:

• 1 मिनट
• 5 मिनट
• 25 मिनट
• 1 घंटा (सीमा)

स्थिति प्रति-एजेंट SQLite प्रमाणीकरण स्थिति में usageStats के अंतर्गत संग्रहीत होती है:

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

बिलिंग अक्षम

बिलिंग/क्रेडिट विफलताओं (उदाहरण के लिए "insufficient credits" / "credit balance too low") को फेलओवर-योग्य माना जाता है, लेकिन वे आमतौर पर अस्थायी नहीं होतीं। छोटे कूलडाउन के बजाय, OpenClaw प्रोफ़ाइल को अक्षम के रूप में चिह्नित करता है (लंबे backoff के साथ) और अगली प्रोफ़ाइल/प्रदाता पर घूमता है।

स्थिति प्रति-एजेंट SQLite प्रमाणीकरण स्थिति में संग्रहीत होती है:

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

डिफ़ॉल्ट:

• बिलिंग backoff 5 घंटे से शुरू होता है, प्रत्येक बिलिंग विफलता पर दोगुना होता है, और 24 घंटे पर सीमित होता है।
• यदि प्रोफ़ाइल 24 घंटे तक विफल नहीं हुई है तो backoff काउंटर रीसेट हो जाते हैं (कॉन्फ़िगर करने योग्य)।
• ओवरलोडेड retries मॉडल फॉलबैक से पहले 1 समान-प्रदाता प्रोफ़ाइल रोटेशन की अनुमति देती हैं।
• ओवरलोडेड retries डिफ़ॉल्ट रूप से 0 ms backoff का उपयोग करती हैं।

मॉडल फॉलबैक

यदि किसी प्रदाता की सभी प्रोफ़ाइल विफल हो जाती हैं, तो OpenClaw agents.defaults.model.fallbacks में अगले मॉडल पर चला जाता है। यह प्रमाणीकरण विफलताओं, दर सीमाओं, और उन timeouts पर लागू होता है जिनमें प्रोफ़ाइल रोटेशन समाप्त हो चुका है (अन्य त्रुटियां फॉलबैक को आगे नहीं बढ़ातीं)। जो प्रदाता त्रुटियां पर्याप्त विवरण उजागर नहीं करतीं, उन्हें फिर भी फॉलबैक स्थिति में सटीक रूप से लेबल किया जाता है: empty_response का अर्थ है कि प्रदाता ने कोई उपयोगी संदेश या स्थिति नहीं लौटाई, no_error_details का अर्थ है कि प्रदाता ने स्पष्ट रूप से Unknown error (no error details in response) लौटाया, और unclassified का अर्थ है कि OpenClaw ने raw preview सुरक्षित रखा लेकिन अभी तक कोई classifier उससे मेल नहीं खाया।

ओवरलोडेड और दर-सीमा त्रुटियों को बिलिंग कूलडाउन की तुलना में अधिक आक्रामक रूप से संभाला जाता है। डिफ़ॉल्ट रूप से, OpenClaw एक समान-प्रदाता auth-profile retry की अनुमति देता है, फिर बिना प्रतीक्षा किए अगले कॉन्फ़िगर किए गए मॉडल फॉलबैक पर स्विच करता है। ModelNotReadyException जैसे provider-busy संकेत उस ओवरलोडेड bucket में आते हैं। इसे auth.cooldowns.overloadedProfileRotations, auth.cooldowns.overloadedBackoffMs, और auth.cooldowns.rateLimitedProfileRotations से समायोजित करें।

जब कोई रन कॉन्फ़िगर किए गए डिफ़ॉल्ट primary, किसी Cron job primary, स्पष्ट fallbacks वाले agent primary, या auto-selected fallback override से शुरू होता है, तो OpenClaw मिलती-जुलती कॉन्फ़िगर की गई fallback chain पर चल सकता है। स्पष्ट fallbacks के बिना agent primaries और स्पष्ट उपयोगकर्ता चयन (उदाहरण के लिए /model ollama/qwen3.5:27b, model picker, sessions.patch, या one-off CLI प्रदाता/मॉडल overrides) strict होते हैं: यदि वह प्रदाता/मॉडल पहुंच योग्य नहीं है या उत्तर देने से पहले विफल हो जाता है, तो OpenClaw किसी असंबंधित fallback से उत्तर देने के बजाय विफलता रिपोर्ट करता है।

Candidate chain नियम

OpenClaw मौजूदा अनुरोधित provider/model और कॉन्फ़िगर किए गए fallbacks से candidate सूची बनाता है।

कौन सी त्रुटियां फॉलबैक को आगे बढ़ाती हैं

Cooldown skip बनाम probe व्यवहार

जब किसी प्रदाता की हर auth profile पहले से ही कूलडाउन में हो, तो OpenClaw उस प्रदाता को हमेशा के लिए अपने-आप skip नहीं करता। यह प्रति-candidate निर्णय लेता है:

Session overrides और live model switching

Session model changes साझा स्थिति हैं। active runner, /model command, compaction/session updates, और live-session reconciliation सभी उसी session entry के हिस्सों को पढ़ते या लिखते हैं।

इसका अर्थ है कि fallback retries को live model switching के साथ समन्वय करना होगा:

• केवल स्पष्ट user-driven model changes pending live switch चिह्नित करते हैं। इसमें /model, session_status(model=...), और sessions.patch शामिल हैं।
• system-driven model changes जैसे fallback rotation, Heartbeat overrides, या Compaction अपने-आप pending live switch चिह्नित नहीं करते।
• User-driven model overrides को fallback policy के लिए exact selections माना जाता है, इसलिए unreachable selected provider agents.defaults.model.fallbacks से छिपने के बजाय failure के रूप में सामने आता है।
• fallback retry शुरू होने से पहले, reply runner selected fallback override fields को session entry में persist करता है।
• Auto fallback overrides बाद के turns पर selected रहते हैं ताकि OpenClaw हर message पर known-bad primary को probe न करे। OpenClaw समय-समय पर configured origin को फिर से probe करता है और recover होने पर auto override साफ़ करता है; /new, /reset, और sessions.reset auto-sourced overrides को तुरंत साफ़ करते हैं।
• User replies fallback transitions और fallback-cleared recovery को प्रति state change एक बार announce करते हैं। Sticky fallback turns notice को दोहराते नहीं हैं।
• /status selected model दिखाता है और, जब fallback state अलग हो, active fallback model और reason भी दिखाता है।
• Live-session reconciliation stale runtime model fields की तुलना में persisted session overrides को प्राथमिकता देता है।
• यदि live-switch error active fallback chain में किसी later candidate की ओर इशारा करती है, तो OpenClaw पहले unrelated candidates पर चलने के बजाय सीधे उस selected model पर जाता है।
• यदि fallback attempt विफल होती है, तो runner केवल उन override fields को rollback करता है जिन्हें उसने लिखा था, और केवल तभी जब वे अब भी उस failed candidate से मेल खाते हों।

यह classic race को रोकता है:

persisted fallback override उस window को बंद करता है, और narrow rollback नए manual या runtime session changes को intact रखता है।

Observability और failure summaries

runWithModelFallback(...) प्रति-attempt details रिकॉर्ड करता है जो logs और user-facing cooldown messaging को feed करती हैं:

• आज़माया गया provider/model
• reason (rate_limit, overloaded, billing, auth, model_not_found, और समान failover reasons)
• optional status/code
• human-readable error summary

Structured model_fallback_decision logs में flat fallbackStep* fields भी शामिल होते हैं जब कोई candidate विफल होता है, skip होता है, या कोई later fallback सफल होता है। ये fields attempted transition को explicit बनाते हैं (fallbackStepFromModel, fallbackStepToModel, fallbackStepFromFailureReason, fallbackStepFromFailureDetail, fallbackStepFinalOutcome) ताकि log और diagnostic exporters terminal fallback भी विफल होने पर भी primary failure को reconstruct कर सकें।

जब हर candidate विफल हो जाता है, OpenClaw FallbackSummaryError throw करता है। outer reply runner इसका उपयोग अधिक specific message बनाने के लिए कर सकता है, जैसे "all models are temporarily rate-limited", और known होने पर soonest cooldown expiry शामिल कर सकता है।

वह cooldown summary model-aware है:

• unrelated model-scoped rate limits को attempted provider/model chain के लिए ignore किया जाता है
• यदि remaining block matching model-scoped rate limit है, तो OpenClaw आख़िरी matching expiry रिपोर्ट करता है जो अब भी उस model को block करती है

संबंधित config

Gateway configuration देखें इनके लिए:

• 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 रूटिंग

व्यापक मॉडल चयन और फ़ॉलबैक अवलोकन के लिए मॉडल देखें।