التكوين

تبديل النماذج الاحتياطي

يتعامل 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: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)
  • اكتمال عملية الضغط (يزداد عداد الضغط)
  • يكون ملف التعريف في فترة تهدئة/معطل

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

لماذا قد يبدو OAuth "ضائعًا"

إذا كان لديك كل من ملف تعريف OAuth وملف تعريف مفتاح API لنفس الموفر، يمكن للتناوب الدوري التبديل بينهما عبر الرسائل ما لم يتم تثبيته. لإجبار استخدام ملف تعريف واحد:

  • ثبت باستخدام auth.order[provider] = ["provider:profileId"]، أو
  • استخدم تجاوزًا لكل جلسة عبر /model … مع تجاوز ملف التعريف (عندما يدعمه واجهة المستخدم/سطح الدردشة الخاص بك).

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

عندما يفشل ملف تعريف بسبب أخطاء المصادقة/حد المعدل (أو مهلة تبدو مثل تحديد المعدل)، يقوم OpenClaw بوضعه في فترة تهدئة والانتقال إلى الملف التعريفي التالي. يتم التعامل مع أخطاء التنسيق/الطلب غير الصالح (على سبيل المثال فشل التحقق من صحة معرف استدعاء أداة Cloud Code Assist) على أنها تستحق التبديل الاحتياطي وتستخدم نفس فترات التهدئة. يتم تصنيف أخطاء أسباب التوقف المتوافقة مع OpenAI مثل Unhandled stop reason: error و stop reason: error و reason: error على أنها إشارات مهلة/تبديل احتياطي. تستخدم فترات التهدئة التراجع الأسي:

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

يتم تخزين الحالة في 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. ينطبق هذا على فشل المصادقة، وحدود المعدل، والمهلات التي استنفدت تناوب ملفات التعريف (الأخطاء الأخرى لا تتقدم في التبديل الاحتياطي). عندما تبدأ عملية تشغيل مع تجاوز للنموذج (خطافات أو سطر أوامر)، لا تزال عمليات التبديل الاحتياطي تنتهي عند agents.defaults.model.primary بعد تجربة أي تبديلات احتياطية مُكونة.

التكوينات ذات الصلة

راجع تكوين البوابة للحصول على:

  • 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

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

مزودو النماذجAnthropic