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

​
فشل النموذج

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

​
تخزين المصادقة (المفاتيح + 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:[email protected]).
توجد ملفات التعريف في ~/.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 في فترة تهدئة وينتقل إلى ملف التعريف التالي. تُعد أخطاء التنسيق/الطلبات غير الصالحة (على سبيل المثال إخفاقات التحقق من معرّف استدعاء أداة Cloud Code Assist) مؤهلة للانتقال الاحتياطي وتستخدم فترات التهدئة نفسها. تستخدم فترات التهدئة تراجعًا أُسّيًا:
  • دقيقة واحدة
  • 5 دقائق
  • 25 دقيقة
  • ساعة واحدة (حد أقصى)
تُخزَّن الحالة في auth-profiles.json ضمن usageStats: 
{
  "usageStats": {
    "provider:profile": {
      "lastUsed": 1736160000000,
      "cooldownUntil": 1736160600000,
      "errorCount": 2
    }
  }
}

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

تُعد إخفاقات الفوترة/الرصيد (على سبيل المثال «رصيد غير كافٍ» / «رصيد منخفض جدًا») مؤهلة للانتقال الاحتياطي، لكنها عادةً غير عابرة. بدل فترة تهدئة قصيرة، يضع OpenClaw علامة معطَّل على ملف التعريف (مع تراجع أطول) ويدوّر إلى ملف التعريف/الموفّر التالي. تُخزَّن الحالة في auth-profiles.json: 
{
  "usageStats": {
    "provider:profile": {
      "disabledUntil": 1736178000000,
      "disabledReason": "billing"
    }
  }
}
الإعدادات الافتراضية:
  • يبدأ تراجع الفوترة عند 5 ساعات، ويتضاعف مع كل فشل فوترة، ويصل إلى حد أقصى 24 ساعة.
  • تُعاد تعيين عدّادات التراجع إذا لم يفشل ملف التعريف لمدة 24 ساعة (قابلة للتهيئة).

​
نموذج الرجوع

إذا فشلت جميع ملفات التعريف لموفّرٍ ما، ينتقل OpenClaw إلى النموذج التالي في agents.defaults.model.fallbacks. ينطبق ذلك على إخفاقات المصادقة وحدود المعدّل والمهل الزمنية التي استنفدت تدوير ملفات التعريف (أما الأخطاء الأخرى فلا تُقدّم الانتقال الاحتياطي). عندما يبدأ التشغيل مع تجاوز نموذج (hooks أو CLI)، تظل الانتقالات الاحتياطية تنتهي عند agents.defaults.model.primary بعد تجربة أي انتقالات احتياطية مُهيَّأة.

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

راجع تهيئة Gateway لمعرفة:
  • auth.profiles / auth.order
  • auth.cooldowns.billingBackoffHours / auth.cooldowns.billingBackoffHoursByProvider
  • auth.cooldowns.billingMaxHours / auth.cooldowns.failureWindowHours
  • agents.defaults.model.primary / agents.defaults.model.fallbacks
  • توجيه agents.defaults.imageModel
راجع النماذج للحصول على نظرة أشمل حول اختيار النماذج والانتقال الاحتياطي.