تجاوز فشل النموذج

يتعامل OpenClaw مع حالات الفشل على مرحلتين:

1. تدوير ملفات تعريف المصادقة داخل المزود الحالي.
2. الرجوع الاحتياطي للنموذج إلى النموذج التالي في agents.defaults.model.fallbacks.

يشرح هذا المستند قواعد وقت التشغيل والبيانات التي تستند إليها.

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

في تشغيل نصي عادي، يقيّم OpenClaw المرشحين بهذا الترتيب:

هذا أضيق عمدًا من "حفظ الجلسة كاملة واستعادتها". لا يحفظ مشغّل الرد إلا حقول اختيار النموذج التي يملكها للرجوع الاحتياطي:

• 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" قبل إعادة المحاولة. يمكن لذلك التجاوز التلقائي أن يواصل السير في سلسلة الرجوع الاحتياطي المكوّنة، ويُمسح بواسطة /new و/reset وsessions.reset.
• تجاوز جلسة المستخدم: تكتب /model، ومنتقي النموذج، وsession_status(model=...)، وsessions.patch قيمة modelOverrideSource: "user". هذا اختيار جلسة دقيق. إذا فشل المزود/النموذج المحدد قبل إنتاج رد، يبلّغ OpenClaw عن الفشل بدلًا من الإجابة من رجوع احتياطي مكوّن غير ذي صلة.
• تجاوز الجلسة القديم: قد تحتوي إدخالات الجلسات الأقدم على modelOverride دون modelOverrideSource. يتعامل OpenClaw معها كتجاوزات مستخدم حتى لا يتحول اختيار قديم صريح بصمت إلى سلوك رجوع احتياطي.
• نموذج حمولة Cron: payload.model / --model في مهمة cron هو نموذج أساسي للمهمة، وليس تجاوز جلسة مستخدم. يستخدم الرجوعات الاحتياطية المكوّنة ما لم تقدم المهمة payload.fallbacks؛ وتجعل payload.fallbacks: [] تشغيل cron صارمًا.

# تخزين المصادقة (المفاتيح + 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 عند أول استخدام).

مزيد من التفاصيل: OAuth

أنواع بيانات الاعتماد:

• type: "api_key" → { provider, key }
• type: "oauth" → { provider, access, refresh, expires, email? } (+ projectId/enterpriseUrl لبعض المزودين)

# معرفات الملفات التعريفية

تنشئ عمليات تسجيل الدخول عبر OAuth ملفات تعريف مميزة حتى يمكن أن تتعايش حسابات متعددة.

• الافتراضي: provider:default عندما لا يتوفر بريد إلكتروني.
• OAuth مع بريد إلكتروني: provider:<email> (على سبيل المثال google-antigravity:[email protected]).

تعيش الملفات التعريفية في ~/.openclaw/agents/<agentId>/agent/auth-profiles.json تحت profiles.

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

عندما يملك مزود ملفات تعريف متعددة، يختار OpenClaw ترتيبًا مثل هذا:

إذا لم يُكوَّن ترتيب صريح، يستخدم OpenClaw ترتيبًا دائريًا:

• المفتاح الأساسي: نوع الملف التعريفي (OAuth قبل مفاتيح API).
• المفتاح الثانوي: usageStats.lastUsed (الأقدم أولًا، داخل كل نوع).
• تُنقل الملفات التعريفية في التهدئة/المعطلة إلى النهاية، مرتبة حسب أقرب انتهاء.

# ثبات الجلسة (صديق للتخزين المؤقت)

يثبّت OpenClaw ملف تعريف المصادقة المختار لكل جلسة للحفاظ على دفء ذاكرات التخزين المؤقت لدى المزود. وهو لا يدوّر عند كل طلب. يُعاد استخدام الملف التعريفي المثبت حتى:

• تُعاد ضبط الجلسة (/new / /reset)
• تكتمل Compaction (يزداد عدّ Compaction)
• يكون الملف التعريفي في تهدئة/معطّلًا

يضبط الاختيار اليدوي عبر /model …@<profileId> تجاوز مستخدم لتلك الجلسة ولا يُدوَّر تلقائيًا حتى تبدأ جلسة جديدة.

# لماذا قد يبدو OAuth "مفقودًا"

إذا كان لديك ملف تعريف OAuth وملف تعريف مفتاح API للمزود نفسه، فيمكن للتدوير الدائري أن يبدّل بينهما عبر الرسائل ما لم يكن مثبتًا. لفرض ملف تعريف واحد:

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

# التهدئات

عندما يفشل ملف تعريف بسبب أخطاء المصادقة/حدود المعدل (أو مهلة تبدو كحد معدل)، يضعه OpenClaw في التهدئة وينتقل إلى الملف التعريفي التالي.

تستخدم التهدئات تراجعًا أسيًا:

• دقيقة واحدة
• 5 دقائق
• 25 دقيقة
• ساعة واحدة (سقف)

تُخزن الحالة في auth-state.json تحت usageStats:

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

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

تُعامل إخفاقات الفوترة/الرصيد (على سبيل المثال "insufficient credits" / "credit balance too low") على أنها تستحق التحويل، لكنها عادةً ليست عابرة. بدلًا من تهدئة قصيرة، يعلّم OpenClaw الملف التعريفي بأنه معطّل (مع تراجع أطول) ويدوّر إلى الملف التعريفي/المزود التالي.

تُخزن الحالة في auth-state.json:

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

القيم الافتراضية:

• يبدأ تراجع الفوترة عند 5 ساعات، ويتضاعف مع كل إخفاق فوترة، ويبلغ سقفه عند 24 ساعة.
• تُصفّر عدادات التراجع إذا لم يفشل الملف التعريفي لمدة 24 ساعة (قابلة للتكوين).
• تسمح إعادة محاولات التحميل الزائد بـ تدوير ملف تعريف واحد لدى المزود نفسه قبل الرجوع الاحتياطي للنموذج.
• تستخدم إعادة محاولات التحميل الزائد 0 ms تراجع افتراضيًا.

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

إذا فشلت كل الملفات التعريفية لمزود ما، ينتقل OpenClaw إلى النموذج التالي في agents.defaults.model.fallbacks. ينطبق هذا على إخفاقات المصادقة، وحدود المعدل، والمهل التي استنفدت تدوير الملفات التعريفية (الأخطاء الأخرى لا تقدم الرجوع الاحتياطي). لا تزال أخطاء المزود التي لا تكشف تفاصيل كافية تُوسم بدقة في حالة الرجوع الاحتياطي: تعني empty_response أن المزود لم يُرجع رسالة أو حالة قابلة للاستخدام، وتعني no_error_details أن المزود أرجع صراحةً Unknown error (no error details in response)، وتعني unclassified أن OpenClaw احتفظ بالمعاينة الخام لكن لم يطابقها أي مصنّف بعد.

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

عندما يبدأ تشغيل من الأساسي الافتراضي المهيّأ، أو أساسي مهمة cron، أو أساسي وكيل لديه بدائل صريحة، أو تجاوز بديل مختار تلقائيًا، يستطيع OpenClaw السير عبر سلسلة البدائل المهيّأة المطابقة. أساسيات الوكلاء التي لا تحتوي على بدائل صريحة والاختيارات الصريحة للمستخدمين (على سبيل المثال /model ollama/qwen3.5:27b أو منتقي النماذج أو sessions.patch أو تجاوزات المزوّد/النموذج لمرة واحدة عبر CLI) تكون صارمة: إذا تعذّر الوصول إلى ذلك المزوّد/النموذج أو فشل قبل إنتاج رد، يبلّغ OpenClaw عن الفشل بدلًا من الإجابة من بديل غير مرتبط.

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

يبني OpenClaw قائمة المرشحين من provider/model المطلوب حاليًا بالإضافة إلى البدائل المهيّأة.

# الأخطاء التي تقدّم البديل

# سلوك تخطي التهدئة مقابل الفحص

عندما تكون كل ملفات تعريف المصادقة لمزوّد ما ضمن فترة تهدئة بالفعل، لا يتخطى OpenClaw ذلك المزوّد تلقائيًا إلى الأبد. بل يتخذ قرارًا لكل مرشح:

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

تغييرات نموذج الجلسة حالة مشتركة. يقرأ المشغّل النشط، وأمر /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 عن آخر انتهاء مطابق لا يزال يحظر ذلك النموذج

# التهيئة ذات الصلة

راجع تهيئة 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

راجع النماذج للحصول على النظرة العامة الأوسع لاختيار النماذج والبدائل.