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

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

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

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

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

حل حالة الجلسة

حل نموذج الجلسة النشط وتفضيل ملف تعريف المصادقة.
2

بناء سلسلة المرشحين

بناء سلسلة مرشحي النموذج من اختيار النموذج الحالي وسياسة الرجوع الاحتياطي لمصدر ذلك الاختيار. يمكن للإعدادات الافتراضية المكوّنة، والنماذج الأساسية لمهام cron، ونماذج الرجوع الاحتياطي المحددة تلقائيا استخدام عمليات الرجوع الاحتياطي المكوّنة؛ أما اختيارات جلسة المستخدم الصريحة فهي صارمة.
3

تجربة المزوّد الحالي

جرّب المزوّد الحالي مع قواعد تدوير/تهدئة ملف تعريف المصادقة.
4

التقدم عند أخطاء تستحق تجاوز الفشل

إذا استنفد ذلك المزوّد مع خطأ يستحق تجاوز الفشل، فانتقل إلى مرشح النموذج التالي.
5

حفظ تجاوز الرجوع الاحتياطي

احفظ تجاوز الرجوع الاحتياطي المحدد قبل بدء إعادة المحاولة كي يرى قارئو الجلسة الآخرون المزوّد/النموذج نفسه الذي يوشك المشغّل على استخدامه. يوسم تجاوز النموذج المحفوظ بـ modelOverrideSource: "auto".
6

التراجع المحدود عند الفشل

إذا فشل مرشح الرجوع الاحتياطي، فتراجع فقط عن حقول تجاوز الجلسة المملوكة للرجوع الاحتياطي عندما تظل مطابقة لذلك المرشح الفاشل.
7

رمي FallbackSummaryError عند الاستنفاد

إذا فشل كل مرشح، فارمِ FallbackSummaryError مع تفاصيل لكل محاولة وأقرب انتهاء تهدئة عندما يكون معروفا.
هذا أضيق عمدا من “حفظ الجلسة كلها واستعادتها”. لا يحفظ مشغّل الرد إلا حقول اختيار النموذج التي يملكها للرجوع الاحتياطي:
  • 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. كما تمسح عمليات 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 صارما.

​
تخزين المصادقة (المفاتيح + 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: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)
  • تكتمل Compaction (يزداد عدد Compaction)
  • يكون ملف التعريف في تهدئة/معطلا
يضبط الاختيار اليدوي عبر /model …@<profileId> تجاوز مستخدم لتلك الجلسة ولا يُدوّر تلقائيا حتى تبدأ جلسة جديدة.
تُعامل ملفات التعريف المثبتة تلقائيا (التي يختارها موجّه الجلسة) كـ تفضيل: تُجرّب أولا، لكن يمكن لـ OpenClaw التدوير إلى ملف تعريف آخر عند حدود المعدل/المهل. عندما يصبح ملف التعريف الأصلي متاحا مرة أخرى، يمكن للتشغيلات الجديدة تفضيله مجددا من دون تغيير النموذج أو وقت التشغيل المحدد. تبقى ملفات التعريف المثبتة بواسطة المستخدم مقفلة على ذلك الملف؛ إذا فشل وكانت عمليات الرجوع الاحتياطي للنموذج مكوّنة، ينتقل OpenClaw إلى النموذج التالي بدلا من تبديل ملفات التعريف.

​
اشتراك OpenAI Codex مع نسخة احتياطية بمفتاح API

بالنسبة إلى نماذج وكلاء OpenAI، تكون المصادقة ووقت التشغيل منفصلين. يبقى openai/gpt-* على حزمة Codex بينما يمكن للمصادقة التدوير بين ملف تعريف اشتراك Codex ونسخة احتياطية بمفتاح OpenAI API. استخدم auth.order.openai للترتيب الموجّه للمستخدم: 
{
  auth: {
    order: {
      openai: ["openai-codex:user@example.com", "openai:api-key-backup"],
    },
  },
}
قد تظل ملفات تعريف اشتراك Codex الحالية تستخدم معرّف ملف التعريف القديم openai-codex:*. يمكن أن تكون النسخة الاحتياطية المرتبة بمفتاح API ملف تعريف مفتاح API عاديا openai:*. عندما يبلغ الاشتراك حد استخدام Codex، يسجل OpenClaw وقت إعادة الضبط الدقيق عندما يوفره Codex، ويجرّب ملف تعريف المصادقة المرتب التالي، ويبقي التشغيل داخل حزمة Codex. وبمجرد مرور وقت إعادة الضبط، يصبح ملف تعريف الاشتراك مؤهلا مرة أخرى ويمكن للاختيار التلقائي التالي العودة إليه. استخدم ملف تعريف مثبتا بواسطة المستخدم فقط عندما تريد فرض حساب/مفتاح واحد لتلك الجلسة. تكون ملفات التعريف المثبتة بواسطة المستخدم صارمة عمدا ولا تنتقل بصمت إلى ملف تعريف آخر.

​
التهدئات

عندما يفشل ملف تعريف بسبب أخطاء المصادقة/حدود المعدل (أو مهلة تشبه تحديد المعدل)، يضعه OpenClaw في تهدئة وينتقل إلى ملف التعريف التالي.
حاوية حد المعدل هذه أوسع من 429 فقط: فهي تشمل أيضا رسائل المزوّد مثل Too many concurrent requests وThrottlingException وconcurrency limit reached وworkers_ai ... quota limit exceeded وthrottled وresource exhausted وحدود نوافذ الاستخدام الدورية مثل weekly/monthly limit reached.عادة ما تكون أخطاء التنسيق/الطلبات غير الصالحة نهائية لأن إعادة محاولة الحمولة نفسها ستفشل بالطريقة نفسها، لذلك يعرضها OpenClaw بدلا من تدوير ملفات تعريف المصادقة. يمكن لمسارات إصلاح إعادة المحاولة المعروفة الاشتراك صراحة: على سبيل المثال، تُنظّف حالات فشل التحقق من معرّف استدعاء أداة Cloud Code Assist وتُعاد المحاولة مرة واحدة عبر سياسة allowFormatRetry. تُصنّف أخطاء سبب التوقف المتوافقة مع OpenAI مثل Unhandled stop reason: error وstop reason: error وreason: error كإشارات مهلة/تجاوز فشل.يمكن أن يقع نص الخادم العام أيضا في حاوية المهلة تلك عندما يطابق المصدر نمطا عابرا معروفا. على سبيل المثال، تُعامل رسالة مغلّف بث pi-ai المجردة An unknown error occurred كجديرة بتجاوز الفشل لكل مزوّد لأن pi-ai يصدرها عندما تنتهي بثوث المزوّد بـ stopReason: "aborted" أو stopReason: "error" من دون تفاصيل محددة. كما تُعامل حمولات 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. فيبقى محافظا ولا يفعّل تجاوز الفشل بذاته.
قد تنام بعض SDKs الخاصة بالمزوّدين خلاف ذلك لمدة نافذة Retry-After طويلة قبل إعادة التحكم إلى OpenClaw. بالنسبة إلى SDKs المستندة إلى Stainless مثل Anthropic وOpenAI، يحد OpenClaw من انتظارات retry-after-ms / retry-after الداخلية في SDK إلى 60 ثانية افتراضيا، ويعرض الاستجابات الأطول القابلة لإعادة المحاولة فورا كي يعمل مسار تجاوز الفشل هذا. اضبط الحد أو عطّله باستخدام OPENCLAW_SDK_RETRY_MAX_WAIT_SECONDS؛ راجع سلوك إعادة المحاولة.
يمكن أن تكون تهدئات حد المعدل أيضا محددة بنطاق النموذج:
  • يسجل 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 مللي ثانية افتراضيًا.

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

إذا فشلت كل الملفات الشخصية لمزوّد ما، ينتقل 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 استخدام السلسلة المكوّنة الكاملة.
  • عندما لا يُقدَّم تجاوز انتقال احتياطي صريح، تُجرَّب الانتقالات الاحتياطية المكوّنة قبل الأساسي المكوّن حتى إذا كان النموذج المطلوب يستخدم مزوّدًا مختلفًا.
  • عندما لا يُقدَّم تجاوز انتقال احتياطي صريح إلى مشغّل الانتقال الاحتياطي، يُلحَق الأساسي المكوّن في النهاية كي تتمكن السلسلة من الاستقرار مجددًا على الافتراضي العادي بعد استنفاد المرشحين السابقين.
  • عندما يقدّم مستدعٍ fallbacksOverride، يستخدم المشغّل النموذج المطلوب بالضبط بالإضافة إلى قائمة التجاوز تلك. تؤدي القائمة الفارغة إلى تعطيل الانتقال الاحتياطي للنموذج وتمنع إلحاق الأساسي المكوّن كهدف إعادة محاولة مخفي.

​
الأخطاء التي تُقدّم الانتقال الاحتياطي

  • حالات فشل المصادقة
  • حدود المعدل واستنفاد التهدئة
  • أخطاء التحميل الزائد/انشغال المزوّد
  • أخطاء الانتقال الاحتياطي ذات شكل انتهاء المهلة
  • تعطيلات الفوترة
  • LiveSessionModelSwitchError، الذي يُطبَّع إلى مسار انتقال احتياطي كي لا ينشئ نموذج محفوظ قديم حلقة إعادة محاولة خارجية
  • أخطاء أخرى غير معروفة عندما لا يزال هناك مرشحون متبقون

​
سلوك تجاوز التهدئة مقابل الفحص

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

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

تغييرات نموذج الجلسة حالة مشتركة. يقرأ المشغّل النشط، وأمر /model، وتحديثات Compaction/الجلسة، وتسوية الجلسة الحية، أو تكتب جميعها أجزاءً من إدخال الجلسة نفسه. يعني ذلك أن إعادة محاولات الانتقال الاحتياطي يجب أن تنسّق مع التبديل الحي للنموذج:
  • تغييرات النموذج الصريحة التي يقودها المستخدم وحدها تعلّم تبديلًا حيًا معلقًا. يتضمن ذلك /model وsession_status(model=...) وsessions.patch.
  • تغييرات النموذج التي يقودها النظام مثل تدوير الانتقال الاحتياطي، أو تجاوزات Heartbeat، أو Compaction لا تعلّم أبدًا تبديلًا حيًا معلقًا بمفردها.
  • تُعامل تجاوزات النموذج التي يقودها المستخدم كاختيارات دقيقة لسياسة الانتقال الاحتياطي، لذلك يظهر المزوّد المحدد غير القابل للوصول كفشل بدلًا من حجبه بواسطة agents.defaults.model.fallbacks.
  • قبل بدء إعادة محاولة انتقال احتياطي، يحفظ مشغّل الرد حقول تجاوز الانتقال الاحتياطي المحددة في إدخال الجلسة.
  • تبقى تجاوزات الانتقال الاحتياطي التلقائية محددة في الأدوار اللاحقة كي لا يفحص OpenClaw أساسيًا معروف السوء في كل رسالة. يمسح /new و/reset وsessions.reset التجاوزات ذات المصدر التلقائي ويعيد الجلسة إلى الافتراضي المكوّن.
  • يعرض /status النموذج المحدد، وعندما تختلف حالة الانتقال الاحتياطي، يعرض نموذج الانتقال الاحتياطي النشط والسبب.
  • تفضّل تسوية الجلسة الحية تجاوزات الجلسة المحفوظة على حقول نموذج وقت التشغيل القديمة.
  • إذا أشار خطأ تبديل حي إلى مرشح لاحق في سلسلة الانتقال الاحتياطي النشطة، يقفز OpenClaw مباشرةً إلى ذلك النموذج المحدد بدلًا من السير في مرشحين غير ذوي صلة أولًا.
  • إذا فشلت محاولة الانتقال الاحتياطي، يعيد المشغّل فقط حقول التجاوز التي كتبها، وفقط إذا كانت لا تزال تطابق ذلك المرشح الفاشل.
يمنع هذا السباق التقليدي:
1

فشل الأساسي

فشل النموذج الأساسي المحدد.
2

اختيار الانتقال الاحتياطي في الذاكرة

اختير مرشح الانتقال الاحتياطي في الذاكرة.
3

مخزن الجلسة لا يزال يقول الأساسي القديم

لا يزال مخزن الجلسة يعكس الأساسي القديم.
4

تسوية الجلسة الحية تقرأ حالة قديمة

تقرأ تسوية الجلسة الحية حالة الجلسة القديمة.
5

إرجاع إعادة المحاولة إلى الوراء

تُعاد إعادة المحاولة إلى النموذج القديم قبل أن تبدأ محاولة الانتقال الاحتياطي.
يغلق تجاوز الانتقال الاحتياطي المحفوظ تلك النافذة، وتحافظ الإعادة الضيقة على تغييرات الجلسة اليدوية أو وقت التشغيل الأحدث سليمة.

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

يسجّل 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
راجع النماذج للاطلاع على النظرة العامة الأوسع لاختيار النموذج والانتقال الاحتياطي.