मॉडल फ़ेलओवर

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

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

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

सत्र स्थिति का समाधान करें

सक्रिय सत्र मॉडल और प्रमाणीकरण-प्रोफ़ाइल वरीयता का समाधान करें।

उम्मीदवार शृंखला बनाएँ

वर्तमान मॉडल चयन और उस चयन स्रोत की फ़ॉलबैक नीति से मॉडल उम्मीदवार शृंखला बनाएँ। कॉन्फ़िगर किए गए डिफ़ॉल्ट, Cron जॉब के प्राथमिक मॉडल और स्वतः चयनित फ़ॉलबैक मॉडल कॉन्फ़िगर किए गए फ़ॉलबैक का उपयोग कर सकते हैं; स्पष्ट उपयोगकर्ता सत्र चयन सख्त होते हैं।

वर्तमान प्रदाता को आज़माएँ

प्रमाणीकरण-प्रोफ़ाइल रोटेशन/कूलडाउन नियमों के साथ वर्तमान प्रदाता को आज़माएँ।

फ़ेलओवर योग्य त्रुटियों पर आगे बढ़ें

यदि वह प्रदाता फ़ेलओवर योग्य त्रुटि के साथ समाप्त हो जाता है, तो अगले मॉडल उम्मीदवार पर जाएँ।

वर्तमान टर्न के लिए फ़ॉलबैक का उपयोग करें

सत्र के चयनित प्रदाता/मॉडल को बदले बिना सफल फ़ॉलबैक उम्मीदवार चलाएँ।

सुरक्षित शुद्ध ओवरलोड समाप्ति पर पुनः प्रयास करें

यदि प्रत्येक उम्मीदवार केवल प्रदाताओं के ओवरलोड होने के कारण विफल होता है, तो जब तक कोई टूल निष्पादन या सहायक आउटपुट शुरू न हुआ हो, एक्सपोनेंशियल बैकऑफ़ के साथ पूरी टर्न-स्थानीय शृंखला को अधिकतम 10 बार पुनः आज़माएँ। 30 सेकंड के बाद एक स्थिति सूचना भेजें, ताकि उपयोगकर्ता को चुपचाप प्रतीक्षा न करनी पड़े।

समाप्त होने पर FallbackSummaryError थ्रो करें

यदि प्रत्येक उम्मीदवार विफल होता है, तो प्रति-प्रयास विवरण और ज्ञात होने पर निकटतम कूलडाउन समाप्ति के साथ एक FallbackSummaryError थ्रो करें।

फ़ॉलबैक निष्पादन टर्न-स्थानीय होता है। उत्तर रनर केवल फ़ॉलबैक सूचना स्थिति को बनाए रखता है, ताकि /status और संक्रमण सूचनाएँ चयनित मॉडल तथा उत्तर देने वाले मॉडल के बीच अंतर कर सकें; यह फ़ॉलबैक को अगले टर्न के मॉडल चयन के रूप में बनाए नहीं रखता।

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

चयन स्रोत नियंत्रित करता है कि फ़ॉलबैक शृंखला की अनुमति है या नहीं:

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

जब कोई टर्न फ़ॉलबैक पर जाता है, तो OpenClaw एक दृश्यमान सूचना भेजता है और जब बाद का कोई टर्न चयनित प्राथमिक मॉडल पर सफल होता है, तो दूसरी सूचना भेजता है। संरक्षित सूचना स्थिति लगातार टर्न में एक ही चयनित/सक्रिय युग्म का उपयोग होने पर दोहराई जाने वाली सूचनाओं को रोकती है, जबकि मॉडल चयन स्वयं अपरिवर्तित रहता है।

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

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

OPENCLAW_FALLBACK_SKIP_TTL_MS=60000

सक्षम होने पर, OpenClaw प्रमाणीकरण-श्रेणी की विफलता के बाद किसी गैर-प्राथमिक फ़ॉलबैक उम्मीदवार के लिए इन-मेमोरी, सत्र-स्कोप वाला स्किप मार्कर दर्ज करता है, जिसकी कुंजी सत्र आईडी, प्रदाता और मॉडल होती है। प्राथमिक उम्मीदवारों को कभी स्किप नहीं किया जाता, इसलिए स्पष्ट उपयोगकर्ता मॉडल चयन में वास्तविक प्रमाणीकरण त्रुटि अब भी दिखाई देती है। कैश प्रक्रिया-स्थानीय है और Gateway के पुनरारंभ होने पर साफ़ हो जाता है। यह मान मिलीसेकंड में TTL है। 0 या इसका सेट न होना कैश को अक्षम करता है। धनात्मक मानों को 1 सेकंड और 10 मिनट के बीच सीमित किया जाता है।

उपयोगकर्ता को दिखाई देने वाली फ़ॉलबैक सूचनाएँ

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

↪️ मॉडल फ़ॉलबैक: <fallback> (चयनित <primary>; <reason>)

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

↪️ मॉडल फ़ॉलबैक हटाया गया: <primary> (पहले <fallback>)

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

प्रमाणीकरण संग्रहण (कुंजियाँ + OAuth)

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

सीक्रेट और रनटाइम प्रमाणीकरण-रूटिंग स्थिति ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite में रहती है।
कॉन्फ़िगरेशन auth.profiles / auth.order केवल मेटाडेटा + रूटिंग हैं (कोई सीक्रेट नहीं)।
केवल आयात के लिए लेगेसी OAuth फ़ाइल: ~/.openclaw/credentials/oauth.json (पहली बार उपयोग करने पर प्रति-एजेंट प्रमाणीकरण स्टोर में आयात की जाती है)।
लेगेसी auth-profiles.json, auth-state.json, और प्रति-एजेंट auth.json फ़ाइलें openclaw doctor --fix द्वारा आयात की जाती हैं।

अधिक विवरण: OAuth क्रेडेंशियल प्रकार:

type: "api_key" → { provider, key }
type: "oauth" → { provider, access, refresh, expires, email? } (कुछ प्रदाताओं के लिए + projectId/enterpriseUrl)
type: "token" → स्थिर बेयरर-शैली टोकन, जो वैकल्पिक रूप से समाप्त हो सकता है; OpenClaw इसे रीफ़्रेश नहीं करता (aws-sdk और अन्य क्रेडेंशियल-शृंखला प्रमाणीकरण मोड के लिए उपयोग किया जाता है)

प्रोफ़ाइल आईडी

OAuth लॉगिन अलग-अलग प्रोफ़ाइल बनाते हैं, ताकि एकाधिक खाते एक साथ मौजूद रह सकें।

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

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

रोटेशन क्रम

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

स्पष्ट कॉन्फ़िगरेशन

auth.order[provider] (यदि सेट हो)।

कॉन्फ़िगर की गई प्रोफ़ाइल

प्रदाता के आधार पर फ़िल्टर किया गया auth.profiles।

संग्रहीत प्रोफ़ाइल

प्रदाता के लिए प्रति-एजेंट SQLite प्रमाणीकरण प्रोफ़ाइल प्रविष्टियाँ।

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

प्राथमिक कुंजी: प्रोफ़ाइल प्रकार (OAuth, फिर स्थिर टोकन, फिर API कुंजी)।
OAuth के लिए द्वितीयक कुंजी: वर्तमान में उपयोग योग्य एक्सेस टोकन वाली प्रोफ़ाइल, समाप्त एक्सेस टोकन वाली प्रोफ़ाइल से पहले। समाप्त OAuth प्रोफ़ाइल पात्र बनी रहती हैं, ताकि कोई उपयोग योग्य समकक्ष उपलब्ध न होने पर रनटाइम उन्हें रीफ़्रेश कर सके।
अगली कुंजी: usageStats.lastUsed (प्रत्येक प्रकार/स्थिति स्तर के भीतर सबसे पुरानी पहले)।
कूलडाउन/अक्षम प्रोफ़ाइल को सबसे निकट समाप्ति के क्रम में अंत में भेज दिया जाता है।

सत्र स्थिरता (कैश-अनुकूल)

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

सत्र रीसेट न हो (/new / /reset)
Compaction पूरी न हो (Compaction संख्या बढ़ती है)
प्रोफ़ाइल कूलडाउन/अक्षम स्थिति में न हो

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

स्वतः पिन की गई प्रोफ़ाइल (सत्र राउटर द्वारा चयनित) को वरीयता माना जाता है: उन्हें पहले आज़माया जाता है, लेकिन दर सीमाओं/टाइमआउट पर OpenClaw किसी अन्य प्रोफ़ाइल पर रोटेट कर सकता है। मूल प्रोफ़ाइल के फिर उपलब्ध होने पर, नए रन चयनित मॉडल या रनटाइम को बदले बिना उसे फिर से प्राथमिकता दे सकते हैं। उपयोगकर्ता द्वारा पिन की गई प्रोफ़ाइल उसी प्रोफ़ाइल पर लॉक रहती हैं; यदि वह विफल होती है और मॉडल फ़ॉलबैक कॉन्फ़िगर हैं, तो OpenClaw प्रोफ़ाइल बदलने के बजाय अगले मॉडल पर चला जाता है।

OpenAI Codex सदस्यता और API-कुंजी बैकअप

OpenAI एजेंट मॉडल के लिए प्रमाणीकरण और रनटाइम अलग-अलग होते हैं। openai/gpt-*, Codex हार्नेस पर बना रहता है, जबकि प्रमाणीकरण Codex सदस्यता प्रोफ़ाइल और OpenAI API-कुंजी बैकअप के बीच रोटेट कर सकता है। उपयोगकर्ता को दिखाई देने वाले क्रम के लिए auth.order.openai का उपयोग करें:

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

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

कूलडाउन

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

दर-सीमा / टाइमआउट बकेट में क्या आता है

वह दर-सीमा बकेट केवल 429 से व्यापक है: इसमें Too many concurrent requests, ThrottlingException, concurrency limit reached, workers_ai ... quota limit exceeded, throttled, resource exhausted जैसे प्रदाता संदेश और weekly limit reached या monthly limit exhausted जैसी आवधिक उपयोग-विंडो सीमाएँ भी शामिल हैं।प्रारूप/अमान्य-अनुरोध त्रुटियाँ आम तौर पर अंतिम होती हैं, क्योंकि उसी पेलोड को पुनः आज़माने पर वह उसी तरह विफल होगा, इसलिए OpenClaw प्रमाणीकरण प्रोफ़ाइल रोटेट करने के बजाय उन्हें प्रदर्शित करता है। ज्ञात पुनः प्रयास-मरम्मत पथ स्पष्ट रूप से शामिल हो सकते हैं: उदाहरण के लिए, Cloud Code Assist टूल कॉल आईडी सत्यापन विफलताओं को स्वच्छ किया जाता है और allowFormatRetry नीति के माध्यम से एक बार पुनः आज़माया जाता है।OpenAI-संगत प्रदाता-पूर्ण किए गए स्टॉप/फ़िनिश कारण, जैसे Unhandled stop reason: error, stop reason: error, reason: error, और Provider finish_reason: error, टाइमआउट नहीं, बल्कि server_error (HTTP-जैसी स्थिति 500) के रूप में वर्गीकृत किए जाते हैं। वे मॉडल/प्रोफ़ाइल रोटेशन के लिए फ़ेलओवर-पात्र बने रहते हैं, लेकिन निदान उपयोगकर्ता प्रति को “LLM अनुरोध का समय समाप्त हो गया।” के रूप में दोबारा लिखने के बजाय प्रदाता का फ़िनिश-कारण टेक्स्ट बनाए रखता है। Provider finish_reason: abort, network_error, और malformed_response जैसे ट्रांसपोर्ट-आकार वाले फ़िनिश कारण टाइमआउट/फ़ेलओवर बकेट (स्थिति 408) में बने रहते हैं।जब स्रोत किसी ज्ञात क्षणिक पैटर्न से मेल खाता है, तो सामान्य सर्वर टेक्स्ट भी उस टाइमआउट बकेट में आ सकता है। उदाहरण के लिए, सादा मॉडल रनटाइम स्ट्रीम-रैपर संदेश An unknown error occurred को प्रत्येक प्रदाता के लिए फ़ेलओवर योग्य माना जाता है, क्योंकि साझा मॉडल रनटाइम इसे तब उत्सर्जित करता है, जब प्रदाता स्ट्रीम बिना विशिष्ट विवरण के stopReason: "aborted" या stopReason: "error" के साथ समाप्त होती हैं। internal server error, unknown error, 520, upstream error, या backend error जैसे क्षणिक सर्वर टेक्स्ट वाले JSON api_error पेलोड को भी फ़ेलओवर योग्य टाइमआउट माना जाता है।OpenRouter-विशिष्ट सामान्य अपस्ट्रीम टेक्स्ट, जैसे केवल Provider returned error, को टाइमआउट केवल तभी माना जाता है जब प्रोवाइडर संदर्भ वास्तव में OpenRouter हो। सामान्य आंतरिक फ़ॉलबैक टेक्स्ट, जैसे LLM request failed with an unknown error., सतर्क बना रहता है और स्वयं फ़ेलओवर ट्रिगर नहीं करता।

SDK retry-after सीमाएँ

अन्यथा कुछ प्रोवाइडर SDK, OpenClaw को नियंत्रण वापस देने से पहले लंबे Retry-After अंतराल तक प्रतीक्षा कर सकते हैं। Anthropic और OpenAI जैसे Stainless-आधारित SDK के लिए, OpenClaw डिफ़ॉल्ट रूप से SDK-आंतरिक retry-after-ms / retry-after प्रतीक्षा को 60 सेकंड तक सीमित करता है और अधिक लंबी पुनः प्रयास योग्य प्रतिक्रियाओं को तुरंत सामने लाता है, ताकि यह फ़ेलओवर पथ चल सके। OPENCLAW_SDK_RETRY_MAX_WAIT_SECONDS से सीमा समायोजित या अक्षम करें; पुनः प्रयास व्यवहार देखें।

मॉडल-सीमित कूलडाउन

दर-सीमा कूलडाउन मॉडल तक भी सीमित हो सकते हैं:

विफल मॉडल आईडी ज्ञात होने पर OpenClaw दर-सीमा विफलताओं के लिए cooldownModel रिकॉर्ड करता है।
जब कूलडाउन किसी अलग मॉडल तक सीमित हो, तब भी उसी प्रोवाइडर पर किसी सहोदर मॉडल को आज़माया जा सकता है।
बिलिंग/अक्षम अवधियाँ अब भी सभी मॉडलों में पूरी प्रोफ़ाइल को अवरुद्ध करती हैं।

नियमित (गैर-बिलिंग, गैर-स्थायी-प्रमाणीकरण) कूलडाउन प्रोफ़ाइल की हाल की त्रुटियों की संख्या के अनुसार बढ़ते हैं:

पहली विफलता: 30 सेकंड
दूसरी विफलता: 1 मिनट
तीसरी या बाद की विफलता: 5 मिनट (अधिकतम सीमा)

प्रोफ़ाइल की अंतर्निहित विफलता अवधि बीत जाने पर काउंटर रीसेट हो जाते हैं। स्थिति को प्रति-एजेंट SQLite प्रमाणीकरण स्थिति में usageStats के अंतर्गत संग्रहीत किया जाता है:

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

बिलिंग के कारण अक्षमता

बिलिंग/क्रेडिट विफलताओं (उदाहरण के लिए “अपर्याप्त क्रेडिट” / “क्रेडिट शेष बहुत कम”) को फ़ेलओवर योग्य माना जाता है, लेकिन वे आम तौर पर अस्थायी नहीं होतीं। छोटे कूलडाउन के बजाय, OpenClaw प्रोफ़ाइल को अक्षम चिह्नित करता है (अधिक लंबे बैकऑफ़ के साथ) और अगली प्रोफ़ाइल/प्रोवाइडर पर चला जाता है।

बिलिंग जैसी दिखने वाली हर प्रतिक्रिया 402 नहीं होती, और प्रत्येक HTTP 402 यहाँ नहीं आता। प्रोवाइडर द्वारा इसके बजाय 401 या 403 लौटाए जाने पर भी OpenClaw स्पष्ट बिलिंग टेक्स्ट को बिलिंग श्रेणी में रखता है, लेकिन प्रोवाइडर-विशिष्ट मिलानकर्ता अपने स्वामी प्रोवाइडर तक सीमित रहते हैं (उदाहरण के लिए OpenRouter 403 Key limit exceeded)।इस बीच, अस्थायी 402 उपयोग-अवधि और संगठन/वर्कस्पेस खर्च-सीमा त्रुटियों को संदेश पुनः प्रयास योग्य दिखने पर rate_limit के रूप में वर्गीकृत किया जाता है (उदाहरण के लिए weekly usage limit exhausted, daily limit reached, resets tomorrow, या organization spending limit exceeded)। वे लंबे बिलिंग-अक्षमता पथ के बजाय छोटे कूलडाउन/फ़ेलओवर पथ पर रहती हैं।

उच्च-विश्वास वाली स्थायी प्रमाणीकरण विफलताओं (निरस्त/निष्क्रिय कुंजियाँ, निष्क्रिय वर्कस्पेस) को समान अक्षम श्रेणी मिलती है, लेकिन वे बिलिंग की तुलना में बहुत जल्दी पुनः सक्रिय होती हैं, क्योंकि कुछ प्रोवाइडर घटनाओं के दौरान अस्थायी रूप से प्रमाणीकरण जैसे दिखने वाले पेलोड प्रस्तुत करते हैं। स्थिति को प्रति-एजेंट SQLite प्रमाणीकरण स्थिति में संग्रहीत किया जाता है:

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

अतिभार और दर-सीमा त्रुटियों को बिलिंग कूलडाउन की तुलना में अधिक आक्रामक रूप से संभाला जाता है: डिफ़ॉल्ट रूप से, OpenClaw उसी प्रोवाइडर की प्रमाणीकरण-प्रोफ़ाइल पर एक पुनः प्रयास की अनुमति देता है, फिर बिना प्रतीक्षा किए अगले कॉन्फ़िगर किए गए मॉडल फ़ॉलबैक पर चला जाता है।

मॉडल फ़ॉलबैक

यदि किसी प्रोवाइडर की सभी प्रोफ़ाइल विफल हो जाती हैं, तो OpenClaw agents.defaults.model.fallbacks में अगले मॉडल पर चला जाता है। यह उन प्रमाणीकरण विफलताओं, दर सीमाओं और टाइमआउट पर लागू होता है जिनमें प्रोफ़ाइल रोटेशन समाप्त हो चुका है (अन्य त्रुटियाँ फ़ॉलबैक को आगे नहीं बढ़ातीं)। पर्याप्त विवरण न देने वाली प्रोवाइडर त्रुटियों को भी फ़ॉलबैक स्थिति में सटीक लेबल मिलता है: empty_response का अर्थ है कि प्रोवाइडर ने कोई उपयोग योग्य संदेश या स्थिति नहीं लौटाई, no_error_details का अर्थ है कि प्रोवाइडर ने स्पष्ट रूप से Unknown error (no error details in response) लौटाया, और unclassified का अर्थ है कि OpenClaw ने मूल पूर्वावलोकन सुरक्षित रखा लेकिन अभी तक कोई वर्गीकारक उससे मेल नहीं खाया। ModelNotReadyException जैसे प्रोवाइडर-व्यस्त संकेत अतिभारित श्रेणी में आते हैं और दर सीमाओं की तरह एक-रोटेशन-फिर-फ़ॉलबैक नीति का पालन करते हैं (ऊपर डिफ़ॉल्ट तालिका देखें)। यदि पूरी उम्मीदवार शृंखला केवल अतिभार विफलताओं के कारण समाप्त होती है, तो उत्तर रनर उसी टर्न में शृंखला को अधिकतम 10 बार पुनः आज़माता है। पूरे टर्न का पुनः प्रयास केवल टूल निष्पादन या सहायक आउटपुट आरंभ होने से पहले अनुमत है, ताकि देखने योग्य कार्य के बाद अतिभार आने पर दोहराए गए परिवर्तन या संदेश न बनें। बैकऑफ़ 2.5 सेकंड से आरंभ होता है और दोगुना होकर 30-सेकंड की अधिकतम सीमा तक पहुँचता है। टर्न के 30 सेकंड तक प्रतीक्षा करने के बाद, OpenClaw एक अस्थायी स्थिति सूचना भेजता है: The AI service is temporarily overloaded. I’m still retrying; this may take a few minutes. पुनः प्रयास और कोई भी विजेता फ़ॉलबैक टर्न तक सीमित रहते हैं; सामान्य अस्थायी सर्वर त्रुटियाँ अपनी अलग एक-पुनः-प्रयास नीति बनाए रखती हैं। जब कोई रन कॉन्फ़िगर किए गए डिफ़ॉल्ट प्राथमिक, Cron जॉब प्राथमिक, स्पष्ट फ़ॉलबैक वाले एजेंट प्राथमिक, या स्वतः चयनित फ़ॉलबैक ओवरराइड से आरंभ होता है, तो OpenClaw मेल खाने वाली कॉन्फ़िगर की गई फ़ॉलबैक शृंखला पर आगे बढ़ सकता है। स्पष्ट फ़ॉलबैक के बिना एजेंट प्राथमिक और स्पष्ट उपयोगकर्ता चयन (उदाहरण के लिए /model ollama/qwen3.5:27b, मॉडल चयनकर्ता, sessions.patch, या एकबारगी CLI प्रोवाइडर/मॉडल ओवरराइड) सख्त होते हैं: यदि वह प्रोवाइडर/मॉडल पहुँच योग्य नहीं है या उत्तर देने से पहले विफल होता है, तो OpenClaw किसी असंबंधित फ़ॉलबैक से उत्तर देने के बजाय विफलता की सूचना देता है।

उम्मीदवार शृंखला के नियम

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

नियम

अनुरोधित मॉडल हमेशा पहले होता है।
स्पष्ट रूप से कॉन्फ़िगर किए गए फ़ॉलबैक की डुप्लिकेट प्रविष्टियाँ हटाई जाती हैं, लेकिन उन्हें मॉडल अनुमति-सूची के आधार पर फ़िल्टर नहीं किया जाता। उन्हें ऑपरेटर की स्पष्ट मंशा माना जाता है।
यदि वर्तमान रन पहले से उसी प्रोवाइडर परिवार के किसी कॉन्फ़िगर किए गए फ़ॉलबैक पर है, तो OpenClaw पूरी कॉन्फ़िगर की गई शृंखला का उपयोग जारी रखता है।
जब कोई स्पष्ट फ़ॉलबैक ओवरराइड नहीं दिया जाता, तो अनुरोधित मॉडल द्वारा किसी अलग प्रोवाइडर का उपयोग किए जाने पर भी कॉन्फ़िगर किए गए फ़ॉलबैक को कॉन्फ़िगर किए गए प्राथमिक से पहले आज़माया जाता है।
जब फ़ॉलबैक रनर को कोई स्पष्ट फ़ॉलबैक ओवरराइड नहीं दिया जाता, तो कॉन्फ़िगर किए गए प्राथमिक को अंत में जोड़ा जाता है, ताकि पहले के उम्मीदवार समाप्त होने पर शृंखला सामान्य डिफ़ॉल्ट पर वापस स्थिर हो सके।
जब कोई कॉलर fallbacksOverride देता है, तो रनर केवल अनुरोधित मॉडल और उस ओवरराइड सूची का उपयोग करता है। खाली सूची मॉडल फ़ॉलबैक को अक्षम करती है और कॉन्फ़िगर किए गए प्राथमिक को छिपे हुए पुनः प्रयास लक्ष्य के रूप में जोड़े जाने से रोकती है।

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

इन पर जारी रहता है
इन पर जारी नहीं रहता

प्रमाणीकरण विफलताएँ
दर सीमाएँ और कूलडाउन समाप्ति
अतिभारित/प्रोवाइडर-व्यस्त त्रुटियाँ
टाइमआउट जैसी दिखने वाली फ़ेलओवर त्रुटियाँ
बिलिंग के कारण अक्षमता
LiveSessionModelSwitchError, जिसे फ़ेलओवर पथ में सामान्यीकृत किया जाता है, ताकि पुराना संग्रहीत मॉडल बाहरी पुनः प्रयास लूप न बनाए
जब अभी भी उम्मीदवार शेष हों, तब अन्य अपरिचित त्रुटियाँ

स्पष्ट निरस्तीकरण जो टाइमआउट/फ़ेलओवर जैसे न हों
संदर्भ अतिप्रवाह त्रुटियाँ जिन्हें Compaction/पुनः प्रयास तर्क के भीतर रहना चाहिए (उदाहरण के लिए request_too_large, input token count exceeds the maximum number of input tokens, input exceeds the maximum number of tokens, input too long for the model, या ollama error: context length exceeded)
जब कोई उम्मीदवार शेष न हो, तब अंतिम अज्ञात त्रुटि
Claude Fable 5 सुरक्षा अस्वीकृतियाँ; प्रत्यक्ष API-कुंजी अनुरोध इसके बजाय Anthropic के सर्वर-साइड फ़ॉलबैक के माध्यम से प्रोवाइडर स्तर पर claude-opus-4-8 पर इन्हें संभालते हैं (Anthropic देखें)

कूलडाउन छोड़ने बनाम जाँचने का व्यवहार

जब किसी प्रोवाइडर की हर प्रमाणीकरण प्रोफ़ाइल पहले से कूलडाउन में हो, तो OpenClaw उस प्रोवाइडर को हमेशा के लिए स्वतः नहीं छोड़ता। यह प्रत्येक उम्मीदवार के लिए अलग निर्णय लेता है:

प्रति-उम्मीदवार निर्णय

स्थायी प्रमाणीकरण विफलताएँ पूरे प्रोवाइडर को तुरंत छोड़ देती हैं।
बिलिंग के कारण अक्षमता सामान्यतः छोड़ दी जाती है, लेकिन प्राथमिक उम्मीदवार की सीमित आवृत्ति पर फिर भी जाँच की जा सकती है, ताकि पुनः आरंभ किए बिना पुनर्प्राप्ति संभव हो।
प्राथमिक उम्मीदवार की जाँच कूलडाउन समाप्ति के निकट, प्रति-प्रोवाइडर सीमित आवृत्ति के साथ की जा सकती है।
विफलता अस्थायी दिखने पर (rate_limit, overloaded, या अज्ञात) कूलडाउन के बावजूद उसी प्रोवाइडर के सहोदर फ़ॉलबैक आज़माए जा सकते हैं। यह विशेष रूप से तब प्रासंगिक है जब दर सीमा मॉडल तक सीमित हो और कोई सहोदर मॉडल तुरंत पुनर्प्राप्त हो सकता हो।
अस्थायी कूलडाउन जाँच प्रत्येक फ़ॉलबैक रन में प्रति प्रोवाइडर एक तक सीमित होती है, ताकि कोई एक प्रोवाइडर अंतर-प्रोवाइडर फ़ॉलबैक को न रोके।

सत्र ओवरराइड और लाइव मॉडल स्विचिंग

सत्र मॉडल परिवर्तन साझा स्थिति हैं। सक्रिय रनर, /model कमांड, Compaction/सत्र अपडेट और लाइव-सत्र सामंजस्य सभी एक ही सत्र प्रविष्टि के हिस्सों को पढ़ते या लिखते हैं। फ़ॉलबैक निष्पादन मॉडल-चयन फ़ील्ड नहीं लिखता, इसलिए पुनः प्रयास करते समय वह किसी नए मैन्युअल चयन को प्रतिस्थापित नहीं कर सकता। लाइव मॉडल स्विचिंग इन नियमों का पालन करती है:

केवल स्पष्ट उपयोगकर्ता-प्रेरित मॉडल परिवर्तन लंबित लाइव स्विच को चिह्नित करते हैं। इसमें /model, session_status(model=...), और sessions.patch शामिल हैं।
फ़ॉलबैक रोटेशन, Heartbeat ओवरराइड या Compaction जैसे सिस्टम-प्रेरित मॉडल परिवर्तन स्वयं कभी लंबित लाइव स्विच को चिह्नित नहीं करते।
उपयोगकर्ता-प्रेरित मॉडल ओवरराइड को फ़ॉलबैक नीति के लिए सटीक चयन माना जाता है, इसलिए पहुँच से बाहर चयनित प्रोवाइडर को agents.defaults.model.fallbacks द्वारा छिपाए जाने के बजाय विफलता के रूप में प्रस्तुत किया जाता है।
रनटाइम फ़ॉलबैक उम्मीदवार टर्न तक सीमित रहते हैं। अगला टर्न वर्तमान चयनित मॉडल से आरंभ होता है, जिसमें पिछले रन के दौरान आया मैन्युअल चयन भी शामिल है।
पहले संग्रहीत स्वतः फ़ॉलबैक ओवरराइड समर्थित रहते हैं: OpenClaw समय-समय पर उनके कॉन्फ़िगर किए गए मूल की जाँच करता है और उसके पुनर्प्राप्त होने पर ओवरराइड हटा देता है; /new, /reset, और sessions.reset स्वतः-स्रोत ओवरराइड को तुरंत हटा देते हैं।
उपयोगकर्ता उत्तर प्रत्येक स्थिति परिवर्तन पर फ़ॉलबैक संक्रमण और फ़ॉलबैक-हटने के बाद पुनर्प्राप्ति की घोषणा एक बार करते हैं। समान चयनित/सक्रिय जोड़ी वाले दोहराए गए टर्न सूचना को पुनः नहीं दोहराते।
/status चयनित मॉडल और फ़ॉलबैक स्थिति अलग होने पर सक्रिय फ़ॉलबैक मॉडल तथा कारण दिखाता है।
लाइव-सत्र सामंजस्य पुराने रनटाइम मॉडल फ़ील्ड के बजाय संग्रहीत सत्र ओवरराइड को प्राथमिकता देता है।
यदि लाइव-स्विच त्रुटि सक्रिय फ़ॉलबैक शृंखला के किसी बाद के उम्मीदवार की ओर संकेत करती है, तो OpenClaw पहले असंबंधित उम्मीदवारों पर चलने के बजाय सीधे उस चयनित मॉडल पर पहुँच जाता है।

सक्रिय रन अपने चुने हुए उम्मीदवार को सीधे साथ रखता है। लाइव सामंजस्य केवल स्पष्ट लंबित उपयोगकर्ता स्विच के लिए उस उम्मीदवार को बदलता है, इसलिए किसी अस्थायी फ़ॉलबैक ओवरराइड या रोलबैक की आवश्यकता नहीं होती।

प्रेक्षणीयता और विफलता सारांश

runWithModelFallback(...) प्रत्येक प्रयास का विवरण रिकॉर्ड करता है, जिसका उपयोग लॉग और उपयोगकर्ता-दृश्य कूलडाउन संदेशों में होता है:

आज़माया गया प्रोवाइडर/मॉडल
कारण (rate_limit, overloaded, billing, auth, model_not_found, और इसी तरह के फ़ेलओवर कारण)
वैकल्पिक स्थिति/कोड
मानव-पठनीय त्रुटि सारांश

संरचित model_fallback_decision लॉग में किसी उम्मीदवार के विफल होने, छोड़े जाने या किसी बाद के फ़ॉलबैक के सफल होने पर समतल fallbackStep* फ़ील्ड भी शामिल होते हैं। ये फ़ील्ड प्रयास किए गए संक्रमण को स्पष्ट बनाते हैं (fallbackStepFromModel, fallbackStepToModel, fallbackStepFromFailureReason, fallbackStepFromFailureDetail, fallbackStepFinalOutcome), ताकि अंतिम फ़ॉलबैक भी विफल होने पर लॉग और निदान निर्यातक प्राथमिक विफलता का पुनर्निर्माण कर सकें। जब हर उम्मीदवार विफल हो जाता है, तो OpenClaw FallbackSummaryError थ्रो करता है। बाहरी उत्तर रनर इसका उपयोग “सभी मॉडल अस्थायी रूप से दर-सीमित हैं” जैसा अधिक विशिष्ट संदेश बनाने और, जब ज्ञात हो, सबसे पहले समाप्त होने वाली कूलडाउन अवधि शामिल करने के लिए कर सकता है। वह कूलडाउन सारांश मॉडल-सजग है:

प्रयास की गई प्रदाता/मॉडल शृंखला के लिए असंबंधित मॉडल-स्कोप वाली दर सीमाओं को अनदेखा किया जाता है
यदि शेष अवरोध मेल खाने वाली मॉडल-स्कोप वाली दर सीमा है, तो OpenClaw उस अंतिम मेल खाने वाली समाप्ति का उल्लेख करता है जो अभी भी उस मॉडल को अवरुद्ध करती है

Overview

Concepts and configuration

Providers

मॉडल फ़ेलओवर

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

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

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

उपयोगकर्ता को दिखाई देने वाली फ़ॉलबैक सूचनाएँ

प्रमाणीकरण संग्रहण (कुंजियाँ + OAuth)

प्रोफ़ाइल आईडी

रोटेशन क्रम

सत्र स्थिरता (कैश-अनुकूल)

OpenAI Codex सदस्यता और API-कुंजी बैकअप

कूलडाउन

बिलिंग के कारण अक्षमता

मॉडल फ़ॉलबैक

उम्मीदवार शृंखला के नियम

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

कूलडाउन छोड़ने बनाम जाँचने का व्यवहार

सत्र ओवरराइड और लाइव मॉडल स्विचिंग

प्रेक्षणीयता और विफलता सारांश

संबंधित कॉन्फ़िगरेशन

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

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

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

​उपयोगकर्ता को दिखाई देने वाली फ़ॉलबैक सूचनाएँ

​प्रमाणीकरण संग्रहण (कुंजियाँ + OAuth)

​प्रोफ़ाइल आईडी

​रोटेशन क्रम

​सत्र स्थिरता (कैश-अनुकूल)

​OpenAI Codex सदस्यता और API-कुंजी बैकअप

​कूलडाउन

​बिलिंग के कारण अक्षमता

​मॉडल फ़ॉलबैक

​उम्मीदवार शृंखला के नियम

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

​कूलडाउन छोड़ने बनाम जाँचने का व्यवहार

​सत्र ओवरराइड और लाइव मॉडल स्विचिंग

​प्रेक्षणीयता और विफलता सारांश

​संबंधित कॉन्फ़िगरेशन

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

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

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

उपयोगकर्ता को दिखाई देने वाली फ़ॉलबैक सूचनाएँ

प्रमाणीकरण संग्रहण (कुंजियाँ + OAuth)

प्रोफ़ाइल आईडी

रोटेशन क्रम

सत्र स्थिरता (कैश-अनुकूल)

OpenAI Codex सदस्यता और API-कुंजी बैकअप

कूलडाउन

बिलिंग के कारण अक्षमता

मॉडल फ़ॉलबैक

उम्मीदवार शृंखला के नियम

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

कूलडाउन छोड़ने बनाम जाँचने का व्यवहार

सत्र ओवरराइड और लाइव मॉडल स्विचिंग

प्रेक्षणीयता और विफलता सारांश

संबंधित कॉन्फ़िगरेशन