الانتقال إلى المحتوى الرئيسي

​
الرجوع الاحتياطي للنموذج

يتعامل OpenClaw مع حالات الفشل على مرحلتين:
  1. تدوير ملف تعريف المصادقة داخل المزوّد الحالي.
  2. الرجوع الاحتياطي للنموذج إلى النموذج التالي في agents.defaults.model.fallbacks.
تشرح هذه الوثيقة قواعد وقت التشغيل والبيانات التي تستند إليها.

​
تدفق وقت التشغيل

في تشغيل نصي عادي، يقيّم OpenClaw المرشحين بهذا الترتيب:
  1. نموذج الجلسة المحدد حاليًا.
  2. القيم المضبوطة في agents.defaults.model.fallbacks بالترتيب.
  3. النموذج الأساسي المكوّن في النهاية عندما يكون التشغيل قد بدأ من تجاوز.
داخل كل مرشح، يجرّب OpenClaw الرجوع الاحتياطي لملف تعريف المصادقة قبل الانتقال إلى مرشح النموذج التالي. التسلسل عالي المستوى:
  1. حل نموذج الجلسة النشط وتفضيل ملف تعريف المصادقة.
  2. إنشاء سلسلة مرشحي النموذج.
  3. تجربة المزوّد الحالي مع قواعد تدوير ملف تعريف المصادقة/فترة التهدئة.
  4. إذا استُنفد هذا المزوّد مع خطأ يستحق الرجوع الاحتياطي، فانتقل إلى مرشح النموذج التالي.
  5. الاحتفاظ بتجاوز الرجوع الاحتياطي المحدد قبل بدء إعادة المحاولة حتى ترى قرّاء الجلسة الآخرون نفس المزوّد/النموذج الذي يوشك المشغّل على استخدامه.
  6. إذا فشل مرشح الرجوع الاحتياطي، فتراجع فقط عن حقول تجاوز الجلسة المملوكة للرجوع الاحتياطي عندما تظل مطابقة لذلك المرشح الفاشل.
  7. إذا فشل كل المرشحين، فاطرح FallbackSummaryError مع تفاصيل كل محاولة وأقرب وقت لانتهاء فترة التهدئة عندما يكون ذلك معروفًا.
هذا أضيق عمدًا من “حفظ الجلسة بالكامل واستعادتها”. مشغّل الرد يحتفظ فقط بحقول اختيار النموذج التي يملكها للرجوع الاحتياطي:
  • providerOverride
  • modelOverride
  • authProfileOverride
  • authProfileOverrideSource
  • authProfileOverrideCompactionCount
يمنع ذلك إعادة محاولة رجوع احتياطي فاشلة من الكتابة فوق طفرات جلسة أحدث وغير مرتبطة، مثل تغييرات /model اليدوية أو تحديثات تدوير الجلسة التي حدثت أثناء تشغيل المحاولة.

​
تخزين المصادقة (المفاتيح + OAuth)

يستخدم OpenClaw ملفات تعريف المصادقة لكل من مفاتيح API ورموز OAuth.
  • تُخزَّن الأسرار في ~/.openclaw/agents/<agentId>/agent/auth-profiles.json (قديمًا: ~/.openclaw/agent/auth-profiles.json).
  • تُخزَّن حالة توجيه المصادقة في وقت التشغيل في ~/.openclaw/agents/<agentId>/agent/auth-state.json.
  • الإعداد auth.profiles / auth.order مخصّصان فقط لـ البيانات الوصفية + التوجيه (من دون أسرار).
  • ملف OAuth القديم للاستيراد فقط: ~/.openclaw/credentials/oauth.json (يُستورد إلى auth-profiles.json عند أول استخدام).
مزيد من التفاصيل: /concepts/oauth أنواع بيانات الاعتماد:
  • type: "api_key" → { provider, key }
  • type: "oauth" → { provider, access, refresh, expires, email? } (+ projectId/enterpriseUrl لبعض المزوّدين)

​
معرّفات ملفات التعريف

تنشئ عمليات تسجيل دخول OAuth ملفات تعريف مميزة بحيث يمكن لعدة حسابات التعايش.
  • الافتراضي: provider:default عندما لا يكون البريد الإلكتروني متاحًا.
  • OAuth مع بريد إلكتروني: provider:<email> (على سبيل المثال google-antigravity:user@gmail.com).
توجد ملفات التعريف في ~/.openclaw/agents/<agentId>/agent/auth-profiles.json ضمن profiles.

​
ترتيب التدوير

عندما يكون لدى مزوّد عدة ملفات تعريف، يختار OpenClaw الترتيب على هذا النحو:
  1. إعداد صريح: auth.order[provider] (إذا كان مضبوطًا).
  2. ملفات التعريف المكوّنة: auth.profiles بعد تصفيتها حسب المزوّد.
  3. ملفات التعريف المخزنة: الإدخالات في auth-profiles.json لذلك المزوّد.
إذا لم يُضبط ترتيب صريح، يستخدم OpenClaw ترتيبًا دائريًا:
  • المفتاح الأساسي: نوع ملف التعريف (OAuth قبل مفاتيح API).
  • المفتاح الثانوي: usageStats.lastUsed (الأقدم أولًا، داخل كل نوع).
  • ملفات التعريف في فترة التهدئة/المعطلة تُنقل إلى النهاية، وتُرتّب حسب أقرب وقت انتهاء.

​
ثبات الجلسة (ملائم لذاكرة التخزين المؤقت)

يقوم OpenClaw بتثبيت ملف تعريف المصادقة المختار لكل جلسة للحفاظ على سخونة ذاكرات المزوّد المؤقتة. وهو لا يدوّر في كل طلب. يُعاد استخدام ملف التعريف المثبت حتى:
  • تُعاد تعيين الجلسة (/new / /reset)
  • يكتمل ضغط (يزداد عدد مرات الضغط)
  • يكون ملف التعريف في فترة تهدئة/معطلًا
يؤدي الاختيار اليدوي عبر /model …@<profileId> إلى ضبط تجاوز من المستخدم لتلك الجلسة، ولا يُدوَّر تلقائيًا حتى تبدأ جلسة جديدة. تُعامَل ملفات التعريف المثبتة تلقائيًا (التي يختارها موجّه الجلسة) على أنها تفضيل: تُجرَّب أولًا، لكن قد يدوّر OpenClaw إلى ملف تعريف آخر عند حدود المعدل/المهلات الزمنية. تظل ملفات التعريف المثبتة من المستخدم مقفلة على ذلك الملف؛ وإذا فشل وتم تكوين نماذج رجوع احتياطي، ينتقل OpenClaw إلى النموذج التالي بدلًا من تبديل ملفات التعريف.

​
لماذا قد يبدو OAuth “مفقودًا”

إذا كان لديك كل من ملف تعريف OAuth وملف تعريف مفتاح API للمزوّد نفسه، فقد يبدّل الترتيب الدائري بينهما عبر الرسائل ما لم يكن أحدهما مثبتًا. لفرض ملف تعريف واحد:
  • ثبّته باستخدام auth.order[provider] = ["provider:profileId"]، أو
  • استخدم تجاوزًا لكل جلسة عبر /model … مع تجاوز لملف تعريف (عندما يكون مدعومًا من واجهة المستخدم/سطح الدردشة لديك).

​
فترات التهدئة

عندما يفشل ملف تعريف بسبب أخطاء المصادقة/حدود المعدل (أو مهلة زمنية تبدو كأنها مرتبطة بحدود المعدل)، يضعه OpenClaw في فترة تهدئة وينتقل إلى ملف التعريف التالي. سلة حدود المعدل هذه أوسع من مجرد 429: فهي تتضمن أيضًا رسائل مزوّد مثل Too many concurrent requests وThrottlingException و concurrency limit reached وworkers_ai ... quota limit exceeded و throttled وresource exhausted وحدود نوافذ الاستخدام الدورية مثل weekly/monthly limit reached. تُعامل أخطاء التنسيق/الطلب غير الصالح (على سبيل المثال أخطاء التحقق من صحة معرّف استدعاء الأداة في Cloud Code Assist) على أنها جديرة بالرجوع الاحتياطي وتستخدم فترات التهدئة نفسها. تُصنَّف أخطاء سبب التوقف المتوافقة مع OpenAI مثل Unhandled stop reason: error وstop reason: error وreason: error على أنها إشارات مهلة زمنية/رجوع احتياطي. يمكن أيضًا أن تقع نصوص الخادم العامة على مستوى المزوّد ضمن سلة المهلة الزمنية تلك عندما يطابق المصدر نمطًا عابرًا معروفًا. على سبيل المثال، يُعامل النص المجرد An unknown error occurred في Anthropic وحمولات JSON api_error ذات نصوص الخادم العابرة مثل internal server error و unknown error, 520 وupstream error وbackend error على أنها مهلات زمنية جديرة بالرجوع الاحتياطي. كما يُعامل النص العام الخاص بـ OpenRouter للمصبّ العلوي مثل Provider returned error كمهلة زمنية فقط عندما يكون سياق المزوّد هو OpenRouter فعلًا. أما النص الاحتياطي الداخلي العام مثل LLM request failed with an unknown error. فيظل متحفظًا ولا يفعّل الرجوع الاحتياطي بمفرده. يمكن أيضًا أن تكون فترات تهدئة حدود المعدل مقيّدة بالنموذج:
  • يسجّل OpenClaw cooldownModel لفشل حدود المعدل عندما يكون معرّف النموذج الفاشل معروفًا.
  • لا يزال من الممكن تجربة نموذج شقيق على المزوّد نفسه عندما تكون فترة التهدئة مقصورة على نموذج مختلف.
  • تظل نوافذ الفوترة/التعطيل تحظر ملف التعريف بالكامل عبر النماذج.
تستخدم فترات التهدئة تراجعًا أسيًا:
  • دقيقة واحدة
  • 5 دقائق
  • 25 دقيقة
  • ساعة واحدة (الحد الأقصى)
تُخزَّن الحالة في auth-state.json ضمن usageStats: 
{
  "usageStats": {
    "provider:profile": {
      "lastUsed": 1736160000000,
      "cooldownUntil": 1736160600000,
      "errorCount": 2
    }
  }
}

​
تعطيلات الفوترة

تُعامل حالات فشل الفوترة/الرصيد (على سبيل المثال “insufficient credits” / “credit balance too low”) على أنها جديرة بالرجوع الاحتياطي، لكنها غالبًا ليست عابرة. بدلًا من فترة تهدئة قصيرة، يضع OpenClaw علامة على ملف التعريف بأنه معطل (مع تراجع أطول) ويدوّر إلى ملف التعريف/المزوّد التالي. ليست كل الاستجابات التي تبدو فوترة هي 402، وليست كل استجابة HTTP 402 تقع هنا. يحتفظ OpenClaw بنصوص الفوترة الصريحة ضمن مسار الفوترة حتى عندما يعيد مزوّد ما 401 أو 403 بدلًا من ذلك، لكن أدوات المطابقة الخاصة بالمزوّد تظل مقصورة على المزوّد الذي يملكها (على سبيل المثال OpenRouter 403 Key limit exceeded). وفي الوقت نفسه، تُصنَّف أخطاء 402 المؤقتة الخاصة بنافذة الاستخدام وحدود إنفاق المؤسسة/مساحة العمل على أنها rate_limit عندما تبدو الرسالة قابلة لإعادة المحاولة (على سبيل المثال weekly usage limit exhausted أو daily limit reached, resets tomorrow أو organization spending limit exceeded). تظل هذه في مسار فترة التهدئة القصيرة/الرجوع الاحتياطي بدلًا من مسار تعطيل الفوترة الطويل. تُخزَّن الحالة في auth-state.json: 
{
  "usageStats": {
    "provider:profile": {
      "disabledUntil": 1736178000000,
      "disabledReason": "billing"
    }
  }
}
القيم الافتراضية:
  • يبدأ تراجع الفوترة من 5 ساعات، ويتضاعف مع كل فشل فوترة، ويصل إلى حد أقصى 24 ساعة.
  • يُعاد تعيين عدادات التراجع إذا لم يفشل ملف التعريف لمدة 24 ساعة (قابل للتهيئة).
  • تسمح عمليات إعادة المحاولة عند الحمل الزائد بـ تدوير واحد لملف تعريف على المزوّد نفسه قبل الرجوع الاحتياطي للنموذج.
  • تستخدم عمليات إعادة المحاولة عند الحمل الزائد تراجعًا افتراضيًا مقداره 0 ms.

​
الرجوع الاحتياطي للنموذج

إذا فشلت كل ملفات التعريف الخاصة بمزوّد ما، ينتقل OpenClaw إلى النموذج التالي في agents.defaults.model.fallbacks. ينطبق هذا على حالات فشل المصادقة وحدود المعدل والمهلات الزمنية التي استنفدت تدوير ملفات التعريف (أما الأخطاء الأخرى فلا تتقدم في الرجوع الاحتياطي). تُعالَج أخطاء الحمل الزائد وحدود المعدل بشكل أكثر حزمًا من فترات تهدئة الفوترة. افتراضيًا، يسمح OpenClaw بإعادة محاولة واحدة لملف تعريف مصادقة على المزوّد نفسه، ثم ينتقل إلى النموذج الاحتياطي التالي المكوّن من دون انتظار. تقع إشارات انشغال المزوّد مثل ModelNotReadyException ضمن سلة الحمل الزائد تلك. اضبط هذا عبر auth.cooldowns.overloadedProfileRotations و auth.cooldowns.overloadedBackoffMs و auth.cooldowns.rateLimitedProfileRotations. عندما يبدأ تشغيل مع تجاوز نموذج (hooks أو CLI)، تظل النهايات الاحتياطية عند agents.defaults.model.primary بعد تجربة أي نماذج احتياطية مكوّنة.

​
قواعد سلسلة المرشحين

ينشئ OpenClaw قائمة المرشحين من provider/model المطلوب حاليًا بالإضافة إلى القيم الاحتياطية المكوّنة. القواعد:
  • يكون النموذج المطلوب دائمًا أولًا.
  • تُزال التكرارات من القيم الاحتياطية الصريحة المكوّنة لكنها لا تُرشَّح حسب قائمة السماح الخاصة بالنموذج. فهي تُعامل على أنها نية تشغيلية صريحة.
  • إذا كان التشغيل الحالي موجودًا أصلًا على نموذج احتياطي مكوّن في عائلة المزوّد نفسها، فإن OpenClaw يواصل استخدام السلسلة المكوّنة بالكامل.
  • إذا كان التشغيل الحالي على مزوّد مختلف عن الإعداد وكان هذا النموذج الحالي ليس جزءًا من سلسلة الرجوع الاحتياطي المكوّنة أصلًا، فلن يضيف OpenClaw قيم رجوع احتياطي غير مرتبطة من مزوّد آخر.
  • عندما يكون التشغيل قد بدأ من تجاوز، يُضاف النموذج الأساسي المكوّن في النهاية حتى تتمكن السلسلة من الاستقرار مجددًا على الافتراضي العادي بعد استنفاد المرشحين السابقين.

​
أي الأخطاء تدفع الرجوع الاحتياطي إلى الأمام

يستمر الرجوع الاحتياطي للنموذج في الحالات التالية:
  • فشل المصادقة
  • حدود المعدل واستنفاد فترة التهدئة
  • أخطاء الحمل الزائد/انشغال المزوّد
  • أخطاء الرجوع الاحتياطي ذات شكل المهلة الزمنية
  • تعطيلات الفوترة
  • LiveSessionModelSwitchError، الذي يُطبَّع إلى مسار رجوع احتياطي حتى لا ينشئ النموذج المحفوظ القديم حلقة إعادة محاولة خارجية
  • الأخطاء الأخرى غير المعروفة عندما لا يزال هناك مرشحون متبقون
لا يستمر الرجوع الاحتياطي للنموذج في الحالات التالية:
  • الإيقافات الصريحة التي ليست ذات شكل مهلة زمنية/رجوع احتياطي
  • أخطاء تجاوز سعة السياق التي يجب أن تبقى ضمن منطق الضغط/إعادة المحاولة (على سبيل المثال 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 وollama error: context length exceeded)
  • خطأ نهائي غير معروف عندما لا يبقى أي مرشحين

​
سلوك تخطي فترة التهدئة مقابل الاستقصاء

عندما تكون كل ملفات تعريف المصادقة الخاصة بمزوّد ما موجودة أصلًا في فترة تهدئة، لا يتخطى OpenClaw ذلك المزوّد تلقائيًا إلى الأبد. بل يتخذ قرارًا لكل مرشح على حدة:
  • تتخطى حالات فشل المصادقة المستمرة المزوّد بالكامل فورًا.
  • عادةً ما تتخطى تعطيلات الفوترة، لكن لا يزال من الممكن استقصاء المرشح الأساسي مع خنق حتى يصبح الاسترداد ممكنًا من دون إعادة التشغيل.
  • يمكن استقصاء المرشح الأساسي قرب انتهاء فترة التهدئة، مع خنق لكل مزوّد.
  • يمكن محاولة الأشقاء الاحتياطيين على المزوّد نفسه رغم فترة التهدئة عندما يبدو الفشل عابرًا (rate_limit أو overloaded أو غير معروف). وهذا مهم بشكل خاص عندما تكون حدود المعدل مقيّدة بالنموذج وقد يتعافى نموذج شقيق على الفور.
  • تقتصر استقصاءات فترات التهدئة العابرة على واحدة لكل مزوّد في كل تشغيل رجوع احتياطي حتى لا يعرقل مزوّد واحد الرجوع الاحتياطي عبر المزوّدين.

​
تجاوزات الجلسة وتبديل النموذج المباشر

تغييرات نموذج الجلسة هي حالة مشتركة. إذ يقرأ المشغّل النشط وأمر /model، وتحديثات الضغط/الجلسة، وتسوية الجلسة المباشرة أو يكتبون أجزاءً من إدخال الجلسة نفسه. وهذا يعني أن عمليات إعادة المحاولة الخاصة بالرجوع الاحتياطي يجب أن تنسّق مع تبديل النموذج المباشر:
  • فقط تغييرات النموذج الصريحة التي يقودها المستخدم تضع علامة على وجود تبديل مباشر معلّق. ويشمل ذلك /model وsession_status(model=...) و sessions.patch.
  • تغييرات النموذج التي يدفعها النظام مثل تدوير الرجوع الاحتياطي، أو تجاوزات نبضات القلب، أو الضغط لا تضع علامة على وجود تبديل مباشر معلّق من تلقاء نفسها.
  • قبل بدء إعادة محاولة الرجوع الاحتياطي، يحتفظ مشغّل الرد بحقول تجاوز الرجوع الاحتياطي المحددة في إدخال الجلسة.
  • تفضّل تسوية الجلسة المباشرة تجاوزات الجلسة المحفوظة على حقول النموذج القديمة في وقت التشغيل.
  • إذا فشلت محاولة الرجوع الاحتياطي، يتراجع المشغّل فقط عن حقول التجاوز التي كتبها، وفقط إذا ظلت مطابقة لذلك المرشح الفاشل.
يمنع هذا السباق الكلاسيكي:
  1. يفشل النموذج الأساسي.
  2. يُختار مرشح الرجوع الاحتياطي في الذاكرة.
  3. لا يزال مخزن الجلسة يشير إلى النموذج الأساسي القديم.
  4. تقرأ تسوية الجلسة المباشرة حالة الجلسة القديمة.
  5. تُعاد المحاولة إلى النموذج القديم قبل أن تبدأ محاولة الرجوع الاحتياطي.
يُغلق تجاوز الرجوع الاحتياطي المحفوظ هذه النافذة، ويحافظ التراجع الضيق على سلامة تغييرات الجلسة الأحدث اليدوية أو التشغيلية.

​
قابلية الملاحظة وملخصات الفشل

يسجل runWithModelFallback(...) تفاصيل كل محاولة، والتي تُغذي السجلات ورسائل فترة التهدئة الظاهرة للمستخدم:
  • المزوّد/النموذج الذي تمت محاولته
  • السبب (rate_limit وoverloaded وbilling وauth وmodel_not_found وأسباب رجوع احتياطي مشابهة)
  • حالة/رمز اختياري
  • ملخص خطأ مقروء للبشر
عندما يفشل كل المرشحين، يطرح OpenClaw FallbackSummaryError. يمكن لمشغّل الرد الخارجي استخدام ذلك لإنشاء رسالة أكثر تحديدًا مثل “جميع النماذج مقيدة مؤقتًا بحدود المعدل” وتضمين أقرب وقت لانتهاء فترة التهدئة عندما يكون معروفًا. هذا الملخص الخاص بفترة التهدئة مدرك للنموذج:
  • تُتجاهل حدود المعدل غير المرتبطة والمقيّدة بنموذج ضمن سلسلة المزوّد/النموذج التي تمت محاولتها
  • إذا كان الحظر المتبقي هو حد معدل مقيّدًا بنموذج مطابق، يبلغ OpenClaw عن آخر وقت انتهاء مطابق لا يزال يحظر ذلك النموذج

​
الإعدادات ذات الصلة

راجع إعدادات Gateway للاطلاع على:
  • 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
راجع النماذج للحصول على نظرة عامة أوسع حول اختيار النموذج والرجوع الاحتياطي.