ماذا تفعل إذا تعذّر التثبيت: استكشاف أخطاء البداية وفحص سريع في 60 ثانية
انتهيت من تنفيذ أوامر درس التثبيت، لكن عند كتابة claude لا يحدث شيء — لا تتعجل بإعادة التثبيت. فشل تثبيت Claude Code يتعلق في الغالبية الساحقة بأربع مراحل: التنزيل، التثبيت، توفر الأمر، تسجيل الدخول، ولكل مرحلة مظهر أخطاء مختلف. تنظم هذه الصفحة الأخطاء عالية التكرار من وثائق استكشاف الأخطاء الرسمية بأسلوب «مطابقة النص الأصلي»: حدّد المرحلة أولًا بالفحص السريع في 60 ثانية، ثم اتبع البند المقابل للإصلاح.
كيف تستخدم هذه الصفحة: انسخ نص الخطأ الذي واجهته حرفيًا وطابقه مع نصوص الأخطاء في عناوين H4 أدناه، ثم اقرأ مباشرة بند «السبب + الحل» الخاص به. وإن لم تجد تطابقًا تامًا، فشغّل الفحص السريع في 60 ثانية لتضييق النطاق. (وقت التحقق من الحقائق 2026-11-04؛ الأوامر والأخطاء تتغير مع تحديثات الإصدارات، والمرجع هو وثائق استكشاف الأخطاء الرسمية.)
💡 الأخطاء التي تظهر بعد نجاح التثبيت ليست ضمن هذه الصفحة
تهتم هذه الصفحة بحالات «تعذّر التثبيت، تعذّر تسجيل الدخول». أما إذا كان الحوار يعمل بشكل طبيعي والخطأ وقع أثناء التشغيل (أخطاء النموذج، تعطل الأدوات)، فانتقل إلى حلقة الأخطاء: أعد تغذية رسالة الخطأ كما هي.
ماذا ستستطيع أن تفعل بعد إتمام الدرس
- تحديد المرحلة المتعثرة خلال 60 ثانية باستخدام 4 أوامر: توفر الأمر، ملفات التثبيت، الشبكة، سلامة التثبيت
- إصلاح
claude command not found/'claude' is not recognized(إعداد PATH لمرة واحدة، وبعد ضبطه لا تحتاج للعودة إليه) - التمييز بين أخطاء التنزيل (403، TLS، تحول السكربت إلى صفحة ويب): هل تعيد المحاولة أم تفحص الشبكة أم تغيّر قناة التثبيت
- معالجة أعطال تثبيت npm الثلاثة الكبرى: أذونات
EACCES، وتخطي npm 12 لـ postinstall، والمجلدات المتبقيةENOTEMPTY - عند تعثّر تسجيل الدخول اتبع خطوات «تسجيل الخروج ← إعادة الفتح ← تسجيل الدخول من جديد»، وفرّق بين أعراض الاشتراك والدور وتغطية مفتاح API
ما الذي تواجهه الآن
- انتهى أمر التثبيت، لكن عند كتابة
claudeتظهر رسالة command not found — هل تم التثبيت فعلًا أم لا؟ - رسالة الخطأ نص طويل بالإنجليزية، ولا تدري هل تعيد المحاولة في مكانك أم تفحص الشبكة أم تغيّر طريقة التثبيت وتبدأ من جديد
- تم التثبيت بنجاح، لكن صفحة تسجيل الدخول تدور في حلقة أو تعرض خطأ ولا يمكنك الدخول
متى تستخدم هذه الطريقة
عندما تحتاج إلى:
- إصلاح الأخطاء المتعثرة في درس تثبيت Claude Code أو درس طرق التثبيت البديلة
- قبل أن تنشر منشورًا طلبًا للمساعدة، اقضِ 60 ثانية بنفسك لتحديد المرحلة التي نشأ فيها الخطأ
وأيضًا لا تريد:
- أن تذهب إلى المنتديات وتنتظر الردود عند أول خطأ — الفحص السريع يحل معظم مشكلات التثبيت
- أن تتعامل مع «فشل التنزيل» كأنه «لم يُثبَّت» فتعيد التثبيت مرارًا وتزيد الأمور سوءًا
🎒 التحضير قبل البدء
- أن تكون قد نفّذت درس تثبيت Claude Code (لا مشكلة إن تعثّرت، فهذه الصفحة موجودة لحل التعثر)
- أن تعرف أي طرفية تفتحها: على macOS / Linux هي نافذة الطرفية؛ وعلى Windows هناك PowerShell (المحث يحمل
PS) و CMD (بدونه) - أن تنسخ نص الخطأ حرفيًا — المطابقة الحرفية أسرع بكثير من وصفه بترجمة
الفكرة الجوهرية: Claude Code المراحل الأربع لفشل تثبيت
حدّد المرحلة أولًا، ثم انظر إلى رسالة الخطأ. من تشغيل أمر التثبيت حتى القدرة على إجراء محادثة، يجب اجتياز أربع مراحل بالتتابع، وشكل رسالة الخطأ في كل مرحلة مختلف:
| المرحلة | أعراض التعثر | رسالة خطأ نموذجية | المجموعة المقابلة في هذه الصفحة |
|---|---|---|---|
| 1. التنزيل | أمر التثبيت لا يكتمل، أو ما تم تنزيله هو صفحة ويب | curl: (22) The requested URL returned error: 403 وsyntax error near unexpected token '<' | مشكلات التنزيل والشبكة |
| 2. التثبيت | استخدام shell خاطئ في الأمر، أو عدم وجود صلاحيات على المجلد، أو توقف تثبيت npm في منتصفه | 'irm' is not recognized وEACCES وnpm error code ENOTEMPTY | مشكلات أمر التثبيت على Windows / مشكلات تثبيت npm |
| 3. توفر الأمر | تم التثبيت، لكن الـ shell لا يجد الأمر | zsh: command not found: claude | مشكلات توفر الأمر (PATH) |
| 4. تسجيل الدخول | اكتمل التثبيت، لكن صفحة تسجيل الدخول تُحمّل بلا نهاية أو تُظهر خطأ | OAuth error: Invalid code | مشكلات تسجيل الدخول والمصادقة |
نص رسالة الخطأ الأصلي هو المفتاح. توثّق استكشاف الأخطاء الرسمي الحلول بحسب نص رسالة الخطأ الأصلي، وهذه الصفحة تفعل المثل: انسخ رسالة الخطأ التي واجهتها حرفيًا وطابقها مع عناوين H4 أدناه. الأوصاف المترجمة كثيرًا ما لا تتطابق — إذا تُرجمت 'claude' is not recognized إلى «غير معروف»، فلن تجد الحل الأصلي بالبحث.
التحقق بعد الإصلاح موحّد في خطوة واحدة: افتح طرفية جديدة وشغّل claude --version، وإذا طُبع رقم الإصدار (بصيغة 2.1.211 (Claude Code)) فاعتبر المرحلة مجتازة.
الفحص الأول: فحص سريع في 60 ثانية
شغّل الأوامر الأربعة بالترتيب، للتحقق تباعًا من توفر الأمر، وملفات التثبيت، والشبكة، وسلامة التثبيت — أي أمر يتوقف عنده، فالمشكلة في تلك المرحلة.
macOS / Linux (شغّله في الطرفية):
# 1. 命令可用吗?——能打印版本号 = 安装环节全过,卡的是登录,直接跳「登录认证问题」
claude --version
# 2. 安装文件在吗?——有列表输出 = 装上了,是 PATH 问题,跳「命令可用(PATH)问题」
# No such file or directory = 没装上,看第 3 条
ls -la ~/.local/bin/claude
# 3. 网络通吗?——第一行 HTTP/2 200 = 下载服务器可达,重装一次多半就好
# 403 或无输出 = 网络/地区问题,跳「下载与网络问题」
curl -sI https://downloads.claude.ai/claude-code-releases/latest
# 4. 安装健康吗?——第 1 条能出版本号、但 claude 一启动就崩或卡住时,跑官方自检看诊断报告
claude doctorWindows (شغّله في PowerShell؛ لاحظ أن curl يجب كتابته curl.exe، فـ curl في PowerShell هو اسم بديل لـ Invoke-WebRequest ولا يتعرف على -sI):
# 1. 命令可用吗?——能打印版本号 = 安装环节全过,卡的是登录
claude --version
# 2. 安装文件在吗?——True = 装上了,是 PATH 问题;False = 没装上,看第 3 条
Test-Path "$env:USERPROFILE\.local\bin\claude.exe"
# 3. 网络通吗?——第一行 HTTP/1.1 200 OK = 下载服务器可达
curl.exe -sI https://downloads.claude.ai/claude-code-releases/latest
# 4. 安装健康吗?——版本号能打印、但 claude 启动就崩或卡住时,跑官方自检
claude doctorكيفية قراءة النتيجة:
| نتيجة الفحص السريع | أين تعثرت المرحلة | إلى أي قسم تذهب |
|---|---|---|
| الأمر رقم 1 يطبع رقم الإصدار | التثبيت اجتاز كله | تسجيل الدخول متعثر ← «مشكلات تسجيل الدخول والمصادقة» |
| الأمر رقم 1 يُظهر command not found، والأمر رقم 2 يُظهر ملفًا / True | PATH | «مشكلات توفر الأمر (PATH)» |
| الأمر رقم 2 يقول إن الملف غير موجود، والأمر رقم 3 يُظهر 200 | التثبيت لم يكتمل | ارجع إلى درس تثبيت التثبيت Claude Code وأعد التثبيت |
| الأمر رقم 3 يُظهر 403 / بلا مخرجات / انتهاء المهلة | التنزيل والشبكة | «مشكلات التنزيل والشبكة» |
| رقم الإصدار يُطبع، لكن التشغيل ينهار أو يتوقف فورًا | سلامة التثبيت | الأمر رقم 4 claude doctor؛ إذا لم ينجح ← «ما زال لا يعمل؟» |
استكشاف المشكلات الشائعة
عناوين H4 أدناه كلها نصوص رسائل الخطأ الأصلية (أو نصوص الأعراض المذكورة في التوثيق الرسمي)، طابقها حرفيًا. كل مجموعة تقابل مرحلة من مراحل الفحص السريع.
مشكلات التنزيل والشبكة
"syntax error near unexpected token '<'"
السبب: ما نزّله أمر التثبيت ليس سكربتًا بل صفحة ويب — نفّذ bash السطر الأول من الصفحة <!DOCTYPE html> كأمر. يحدث هذا غالبًا بسبب مشكلات في الشبكة أو التوجيه الإقليمي أو عطل خدمة مؤقت. المظهر المقابل على Windows: يُظهر CMD الخطأ < was unexpected at this time.، وتُظهر PowerShell سلسلة أخطاء تحليل تتضمن HTML/CSS.
الحل:
انتظر بضع دقائق وأعد تجربة الأمر الأصلي — هذه المشكلة غالبًا مؤقتة.
إذا لم ينجح ذلك فغيّر قناة التثبيت (لاحظ: التثبيت عبر Homebrew / WinGet لن يتحدث تلقائيًا بعد التثبيت، ويجب الترقية يدويًا):
macOS:
bashbrew install --cask claude-codeWindows:
powershellwinget install Anthropic.ClaudeCodeافتح طرفية جديدة للتحقق:
bashclaude --versionينبغي أن ترى: رقم الإصدار، بصيغة
2.1.211 (Claude Code). إذا ظل يقول إن الأمر غير موجود بعد التثبيت، فافتح نافذة طرفية جديدة وأعد المحاولة — الجلسة التي ثبّت فيها ما زالت تحمل PATH القديم.
هل تشير رسالة الخطأ إلى App unavailable in region؟ انتقل مباشرة إلى بند المنطقة أدناه.
"curl: (22) The requested URL returned error: 403"
السبب: خادم التنزيل حجب الطلب. مصدران شائعان: وكيل / تصفية شبكة اعترضت downloads.claude.ai، أو أن منطقتك ليست في قائمة الدعم الرسمية.
الحل:
شغّل أولًا فحص الاتصال في الأمر رقم 3 من الفحص السريع:
bashcurl -sI https://downloads.claude.ai/claude-code-releases/latest403← وكيل/تصفية شبكة، أو مشكلة منطقة (انظر البند التالي)5xx← عطل خدمة مؤقت، انتظر بضع دقائق وأعد المحاولة- بلا مخرجات /
Could not resolve host/ انتهاء مهلة الاتصال ← الشبكة حجبت الاتصال: جدار حماية الشركة، أو قيود الشبكة الإقليمية، أو مشكلة TLS (انظر بند TLS)
إذا ظهر 403 رغم أنك في منطقة مدعومة ← تحقق من الوكيل. في شبكة الشركة اطلب عنوان الوكيل من قسم IT، واضبطه قبل التثبيت ثم شغّل أمر التثبيت:
bashexport HTTP_PROXY=http://proxy.example.com:8080 export HTTPS_PROXY=http://proxy.example.com:8080 curl -fsSL https://claude.ai/install.sh | bashWindows PowerShell:
powershell$env:HTTP_PROXY = 'http://proxy.example.com:8080' $env:HTTPS_PROXY = 'http://proxy.example.com:8080' irm https://claude.ai/install.ps1 | iexلا تتعجل في تغيير القناة: مثبّت النسخة الاحتياطية يتصل بنفس الخوادم، فإذا كانت الشبكة لا تعمل فلن يفيد تغيير القناة، أصلح الشبكة أولًا.
"curl: (35) TLS connect error"
السبب: فشل مصافحة TLS — شهادات CA في النظام قديمة، أو وكيل الشركة يفحص TLS، أو أن Windows PowerShell 5.1 لا يفعّل TLS 1.2 افتراضيًا. أخطاء من العائلة نفسها: Could not create SSL/TLS secure channel وunable to get local issuer certificate وSELF_SIGNED_CERT_IN_CHAIN.
الحل:
حدّث شهادات CA للنظام. Ubuntu / Debian:
bashsudo apt-get update && sudo apt-get install ca-certificatesيستخدم curl في macOS مخزن الثقة في Keychain، ويكفي تحديث macOS نفسه.
في Windows PowerShell 5.1 فعّل TLS 1.2 أولًا، ثم شغّل المثبّت في النافذة نفسها:
powershell[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12 irm https://claude.ai/install.ps1 | iexوكيل الشركة الذي يفحص TLS يسبب هذا النوع من الأخطاء — اطلب من قسم IT شهادة CA الخاصة بالوكيل، وأضف
--cacertإلى أمر التثبيت بنسخة curl:bashcurl --cacert /path/to/corporate-ca.pem -fsSL https://claude.ai/install.sh | bash
"App unavailable in region"
السبب: منطقتك ليست في قائمة الدعم الرسمية من Anthropic — القائمة لا تشمل البر الرئيسي للصين أو هونغ كونغ أو ماكاو. هذا قيد سياسة رسمية، وليس عطلًا في التثبيت.
الحل:
- انتقل إلى صفحة قائمة البلدان المدعومة رسميًا للتحقق من منطقتك.
- تغيير قناة التثبيت لا يتجاوز القيد — فـ npm وHomebrew وWinGet تتصل جميعها بنفس الخدمة، والقيود الإقليمية لا تتغير بتغير طريقة التثبيت.
- إذا أردت البدء في vibe coding الآن، انتقل إلى أدوات لا تتطلب حسابًا خارجيًا: WorkBuddy (من Tencent، تسجيل دخول بمسح رمز WeChat، بدون سطر أوامر) أو OpenCode القادر على الاتصال بالنماذج الصينية. للاختيار راجع كيفية اختيار الأدوات الأربع، ولتثبيت WorkBuddy راجع طرق التثبيت البديلة.
مشكلات أوامر التثبيت على Windows
"'irm' is not recognized as an internal or external command"
السبب: irm هو أمر PowerShell، وقد شغّلت أمر تثبيت نسخة PowerShell داخل CMD — عدم تطابق بين الأمر وshell.
الحل (اختر أحدهما):
الخيار 1: افتح PowerShell — ابحث عن "PowerShell" في قائمة ابدأ وشغّل الأمر الأصلي:
irm https://claude.ai/install.ps1 | iexالخيار 2: ابقَ في CMD واستخدم أمر تثبيت نسخة CMD:
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmdبعد التثبيت افتح طرفية جديدة وشغّل claude --version للتحقق.
بالمناسبة: The token '&&' is not a valid statement separator هو الخطأ العكسي — شغّلت أمر CMD داخل PowerShell، وبالمثل استخدم نسخة irm.
"A parameter cannot be found that matches parameter name 'fsSL'"
السبب: شغّلت curl -fsSL ... | bash الخاص بـ macOS / Linux داخل Windows PowerShell — ففي PowerShell يكون curl اسمًا مستعارًا لـ Invoke-WebRequest ولا يتعرف على معاملات مثل -fsSL.
الحل: على Windows استخدم أمر تثبيت نسخة PowerShell:
irm https://claude.ai/install.ps1 | iexافتح طرفية جديدة وشغّل claude --version للتحقق.
مشكلات توفر الأمر (PATH)
"zsh: command not found: claude"
السبب: التثبيت تم بالفعل، لكن مجلد التثبيت ~/.local/bin ليس في PATH، فلا يجد الـ shell الأمر claude. المثبّت في الواقع نبّهك: Native installation exists but ~/.local/bin is not in your PATH.. الخطأ المقابل على Linux هو bash: claude: command not found.
الحل (macOS / Linux، ضبط PATH مرة واحدة يبقى دائمًا):
تأكد من وجود الملف:
bashls -la ~/.local/bin/claudeيفترض أن ترى: سطرًا بقائمة الملفات.
No such file or directory= لم يُثبَّت أصلًا، ارجع إلى تثبيت Claude Code وأعد التثبيت.تحقق مما إذا كان هذا المجلد موجودًا في PATH:
bashecho $PATH | tr ':' '\n' | grep -Fx "$HOME/.local/bin"وجود مخرجات = المجلد في PATH، والمشكلة في مكان آخر، راجع نقاط الفحص في الخطوة 4؛ لا مخرجات = غير موجود، أضفه في الخطوة التالية.
اكتبه في إعدادات shell ليسري فورًا. الافتراضي على macOS هو zsh:
bashecho 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc source ~/.zshrcعلى Linux الافتراضي bash اكتب في
~/.bashrc؛ وعلى macOS إذا كنت تستخدم bash فاكتب في~/.bash_profile(طرفية macOS تشغّل bash كـ login shell ولا تقرأ~/.bashrc).تحقق:
bashclaude --versionيفترض أن ترى: رقم الإصدار. ما زال لا يُجد؟ ثلاثة أسباب شائعة:
- نافذة طرفية قديمة تحمل PATH القديم — افتح نافذة جديدة؛
- الطرفية المدمجة في المحرر ترث PATH الخاص بالمحرر — أغلق المحرر وأعد تشغيله؛
- الإعدادات كُتبت في ملف shell آخر — استخدم
echo $0لمعرفة الـ shell الحالي واضبط الإعدادات لذلك الـ shell.
"'claude' is not recognized as an internal or external command"
السبب: نفس مشكلة PATH بنسخة Windows — %USERPROFILE%\.local\bin ليس في PATH. شكل الخطأ في PowerShell هو claude : The term 'claude' is not recognized as the name of a cmdlet.
الحل (PowerShell):
تأكد من وجود الملف:
powershellTest-Path "$env:USERPROFILE\.local\bin\claude.exe"يفترض أن ترى:
True.False= لم يُثبَّت، ارجع إلى درس التثبيت وأعد التثبيت.أضِفه إلى User PATH (يُضبط مرة واحدة):
powershell$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User') [Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')أعد تشغيل الطرفية وشغّل
claude --versionللتحقق. إن لم ينجح فافحص ما إذا كانت مخرجات[Environment]::GetEnvironmentVariable('PATH', 'User')تحتوي على.local\bin، وإن لم تكن موجودة فأعد تشغيل الخطوة 2؛ الطرفية المدمجة في المحرر تتطلب إعادة تشغيل المحرر.
لمستخدمي CMD: dir "%USERPROFILE%\.local\bin\claude.exe" للتأكد من الملف، وecho %PATH% | findstr /i "local\bin" لفحص PATH؛ إن لم يكن موجودًا فاذهب إلى إعدادات النظام ← متغيرات البيئة، وأضِف %USERPROFILE%\.local\bin إلى PATH الخاص بالمستخدم، ثم أعد تشغيل الطرفية.
حالة خاصة: على Windows، إذا ظهر هذا الخطأ بعد اكتمال التحديث للتو → فربما نقل التحديث claude.exe إلى النسخة الاحتياطية. أمر الاستعادة الوارد في الوثائق الرسمية (إعادة تسمية أحدث نسخة احتياطية إلى الاسم الأصلي):
Get-ChildItem "$env:USERPROFILE\.local\bin\claude.exe.old.*" | Sort-Object Name | Select-Object -Last 1 | Rename-Item -NewName claude.exeإذا لم توجد نسخة احتياطية claude.exe.old.*، أو ظل الأمر لا يعمل بعد التعديل → أعد التثبيت: irm https://claude.ai/install.ps1 | iex.
مشكلات التثبيت عبر npm
"running scripts is disabled on this system"
السبب: عند تثبيت Claude Code عبر npm على Windows، تعترض سياسة التنفيذ في PowerShell سكربت الإقلاع .ps1 الذي ينشئه npm (ويظهر في الخطأ أيضًا PSSecurityException). عند تشغيل claude يشير الخطأ صراحةً إلى claude.ps1. مثبّت PowerShell الرسمي غير متأثر — فهو ينفّذ النص المُنزَّل مباشرة دون المرور بملف سكربت.
الحل (اختر واحدًا من ثلاثة):
اسمح بالسكربتات المحلية (يسري على المستخدم الحالي فقط)، ثم أعد المحاولة:
powershellSet-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUserغيّر المُشغِّل إلى مُشغِّل
.cmd:npm.cmdوclaude.cmdيقومان بنفس العمل، وسياسة التنفيذ لا تصل إليهما.استخدم مثبّت PowerShell الرسمي — فهو يثبّت ملفًا ثنائيًا وليس
.ps1:powershellirm https://claude.ai/install.ps1 | iex
"Error: claude native binary not installed."
السبب: claude داخل حزمة npm مجرد سكربت مؤقت، وخطوة postinstall هي المسؤولة عن استبداله بالملف الثنائي الحقيقي (يُنشر الملف الثنائي حسب المنصة كتبعية اختيارية، مثل @anthropic-ai/claude-code-darwin-arm64). إذا تخطّى التنزيل أو خطوة postinstall، يبقى السكربت المؤقت. أشيع المسببات: npm 12 يتخطى postinstall افتراضيًا، و--omit=optional يعطّل التبعيات الاختيارية، و--ignore-scripts يعطّل سكربتات التثبيت.
الحل:
شغّل أولًا
npm --version— إذا بدأت المخرجات بـ npm 12 فالمشكلة في npm 12، اتبع أحد الخيارين التاليين.الخيار 1 (موصى به، حل نهائي): انتقل إلى المثبّت الرسمي الأصلي، ثم أزل نسخة npm:
bashcurl -fsSL https://claude.ai/install.sh | bash npm uninstall -g @anthropic-ai/claude-codeبعد التبديل لن تمر التحديثات عبر npm، ولن يعود هذا الخطأ.
الخيار 2: ابقَ على npm — أضِف Claude Code إلى
allow-scriptsثم أعد التثبيت:bashnpm config set "allow-scripts=@anthropic-ai/claude-code" --location=user npm install -g @anthropic-ai/claude-codeانتبه لنقطتين: أولاً قم بترقية npm 12.0.x عبر
npm install -g npm@latestإلى 12.1 أو أحدث؛ وقبل الإعداد شغّلnpm config get allow-scriptsللاطلاع على القائمة الحالية — أمر الإعداد يستبدل القائمة بأكملها، فإذا كانت تحتوي على حزم أخرى اكتبها معًا داخل علامات الاقتباس. إذا ظهرEACCESفي هذه الخطوة لا تضف sudo، بل انتقل مباشرة إلى الحل 1.تعطي رسالة الخطأ أيضًا إجراءً يدويًا للمعالجة (عدّل مسار التثبيت العام/المحلي بنفسك):
bashnode node_modules/@anthropic-ai/claude-code/install.cjs
"EACCES: permission denied"
السبب: الدليل الذي يحتاج التثبيت للكتابة فيه لا يملك صلاحية كتابة. المثبّت الأصلي يكتب على macOS / Linux في ~/.claude/downloads/ و~/.local/bin/ و~/.local/share/claude/ وغيرها؛ أما خطأ EACCES عند التثبيت عبر npm فهو مشكلة صلاحيات في دليل npm العام.
الحل:
تحقق مما إذا كان الدليل قابلًا للكتابة:
bashtest -w ~/.local/bin && echo "writable" || echo "not writable" test -w ~/.claude && echo "writable" || echo "not writable"إن لم يكن قابلًا للكتابة فأنشئ الدليل واستعد ملكيته:
bashsudo mkdir -p ~/.local/bin sudo chown -R $(whoami) ~/.localخطأ EACCES من تثبيت npm → لا تعد المحاولة باستخدام sudo، بل انتقل إلى المثبّت الأصلي الرسمي:
bashcurl -fsSL https://claude.ai/install.sh | bashالسبب: Claude Code عند تحديث نفسه لا يستخدم npm بصلاحيات sudo، والحزم المثبتة عبر sudo ستفشل التحديثات التلقائية لها بالطريقة نفسها.
"npm error code ENOTEMPTY"
السبب: عند إعادة التثبيت أو التحديث فوق تثبيت قائم، يجد npm دليل الحزمة القديمة غير فارغ عند نقله فيفشل rename — وعادةً يكون ذلك دليلًا متبقيًا من تثبيت سابق توقف في المنتصف.
الحل:
انظر إلى الدليل المذكور في سطر
npm error pathضمن رسالة الخطأ — ذلك هو الدليل الذي عجز npm عن نقله.احذفه مع أدلة
.claude-code-*المؤقتة المتبقية بجانبه (macOS / Linux):bashrm -rf "$(npm root -g)/@anthropic-ai/claude-code" rm -rf "$(npm root -g)/@anthropic-ai/.claude-code-"*إذا أبلغ Zsh عن
no matches found= لا توجد بقايا للحذف، وهذا طبيعي. أما Windows PowerShell:powershellRemove-Item -Recurse -Force "$(npm root -g)/@anthropic-ai/claude-code", "$(npm root -g)/@anthropic-ai/.claude-code-*"ملاحظة: عندما لا يقع الدليل المذكور في الخطأ تحت
npm root -g(مثلًا إذا غيّرت إصدار Node عبر nvm)، احذف وفق المسار المكتوب في رسالة الخطأ ولا تخمّن اعتمادًا على الأوامر أعلاه.أعد التثبيت وتحقق:
bashnpm install -g @anthropic-ai/claude-code claude --version
مشاكل تسجيل الدخول والمصادقة
عندما يتعطل تسجيل الدخول لسبب غير معروف، شغّل أولًا «الحلول الثلاثة» التي توصي بها الجهة الرسمية، فهي تحل معظم الحالات:
- أدخل
/logoutفي الجلسة لتسجيل الخروج تمامًا - أغلق Claude Code
- أعد تشغيل
claude، وأكمل عملية المصادقة كاملة
لم يفتح المتصفح تلقائيًا؟ اضغط c لنسخ رابط تسجيل الدخول والصقه يدويًا في المتصفح. هذه الحيلة تفيد أيضًا عندما ينكسر الرابط على سطور متعددة في طرفية SSH ضيقة ولا يمكن النقر عليه.
"OAuth error: Invalid code. Please make sure the full code was copied"
السبب: انتهت صلاحية رمز تسجيل الدخول، أو تم اقتطاعه أثناء النسخ.
الحل:
- اضغط Enter لإعادة المحاولة، وأكمل تسجيل الدخول بأسرع ما يمكن بعد فتح المتصفح.
- إذا لم يفتح المتصفح تلقائيًا: أدخل
cلنسخ الرابط الكامل، وافتح المتصفح يدويًا. - في جلسات SSH / البعيدة: قد يكون المتصفح قد فُتح على الجهاز البعيد — انسخ الرابط المعروض في الطرفية وافتحه في متصفحك المحلي.
"API Error: 403 Request not allowed"
السبب: نجح تسجيل الدخول لكن الطلب قوبل بالرفض. ثلاث احتمالات بأعراض متطابقة، طابق حالتك: اشتراك غير نشط، أو حساب Console لا يحمل الدور الصحيح، أو وكيل (proxy) يعترض طلبات API.
الحل:
- لمستخدمي Claude Pro / Max / Ultra: اذهب إلى claude.ai/settings وتأكد من أن الاشتراك ساري.
- لمستخدمي Anthropic Console: اطلب من المسؤول في platform.claude.com/settings/members إضافة دور "Claude Code" أو "Developer" إلى حسابك.
- قد يعترض وكيل الشركة طلبات API: تحقق من إعدادات الوكيل في تكوين الشبكة.
"Claude Code access has not been granted for this account"
السبب: ضبطت مؤسسة Claude Enterprise دورك على أنه Custom، والدور المخصص المخصص لك لا يتضمن صلاحية Claude Code. لن ينفع أي تعديل تقوم به في Claude Code، بل لا بد أن يتدخل المسؤول.
الحل:
- تواصل مع مالك المؤسسة: ليخصص لمجموعتك دورًا مخصصًا يتضمن Claude Code، أو يغيّر دورك من Custom إلى دور قياسي مثل User (تُدار الأدوار في role settings الخاصة بالمؤسسة).
- بعد التعديل شغّل
claudeلإعادة تسجيل الدخول.
"This organization has been disabled"
السبب: الاشتراك نشط بالفعل ومع ذلك يُبلَّغ عن تعطيل المؤسسة — غالبًا لأن متغير البيئة ANTHROPIC_API_KEY المتبقي في الـ shell يستبدل تسجيل دخول الاشتراك. الحالة الأكثر شيوعًا هي بقاء مفتاح (key) من شركة سابقة أو مشروع قديم في التكوين.
الحل:
أزله في هذه الجلسة قبل التشغيل (macOS / Linux):
bashunset ANTHROPIC_API_KEY claudeWindows PowerShell:
powershellRemove-Item Env:ANTHROPIC_API_KEY claudeللإزالة الدائمة: افحص سطر
export ANTHROPIC_API_KEY=...في~/.zshrcو~/.bashrcو~/.profileواحذفه؛ وفي Windows افحص PowerShell profile ($PROFILE) ومتغيرات بيئة المستخدم.شغّل
/statusفي الجلسة للتأكد من أن طريقة المصادقة السارية حاليًا هي الاشتراك وليست مفتاح API.
ما زال لا يعمل؟
اجمع الأدلة أولًا قبل السؤال. نظام التشغيل + أمر التثبيت الذي شغّلته + النص الكامل لرسالة الخطأ، أنفع من مئة جملة وصف. claude --version وإذا أمكنك إظهار رقم الإصدار أيضًا، فأرفق تقرير الفحص الذاتي الرسمي:
# 证据三件套:版本、官方诊断报告、下载服务器连通性
claude --version # 能出版本号,claude doctor 才跑得起来
claude doctor # 官方自动诊断报告
curl -sI https://downloads.claude.ai/claude-code-releases/latest # 网络连通性(Windows 用 curl.exe)إلى أين تذهب بالسؤال:
| القناة | متى تذهب |
|---|---|
| GitHub Issues | مشاكل التثبيت: ابحث أولًا في المشاكل المعروفة، وإن لم تجد فافتح issue جديدًا مع نظام التشغيل وأمر التثبيت ورسالة الخطأ الكاملة |
claude doctor | رقم الإصدار يُطبع لكن السلوك خاطئ: انظر أولًا إلى ما يقوله تقرير التشخيص |
/feedback | يمكن الدخول إلى الجلسة: أبلغ عن المشكلة مباشرة من داخل الجلسة |
| دعم Anthropic | مشاكل الحساب: حلقة تسجيل الدخول، عدم التعرف على الاشتراك، تعطيل المؤسسة — سجّل الدخول إلى claude.ai وانقر على الصورة الرمزية أسفل اليسار واختر Get help |
نقاط تحقق ✅
- شغّلت أوامر الفحص السريع البالغة 4 وأعرف عند أي مرحلة تعطل الأمر
command not foundأتحقق أولًا من وجود الملف ثم من PATH — إعداد واحد يبقى ساريًا بشكل دائم- نص رسالة الخطأ يطابق أحد بنود H4، وبعد إصلاحه وفق الخطوات أتحقق باستخدام
claude --version - عند تعطل تسجيل الدخول أشغّل أولًا «تسجيل الخروج → إعادة الفتح → إعادة تسجيل الدخول»، ثم أطابق الأعراض الثلاثة: الاشتراك / الدور / مفتاح API
- قبل السؤال أجهّز العناصر الثلاثة: نظام التشغيل + أمر التثبيت + النص الكامل لرسالة الخطأ
خلاصة هذا الدرس
✅ Claude Code عند فشل التثبيت حدد المرحلة أولًا ثم انظر إلى رسالة الخطأ: التنزيل (الشبكة/المنطقة) → التثبيت (الأمر/الصلاحيات/npm) → عمل الأمر (PATH) → تسجيل الدخول (المصادقة/الاشتراك/الدور).
✅ لكل الأخطاء الشائعة حل: command not found يعني إعداد PATH لمرة واحدة؛ 403، وعندما يتحول السكربت إلى صفحة ويب تحقق من الشبكة أولاً ثم بدّل القناة؛ أما إخفاقات npm الثلاثة الكبرى (EACCES، و npm 12 يتخطى postinstall، و ENOTEMPTY) فالأسهل حلها بالانتقال إلى المثبّت الرسمي الأصلي.
✅ مشاكل تسجيل الدخول تُصنَّف حسب العَرَض: الاشتراك يُفحص في settings، والدور يُطلب من المسؤول، وإذا تم استبدال مفتاح API فامسح متغيرات البيئة؛ وابدأ دائمًا بالخطوات الثلاث (تسجيل الخروج → إعادة الفتح → تسجيل الدخول من جديد).
✅ التحقق بعد الإصلاح واحد في كل الحالات: افتح طرفية جديدة ونفّذ claude --version فيظهر رقم الإصدار.
مرجع سريع لأبرز الأخطاء:
| الخطأ | أين يعلق | الخطوة الأولى |
|---|---|---|
zsh: command not found: claude | الأمر متاح | ls -la ~/.local/bin/claude لفحص الملف، ثم إعداد PATH |
syntax error near unexpected token '<' | التنزيل | انتظر بضع دقائق وأعد المحاولة؛ إن لم ينجح فبدّل إلى Homebrew / WinGet |
curl: (22) The requested URL returned error: 403 | التنزيل | curl -sI https://downloads.claude.ai/claude-code-releases/latest لفحص الاتصال |
Error: claude native binary not installed. | npm | بدّل إلى المثبّت الرسمي الأصلي |
OAuth error: Invalid code. Please make sure the full code was copied | تسجيل الدخول | اضغط Enter لإعادة المحاولة؛ c انسخ الرابط وافتح المتصفح يدويًا |
جولة في الدرس القادم
اكتمل التثبيت وتسجيل الدخول، وبذلك تنتهي معالجة أخطاء البداية — أدواتك جاهزة الآن. الخطوة التالية هي الانتقال إلى الاستخدام اليومي: الطريقة الصحيحة لاستخدام كل من الأدوات الأربع.
ستتعلم:
- Claude Code الطريقة الصحيحة لاستخدامه في الطرفية: كيف تبدأ وكيف تتحاور معه
- Codex و OpenCode و WorkBuddy الطريقة الصحيحة لفتح كل منها
- مقارنة أسعار الأدوات الأربع: كم تنفق، وأنت تعلم تمامًا