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

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

يتعامل 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).
  • الإعداد 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 ترتيب round-robin:
  • المفتاح الأساسي: نوع ملف التعريف (OAuth قبل مفاتيح API).
  • المفتاح الثانوي: usageStats.lastUsed (الأقدم أولًا، داخل كل نوع).
  • ملفات التعريف في حالة التهدئة/المعطلة تُنقل إلى النهاية، مرتبة حسب أقرب وقت انتهاء.

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

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

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

إذا كان لديك ملف تعريف OAuth وملف تعريف مفتاح API للموفّر نفسه، فقد يؤدي round-robin إلى التبديل بينهما عبر الرسائل ما لم يتم تثبيت أحدهما. لفرض ملف تعريف واحد:
  • ثبّته باستخدام 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 على أنها إشارات مهلة/تراجع احتياطي. ويمكن أيضًا أن تقع نصوص الخادم العامة ذات النطاق الخاص بالموفّر في حزمة المهلات تلك عندما يطابق المصدر نمطًا عابرًا معروفًا. على سبيل المثال، يُعامَل النص العاري في Anthropic An unknown error occurred وحمولات 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-profiles.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-profiles.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.
  • تغييرات النماذج المدفوعة من النظام مثل تدوير التراجع الاحتياطي، أو تجاوزات heartbeat، أو الضغط، لا تحدد أبدًا تبديلًا حيًا معلقًا من تلقاء نفسها.
  • قبل بدء إعادة محاولة التراجع الاحتياطي، يحفظ مشغّل الرد حقول تجاوز التراجع الاحتياطي المحددة في إدخال الجلسة.
  • تفضّل تسوية الجلسة الحية تجاوزات الجلسة المحفوظة على حقول النموذج القديمة في وقت التشغيل.
  • إذا فشلت محاولة التراجع الاحتياطي، فإن المشغّل يرجع فقط حقول التجاوز التي كتبها، وفقط إذا كانت لا تزال تطابق ذلك المرشح الفاشل.
وهذا يمنع السباق الكلاسيكي:
  1. يفشل النموذج الأساسي.
  2. يُختار مرشح تراجع احتياطي في الذاكرة.
  3. ما زال مخزن الجلسة يشير إلى النموذج الأساسي القديم.
  4. تقرأ تسوية الجلسة الحية حالة الجلسة القديمة.
  5. تُعاد المحاولة إلى النموذج القديم قبل أن تبدأ محاولة التراجع الاحتياطي.
يغلق تجاوز التراجع الاحتياطي المحفوظ هذه النافذة، ويُبقي التراجع الضيق تغييرات الجلسة الأحدث اليدوية أو التشغيلية سليمة.

​
قابلية المراقبة وملخصات الإخفاق

يسجل runWithModelFallback(...) تفاصيل لكل محاولة تغذي السجلات ورسائل التهدئة الموجهة للمستخدم:
  • الموفّر/النموذج الذي جرت محاولته
  • السبب (rate_limit أو overloaded أو billing أو auth أو model_not_found و أسباب مشابهة للتراجع الاحتياطي)
  • status/code اختياري
  • ملخص خطأ قابل للقراءة البشرية
عندما يفشل كل مرشح، يرفع 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
راجع النماذج للحصول على نظرة أشمل حول اختيار النموذج والتراجع الاحتياطي.