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

لاستكشاف المشكلات في OpenCode وإصلاحها، ابدأ بالتحقق من السجلات والبيانات المحلية التي يخزنها على القرص.

---

السجلات

يتم حفظ ملفات السجل في:

• macOS/Linux: ~/.local/share/opencode/log/
• Windows: اضغط WIN+R والصق %USERPROFILE%\.local\share\opencode\log

تتم تسمية ملفات السجل بطوابع زمنية (مثل 2025-01-09T123456.log) ويتم الاحتفاظ بأحدث 10 ملفات سجل.

يمكنك ضبط مستوى السجل باستخدام خيار CLI --log-level للحصول على معلومات تصحيح أكثر تفصيلا. على سبيل المثال: opencode --log-level DEBUG.

---

التخزين

يخزن opencode بيانات الجلسات وبيانات التطبيق الأخرى على القرص في:

• macOS/Linux: ~/.local/share/opencode/
• Windows: اضغط WIN+R والصق %USERPROFILE%\.local\share\opencode

يحتوي هذا الدليل على:

• auth.json - بيانات المصادقة مثل مفاتيح API ورموز OAuth
• log/ - سجلات التطبيق
• project/ - بيانات خاصة بالمشروع مثل بيانات الجلسة والرسائل
  • إذا كان المشروع داخل مستودع Git، فسيتم تخزينه في ./<project-slug>/storage/
  • إذا لم يكن داخل مستودع Git، فسيتم تخزينه في ./global/storage/

---

تطبيق سطح المكتب

يشغل OpenCode Desktop خادما محليا لـ OpenCode (العملية الجانبية opencode-cli) في الخلفية. معظم المشكلات سببها إضافة لا تعمل بشكل صحيح، أو ذاكرة تخزين مؤقت تالفة، أو إعداد خادم غير صحيح.

فحوصات سريعة

• أغلق التطبيق تماما ثم أعد تشغيله.
• إذا عرض التطبيق شاشة خطأ، انقر Restart وانسخ تفاصيل الخطأ.
• على macOS فقط: قائمة OpenCode -> Reload Webview (يفيد إذا كانت الواجهة فارغة/متجمدة).

---

تعطيل الإضافات

إذا كان تطبيق سطح المكتب يتعطل عند التشغيل، أو يتوقف عن الاستجابة، أو يتصرف بشكل غريب، فابدأ بتعطيل الإضافات.

تحقق من الإعدادات العامة

افتح ملف الإعدادات العام وابحث عن المفتاح plugin.

• macOS/Linux: ~/.config/opencode/opencode.jsonc (أو ~/.config/opencode/opencode.json)
• macOS/Linux (عمليات تثبيت أقدم): ~/.local/share/opencode/opencode.jsonc
• Windows: اضغط WIN+R والصق %USERPROFILE%\.config\opencode\opencode.jsonc

إذا كانت لديك إضافات مضبوطة، فقم بتعطيلها مؤقتا بإزالة المفتاح أو ضبطه على مصفوفة فارغة:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": [],
}

تحقق من أدلة الإضافات

يمكن لـ OpenCode أيضا تحميل إضافات محلية من القرص. انقلها مؤقتا إلى مكان آخر (أو أعد تسمية المجلد) ثم أعد تشغيل تطبيق سطح المكتب:

• إضافات عامة
  • macOS/Linux: ~/.config/opencode/plugins/
  • Windows: اضغط WIN+R والصق %USERPROFILE%\.config\opencode\plugins
• إضافات المشروع (فقط إذا كنت تستخدم إعدادات لكل مشروع)
  • <your-project>/.opencode/plugins/

إذا عاد التطبيق للعمل، فأعد تفعيل الإضافات واحدة تلو الأخرى لمعرفة أيها يسبب المشكلة.

---

مسح ذاكرة التخزين المؤقت

إذا لم يساعد تعطيل الإضافات (أو كانت عملية تثبيت إضافة عالقة)، فامسح ذاكرة التخزين المؤقت حتى يتمكن OpenCode من إعادة بنائها.

1. أغلق OpenCode Desktop تماما.
2. احذف دليل ذاكرة التخزين المؤقت:

• macOS: Finder -> Cmd+Shift+G -> الصق ~/.cache/opencode
• Linux: احذف ~/.cache/opencode (أو شغّل rm -rf ~/.cache/opencode)
• Windows: اضغط WIN+R والصق %USERPROFILE%\.cache\opencode

3. أعد تشغيل OpenCode Desktop.

---

إصلاح مشكلات اتصال الخادم

يمكن لـ OpenCode Desktop إما تشغيل خادمه المحلي (افتراضيا) أو الاتصال بعنوان URL لخادم قمت بتهيئته.

إذا ظهرت نافذة “Connection Failed” (أو لم يتجاوز التطبيق شاشة البداية)، فتحقق مما إذا كان هناك عنوان URL مخصص للخادم.

مسح عنوان URL الافتراضي لخادم سطح المكتب

من شاشة Home، انقر اسم الخادم (مع نقطة الحالة) لفتح محدد الخوادم. في قسم Default server، انقر Clear.

إزالة server.port / server.hostname من الإعدادات

إذا كان opencode.json(c) يحتوي على قسم server، فأزله مؤقتا ثم أعد تشغيل تطبيق سطح المكتب.

تحقق من متغيرات البيئة

إذا كان OPENCODE_PORT مضبوطا في بيئتك، فسيحاول تطبيق سطح المكتب استخدام ذلك المنفذ للخادم المحلي.

• أزل ضبط OPENCODE_PORT (أو اختر منفذا متاحا) ثم أعد التشغيل.

---

Linux: مشكلات Wayland / X11

على Linux، قد تتسبب بعض إعدادات Wayland في نوافذ فارغة أو أخطاء في مدير التركيب (compositor).

• إذا كنت تستخدم Wayland وكانت نافذة التطبيق فارغة/يتعطل، فجرّب التشغيل مع OC_ALLOW_WAYLAND=1.
• إذا جعل ذلك الأمور أسوأ، فأزل هذا المتغير وجرّب التشغيل ضمن جلسة X11 بدلا من ذلك.

---

Windows: بيئة تشغيل WebView2

على Windows، يتطلب OpenCode Desktop وجود WebView2 Runtime الخاصة بـ Microsoft Edge. إذا فتح التطبيق نافذة فارغة أو لم يبدأ، فقم بتثبيت/تحديث WebView2 ثم جرّب مجددا.

---

Windows: مشكلات الأداء العامة

إذا كنت تواجه بطءا في الأداء، أو مشكلات في الوصول إلى الملفات، أو مشكلات في terminal على Windows، فجرّب استخدام WSL (نظام Windows الفرعي لـ Linux). يوفر WSL بيئة Linux تعمل بسلاسة أكبر مع ميزات OpenCode.

---

الإشعارات لا تظهر

لا يعرض OpenCode Desktop إشعارات النظام إلا عندما:

• تكون الإشعارات مفعلة لـ OpenCode في إعدادات نظام التشغيل، و
• تكون نافذة التطبيق غير نشطة.

---

إعادة تعيين تخزين تطبيق سطح المكتب (كحل أخير)

إذا لم يبدأ التطبيق ولم تتمكن من مسح الإعدادات من داخل الواجهة، فأعد تعيين الحالة المحفوظة لتطبيق سطح المكتب.

1. أغلق OpenCode Desktop.
2. اعثر على هذه الملفات واحذفها (توجد في دليل بيانات تطبيق OpenCode Desktop):

• opencode.settings.dat (عنوان URL الافتراضي لخادم سطح المكتب)
• opencode.global.dat و opencode.workspace.*.dat (حالة الواجهة مثل الخوادم/المشاريع الأخيرة)

للعثور على الدليل بسرعة:

• macOS: Finder -> Cmd+Shift+G -> ~/Library/Application Support (ثم ابحث عن أسماء الملفات أعلاه)
• Linux: ابحث ضمن ~/.local/share عن أسماء الملفات أعلاه
• Windows: اضغط WIN+R -> %APPDATA% (ثم ابحث عن أسماء الملفات أعلاه)

---

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

إذا كنت تواجه مشكلات مع OpenCode:

1. الإبلاغ عن المشكلات على GitHub

   أفضل طريقة للإبلاغ عن الأخطاء أو طلب الميزات هي عبر مستودعنا على GitHub:

   github.com/anomalyco/opencode/issues

   قبل إنشاء مشكلة جديدة، ابحث في المشكلات الموجودة لمعرفة ما إذا كانت مشكلتك قد تم الإبلاغ عنها بالفعل.

2. انضم إلى Discord

   للحصول على مساعدة فورية ونقاشات المجتمع، انضم إلى خادم Discord الخاص بنا:

   opencode.ai/discord

---

مشكلات شائعة

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

---

OpenCode لا يبدأ

1. تحقق من السجلات بحثا عن رسائل الخطأ
2. جرّب التشغيل مع --print-logs لرؤية المخرجات في terminal
3. تأكد من أنك تستخدم أحدث إصدار عبر opencode upgrade

---

مشكلات المصادقة

1. جرّب إعادة المصادقة باستخدام الأمر /connect في واجهة TUI
2. تحقق من أن مفاتيح API الخاصة بك صالحة
3. تأكد من أن شبكتك تسمح بالاتصال بواجهة API الخاصة بالمزوّد

---

النموذج غير متاح

1. تحقق من أنك قمت بالمصادقة مع المزوّد
2. تأكد من أن اسم النموذج في الإعدادات صحيح
3. قد تتطلب بعض النماذج صلاحيات وصول محددة أو اشتراكات

إذا واجهت ProviderModelNotFoundError فمن المرجح أنك تشير إلى نموذج بشكل غير صحيح في مكان ما. يجب الإشارة إلى النماذج بهذه الصيغة: <providerId>/<modelId>

أمثلة:

• openai/gpt-4.1
• openrouter/google/gemini-2.5-flash
• opencode/kimi-k2

لمعرفة النماذج التي لديك صلاحية الوصول إليها، شغّل opencode models

---

ProviderInitError

إذا واجهت ProviderInitError، فمن المحتمل أن إعداداتك غير صالحة أو تالفة.

لحل ذلك:

1. أولا، تحقق من أن المزوّد مضبوط بشكل صحيح باتباع دليل المزوّدين

2. إذا استمرت المشكلة، فجرّب مسح الإعدادات المخزنة لديك:

   rm -rf ~/.local/share/opencode

   على Windows، اضغط WIN+R واحذف: %USERPROFILE%\.local\share\opencode

3. أعد المصادقة مع المزوّد باستخدام الأمر /connect في واجهة TUI.

---

AI_APICallError ومشكلات حزم المزوّد

إذا واجهت أخطاء في استدعاءات API، فقد يكون السبب حزم مزوّد قديمة. يقوم opencode بتثبيت حزم المزوّد (OpenAI و Anthropic و Google وغير ذلك) ديناميكيا عند الحاجة ويقوم بتخزينها مؤقتا محليا.

لحل مشكلات حزم المزوّد:

1. امسح ذاكرة التخزين المؤقت لحزم المزوّد:

   rm -rf ~/.cache/opencode

   على Windows، اضغط WIN+R واحذف: %USERPROFILE%\.cache\opencode

2. أعد تشغيل opencode لإعادة تثبيت أحدث حزم المزوّد

سيجبر ذلك opencode على تنزيل أحدث إصدارات حزم المزوّد، وهو ما يحل غالبا مشكلات التوافق مع معاملات النماذج وتغييرات API.

---

النسخ/اللصق لا يعمل على Linux

يحتاج مستخدمو Linux إلى تثبيت إحدى أدوات الحافظة التالية حتى تعمل ميزة النسخ/اللصق:

لأنظمة X11:

apt install -y xclip
# or
apt install -y xsel

لأنظمة Wayland:

apt install -y wl-clipboard

للبيئات بدون واجهة رسومية (Headless):

apt install -y xvfb
# and run:
Xvfb :99 -screen 0 1024x768x24 > /dev/null 2>&1 &
export DISPLAY=:99.0

سيكتشف opencode ما إذا كنت تستخدم Wayland ويفضل wl-clipboard، وإلا فسيحاول العثور على أدوات الحافظة بالترتيب التالي: xclip ثم xsel.