# استكشاف الأخطاء وإصلاحها

🌐 **Languages:** 🇺🇸 [English](../../TROUBLESHOOTING.md) | 🇧🇷 [Português (Brasil)](../pt-BR/TROUBLESHOOTING.md) | 🇪🇸 [Español](../es/TROUBLESHOOTING.md) | 🇫🇷 [Français](../fr/TROUBLESHOOTING.md) | 🇮🇹 [Italiano](../it/TROUBLESHOOTING.md) | 🇷🇺 [Русский](../ru/TROUBLESHOOTING.md) | 🇨🇳 [中文 (简体)](../zh-CN/TROUBLESHOOTING.md) | 🇩🇪 [Deutsch](../de/TROUBLESHOOTING.md) | 🇮🇳 [हिन्दी](../in/TROUBLESHOOTING.md) | 🇹🇭 [ไทย](../th/TROUBLESHOOTING.md) | 🇺🇦 [Українська](../uk-UA/TROUBLESHOOTING.md) | 🇸🇦 [العربية](../ar/TROUBLESHOOTING.md) | 🇯🇵 [日本語](../ja/TROUBLESHOOTING.md) | 🇻🇳 [Tiếng Việt](../vi/TROUBLESHOOTING.md) | 🇧🇬 [Български](../bg/TROUBLESHOOTING.md) | 🇩🇰 [Dansk](../da/TROUBLESHOOTING.md) | 🇫🇮 [Suomi](../fi/TROUBLESHOOTING.md) | 🇮🇱 [עברית](../he/TROUBLESHOOTING.md) | 🇭🇺 [Magyar](../hu/TROUBLESHOOTING.md) | 🇮🇩 [Bahasa Indonesia](../id/TROUBLESHOOTING.md) | 🇰🇷 [한국어](../ko/TROUBLESHOOTING.md) | 🇲🇾 [Bahasa Melayu](../ms/TROUBLESHOOTING.md) | 🇳🇱 [Nederlands](../nl/TROUBLESHOOTING.md) | 🇳🇴 [Norsk](../no/TROUBLESHOOTING.md) | 🇵🇹 [Português (Portugal)](../pt/TROUBLESHOOTING.md) | 🇷🇴 [Română](../ro/TROUBLESHOOTING.md) | 🇵🇱 [Polski](../pl/TROUBLESHOOTING.md) | 🇸🇰 [Slovenčina](../sk/TROUBLESHOOTING.md) | 🇸🇪 [Svenska](../sv/TROUBLESHOOTING.md) | 🇵🇭 [Filipino](../phi/TROUBLESHOOTING.md)

المشاكل والحلول الشائعة لـ OmniRoute.

---

## إصلاحات سريعة

| مشكلة                             | الحل                                                              |
| --------------------------------- | ----------------------------------------------------------------- |
| تسجيل الدخول الأول لا يعمل        | تحقق من `INITIAL_PASSWORD` في `.env` (الافتراضي: `123456`)        |
| تفتح لوحة المعلومات على منفذ خاطئ | اضبط `PORT=20128` و`NEXT_PUBLIC_BASE_URL=http://localhost:20128`  |
| لا توجد سجلات للطلب ضمن `logs/`   | تعيين `ENABLE_REQUEST_LOGS=true`                                  |
| EACCES: تم رفض الإذن              | اضبط `DATA_DIR=/path/to/writable/dir` لتجاوز `~/.omniroute`       |
| استراتيجية التوجيه لا تنقذ        | التحديث إلى الإصدار 1.4.11+ (إصلاح مخطط Zod لاستمرارية الإعدادات) |

---

## مشكلات المزود

### "نموذج اللغة لم يقدم رسائل"

**السبب:** استنفدت حصة الموفر.

**الإصلاح:**

1. تحقق من تعقب الحصص في لوحة القيادة
2. استخدم مجموعة من المستويات الاحتياطية
3. قم بالتبديل إلى الطبقة الأرخص/المجانية

### تحديد المعدل

**السبب:** استنفدت حصة الاشتراك.

**الإصلاح:**

- إضافة احتياطي: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`
- استخدم GLM/MiniMax كنسخة احتياطية رخيصة الثمن

### انتهت صلاحية رمز OAuth

يقوم OmniRoute بتحديث الرموز المميزة تلقائيًا. إذا استمرت المشكلات:

1. لوحة المعلومات → الموفر → إعادة الاتصال
2. قم بحذف وإعادة إضافة اتصال الموفر

---

## مشكلات السحابة

### أخطاء المزامنة السحابية

1. تحقق من نقاط `BASE_URL` لمثيلك قيد التشغيل (على سبيل المثال، `http://localhost:20128`)
2. تحقق من نقاط `CLOUD_URL` إلى نقطة نهاية السحابة الخاصة بك (على سبيل المثال، `https://omniroute.dev`)
3. حافظ على محاذاة قيم `NEXT_PUBLIC_*` مع القيم من جانب الخادم

### السحابة `stream=false` تُرجع 500

**العَرَض:** `Unexpected token 'd'...` على نقطة نهاية السحابة للمكالمات غير المتدفقة.

**السبب:** يقوم المنبع بإرجاع حمولة SSE بينما يتوقع العميل JSON.

**الحل البديل:** استخدم `stream=true` للمكالمات السحابية المباشرة. يتضمن وقت التشغيل المحلي SSE → JSON الاحتياطي.

### تقول السحابة إنها متصلة ولكن "مفتاح واجهة برمجة التطبيقات غير صالح"

1. قم بإنشاء مفتاح جديد من لوحة المعلومات المحلية (`/api/keys`)
2. قم بتشغيل المزامنة السحابية: قم بتمكين السحابة → المزامنة الآن
3. لا يزال بإمكان المفاتيح القديمة/غير المتزامنة إرجاع `401` على السحابة

---

## مشكلات عامل الميناء

### تظهر أداة CLI غير مثبتة

1. تحقق من حقول وقت التشغيل: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq`
2. بالنسبة للوضع المحمول: استخدم هدف الصورة `runner-cli` (CLIs المجمعة)
3. بالنسبة لوضع تثبيت المضيف: قم بتعيين `CLI_EXTRA_PATHS` وتثبيت دليل حاوية المضيف للقراءة فقط
4. إذا تم العثور على `installed=true` و`runnable=false`: ثنائي ولكن فشل التحقق من الصحة

### التحقق السريع من وقت التشغيل

```bash
curl -s http://localhost:20128/api/cli-tools/codex-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}'
curl -s http://localhost:20128/api/cli-tools/claude-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}'
curl -s http://localhost:20128/api/cli-tools/openclaw-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}'
```

---

## قضايا التكلفة

### ارتفاع التكاليف

1. تحقق من إحصائيات الاستخدام في لوحة المعلومات → الاستخدام
2. قم بتبديل النموذج الأساسي إلى GLM/MiniMax
3. استخدم الطبقة المجانية (Gemini CLI، iFlow) للمهام غير الحرجة
4. قم بتعيين ميزانيات التكلفة لكل مفتاح واجهة برمجة التطبيقات: لوحة المعلومات ← مفاتيح واجهة برمجة التطبيقات ← الميزانية

---

## التصحيح

### تمكين سجلات الطلبات

قم بتعيين `ENABLE_REQUEST_LOGS=true` في ملف `.env` الخاص بك. تظهر السجلات ضمن الدليل `logs/`.

### التحقق من صحة مقدم الخدمة

```bash
# Health dashboard
http://localhost:20128/dashboard/health

# API health check
curl http://localhost:20128/api/monitoring/health
```

### تخزين وقت التشغيل

- الحالة الرئيسية: `${DATA_DIR}/db.json` (المزودون، المجموعات، الأسماء المستعارة، المفاتيح، الإعدادات)
- الاستخدام: `${DATA_DIR}/usage.json`، `${DATA_DIR}/log.txt`، `${DATA_DIR}/call_logs/`
- سجلات الطلب: `<repo>/logs/...` (عندما `ENABLE_REQUEST_LOGS=true`)

---

## مشكلات قواطع الدائرة

### الموفر عالق في الحالة المفتوحة

عندما يكون قاطع دائرة الموفر مفتوحًا، يتم حظر الطلبات حتى تنتهي فترة التهدئة.

**الإصلاح:**

1. انتقل إلى **لوحة التحكم ← الإعدادات ← المرونة**
2. تحقق من بطاقة قاطع الدائرة الكهربائية الخاصة بالمزود المتأثر
3. انقر فوق **إعادة تعيين الكل** لمسح جميع القواطع، أو انتظر حتى تنتهي فترة التهدئة
4. تحقق من أن الموفر متاح فعليًا قبل إعادة التعيين

### يستمر المزود في تعطيل قاطع الدائرة

إذا دخل مقدم الخدمة بشكل متكرر في الحالة المفتوحة:

1. تحقق من **Dashboard → Health → Provider Health** لمعرفة نمط الفشل
2. انتقل إلى **الإعدادات → المرونة → ملفات تعريف الموفر** وقم بزيادة حد الفشل
3. تحقق مما إذا كان الموفر قد قام بتغيير حدود واجهة برمجة التطبيقات (API) أو طلب إعادة المصادقة
4. قم بمراجعة القياس عن بعد لزمن الاستجابة - قد يتسبب زمن الاستجابة العالي في حدوث أعطال بسبب انتهاء المهلة

---

## مشكلات النسخ الصوتي

### خطأ "نموذج غير مدعوم".

- تأكد من أنك تستخدم البادئة الصحيحة: `deepgram/nova-3` أو `assemblyai/best`
- تحقق من أن الموفر متصل في **لوحة التحكم ← الموفرون**

### يعود النسخ فارغًا أو يفشل

- تحقق من تنسيقات الصوت المدعومة: `mp3`، `wav`، `m4a`، `flac`، `ogg`، `webm`
- التحقق من أن حجم الملف يقع ضمن حدود الموفر (عادةً أقل من 25 ميجابايت)
- التحقق من صلاحية مفتاح API الخاص بالموفر في بطاقة المزود

---

## تصحيح أخطاء المترجم

استخدم **لوحة المعلومات → المترجم** لتصحيح مشكلات ترجمة التنسيق:

| الوضع                | متى تستخدم                                                                         |
| -------------------- | ---------------------------------------------------------------------------------- |
| **ساحة اللعب**       | قارن تنسيقات الإدخال/الإخراج جنبًا إلى جنب — الصق طلبًا فاشلاً لترى كيف تتم ترجمته |
| ** اختبار الدردشة ** | أرسل رسائل مباشرة وافحص حمولة الطلب/الاستجابة الكاملة بما في ذلك الرؤوس            |
| ** مقعد الاختبار **  | قم بإجراء اختبارات مجمعة عبر مجموعات التنسيق للعثور على الترجمات المعطلة           |
| **مراقبة حية**       | شاهد تدفق الطلبات في الوقت الفعلي للتعرف على مشكلات الترجمة المتقطعة               |

### مشكلات التنسيق الشائعة

- **لا تظهر علامات التفكير** — تحقق مما إذا كان الموفر المستهدف يدعم التفكير وإعداد ميزانية التفكير
- **استدعاءات الأداة** — قد تؤدي بعض ترجمات التنسيق إلى إزالة الحقول غير المدعومة؛ تحقق في وضع الملعب
- **مطالبة النظام مفقودة** — يتعامل نظام Claude وGemini مع المطالبات بشكل مختلف؛ التحقق من إخراج الترجمة
- ** تقوم SDK بإرجاع سلسلة أولية بدلاً من الكائن ** - تم الإصلاح في الإصدار 1.1.0: تقوم أداة معالجة الاستجابة الآن بإزالة الحقول غير القياسية (`x_groq`، `usage_breakdown`، وما إلى ذلك) التي تتسبب في فشل التحقق من صحة OpenAI SDK Pydantic
- **GLM/ERNIE يرفض دور `system`** — تم إصلاحه في الإصدار 1.1.0: يقوم مُطبيع الدور تلقائيًا بدمج رسائل النظام في رسائل المستخدم للنماذج غير المتوافقة
- **`developer` لم يتم التعرف على الدور** — تم إصلاحه في الإصدار 1.1.0: تم تحويله تلقائيًا إلى `system` لمقدمي الخدمات غير التابعين لـ OpenAI
- **`json_schema` لا يعمل مع Gemini** — تم إصلاحه في الإصدار 1.1.0: `response_format` تم تحويله الآن إلى `responseMimeType` + `responseSchema` الخاص بـ Gemini\_\_

---

## إعدادات المرونة

### لا يتم تشغيل حد المعدل التلقائي

- ينطبق حد المعدل التلقائي فقط على موفري مفاتيح واجهة برمجة التطبيقات (وليس OAuth/الاشتراك)
- تحقق من أن **الإعدادات → المرونة → ملفات تعريف الموفر** تم تمكين حد المعدل التلقائي
- تحقق مما إذا كان الموفر يعرض `429` رموز الحالة أو رؤوس `Retry-After`

### ضبط التراجع الأسي

تدعم ملفات تعريف الموفر هذه الإعدادات:

- **التأخير الأساسي** — وقت الانتظار الأولي بعد الفشل الأول (الافتراضي: 1 ثانية)
- **الحد الأقصى للتأخير** — الحد الأقصى لوقت الانتظار (الافتراضي: 30 ثانية)
- **المضاعف** — مقدار زيادة التأخير لكل فشل متتالي (الافتراضي: 2x)

### قطيع مضاد للرعد

عندما تصل العديد من الطلبات المتزامنة إلى موفر محدود السعر، يستخدم OmniRoute تحديد المعدل التلقائي + mutex لإجراء تسلسل للطلبات ومنع حالات الفشل المتتالية. وهذا تلقائي لموفري مفاتيح API.

---

## هل مازلت عالقًا؟

- **مشكلات GitHub**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
- **الهندسة المعمارية**: راجع [link](ARCHITECTURE.md) للحصول على التفاصيل الداخلية
- **مرجع واجهة برمجة التطبيقات**: راجع [link](API_REFERENCE.md) لجميع نقاط النهاية
- **لوحة معلومات الصحة**: تحقق من **لوحة المعلومات ← الصحة** لمعرفة حالة النظام في الوقت الفعلي
- **المترجم**: استخدم **لوحة المعلومات ← المترجم** لتصحيح مشكلات التنسيق
