التثبيت لم ينجح؟ حلول المشاكل الشائعة

مقدمة

في الدرس السابق ثبّتنا Claude Code، وسجّلنا الدخول، وشغّلنا أول أمر. عند بعض الناس تمشي العملية من أول مرة خلال دقيقتين. وعند غيرهم تظهر رسالة حمراء غريبة. أو يكتب أحدهم claude، فيرد عليه الـ Terminal بأن الأمر غير معروف.

إذا كنت من المجموعة الثانية: المشكلة مش فيك، وجهازك مش معطّل. كل المشاكل تقريباً في هذه المرحلة تعود إلى أربعة أسباب فقط، وكلها تنحل في دقائق.

هذا الدرس مكتوب ليكون مرجعاً ترجع إليه وقت الحاجة. لا تحتاج قراءته كاملاً هسا. ابحث عن الرسالة التي ظهرت عندك، واقرأ القسم الخاص بها.

الأهداف التعليمية

بنهاية هذا الدرس، ستكون قادراً على:

• قراءة رسالة الخطأ ومعرفة أي نوع من المشاكل هي
• إصلاح مشكلة الـ PATH على Windows بشكل صحيح
• التأكد من أن اشتراكك يسمح باستخدام الأداة أصلاً
• التعامل مع رفض الصلاحيات على Mac
• معرفة متى تكون المشكلة في الشبكة، مش في التثبيت

المشكلة الأولى: كتبت claude فقال لي الأمر غير معروف

هذه أشهر مشكلة على الإطلاق، وشكلها كالتالي على Windows:

'claude' is not recognized as an internal or external command,
operable program or batch file.

أو على Mac:

command not found: claude

ماذا تعني هذه الرسالة؟ تعني أن التثبيت نجح فعلاً، لكن الـ Terminal لا يعرف وين وضع البرنامج. تخيّل أنك ركّبت تطبيقاً على جهازك، لكن لم يظهر له اختصار على سطح المكتب. التطبيق موجود، لكنك لا تملك طريقة لتشغيله بالاسم.

المكان الذي يبحث فيه الـ Terminal عن البرامج اسمه الـ PATH، وهو ببساطة قائمة مجلدات. إذا لم يكن مجلد Claude Code ضمن هذه القائمة، فلن يجده الـ Terminal.

الحل على Windows

عند انتهاء التثبيت، يطبع لك الـ Terminal مساراً يشبه هذا:

C:\Users\Shadow\.local\bin\claudecode.exe

انسخ هذا المسار، ثم:

1. ابحث في Windows عن Environment Variables واختر Edit the system environment variables
2. اضغط زر Environment Variables
3. ضمن System Variables، ابحث عن Path وانقر عليه نقراً مزدوجاً
4. اضغط New والصق المسار الذي نسخته
5. اضغط OK على كل النوافذ المفتوحة لحفظ الإعدادات

بعد الحفظ، أغلق الـ Terminal تماماً وافتحه من جديد. الـ Terminal يقرأ الـ PATH مرة واحدة فقط، عند فتحه. لذلك النافذة المفتوحة حالياً ما زالت تعمل بالقائمة القديمة. هذه الخطوة وحدها تحل نصف الحالات التي يقول أصحابها: "عملت كل شيء ولم ينفع".

الحل على Mac

على Mac، غالباً تكون المشكلة أن التثبيت وضع البرنامج في مجلد غير مضاف للـ PATH. تأكد أولاً أن الملف موجود فعلاً:

ls ~/.local/bin

إذا رأيت الملف هناك، أضف المجلد إلى الـ PATH:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc

ثم أغلق الـ Terminal وافتحه من جديد، أو نفّذ:

source ~/.zshrc

المشكلة الثانية: سجّلت الدخول لكن الأداة ترفض الاشتراك

قد تنجح في التثبيت وتسجيل الدخول، ثم تصطدم برسالة تخبرك أن حسابك لا يسمح باستخدام الأداة.

السبب: برنامج Claude Code يحتاج اشتراكاً مدفوعاً من نوع Pro أو Max أو Team. الحساب المجاني لا يشغّل الأداة، مهما كان التثبيت صحيحاً.

هذه مش مشكلة تقنية تنحل بأمر في الـ Terminal، ولا يوجد طريق للالتفاف عليها. الحل إما اشتراك مدفوع، أو مفتاح الـ API (رمز سري يربط الأداة بحساب فيه رصيد). عند تشغيل الأداة لأول مرة ستسألك أيهما تريد. ويمكنك اختيار مفتاح الـ API بدل تسجيل الدخول بالحساب.

المشكلة الثالثة: المتصفح فتح لكن تسجيل الدخول لم يكتمل

عند اختيار تسجيل الدخول بالحساب، يفتح Claude Code المتصفح تلقائياً. ثم يطلب منك الموافقة على الصلاحيات بالضغط على Authorize. أحياناً تظهر رسالة النجاح في المتصفح، لكن الـ Terminal يبقى ينتظر.

جرّب بالترتيب:

1. تأكد أنك مسجّل الدخول في المتصفح مسبقاً. إذا فتحت الصفحة وأنت غير مسجّل، ستدخل في دورة تسجيل دخول لا ترجع بك إلى الـ Terminal.
2. افتح الرابط في متصفحك الافتراضي. إذا انفتح الرابط في متصفح لا تستخدمه، ولست مسجّل الدخول فيه، انسخ الرابط والصقه في المتصفح الذي تعمل عليه.
3. أوقف العملية وأعد المحاولة. اضغط Control + C في الـ Terminal، ثم اكتب claude من جديد.
4. أغلق الـ VPN إن كان يعمل. خطوة التحقق تتم بين جهازك والخوادم مباشرة، وبعض خدمات الـ VPN تقطعها.

المشكلة الرابعة: جهاز Mac يرفض تشغيل الملف

على Mac قد تظهر رسالة Permission denied، أو تحذير بأن التطبيق من مطوّر غير موثوق.

للحالة الأولى، امنح الملف صلاحية التنفيذ:

chmod +x ~/.local/bin/claude

أما التحذير الأمني، فهو من نظام macOS نفسه، مش من الأداة. افتح System Settings ثم Privacy & Security، وستجد في الأسفل زراً يسمح بتشغيل التطبيق الذي منعه النظام للتو.

المشكلة الخامسة: التثبيت يتوقف في المنتصف

إذا توقف التثبيت أو ظهرت رسالة عن انقطاع الاتصال أو انتهاء المهلة، فالمشكلة غالباً في الشبكة لا في جهازك:

• شبكات الشركات والجامعات تحجب كثيراً من عناوين التحميل. جرّب من شبكة أخرى أو من بيانات الهاتف.
• برنامج مكافحة الفيروسات قد يوقف التحميل بصمت. أوقفه مؤقتاً وأعد المحاولة.
• أعد تشغيل الأمر ببساطة. التثبيت آمن للإعادة، ولن يفسد شيئاً إذا شغّلته مرة ثانية.

قاعدة عامة قبل أن تسأل

قبل أن تبحث عن حل، اسأل نفسك هذه الأسئلة الأربعة بالترتيب:

1. هل أغلقت الـ Terminal وفتحته من جديد بعد التعديل؟ إذا لم تفعل، فأنت تختبر الإعدادات القديمة.
2. هل المسار في الـ PATH ينتهي عند المجلد، مش عند الملف؟ أشهر خطأ على الإطلاق.
3. هل اشتراكك مدفوع؟ لا يوجد حل تقني لهذه النقطة.
4. هل قرأت الرسالة كاملة؟ في الغالب يخبرك الـ Terminal بالمشكلة بوضوح، لكن العين تقفز فوق النص الإنجليزي الطويل. اقرأ السطر الأخير تحديداً.

وإذا وصلت إلى هنا ولم تنحل المشكلة، انسخ الأمر الذي كتبته والرسالة كاملة. هذان هما كل ما يحتاجه أي شخص لمساعدتك. وبدونهما لا أحد يستطيع تخمين ما حدث.

خلاصة الدرس

1. رسالة command not found تعني أن التثبيت نجح، لكن الـ Terminal لا يجد البرنامج. المشكلة في الـ PATH، مش في التثبيت نفسه.

2. المسار في الـ PATH لازم ينتهي عند المجلد bin، مش عند الملف claudecode.exe. هذا الخطأ يبدو صحيحاً ولا يعطي أي رسالة، ولذلك يضيّع وقتاً أطول من غيره.

3. أغلق الـ Terminal وافتحه من جديد بعد أي تعديل على الإعدادات. النافذة المفتوحة تعمل بالقائمة القديمة.

4. الاشتراك المجاني لا يشغّل Claude Code. تحتاج اشتراك Pro أو Max أو Team، أو مفتاح الـ API بحساب فيه رصيد. وهذه نقطة تحسمها قبل التثبيت، مش بعده.

5. مشاكل تسجيل الدخول غالباً سببها المتصفح أو الـ VPN، مش الأداة. سجّل الدخول في المتصفح مسبقاً، وأغلق الـ VPN وقت التحقق.

6. التوقف في منتصف التحميل مشكلة شبكة. جرّب شبكة أخرى، وأعد تشغيل الأمر. التثبيت آمن للإعادة.

في الدرس الجاي: رح نبدأ تشغيل الـ Agent على شغل حقيقي. وأول مهمة ستكون جمع أخبار الصباح وتلخيصها لك جاهزة.

يلا، نلتقي بالدرس الجاي!