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

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

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

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

هذا أضيق نطاقًا عن قصد من «حفظ الجلسة بأكملها واستعادتها». لا يحفظ مشغّل الرد إلا حقول تحديد النموذج التي يملكها لأغراض الرجوع الاحتياطي: providerOverride وmodelOverride وmodelOverrideSource وauthProfileOverride وauthProfileOverrideSource وauthProfileOverrideCompactionCount. يمنع ذلك محاولة رجوع احتياطي فاشلة من استبدال تغييرات أحدث وغير مرتبطة في الجلسة، مثل تغيير يدوي عبر /model أو تحديث تدوير الجلسة الذي حدث أثناء تنفيذ المحاولة.

سياسة مصدر التحديد

يتحكم مصدر التحديد في السماح بسلسلة الرجوع الاحتياطي:

• الإعداد الافتراضي المضبوط: يستخدم agents.defaults.model.primary القيمة agents.defaults.model.fallbacks.
• النموذج الأساسي للوكيل: يكون agents.list[].model صارمًا ما لم يتضمن كائن نموذج ذلك الوكيل قائمة fallbacks خاصة به. استخدم fallbacks: [] للتصريح بالسلوك الصارم، أو قائمة غير فارغة لتمكين الرجوع الاحتياطي للنموذج لذلك الوكيل.
• تجاوز الرجوع الاحتياطي التلقائي: يكتب الرجوع الاحتياطي في وقت التشغيل القيم providerOverride وmodelOverride وmodelOverrideSource: "auto" ونموذج المصدر المحدد قبل إعادة المحاولة. يواصل هذا التجاوز التقدم عبر سلسلة الرجوع الاحتياطي المضبوطة دون اختبار النموذج الأساسي عند كل رسالة، لكن OpenClaw يختبر المصدر المضبوط كل 5 دقائق (غير قابل للضبط) ويمسح التجاوز بمجرد تعافيه. تمسح /new و/reset وsessions.reset أيضًا التجاوزات ذات المصدر التلقائي. تمسح عمليات Heartbeat التي لا تتضمن heartbeat.model صريحًا التجاوزات التلقائية المباشرة عندما لا يعود مصدرها مطابقًا للإعداد الافتراضي المضبوط حاليًا.
• تجاوز جلسة المستخدم: تكتب /model وأداة اختيار النموذج وsession_status(model=...) وsessions.patch القيمة modelOverrideSource: "user". هذا تحديد دقيق للنموذج في الجلسة. إذا فشل المزوّد أو النموذج المحدد قبل إنتاج رد، يُبلغ OpenClaw عن الفشل بدلًا من الرد باستخدام نموذج رجوع احتياطي مضبوط غير مرتبط.
• تجاوز جلسة قديم: قد تتضمن إدخالات الجلسات الأقدم modelOverride من دون modelOverrideSource. يعامل OpenClaw هذه الإدخالات كتجاوزات مستخدم كي لا يتحول تحديد قديم وصريح بصمت إلى سلوك رجوع احتياطي.
• نموذج حمولة Cron: يُعد payload.model أو --model الخاص بمهمة Cron نموذجًا أساسيًا للمهمة، وليس تجاوزًا لجلسة المستخدم. يستخدم بدائل الرجوع المضبوطة ما لم توفر المهمة payload.fallbacks؛ وتجعل payload.fallbacks: [] تشغيل Cron صارمًا.

يتذكر OpenClaw اختبارات النموذج الأساسي الأخيرة لكل جلسة ونموذج أساسي، بحيث لا يُعاد اختبار نموذج أساسي فاشل عند كل دورة. ويرسل إشعارًا مرئيًا عندما تنتقل الجلسة إلى نموذج رجوع احتياطي وإشعارًا آخر عندما تعود إلى النموذج الأساسي المحدد؛ ولا يكرر الإشعار في كل دورة تستمر في استخدام الرجوع الاحتياطي.

ذاكرة التخزين المؤقت لتخطي إخفاقات المصادقة

افتراضيًا، تحافظ كل دورة جديدة على سلوك إعادة محاولة الرجوع الاحتياطي الحالي: يعيد OpenClaw تجربة كل مرشح رجوع احتياطي مضبوط، بما في ذلك المرشحون غير الأساسيين الذين فشلوا مؤخرًا بسبب auth أو auth_permanent.

فعّل منع تكرار إخفاقات المصادقة باستخدام:

OPENCLAW_FALLBACK_SKIP_TTL_MS=60000

عند تفعيله، يسجل OpenClaw علامة تخطٍّ في الذاكرة ومحددة النطاق بالجلسة لمرشح رجوع احتياطي غير أساسي بعد فشل من فئة المصادقة، ويكون مفتاحها معرّف الجلسة والمزوّد والنموذج. لا يجري تخطي المرشحين الأساسيين أبدًا، لذلك يظل تحديد المستخدم الصريح للنموذج يعرض خطأ المصادقة الفعلي. ذاكرة التخزين المؤقت محلية للعملية وتُمسح عند إعادة تشغيل Gateway.

القيمة هي مدة صلاحية بالمللي ثانية. تؤدي القيمة 0 أو عدم تعيينها إلى تعطيل ذاكرة التخزين المؤقت. تُقيّد القيم الموجبة بين ثانية واحدة و10 دقائق.

إشعارات الرجوع الاحتياطي المرئية للمستخدم

عندما تنتقل جلسة إلى نموذج رجوع احتياطي محدد تلقائيًا، يرسل OpenClaw إشعار حالة في واجهة الرد نفسها:

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

عندما ينجح اختبار لاحق وتعود الجلسة إلى النموذج الأساسي المحدد، يرسل OpenClaw:

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

هذه الإشعارات رسائل تشغيلية وليست محتوى صادرًا عن المساعد. تُسلّم مرة واحدة لكل تغير في الحالة، بما في ذلك الدورات التي تقتصر على الآثار الجانبية عندما يكون ذلك ممكنًا، لكن الدورات المستمرة على الرجوع الاحتياطي لا تكررها. يتجاوز التسليم منع الرد العادي على المصدر، ولا يستهلك خانة أول رد للمساعد في القنوات ذات المحادثات المتسلسلة، ويُستبعد من تحويل النص إلى كلام واستخراج الالتزامات.

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

يستخدم OpenClaw ملفات تعريف المصادقة لكل من مفاتيح API ورموز OAuth المميزة.

• توجد الأسرار وحالة توجيه المصادقة في وقت التشغيل داخل ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite.
• لا تمثل auth.profiles وauth.order في الإعدادات سوى بيانات وصفية وتوجيه (من دون أسرار).
• ملف OAuth القديم المخصص للاستيراد فقط: ~/.openclaw/credentials/oauth.json (يُستورد إلى مخزن مصادقة الوكيل عند أول استخدام).
• يستورد openclaw doctor --fix الملفات القديمة auth-profiles.json وauth-state.json وملفات auth.json الخاصة بكل وكيل.

مزيد من التفاصيل: 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 ترتيبًا كما يلي:

إذا لم يُضبط ترتيب صريح، يستخدم OpenClaw ترتيبًا دوريًا:

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

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

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

• تُعاد تهيئة الجلسة (/new / /reset)
• تكتمل عملية Compaction (تزداد قيمة عداد Compaction)
• يدخل ملف التعريف في فترة تهدئة أو يصبح معطلًا

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

اشتراك OpenAI Codex مع مفتاح API احتياطي

بالنسبة إلى نماذج وكلاء OpenAI، تكون المصادقة ووقت التشغيل منفصلين. يظل openai/gpt-* على بيئة Codex بينما يمكن تدوير المصادقة بين ملف تعريف اشتراك Codex ونسخة احتياطية من مفتاح OpenAI API.

استخدم auth.order.openai للترتيب الذي يراه المستخدم:

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

استخدم openai:* لكل من ملفات تعريف OAuth الخاصة بـ ChatGPT/Codex وملفات تعريف مفاتيح OpenAI API. عندما يصل الاشتراك إلى حد استخدام Codex، يسجل OpenClaw وقت إعادة الضبط الدقيق عندما يوفره Codex، ويجرب ملف تعريف المصادقة التالي في الترتيب، ويُبقي التشغيل داخل بيئة Codex. بعد انقضاء وقت إعادة الضبط، يصبح ملف تعريف الاشتراك مؤهلًا مجددًا، ويمكن للتحديد التلقائي التالي العودة إليه.

استخدم ملف تعريف مثبّتًا بواسطة المستخدم فقط عندما تريد فرض حساب أو مفتاح واحد لتلك الجلسة. ملفات التعريف المثبّتة بواسطة المستخدم صارمة عن قصد ولا تنتقل بصمت إلى ملف تعريف آخر.

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

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

تتدرج فترات التهدئة العادية (غير المتعلقة بالفوترة وغير الناتجة عن إخفاق مصادقة دائم) وفق عدد الأخطاء الحديثة في ملف التعريف:

• الإخفاق الأول: 30 ثانية
• الإخفاق الثاني: دقيقة واحدة
• الإخفاق الثالث وما بعده: 5 دقائق (الحد الأقصى)

تُصفّر العدادات بعد انقضاء نافذة إخفاق ملف التعريف (auth.cooldowns.failureWindowHours، والقيمة الافتراضية 24).

تُخزّن الحالة في حالة مصادقة SQLite الخاصة بكل وكيل ضمن usageStats:

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

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

تُعامل إخفاقات الفوترة/الرصيد (مثل "الرصيد غير كافٍ" / "رصيد الاعتماد منخفض جدًا") على أنها تستدعي تجاوز الفشل، لكنها لا تكون مؤقتة عادةً. بدلًا من فترة تهدئة قصيرة، يضع OpenClaw علامة معطّل على ملف التعريف (مع تراجع أطول) وينتقل إلى ملف التعريف/موفّر الخدمة التالي.

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

تُخزّن الحالة في حالة مصادقة SQLite الخاصة بكل وكيل:

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

القيم الافتراضية (auth.cooldowns.*):

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

الرجوع إلى نموذج بديل

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

تندرج إشارات انشغال موفّر الخدمة مثل ModelNotReadyException ضمن فئة الحمل الزائد، وتتبع سياسة التبديل مرة واحدة ثم الرجوع نفسها المستخدمة لحدود المعدل (راجع جدول القيم الافتراضية أعلاه).

عندما يبدأ تشغيل من النموذج الأساسي الافتراضي المضبوط، أو النموذج الأساسي لمهمة 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 نموذجًا أساسيًا معروف التعطل مع كل رسالة. يختبر 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.authPermanentBackoffMinutes / auth.cooldowns.authPermanentMaxMinutes
• auth.cooldowns.overloadedProfileRotations / auth.cooldowns.overloadedBackoffMs
• auth.cooldowns.rateLimitedProfileRotations
• agents.defaults.model.primary / agents.defaults.model.fallbacks
• توجيه agents.defaults.imageModel

راجع النماذج للحصول على نظرة عامة أشمل حول اختيار النماذج وتجاوز الفشل.