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

يتعامل 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" ونموذج الأصل المحدد قبل إعادة المحاولة. يمكن لذلك التجاوز التلقائي مواصلة السير في سلسلة الرجوع الاحتياطي المكوّنة دون اختبار النموذج الأساسي في كل رسالة، لكن OpenClaw يختبر الأصل المكوّن مجددا دوريا ويمسح التجاوز التلقائي عندما يتعافى. تمسح /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 إشعارا مرئيا عندما تنتقل جلسة إلى الرجوع الاحتياطي، وإشعارا آخر عندما تعود إلى النموذج الأساسي المحدد؛ ولا يكرر الإشعار في كل دور رجوع احتياطي ثابت.

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

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

يمكن للمشغلين الذين يفضلون قمع إخفاقات المصادقة المتكررة هذه الاشتراك باستخدام:

OPENCLAW_FALLBACK_SKIP_TTL_MS=60000

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

القيمة هي TTL بالمللي ثانية. يعطل 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 (يُستورد إلى مخزن مصادقة كل وكيل عند أول استخدام).
• تُستورد ملفات 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 لبعض المزوّدين)

معرّفات الملفات الشخصية

تنشئ تسجيلات الدخول عبر 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:* لكل من ملفات تعريف ChatGPT/Codex OAuth وملفات تعريف مفاتيح OpenAI API. عندما يبلغ الاشتراك حد استخدام Codex، يسجل OpenClaw وقت إعادة الضبط الدقيق عندما يوفره Codex، ويجرّب ملف تعريف المصادقة المرتب التالي، ويبقي التشغيل داخل حزمة Codex. بمجرد مرور وقت إعادة الضبط، يصبح ملف تعريف الاشتراك مؤهلا مرة أخرى ويمكن للاختيار التلقائي التالي العودة إليه.

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

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

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

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

• دقيقة واحدة
• 5 دقائق
• 25 دقيقة
• ساعة واحدة (حد أقصى)

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

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

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

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

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

{  "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 أساسيا معروف السوء في كل رسالة. يفحص 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

راجع النماذج للاطلاع على نظرة عامة أوسع حول اختيار النموذج وآلية الرجوع الاحتياطي.