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

المشاكل الشائعة وكيفية حلها.

---

## مشاكل البوابة

### البوابة لا تبدأ

- **تعارض في المنفذ**, قد تستخدم عملية أخرى المنفذ 18789. تحقق باستخدام `lsof -i :18789`.
- **خطأ في الإعداد**, JSON غير صالح في `neotask.json`. تتحقق البوابة من الإعداد عند بدء التشغيل وتبلّغ عن أخطاء محددة.
- **قفل البوابة**, قد تكون نسخة سابقة تركت ملف قفل قديم. يمكن لأداة التشخيص اكتشاف هذا وإصلاحه.
- **إصدار Node.js**, تتطلب Neotask الإصدار Node 22 أو أحدث.

### البوابة تبدأ لكن لا تتصل القنوات

- **بيانات اعتماد مفقودة**, كل قناة تحتاج إلى مصادقتها الخاصة (رمز البوت أو مسح QR أو مفتاح API).
- **مشاكل الشبكة**, تحتاج القنوات إلى اتصال بالإنترنت للاتصال بـ APIs لمنصات المراسلة.
- **حدود المعدل**, بعض المنصات تحدد معدل الاتصالات الجديدة. انتظر وأعد المحاولة.

### لا يمكن الاتصال من تطبيق سطح المكتب

- **منفذ خاطئ**, تأكد من أن تطبيق سطح المكتب يتصل بمنفذ البوابة الصحيح.
- **عدم تطابق المصادقة**, يجب أن يتطابق رمز البوابة.
- **جدار الحماية**, تأكد من إمكانية الوصول إلى المنفذ إذا كانت البوابة على آلة أخرى.

---

## مشاكل القنوات

### WhatsApp لا يتصل

- **انتهت صلاحية QR**, تنتهي رموز QR بعد حوالي 60 ثانية. امسح بسرعة.
- **حد الأجهزة المتعددة**, WhatsApp يحدد عدد الأجهزة المرتبطة.
- **الجلسة تالفة**, احذف دليل جلسة WhatsApp وأعد الإقران.

### بوت Telegram لا يستقبل الرسائل

- **رمز البوت غير صالح**, تحقق من رمز البوت مع BotFather.
- **وضع الخصوصية**, البوتات ترى الرسائل فقط عند الإشارة إليها في المجموعات بشكل افتراضي.
- **تعارض Webhook**, قد تستهلك خدمة أخرى الرسائل.

### بوت Discord لا يستجيب

- **نوايا مفقودة**, فعّل Gateway Intents المطلوبة في Discord Developer Portal.
- **أذونات مفقودة**, يحتاج البوت إلى أذونات القراءة والإرسال في القنوات المستهدفة.

---

## مشاكل النموذج

### أخطاء المصادقة

- **المفتاح غير مُكوَّن**, تأكد من ضبط مفتاح API الخاص بالموفر.
- **المفتاح منتهي الصلاحية**, بعض رموز OAuth تنتهي صلاحيتها. أعد المصادقة.
- **حد المعدل**, سيتم التبديل التلقائي عند تدوير المفاتيح إذا كان لديك مفاتيح متعددة.

### استجابات بطيئة

- **اختيار النموذج**, النماذج الأكبر أبطأ. جرب نموذجاً أسرع للمهام السريعة.
- **حجم السياق**, المحادثات الطويلة تبطئ المعالجة. جرب `/compact`.
- **زمن استجابة الشبكة**, تحقق من الاتصال بموفر النموذج.

---

## مشاكل العقدة

### تطبيق الجهاز المرافق لا يجد البوابة

- **وضع الارتباط**, يجب ربط البوابة بـ LAN أو Tailnet (وليس loopback) للأجهزة الخارجية.
- **نفس الشبكة**, لاكتشاف Bonjour، يجب أن يكون كلا الجهازين على نفس الشبكة.
- **إدخال يدوي**, أدخل مضيف البوابة والمنفذ يدوياً في إعدادات التطبيق.

---

## مشاكل الجلسة

### تجاوز نافذة السياق

- **الضغط**, استخدم `/compact` لتلخيص السياق وإعادة ضبطه.
- **تفعيل الضغط التلقائي**, اضبط عتبة الضغط في الإعداد.
- **جلسة جديدة**, ابدأ من جديد بـ `/new`.

---

## التشخيص

تتحقق أداة التشخيص المدمجة من المشاكل الشائعة ويمكنها إصلاح كثير منها تلقائياً:

- التحقق من صحة الإعداد
- أذونات الملفات
- اتصال القنوات
- حالة مصادقة النموذج
- توافق Node.js
- تكوين الشبكة

تحقق من سجلات البوابة للحصول على معلومات تفصيلية عن الأخطاء. نقطة النهاية `/health` توفر حالة قابلة للقراءة آلياً لجميع المكونات.

---

## الحصول على المساعدة

1. شغّل أداة التشخيص للإصلاحات التلقائية
2. تحقق من سجلات البوابة للحصول على رسائل خطأ تفصيلية
3. تواصل مع الدعم عبر أداة الدردشة Intercom في تطبيق سطح المكتب