أداة OpenCode لا تعمل: إصلاح PATH والشاشة السوداء وأخطاء النماذج
قائمة إصلاحات لأداة OpenCode تبدأ بالتشخيص — خطأ "command not found" في Windows، ونوافذ الطرفية السوداء، وأخطاء الحصة المجانية والمزوّدين، وقائمة نماذج تبدو ناقصة، وإضافة VS Code — كل إصلاح معروض في تسجيل حقيقي.
إجابات سريعة
- ظهور "opencode: command not found" مباشرة بعد التثبيت؟ مجلد bin من المثبّت غير موجود في PATH — أضِفه بأمر export في ملف تعريف الصدفة (يضيف الفيديو مسار .opencode/bin لـ Git Bash) ثم افتح طرفية جديدة.
- سكربت التثبيت يرمي أخطاء؟ إنه سكربت Bash — تشغيله من PowerShell يفشل عند الراية -fsSL. حوّل أولاً ملف تعريف الطرفية الافتراضي في VS Code إلى Git Bash، ثم أعد تشغيل curl -fsSL https://opencode.ai/install | bash.
- الطرفية أو نافذة التطبيق تُفتح سوداء؟ احذف مجلد البيانات التالف تحت .local/share/opencode (على ويندوز AppData\Local\share\opencode)، وأنهِ العمليات العالقة، وأعد التشغيل — في التسجيل يستعيد الـ TUI رسمه خلال أقل من دقيقة.
- رسالة "Free usage exceeded" أو أخطاء المزوّدين؟ افتح منتقي النماذج بـ /models وبدّل إلى نموذج آخر، أو أعد المصادقة عبر /connect. شغّل opencode auth list للتأكد من وصول بيانات اعتمادك.
- نماذج مفقودة من القائمة؟ يظهر المزوّدون المتصلون فقط. أضف المزوّد عبر /connect، أو نظّم القائمة بمفاتيح model وdisabled_providers وقوائم السماح/الحجب لكل مزوّد في opencode.json.
Fix OpenCode Error in Antigravity Terminal (Git Bash + PATH Solution)
القناة:teacher account5:52
OpenCode docs — install, config & troubleshooting
الوثائق:opencode.ai/docs
اللقطات من ثلاثة تسجيلات شاشة: إصلاح PATH أعلاه، وإصلاح شاشة سوداء في Windows (xiXPoY2d4iw بواسطة Vũ Văn Hà)، وتبديل نموذج بعد نفاد الحصة المجانية (DX8MZFuu1BM بواسطة Free Code). كل خطوة تنقلك إلى موضعها في الفيديو.
تبقى لقطات الفيديو ملك لمبدعيها، وهي مضمّنة هنا كتوثيق خطوة بخطوة مع نسب المحتوى وروابط مباشرة.
إصلاح OpenCode خطوة بخطوة
التثبيت و PATH — مرحلة "الأمر غير معروف"
- 1
احصل على أمر التثبيت الرسمي
افتح opencode.ai وانسخ الأمر من صندوق التثبيت — curl -fsSL https://opencode.ai/install | bash — أو حوّل التبويب إلى npm أو bun أو brew. إذا كانت OpenCode "لا تعمل" لأنها لم تُثبَّت كاملة يوماً، فإن البدء من هذا الأمر الرسمي خير من مناقشة أمر منسوخ على عجل.
صندوق التثبيت في opencode.ai بتبويباته curl وnpm وbun وbrewشاهد عند 0:08 - 2
شغّل المثبّت من صدفة Bash لا من PowerShell
سكربت التثبيت مكتوب لـ Bash. لصقه في PowerShell ينتج الخطأ Invoke-WebRequest: A parameter cannot be found that matches parameter name 'fsSL'، تماماً كما وثّقه التسجيل. الإصلاح الظاهر على الشاشة: ضبط terminal.integrated.defaultProfile.windows إلى Git Bash في settings.json للبيئة ليصل الأمر إلى صدفة Bash.
خطأ -fsSL الذي يرميه PowerShell بجوار إعداد الملف التعريفي الافتراضيشاهد عند 1:32 - 3
أصلح "opencode: command not found" بتمديد PATH
انتهى التثبيت لكن الطرفية ما تزال تقول bash: opencode: command not found — مجلد الملف التنفيذي لم يصل إلى PATH. يضيف التسجيل مجلد .opencode/bin بأمر export PATH=/c/Users/<you>/.opencode/bin:$PATH في Git Bash ثم يشغّل opencode من جديد — والسطر نفسه في ~/.bashrc يجعله دائماً.
رسالة command not found، وأمر تصدير PATH، والمحاولة الناجحةشاهد عند 4:32 - 4
أعد تشغيل المثبّت في Git Bash وتأكد
بعد أن أصبح Git Bash هو الملف التعريفي الافتراضي، شغّل curl -fsSL https://opencode.ai/install | bash مرة أخرى وأكمل حتى النهاية. يمكنك التثبيت أيضاً عبر npm بأمر npm install -g opencode-ai، أو عبر choco وscoop على ويندوز. أعد فتح الطرفية بعدها ليتحدّث PATH.
Git Bash كملف تعريفي افتراضي أثناء إعادة تشغيل أمر التثبيتشاهد عند 2:30
الشاشة السوداء وانهيارات التشغيل
- 5
تعرّف على إقلاع الشاشة السوداء
نمط عطل ثانٍ: تكتب opencode فيتغير عنوان النافذة ويبقى جسمها أسود — لا لافتة ولا محث. يعرض التسجيل هذه النافذة الميتة بالضبط على Windows 11. إدخالك ليس المشكلة؛ حالة تالفة على القرص أو عملية عالقة تمنع الـ TUI من الرسم.
نافذة موجه الأوامر الفارغة بعد إطلاق opencode مباشرةشاهد عند 0:09 - 6
احذف مجلد البيانات التالف
الإصلاح الظاهر في التسجيل: أغلق OpenCode، وأنهِ النسخ العالقة من إدارة المهام، ثم احذف مجلد البيانات AppData\Local\share\opencode (وهو ~/.local/share/opencode على macOS وLinux). يحفظ هذا المجلد auth.json والسجلات وحالة المشاريع، لذا ستحتاج إلى المصادقة من جديد بعده — ثمن زهيد مقابل TUI تعمل.
مجلد بيانات opencode تحت AppData\Local\share قبل الحذفشاهد عند 0:28 - 7
أعد الإطلاق وتأكد من رسم الـ TUI
شغّل opencode مرة أخرى. المشهد التالي في التسجيل هو واجهة الطرفية السليمة — لافتة، ومحث Ask anything، وتلميح "Run /connect to add an AI provider and start coding". إذا بقيت نافذتك معتمة، شغّلها بـ opencode --print-logs وافحص أحدث ملف تحت مجلد log/ لترى السطر المسبب للعطل.
واجهة OpenCode TUI بعد استعادتها عند تنظيف الحالةشاهد عند 1:09
مشكلات المزوّدين والنماذج و IDE
- 8
اقرأ رسالة الحصة المجانية قبل التبديل
عند نفاد حصة نموذج مدمج، تعرض الجلسة لافتة حمراء "Free usage exceeded, subscribe to Go [retrying…]" وتتوقف عن الاستجابة. هذا ليس انهياراً — يُظهر التسجيل الجلسة تستعيد نفسها لحظة اختيار نموذج آخر، فاقرأ الرسالة بوصفها إشارة للانتقال إلى الخطوة 9.
لافتة Free usage exceeded وسطر النموذج الحاليشاهد عند 0:36 - 9
افتح منتقي النماذج واختر نموذجاً آخر
شغّل /models داخل الجلسة (أو opencode models من الصدفة) لعرض كل ما يقدمه مزوّدوك المتصلون. يختار التسجيل نموذجاً آخر موسوماً بـ Free من كتالوج OpenCode Zen؛ أي نموذج تملك بيانات اعتماد له خيار متاح، بما فيه Claude وGPT وGemini بعد ربطها عبر /connect.
منتقي Select model مع نماذج موسومة بـ Free والمزوّدينشاهد عند 0:12 - 10
اختر صيغة جهد استدلال إن عُرضت عليك
بعض النماذج تفتح حوار Select variant ثانياً بخيارات Default وminimal وmedium وhigh وxhigh، كما وثّق التسجيل. الجهود الأدنى تجيب أسرع وبتكلفة أقل؛ واحتفظ بـ high للمهام الصعبة. ينطبق الاختيار على الجلسة الحالية فقط، فالتجربة آمنة.
قائمة Select variant بخيارات استدلال من minimal إلى xhighشاهد عند 0:20 - 11
أكّد التبديل في شريط الحالة
شريط الحالة تحت المحث يسمّي النموذج النشط — في التسجيل يظهر بعد التبديل Build · Muse Spark 1.2 Free · OpenCode Zen · xhigh، ولوحة السياق تعرض الرموز المستخدمة والمصروف $0.00. إذا استمر خطأ عنيد حتى على النموذج الجديد، فأعد المصادقة عبر /connect وتحقق بـ opencode auth list.
شريط الحالة يؤكد النموذج والجهد بعد التبديلشاهد عند 0:30 - 12
اربط OpenCode بـ VS Code
لموقف "لا تعمل داخل VS Code": افتح الطرفية المدمجة وشغّل opencode، فتُثبَّت إضافة OpenCode تلقائياً — يعرض التسجيل opencode for VS Code by SST في قائمة Installed. بعدها يفتح Ctrl+Esc العميل في طرفية منقسمة؛ وإن لم ينجح ذلك، فابحث عن "OpenCode" في سوق الإضافات وثبّتها يدوياً.
إضافة opencode بعد التثبيت وتعليمات تشغيل المثبّتشاهد عند 3:02
ما زالت معطلة؟ امشِ على قائمة الفحص
إن لم تغطِ المراحل الثلاث أعلاه عرضك، فهذه أنماط الأعطال المتبقية — كل واحدة مربوطة بالوثائق الرسمية لتعالج السبب لا العرض.
- 1ما زال "غير معروف" بعد التثبيت — كل طرفية مفتوحة تحتفظ بـ PATH القديم. أغلق الصدفة وافتحها من جديد وضع سطر export في ~/.bashrc (أو اضبط PATH في ويندوز من خصائص النظام) ليبقى بعد إعادة التشغيل. مستخدمو npm: تأكد أن مجلد bin العام لـ npm ضمن PATH أيضاً.
- 2لا تبدأ إطلاقاً — شغّل opencode --print-logs لترى الفشل مباشرة، ثم اقرأ آخر سجل في ~/.local/share/opencode/log/ (على ويندوز %USERPROFILE%\.local\share\opencode\log). يُحتفظ بآخر 10 سجلات فقط؛ والمهم منها الأحدث. إذا شككت في قِدم الملف التنفيذي فجرّب opencode upgrade.
- 3ProviderInitError أو "invalid or corrupted configuration" — توصي الوثائق بمسح مجلد البيانات (rm -rf ~/.local/share/opencode) ثم إعادة المصادقة عبر /connect. العلاج نفسه المتبع في الخطوة 6 لإصلاح الشاشة السوداء، لكن الوصول إليه هذه المرة من رسالة الخطأ.
- 4AI_APICallError في منتصف الجلسة — امسح ذاكرة حزم المزوّدين بـ rm -rf ~/.cache/opencode وأعد التشغيل لتُعاد حزم SDK للمزوّدين. افحص opencode auth list بعدها؛ فانتهاء صلاحية بيانات الاعتماد أو فقدانها هو السبب الثاني شيوعاً.
- 5تطبيق سطح المكتب ميت على ويندوز — حدّث بيئة WebView2، وأغلق تماماً ثم أعد التشغيل، وأزل أي تجاوز مخصص لـ server.port / OPENCODE_PORT. توصي الوثائق بـ WSL لأفضل تجربة على ويندوز، وهو ما يتجاوز أغلب مشكلات الملفات التعريفية للطرفية أيضاً.
- 6لا تظهر كل النماذج — يسرّد /models المزوّدين المتصلين بك فقط. أضف واحداً عبر /connect، ونظّم الكتالوج في opencode.json: اجعل "model": "provider/model-id" افتراضياً، أو أخفِ المزوّدين بـ disabled_providers، أو ضيّق قائمة مزوّد بعناصر السماح/الحجب الخاصة به.
العمل على القائمة بالترتيب يحل الغالبية العظمى من تقارير "opencode لا تعمل": PATH أولاً، ثم الحالة، ثم المزوّدون والنماذج. وإذا لم ينفع شيء، فاحفظ أحدث ملف سجل وافتح issue في مستودع OpenCode — المشرفون يطلبون السجل لا لقطة شاشة.