من وثيقة استكشاف الأخطاء

أصلح مشكلات OpenCode الشائعة

خطوات الاسترداد الرسمية لنافذة سطح مكتب فارغة، ومزود فاشل، وتقارير مكافحة الفيروسات على Windows التي ما زالت تظهر في متعقب المشكلات. نفّذها بالترتيب.

سطح المكتب لا يبدأ

معظم الأعطال ناتجة عن إضافة، أو ذاكرة مؤقتة تالفة، أو عنوان خادم مخصص. الجانب المساعد ما زال OpenCode CLI.

1. أغلق تماماً وأعد التشغيل. إن ظهرت شاشة خطأ، استخدم Restart وانسخ التفاصيل.
2. على macOS استخدم قائمة OpenCode ثم Reload Webview عندما تكون الواجهة فارغة أو متجمدة.
3. افتح %USERPROFILE%\.config\opencode\opencode.jsonc (أو ~/.config/opencode/opencode.jsonc) واضبط "plugin": [].
4. انقل %USERPROFILE%\.config\opencode\plugins وأي مجلد .opencode/plugins/ جانباً، ثم أعد التشغيل.
5. احذف الذاكرة المؤقتة في %USERPROFILE%\.cache\opencode (أو ~/.cache/opencode) وابدأ من جديد.
6. على Windows، إن كانت النافذة فارغة، ثبّت Microsoft Edge WebView2 أو حدّثه.

فشل الاتصال أو شاشة بدء عالقة

1. في الشاشة الرئيسية انقر اسم الخادم (نقطة الحالة) وامسح عنوان الخادم الافتراضي.
2. أزل أي كتلة server.port أو server.hostname من opencode.json وأعد التشغيل.
3. ألغِ OPENCODE_PORT إن كان يشير إلى منفذ مشغول.

أخطاء المزود

ProviderModelNotFoundError

1. تأكد من أنك صادقت عبر /connect.
2. أشر إلى النماذج بصيغة provider/model، مثل openai/gpt-4.1 أو openrouter/google/gemini-2.5-flash.
3. شغّل opencode models واختر اسماً يظهر فعلاً.

ProviderInitError

1. أكّد كتلة المزود في opencode.json.
2. إن بقي معطلاً، احذف %USERPROFILE%\.local\share\opencode (أو ~/.local/share/opencode).
3. شغّل /connect مرة أخرى.

AI_APICallError

1. امسح ذاكرة حزم المزود المؤقتة في %USERPROFILE%\.cache\opencode.
2. أعد التشغيل حتى يعيد OpenCode تثبيت حزم OpenAI أو Anthropic أو Google التي يخزّنها محلياً.

مكافحة فيروسات Windows و Smart App Control

هذه الشكوى التي تظهر كـ Wacatac و Kaspersky PDM و Event 3077. يستخرج OpenCode تبعيات أصلية إلى دليل مؤقت عند أول تشغيل. تعامل محركات الكشف الاستدلالي ذلك على أنه برمجية خبيثة معبأة. وقّع المشرفون CLI وسطح المكتب من v1.3.4. ما زالت إصدارات npm اللاحقة تعثر بعض الأجهزة.

1. فضّل ملف exe سطح المكتب الموقّع من download.html على إسقاط npm i -g opencode-ai الأقدم.
2. قارن SHA256 لملف opencode-desktop-win-x64.exe مع 7e6e4bca1b243609172fa580520e72ed240627fc9c36a80763a6f29bd64b698f.
3. إن حجر Defender مسبقاً مكتبة DLL عشوائية الاسم تحت Temp، استعد ذلك الملف فقط بعد تطابق التجزئة، ثم أضف مجلد تثبيت OpenCode (لا Temp كله) كاستثناء.
4. لا تعطّل Smart App Control. يتجاهل SAC استثناءات Defender. الإصدار الموقّع هو الإصلاح الفعلي.
5. إن وجب البقاء على npm فترة، ثبّت إصداراً معروفاً بأنه سليم بدل أن يسحب التحديث التلقائي الإصدار التالي. وثّق متعقب المشكلات أن التحديث التلقائي أعاد كسر تثبيتاً كان يعمل.

Windows عبر WSL

1. ثبّت WSL من دليل Microsoft نفسه.
2. في طرفية WSL شغّل سكربت التثبيت، ثم cd /mnt/c/Users/YourName/project و opencode.
3. لسطح المكتب مع WSL: opencode serve --hostname 0.0.0.0 --port 4096، ثم اربط التطبيق بـ http://localhost:4096. اضبط OPENCODE_SERVER_PASSWORD عندما تربط 0.0.0.0.
4. فضّل نسخة تحت نظام ملفات Linux (مثلاً ~/code/) عندما يبدو محرك Windows بطيئاً.

حافظة Linux و Wayland

1. X11: ثبّت xclip أو xsel.
2. Wayland: ثبّت wl-clipboard. يفضّله OpenCode عندما يكتشف Wayland.
3. نافذة فارغة أو متعطلة على Wayland: شغّل بـ OC_ALLOW_WAYLAND=1. إن ساء الأمر، احذف المتغير واستخدم جلسة X11.

أفضل الممارسات من المقدمة

أودع AGENTS.md: بعد /init، أودع الملف حتى ترى كل جلسة ملاحظات البنية نفسها.
Plan ثم Build: انتقل بـ Tab إلى Plan لتغيير متعدد الملفات. كرر الخطة. ارجع بـ Tab إلى Build فقط عندما تريد الكتابة.
سمّ الملفات: استخدم @ بدل «ملف المصادقة». مثال المقدمة يشير إلى مسار ملموس تحت packages/functions.
اقرأ السجلات أولاً: Windows: Win+R ثم %USERPROFILE%\.local\share\opencode\log. macOS/Linux: ~/.local/share/opencode/log/. استخدم opencode --log-level DEBUG أو --print-logs.