---
read_when:
    - تشخيص تدوير ملفات تعريف المصادقة، وفترات التهدئة، أو سلوك الرجوع إلى نموذج بديل
    - تحديث قواعد تجاوز الفشل لملفات تعريف المصادقة أو النماذج
    - فهم كيفية تفاعل تجاوزات نموذج الجلسة مع محاولات إعادة المحاولة الاحتياطية
sidebarTitle: Model failover
summary: كيف يدوّر OpenClaw ملفات تعريف المصادقة ويتراجع عبر النماذج
title: التجاوز عند فشل النموذج
x-i18n:
    generated_at: "2026-07-04T15:20:49Z"
    model: gpt-5.5
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: 1521e27c53029ead305f29b7a29b627b519adbd28ed30688c01f32542625855f
    source_path: concepts/model-failover.md
    workflow: 16
---

يتعامل OpenClaw مع الإخفاقات على مرحلتين:

1. **تدوير ملفات تعريف المصادقة** داخل المزوّد الحالي.
2. **الرجوع الاحتياطي للنموذج** إلى النموذج التالي في `agents.defaults.model.fallbacks`.

يوضح هذا المستند قواعد وقت التشغيل والبيانات التي تستند إليها.

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

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

<Steps>
  <Step title="حل حالة الجلسة">
    حل نموذج الجلسة النشط وتفضيل ملف تعريف المصادقة.
  </Step>
  <Step title="بناء سلسلة المرشحين">
    بناء سلسلة نماذج المرشحين من اختيار النموذج الحالي وسياسة الرجوع الاحتياطي لمصدر ذلك الاختيار. يمكن للإعدادات الافتراضية المكوّنة، والنماذج الأساسية لمهام cron، ونماذج الرجوع الاحتياطي المختارة تلقائيا استخدام الرجوعات الاحتياطية المكوّنة؛ أما اختيارات جلسة المستخدم الصريحة فهي صارمة.
  </Step>
  <Step title="تجربة المزوّد الحالي">
    جرّب المزوّد الحالي باستخدام قواعد تدوير/تهدئة ملفات تعريف المصادقة.
  </Step>
  <Step title="التقدم عند أخطاء تستحق التحويل الاحتياطي">
    إذا استُنفد ذلك المزوّد مع خطأ يستحق التحويل الاحتياطي، فانتقل إلى مرشح النموذج التالي.
  </Step>
  <Step title="حفظ تجاوز الرجوع الاحتياطي">
    احفظ تجاوز الرجوع الاحتياطي المحدد قبل بدء إعادة المحاولة، بحيث يرى قارئو الجلسة الآخرون المزوّد/النموذج نفسه الذي يوشك المشغّل على استخدامه. يوسم تجاوز النموذج المحفوظ بـ `modelOverrideSource: "auto"`.
  </Step>
  <Step title="التراجع المحدود عند الفشل">
    إذا فشل مرشح الرجوع الاحتياطي، فتراجع فقط عن حقول تجاوز الجلسة المملوكة للرجوع الاحتياطي عندما لا تزال تطابق ذلك المرشح الفاشل.
  </Step>
  <Step title="طرح FallbackSummaryError إذا استُنفد كل شيء">
    إذا فشل كل مرشح، فاطرح `FallbackSummaryError` يتضمن تفاصيل كل محاولة وأقرب انتهاء تهدئة عندما يكون معروفا.
  </Step>
</Steps>

هذا أضيق عمدا من "حفظ الجلسة كلها واستعادتها". يحفظ مشغّل الرد فقط حقول اختيار النموذج التي يملكها للرجوع الاحتياطي:

- `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`.

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

```bash
OPENCLAW_FALLBACK_SKIP_TTL_MS=60000
```

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

القيمة هي TTL بالمللي ثانية. يعطل `0` أو القيمة غير المضبوطة ذاكرة التخزين المؤقت. تُحصر القيم الموجبة بين ثانية واحدة و10 دقائق.

## إشعارات الرجوع الاحتياطي المرئية للمستخدم

عندما تنتقل جلسة إلى رجوع احتياطي محدد تلقائيا، يرسل OpenClaw إشعار حالة في سطح الرد نفسه:

```text
↪️ Model Fallback: <fallback> (selected <primary>; <reason>)
```

عندما ينجح اختبار لاحق وتعود الجلسة إلى النموذج الأساسي المحدد، يرسل OpenClaw:

```text
↪️ 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](/ar/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-agent.sqlite` لكل وكيل.

## ترتيب التدوير

عندما يكون لدى مزوّد عدة ملفات تعريف، يختار OpenClaw ترتيبا كما يلي:

<Steps>
  <Step title="تهيئة صريحة">
    `auth.order[provider]` (إذا ضُبط).
  </Step>
  <Step title="الملفات الشخصية المكوّنة">
    `auth.profiles` بعد ترشيحها حسب المزوّد.
  </Step>
  <Step title="الملفات الشخصية المخزنة">
    إدخالات ملفات تعريف مصادقة SQLite لكل وكيل الخاصة بالمزوّد.
  </Step>
</Steps>

إذا لم يُكوّن ترتيب صريح، يستخدم OpenClaw ترتيبا دائريا:

- **المفتاح الأساسي:** نوع الملف الشخصي (**OAuth قبل مفاتيح API**).
- **المفتاح الثانوي:** `usageStats.lastUsed` (الأقدم أولا، داخل كل نوع).
- **الملفات الشخصية في التهدئة/المعطّلة** تُنقل إلى النهاية، مرتبة حسب أقرب انتهاء.

### ثبات الجلسة (ملائم لذاكرة التخزين المؤقت)

يثبّت OpenClaw **ملف تعريف المصادقة المختار لكل جلسة** لإبقاء ذاكرات المزوّد المؤقتة دافئة. وهو **لا** يدوّر في كل طلب. يُعاد استخدام الملف الشخصي المثبّت حتى:

- تُعاد ضبط الجلسة (`/new` / `/reset`)
- تكتمل Compaction (يزداد عدّ Compaction)
- يكون الملف الشخصي في حالة تهدئة/تعطيل

يعيّن الاختيار اليدوي عبر `/model …@<profileId>` **تجاوز مستخدم** لتلك الجلسة ولا يُدوّر تلقائيا حتى تبدأ جلسة جديدة.

<Note>
تُعامل الملفات الشخصية المثبّتة تلقائيا (التي يختارها موجه الجلسة) كتفضيل: تُجرّب أولا، لكن يمكن أن يدوّر OpenClaw إلى ملف شخصي آخر عند حدود المعدل/المهل. عندما يصبح الملف الشخصي الأصلي متاحا مرة أخرى، يمكن للتشغيلات الجديدة تفضيله مجددا دون تغيير النموذج المحدد أو وقت التشغيل. تبقى الملفات الشخصية المثبتة بواسطة المستخدم مقفلة على ذلك الملف الشخصي؛ إذا فشل وكانت رجوعات النموذج الاحتياطية مكوّنة، ينتقل OpenClaw إلى النموذج التالي بدلا من تبديل الملفات الشخصية.
</Note>

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

بالنسبة إلى نماذج وكلاء OpenAI، تكون المصادقة ووقت التشغيل منفصلين. يبقى `openai/gpt-*` على حزمة Codex بينما يمكن للمصادقة التدوير بين ملف تعريف اشتراك Codex ونسخة احتياطية من مفتاح OpenAI API.

استخدم `auth.order.openai` للترتيب المرئي للمستخدم:

```json5
{
  auth: {
    order: {
      openai: ["openai:user@example.com", "openai:api-key-backup"],
    },
  },
}
```

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

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

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

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

<AccordionGroup>
  <Accordion title="ما يندرج في حاوية حد المعدل / المهلة">
    حاوية حد المعدل هذه أوسع من `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` كإشارات مهلة/تحويل احتياطي.

    يمكن أن يندرج نص الخادم العام أيضا في حاوية المهلة تلك عندما يطابق المصدر نمطا عابرا معروفا. على سبيل المثال، تُعامل رسالة مغلّف تدفق وقت تشغيل النموذج المجردة `An unknown error occurred` كجديرة بالتحويل الاحتياطي لكل مزوّد لأن وقت تشغيل النموذج المشترك يصدرها عندما تنتهي تدفقات المزوّد بـ `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.` محافظا ولا يؤدي إلى التحويل الاحتياطي وحده.

  </Accordion>
  <Accordion title="حدود retry-after في SDK">
    قد تنتظر بعض حزم SDK الخاصة بالمزوّدين مدة طويلة يحددها `Retry-After` قبل إعادة التحكم إلى OpenClaw. بالنسبة إلى حزم SDK المبنية على Stainless مثل Anthropic وOpenAI، يحد OpenClaw افتراضيا من فترات انتظار `retry-after-ms` / `retry-after` الداخلية في SDK إلى 60 ثانية، ويعرض الاستجابات القابلة لإعادة المحاولة الأطول فورا حتى يتمكن مسار التحويل عند الفشل هذا من العمل. اضبط الحد أو عطله باستخدام `OPENCLAW_SDK_RETRY_MAX_WAIT_SECONDS`؛ راجع [سلوك إعادة المحاولة](/ar/concepts/retry).
  </Accordion>
  <Accordion title="فترات التهدئة محددة النطاق بالنموذج">
    يمكن أيضا أن تكون فترات تهدئة حدود المعدل محددة النطاق بالنموذج:

    - يسجل OpenClaw قيمة `cooldownModel` لإخفاقات حدود المعدل عندما يكون معرف النموذج الفاشل معروفا.
    - يمكن الاستمرار في تجربة نموذج شقيق لدى المزوّد نفسه عندما تكون فترة التهدئة محددة النطاق لنموذج مختلف.
    - ما زالت نوافذ الفوترة/التعطيل تحظر ملف التعريف كله عبر النماذج.

  </Accordion>
</AccordionGroup>

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

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

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

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

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

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

<Note>
ليست كل استجابة تشبه الفوترة هي `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`). تبقى هذه على مسار فترة التهدئة/التحويل عند الفشل القصير بدلا من مسار تعطيل الفوترة الطويل.
</Note>

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

```json
{
  "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` المطلوب حاليا إضافة إلى الرجوعات الاحتياطية المكونة.

<AccordionGroup>
  <Accordion title="القواعد">
    - يكون النموذج المطلوب دائما أولا.
    - تزال التكرارات من الرجوعات الاحتياطية الصريحة المكونة، لكنها لا ترشح بواسطة قائمة النماذج المسموح بها. تعامل على أنها نية تشغيلية صريحة.
    - إذا كان التشغيل الحالي موجودا بالفعل على رجوع احتياطي مكون في عائلة المزوّد نفسها، يستمر OpenClaw في استخدام السلسلة المكونة الكاملة.
    - عند عدم توفير تجاوز رجوع احتياطي صريح، تجرب الرجوعات الاحتياطية المكونة قبل الأساسي المكون حتى إذا كان النموذج المطلوب يستخدم مزودا مختلفا.
    - عند عدم توفير تجاوز رجوع احتياطي صريح لمشغل الرجوع الاحتياطي، يضاف الأساسي المكون في النهاية حتى تستقر السلسلة مرة أخرى على الافتراضي الطبيعي بعد استنفاد المرشحين السابقين.
    - عندما يقدم المستدعي `fallbacksOverride`، يستخدم المشغل النموذج المطلوب بالضبط إضافة إلى قائمة التجاوز تلك. تعطل القائمة الفارغة الرجوع الاحتياطي للنموذج وتمنع إلحاق الأساسي المكون كهدف إعادة محاولة مخفي.

  </Accordion>
</AccordionGroup>

### الأخطاء التي تدفع الرجوع الاحتياطي إلى الأمام

<Tabs>
  <Tab title="يستمر عند">
    - إخفاقات المصادقة
    - حدود المعدل واستنفاد فترات التهدئة
    - أخطاء التحميل الزائد/انشغال المزوّد
    - أخطاء التحويل عند الفشل التي تشبه المهلة
    - تعطيلات الفوترة
    - `LiveSessionModelSwitchError`، الذي يطبع إلى مسار تحويل عند الفشل حتى لا ينشئ نموذج محفوظ قديم حلقة إعادة محاولة خارجية
    - الأخطاء الأخرى غير المعروفة عندما تبقى مرشحات متاحة

  </Tab>
  <Tab title="لا يستمر عند">
    - عمليات الإلغاء الصريحة التي لا تشبه المهلة/التحويل عند الفشل
    - أخطاء فيض السياق التي يجب أن تبقى داخل منطق Compaction/إعادة المحاولة (مثل `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`)
    - خطأ نهائي غير معروف عندما لا تبقى أي مرشحات
    - رفضات السلامة في Claude Fable 5؛ تتعامل طلبات مفتاح API المباشرة مع هذه على مستوى المزوّد عبر الرجوع الاحتياطي من جهة خادم Anthropic إلى `claude-opus-4-8` بدلا من ذلك (راجع [Anthropic](/ar/providers/anthropic#safety-refusal-fallback-claude-fable-5))

  </Tab>
</Tabs>

### سلوك تخطي فترة التهدئة مقابل الفحص

عندما تكون كل ملفات تعريف المصادقة لمزوّد ما بالفعل في فترة تهدئة، لا يتخطى OpenClaw ذلك المزوّد تلقائيا إلى الأبد. يتخذ قرارا لكل مرشح:

<AccordionGroup>
  <Accordion title="قرارات لكل مرشح">
    - تتخطى إخفاقات المصادقة المستمرة المزوّد كله فورا.
    - عادة ما تتخطى تعطيلات الفوترة، لكن يمكن الاستمرار في فحص المرشح الأساسي وفق تقييد حتى يكون التعافي ممكنا دون إعادة تشغيل.
    - قد يفحص المرشح الأساسي قرب انتهاء فترة التهدئة، مع تقييد لكل مزوّد.
    - يمكن محاولة نماذج الرجوع الاحتياطي الشقيقة لدى المزوّد نفسه رغم فترة التهدئة عندما يبدو الفشل عابرا (`rate_limit` أو `overloaded` أو غير معروف). وهذا مهم خصوصا عندما يكون حد المعدل محدد النطاق بالنموذج وقد يتعافى نموذج شقيق فورا.
    - تقتصر فحوصات فترات التهدئة العابرة على فحص واحد لكل مزوّد في كل تشغيل رجوع احتياطي حتى لا يوقف مزوّد واحد الرجوع الاحتياطي عبر المزوّدين.

  </Accordion>
</AccordionGroup>

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

تغييرات نموذج الجلسة حالة مشتركة. يقرأ المشغل النشط، وأمر `/model`، وتحديثات Compaction/الجلسة، ومطابقة الجلسة الحية، أو يكتب كل منها أجزاء من إدخال الجلسة نفسه.

هذا يعني أن عمليات إعادة محاولة الرجوع الاحتياطي يجب أن تنسق مع التبديل الحي للنموذج:

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

هذا يمنع السباق التقليدي:

<Steps>
  <Step title="فشل الأساسي">
    يفشل النموذج الأساسي المحدد.
  </Step>
  <Step title="اختيار الرجوع الاحتياطي في الذاكرة">
    يختار مرشح الرجوع الاحتياطي في الذاكرة.
  </Step>
  <Step title="مخزن الجلسة ما زال يقول الأساسي القديم">
    ما زال مخزن الجلسة يعكس الأساسي القديم.
  </Step>
  <Step title="مطابقة الجلسة الحية تقرأ حالة قديمة">
    تقرأ مطابقة الجلسة الحية حالة الجلسة القديمة.
  </Step>
  <Step title="إعادة المحاولة تعود قسرا">
    تعاد إعادة المحاولة قسرا إلى النموذج القديم قبل بدء محاولة الرجوع الاحتياطي.
  </Step>
</Steps>

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

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

يسجل `runWithModelFallback(...)` تفاصيل كل محاولة تغذي السجلات ورسائل فترات التهدئة الموجهة للمستخدم:

- المزوّد/النموذج الذي تمت محاولته
- السبب (`rate_limit` و`overloaded` و`billing` و`auth` و`model_not_found` وأسباب تحويل عند الفشل مشابهة)
- الحالة/الرمز الاختياري
- ملخص خطأ مقروء للبشر

تتضمن سجلات `model_fallback_decision` المهيكلة أيضا حقول `fallbackStep*` مسطحة عندما يفشل مرشح أو يتم تخطيه أو ينجح رجوع احتياطي لاحق. تجعل هذه الحقول الانتقال الذي تمت محاولته صريحا (`fallbackStepFromModel` و`fallbackStepToModel` و`fallbackStepFromFailureReason` و`fallbackStepFromFailureDetail` و`fallbackStepFinalOutcome`) حتى تتمكن مصدّرات السجلات والتشخيص من إعادة بناء الفشل الأساسي حتى عندما يفشل الرجوع الاحتياطي النهائي أيضا.

عندما يفشل كل المرشحين، يرمي OpenClaw الخطأ `FallbackSummaryError`. يمكن لمشغل الرد الخارجي استخدام ذلك لبناء رسالة أكثر تحديدا مثل "كل النماذج محدودة المعدل مؤقتا" وتضمين أقرب انتهاء لفترة التهدئة عندما يكون معروفا.

ملخص فترة التهدئة هذا واع بالنموذج:

- تتجاهل حدود المعدل محددة النطاق بنماذج غير مرتبطة لسلسلة المزوّد/النموذج التي تمت محاولتها
- إذا كان الحظر المتبقي حد معدل محدد النطاق بنموذج مطابق، يبلغ OpenClaw عن آخر انتهاء مطابق لا يزال يحظر ذلك النموذج

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

راجع [تكوين Gateway](/ar/gateway/configuration) من أجل:

- `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`

راجع [النماذج](/ar/concepts/models) للاطلاع على نظرة عامة أوسع حول اختيار النموذج وآلية الرجوع الاحتياطي.