Skip to content

ماذا تفعل إذا تعذّر التثبيت: استكشاف أخطاء البداية وفحص سريع في 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 (لا مشكلة إن تعثّرت، فهذه الصفحة موجودة لحل التعثر)
  • أن تعرف أي طرفية تفتحها: على 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 (شغّله في الطرفية):

bash
# 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 doctor

Windows (شغّله في PowerShell؛ لاحظ أن curl يجب كتابته curl.exe، فـ curl في PowerShell هو اسم بديل لـ Invoke-WebRequest ولا يتعرف على -sI):

powershell
# 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 يُظهر ملفًا / TruePATH«مشكلات توفر الأمر (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.

الحل:

  1. انتظر بضع دقائق وأعد تجربة الأمر الأصلي — هذه المشكلة غالبًا مؤقتة.

  2. إذا لم ينجح ذلك فغيّر قناة التثبيت (لاحظ: التثبيت عبر Homebrew / WinGet لن يتحدث تلقائيًا بعد التثبيت، ويجب الترقية يدويًا):

    macOS:

    bash
    brew install --cask claude-code

    Windows:

    powershell
    winget install Anthropic.ClaudeCode
  3. افتح طرفية جديدة للتحقق:

    bash
    claude --version

    ينبغي أن ترى: رقم الإصدار، بصيغة 2.1.211 (Claude Code). إذا ظل يقول إن الأمر غير موجود بعد التثبيت، فافتح نافذة طرفية جديدة وأعد المحاولة — الجلسة التي ثبّت فيها ما زالت تحمل PATH القديم.

هل تشير رسالة الخطأ إلى App unavailable in region؟ انتقل مباشرة إلى بند المنطقة أدناه.

"curl: (22) The requested URL returned error: 403" ​

السبب: خادم التنزيل حجب الطلب. مصدران شائعان: وكيل / تصفية شبكة اعترضت downloads.claude.ai، أو أن منطقتك ليست في قائمة الدعم الرسمية.

الحل:

  1. شغّل أولًا فحص الاتصال في الأمر رقم 3 من الفحص السريع:

    bash
    curl -sI https://downloads.claude.ai/claude-code-releases/latest
    • 403 ← وكيل/تصفية شبكة، أو مشكلة منطقة (انظر البند التالي)
    • 5xx ← عطل خدمة مؤقت، انتظر بضع دقائق وأعد المحاولة
    • بلا مخرجات / Could not resolve host / انتهاء مهلة الاتصال ← الشبكة حجبت الاتصال: جدار حماية الشركة، أو قيود الشبكة الإقليمية، أو مشكلة TLS (انظر بند TLS)
  2. إذا ظهر 403 رغم أنك في منطقة مدعومة ← تحقق من الوكيل. في شبكة الشركة اطلب عنوان الوكيل من قسم IT، واضبطه قبل التثبيت ثم شغّل أمر التثبيت:

    bash
    export HTTP_PROXY=http://proxy.example.com:8080
    export HTTPS_PROXY=http://proxy.example.com:8080
    curl -fsSL https://claude.ai/install.sh | bash

    Windows 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
  3. لا تتعجل في تغيير القناة: مثبّت النسخة الاحتياطية يتصل بنفس الخوادم، فإذا كانت الشبكة لا تعمل فلن يفيد تغيير القناة، أصلح الشبكة أولًا.

"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.

الحل:

  1. حدّث شهادات CA للنظام. Ubuntu / Debian:

    bash
    sudo apt-get update && sudo apt-get install ca-certificates

    يستخدم curl في macOS مخزن الثقة في Keychain، ويكفي تحديث macOS نفسه.

  2. في Windows PowerShell 5.1 فعّل TLS 1.2 أولًا، ثم شغّل المثبّت في النافذة نفسها:

    powershell
    [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
    irm https://claude.ai/install.ps1 | iex
  3. وكيل الشركة الذي يفحص TLS يسبب هذا النوع من الأخطاء — اطلب من قسم IT شهادة CA الخاصة بالوكيل، وأضف --cacert إلى أمر التثبيت بنسخة curl:

    bash
    curl --cacert /path/to/corporate-ca.pem -fsSL https://claude.ai/install.sh | bash

"App unavailable in region" ​

السبب: منطقتك ليست في قائمة الدعم الرسمية من Anthropic — القائمة لا تشمل البر الرئيسي للصين أو هونغ كونغ أو ماكاو. هذا قيد سياسة رسمية، وليس عطلًا في التثبيت.

الحل:

  1. انتقل إلى صفحة قائمة البلدان المدعومة رسميًا للتحقق من منطقتك.
  2. تغيير قناة التثبيت لا يتجاوز القيد — فـ npm وHomebrew وWinGet تتصل جميعها بنفس الخدمة، والقيود الإقليمية لا تتغير بتغير طريقة التثبيت.
  3. إذا أردت البدء في 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" في قائمة ابدأ وشغّل الأمر الأصلي:

powershell
irm https://claude.ai/install.ps1 | iex

الخيار 2: ابقَ في CMD واستخدم أمر تثبيت نسخة CMD:

batch
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:

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 مرة واحدة يبقى دائمًا):

  1. تأكد من وجود الملف:

    bash
    ls -la ~/.local/bin/claude

    يفترض أن ترى: سطرًا بقائمة الملفات. No such file or directory = لم يُثبَّت أصلًا، ارجع إلى تثبيت Claude Code وأعد التثبيت.

  2. تحقق مما إذا كان هذا المجلد موجودًا في PATH:

    bash
    echo $PATH | tr ':' '\n' | grep -Fx "$HOME/.local/bin"

    وجود مخرجات = المجلد في PATH، والمشكلة في مكان آخر، راجع نقاط الفحص في الخطوة 4؛ لا مخرجات = غير موجود، أضفه في الخطوة التالية.

  3. اكتبه في إعدادات shell ليسري فورًا. الافتراضي على macOS هو zsh:

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

    على Linux الافتراضي bash اكتب في ~/.bashrc؛ وعلى macOS إذا كنت تستخدم bash فاكتب في ~/.bash_profile (طرفية macOS تشغّل bash كـ login shell ولا تقرأ ~/.bashrc).

  4. تحقق:

    bash
    claude --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):

  1. تأكد من وجود الملف:

    powershell
    Test-Path "$env:USERPROFILE\.local\bin\claude.exe"

    يفترض أن ترى: True. False = لم يُثبَّت، ارجع إلى درس التثبيت وأعد التثبيت.

  2. أضِفه إلى User PATH (يُضبط مرة واحدة):

    powershell
    $currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
    [Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')
  3. أعد تشغيل الطرفية وشغّل 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 إلى النسخة الاحتياطية. أمر الاستعادة الوارد في الوثائق الرسمية (إعادة تسمية أحدث نسخة احتياطية إلى الاسم الأصلي):

powershell
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 الرسمي غير متأثر — فهو ينفّذ النص المُنزَّل مباشرة دون المرور بملف سكربت.

الحل (اختر واحدًا من ثلاثة):

  1. اسمح بالسكربتات المحلية (يسري على المستخدم الحالي فقط)، ثم أعد المحاولة:

    powershell
    Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
  2. غيّر المُشغِّل إلى مُشغِّل .cmd: npm.cmd وclaude.cmd يقومان بنفس العمل، وسياسة التنفيذ لا تصل إليهما.

  3. استخدم مثبّت PowerShell الرسمي — فهو يثبّت ملفًا ثنائيًا وليس .ps1:

    powershell
    irm 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 يعطّل سكربتات التثبيت.

الحل:

  1. شغّل أولًا npm --version — إذا بدأت المخرجات بـ npm 12 فالمشكلة في npm 12، اتبع أحد الخيارين التاليين.

  2. الخيار 1 (موصى به، حل نهائي): انتقل إلى المثبّت الرسمي الأصلي، ثم أزل نسخة npm:

    bash
    curl -fsSL https://claude.ai/install.sh | bash
    npm uninstall -g @anthropic-ai/claude-code

    بعد التبديل لن تمر التحديثات عبر npm، ولن يعود هذا الخطأ.

  3. الخيار 2: ابقَ على npm — أضِف Claude Code إلى allow-scripts ثم أعد التثبيت:

    bash
    npm 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.

  4. تعطي رسالة الخطأ أيضًا إجراءً يدويًا للمعالجة (عدّل مسار التثبيت العام/المحلي بنفسك):

    bash
    node node_modules/@anthropic-ai/claude-code/install.cjs

"EACCES: permission denied" ​

السبب: الدليل الذي يحتاج التثبيت للكتابة فيه لا يملك صلاحية كتابة. المثبّت الأصلي يكتب على macOS / Linux في ~/.claude/downloads/ و~/.local/bin/ و~/.local/share/claude/ وغيرها؛ أما خطأ EACCES عند التثبيت عبر npm فهو مشكلة صلاحيات في دليل npm العام.

الحل:

  1. تحقق مما إذا كان الدليل قابلًا للكتابة:

    bash
    test -w ~/.local/bin && echo "writable" || echo "not writable"
    test -w ~/.claude && echo "writable" || echo "not writable"
  2. إن لم يكن قابلًا للكتابة فأنشئ الدليل واستعد ملكيته:

    bash
    sudo mkdir -p ~/.local/bin
    sudo chown -R $(whoami) ~/.local
  3. خطأ EACCES من تثبيت npm → لا تعد المحاولة باستخدام sudo، بل انتقل إلى المثبّت الأصلي الرسمي:

    bash
    curl -fsSL https://claude.ai/install.sh | bash

    السبب: Claude Code عند تحديث نفسه لا يستخدم npm بصلاحيات sudo، والحزم المثبتة عبر sudo ستفشل التحديثات التلقائية لها بالطريقة نفسها.

"npm error code ENOTEMPTY" ​

السبب: عند إعادة التثبيت أو التحديث فوق تثبيت قائم، يجد npm دليل الحزمة القديمة غير فارغ عند نقله فيفشل rename — وعادةً يكون ذلك دليلًا متبقيًا من تثبيت سابق توقف في المنتصف.

الحل:

  1. انظر إلى الدليل المذكور في سطر npm error path ضمن رسالة الخطأ — ذلك هو الدليل الذي عجز npm عن نقله.

  2. احذفه مع أدلة .claude-code-* المؤقتة المتبقية بجانبه (macOS / Linux):

    bash
    rm -rf "$(npm root -g)/@anthropic-ai/claude-code"
    rm -rf "$(npm root -g)/@anthropic-ai/.claude-code-"*

    إذا أبلغ Zsh عن no matches found = لا توجد بقايا للحذف، وهذا طبيعي. أما Windows PowerShell:

    powershell
    Remove-Item -Recurse -Force "$(npm root -g)/@anthropic-ai/claude-code", "$(npm root -g)/@anthropic-ai/.claude-code-*"

    ملاحظة: عندما لا يقع الدليل المذكور في الخطأ تحت npm root -g (مثلًا إذا غيّرت إصدار Node عبر nvm)، احذف وفق المسار المكتوب في رسالة الخطأ ولا تخمّن اعتمادًا على الأوامر أعلاه.

  3. أعد التثبيت وتحقق:

    bash
    npm install -g @anthropic-ai/claude-code
    claude --version

مشاكل تسجيل الدخول والمصادقة ​

عندما يتعطل تسجيل الدخول لسبب غير معروف، شغّل أولًا «الحلول الثلاثة» التي توصي بها الجهة الرسمية، فهي تحل معظم الحالات:

  1. أدخل /logout في الجلسة لتسجيل الخروج تمامًا
  2. أغلق Claude Code
  3. أعد تشغيل claude، وأكمل عملية المصادقة كاملة

لم يفتح المتصفح تلقائيًا؟ اضغط c لنسخ رابط تسجيل الدخول والصقه يدويًا في المتصفح. هذه الحيلة تفيد أيضًا عندما ينكسر الرابط على سطور متعددة في طرفية SSH ضيقة ولا يمكن النقر عليه.

"OAuth error: Invalid code. Please make sure the full code was copied" ​

السبب: انتهت صلاحية رمز تسجيل الدخول، أو تم اقتطاعه أثناء النسخ.

الحل:

  1. اضغط Enter لإعادة المحاولة، وأكمل تسجيل الدخول بأسرع ما يمكن بعد فتح المتصفح.
  2. إذا لم يفتح المتصفح تلقائيًا: أدخل c لنسخ الرابط الكامل، وافتح المتصفح يدويًا.
  3. في جلسات SSH / البعيدة: قد يكون المتصفح قد فُتح على الجهاز البعيد — انسخ الرابط المعروض في الطرفية وافتحه في متصفحك المحلي.

"API Error: 403 Request not allowed" ​

السبب: نجح تسجيل الدخول لكن الطلب قوبل بالرفض. ثلاث احتمالات بأعراض متطابقة، طابق حالتك: اشتراك غير نشط، أو حساب Console لا يحمل الدور الصحيح، أو وكيل (proxy) يعترض طلبات API.

الحل:

  1. لمستخدمي Claude Pro / Max / Ultra: اذهب إلى claude.ai/settings وتأكد من أن الاشتراك ساري.
  2. لمستخدمي Anthropic Console: اطلب من المسؤول في platform.claude.com/settings/members إضافة دور "Claude Code" أو "Developer" إلى حسابك.
  3. قد يعترض وكيل الشركة طلبات API: تحقق من إعدادات الوكيل في تكوين الشبكة.

"Claude Code access has not been granted for this account" ​

السبب: ضبطت مؤسسة Claude Enterprise دورك على أنه Custom، والدور المخصص المخصص لك لا يتضمن صلاحية Claude Code. لن ينفع أي تعديل تقوم به في Claude Code، بل لا بد أن يتدخل المسؤول.

الحل:

  1. تواصل مع مالك المؤسسة: ليخصص لمجموعتك دورًا مخصصًا يتضمن Claude Code، أو يغيّر دورك من Custom إلى دور قياسي مثل User (تُدار الأدوار في role settings الخاصة بالمؤسسة).
  2. بعد التعديل شغّل claude لإعادة تسجيل الدخول.

"This organization has been disabled" ​

السبب: الاشتراك نشط بالفعل ومع ذلك يُبلَّغ عن تعطيل المؤسسة — غالبًا لأن متغير البيئة ANTHROPIC_API_KEY المتبقي في الـ shell يستبدل تسجيل دخول الاشتراك. الحالة الأكثر شيوعًا هي بقاء مفتاح (key) من شركة سابقة أو مشروع قديم في التكوين.

الحل:

  1. أزله في هذه الجلسة قبل التشغيل (macOS / Linux):

    bash
    unset ANTHROPIC_API_KEY
    claude

    Windows PowerShell:

    powershell
    Remove-Item Env:ANTHROPIC_API_KEY
    claude
  2. للإزالة الدائمة: افحص سطر export ANTHROPIC_API_KEY=... في ~/.zshrc و~/.bashrc و~/.profile واحذفه؛ وفي Windows افحص PowerShell profile ($PROFILE) ومتغيرات بيئة المستخدم.

  3. شغّل /status في الجلسة للتأكد من أن طريقة المصادقة السارية حاليًا هي الاشتراك وليست مفتاح API.

ما زال لا يعمل؟ ​

اجمع الأدلة أولًا قبل السؤال. نظام التشغيل + أمر التثبيت الذي شغّلته + النص الكامل لرسالة الخطأ، أنفع من مئة جملة وصف. claude --version وإذا أمكنك إظهار رقم الإصدار أيضًا، فأرفق تقرير الفحص الذاتي الرسمي:

bash
# 证据三件套:版本、官方诊断报告、下载服务器连通性
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 الطريقة الصحيحة لفتح كل منها
  • مقارنة أسعار الأدوات الأربع: كم تنفق، وأنت تعلم تمامًا

دروس ذات صلة ​

gaodong.aiAboutPrivacyContact

Independent tutorials, not affiliated with any product mentioned. Product names and trademarks belong to their owners. Check official pages for prices and policies.