أشهر أخطاء تثبيت وتشغيل Claude Code وطريقة إصلاحها - تعلم كلود AIأخطاء Claude Code: حل مشاكل التثبيت وتسجيل الدخول

نطاق الدليل: يغطي هذا المقال أخطاء تثبيت Claude Code CLI، ومشكلات تسجيل الدخول والمصادقة، وأخطاء التشغيل الأساسية، ومشكلات تشغيله داخل VS Code وبيئات Windows وWSL. لا يتناول أخطاء الكود الموجود داخل مشروعك.

تنويه الاستقلالية: هذا موقع تعليمي عربي مستقل، ولا يتبع Anthropic ولا يمثل Claude رسميًا. نفّذ أوامر الحذف وتعديل متغيرات البيئة بحذر، واحتفظ بنسخة من إعداداتك قبل إجراء تغييرات كبيرة.

قد يظهر Claude Code Error أثناء تنزيل الأداة، أو بعد نجاح التثبيت، أو عند تسجيل الدخول، أو داخل جلسة العمل نفسها. لذلك لا يوجد حل واحد لجميع الحالات؛ فخطأ command not found يختلف تمامًا عن خطأ OAuth، وخطأ 429 لا يُحل بإعادة التثبيت، بينما رسالة process exited with code 1 داخل VS Code ليست السبب الحقيقي غالبًا، بل غلاف لخطأ آخر.

أفضل طريقة للإصلاح هي تحديد الطبقة التي فشلت أولًا: التثبيت، المسار PATH، المصادقة، الشبكة، خوادم الخدمة، إعدادات المشروع، أو البرنامج الذي يحاول تشغيل Claude Code.

الإجابة السريعة: ما أول حل يجب تجربته؟

رسالة الخطأ أو العرض	السبب الأكثر احتمالًا	أول إجراء
`claude: command not found`	مجلد التثبيت غير موجود في PATH أو لم تُفتح نافذة Terminal جديدة	أعد فتح Terminal ثم شغّل `claude --version`
`irm is not recognized`	تشغيل أمر PowerShell داخل CMD	افتح PowerShell أو استخدم أمر CMD الصحيح
`syntax error near unexpected token '<'`	رابط التثبيت أعاد صفحة HTML أو خطأ 403	اختبر الشبكة والمنطقة والـProxy
`EACCES` أو Permission denied	صلاحيات npm أو مجلد التثبيت غير صحيحة	استخدم Native Installer ولا تستخدم `sudo npm`
`OAuth error: Invalid code`	الكود انتهت صلاحيته أو نُسخ ناقصًا	أعد تسجيل الدخول وانسخ الرابط أو الكود كاملًا
`403 Forbidden` بعد الدخول	اشتراك غير نشط أو دور غير صحيح أو Proxy	تحقق من الحساب والدور وطريقة المصادقة
`This organization has been disabled`	مفتاح API قديم يتغلب على اشتراكك	أزل `ANTHROPIC_API_KEY` وتحقق عبر `/status`
`Not logged in`	انتهاء رمز OAuth أو عدم حفظه	شغّل `/login`
`429`	حد استخدام أو معدل طلبات أو رصيد	افتح `/status` وانتظر إعادة الضبط أو خفّض الطلبات
`500` أو `529`	مشكلة مؤقتة في الخدمة أو مزود النموذج	تحقق من صفحة الحالة ثم أعد المحاولة
`process exited with code 1`	VS Code أو برنامج آخر أخفى الخطأ الأصلي	افتح سجل Output وشغّل `claude` يدويًا في Terminal
Claude Code يتوقف أو يستهلك الذاكرة	سياق كبير أو Plugin أو MCP أو ملفات ضخمة	جرّب `/compact` أو `claude --safe-mode`

تجمع وثائق Claude Code الرسمية أخطاء التثبيت، والمصادقة، والتشغيل في صفحات منفصلة. ويُفضل مطابقة نص الرسالة الفعلي مع الحل بدل إعادة تثبيت الأداة عشوائيًا.

Common Claude Code errors including command not found, OAuth login, 403, 429, 529, and ripgrep issues

قبل الإصلاح: هل المشكلة من جهازك أم من خدمة Claude؟

قبل تعديل PATH أو حذف ملفات أو إعادة تثبيت Claude Code، افتح صفحة حالة Claude الرسمية. إذا كانت هناك مشكلة عامة تؤثر في Claude Code أو Claude API أو تسجيل الدخول، فلن يؤدي تغيير إعدادات جهازك إلى حلها. سجل الحالة الرسمي يعرض الحوادث الحالية والسابقة التي تؤثر في Claude Code وبقية خدمات Claude.

بعد استبعاد العطل العام، نفّذ الفحوصات التالية من Terminal:

claude --version
claude doctor

claude --version يؤكد أن النظام يستطيع العثور على الملف التنفيذي وتشغيله.
claude doctor يعرض فحوصات التثبيت والإعدادات دون بدء جلسة تفاعلية.
داخل Claude Code، استخدم /doctor لإجراء فحص أوسع يمكنه اقتراح إصلاحات بعد موافقتك.
استخدم /status لمعرفة الحساب وطريقة المصادقة والإعدادات النشطة.
استخدم /mcp إذا كانت المشكلة مرتبطة بخادم MCP أو أدواته.

توضح الوثائق الرسمية أن claude doctor يفحص صحة التثبيت وأخطاء ملفات الإعدادات والتحذيرات، بينما يعرض /status مصادر الإعدادات وطريقة تسجيل الدخول الفعلية.

ما الطريقة الصحيحة حاليًا لتثبيت Claude Code؟

الطريقة الموصى بها حاليًا هي Native Install. هذا المسار يثبت ملفًا تنفيذيًا أصليًا ولا يحتاج إلى تثبيت Node.js. كما أن التثبيت الأصلي يدعم التحديثات التلقائية في الخلفية.

macOS وLinux وWSL

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

Windows PowerShell

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

Windows CMD

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Homebrew على macOS

brew install --cask claude-code

WinGet على Windows

winget install Anthropic.ClaudeCode

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

claude --version
claude doctor
claude

يدعم Claude Code حاليًا macOS 13 أو أحدث، وWindows 10 إصدار 1809 أو أحدث، وUbuntu 20.04 أو أحدث، وDebian 10 أو أحدث، وAlpine 3.19 أو أحدث، مع معالج x64 أو ARM64 وذاكرة 4 GB على الأقل واتصال بالإنترنت. كما يحتاج الوصول إلى حساب Pro أو Max أو Team أو Enterprise أو Console؛ الخطة المجانية لا تتضمن Claude Code.

Claude Code installation troubleshooting guide for Native Install, PATH, command not found, and download errors

حل خطأ claude: command not found

هذه الرسالة تعني عادة أن التثبيت اكتمل، لكن Terminal لا يعرف مكان الملف التنفيذي. يضع التثبيت الأصلي الملف في ~/.local/bin/claude على macOS وLinux، وفي %USERPROFILE%\.local\bin\claude.exe على Windows.

الحل السريع

أغلق جميع نوافذ Terminal.
افتح نافذة جديدة.
نفّذ claude --version.
إذا استمرت المشكلة، افحص PATH كما هو موضح أدناه.

إضافة المسار على macOS باستخدام Zsh

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

إضافة المسار على Linux باستخدام Bash

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
claude --version

إضافة المسار على Windows PowerShell

$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

أغلق PowerShell وافتحه مجددًا بعد تنفيذ الأمر، ثم شغّل:

claude --version

تحذر الوثائق من كتابة المسار بالشكل "~/.local/bin" داخل علامات اقتباس في بعض إعدادات shell؛ الأفضل استخدام $HOME/.local/bin حتى يتم توسيع مسار المنزل بطريقة صحيحة.

ثبّتُّ إضافة Claude Code في VS Code لكن أمر claude غير موجود

تثبيت إضافة VS Code لا يعني أنك ثبّت Claude Code CLI بصورة مستقلة. الإضافة تحتوي على نسخة خاصة تستخدمها داخل لوحة المحادثة، لكنها لا تضيف أمر claude إلى PATH. لاستخدام Claude Code من Terminal، نفّذ التثبيت الأصلي المستقل.

للتأكد من وجود CLI مستقل:

claude --version

إذا كانت الإضافة تعمل بينما يفشل الأمر السابق، فالمشكلة ليست في الإضافة؛ أنت تحتاج إلى تثبيت CLI أو إضافته إلى PATH.

أخطاء أوامر التثبيت على Windows

PowerShell وCMD وGit Bash ليست الواجهة نفسها، ولا تقبل دائمًا الأوامر نفسها. كثير من مشكلات Claude Code Installation Problem على Windows تنتج عن نسخ أمر صحيح داخل shell غير مناسب.

الرسالة	ما تعنيه	الحل
`irm is not recognized`	أنت داخل CMD وليس PowerShell	افتح PowerShell أو استخدم أمر CMD
`The token '&&' is not valid`	نفّذت أمر CMD داخل PowerShell	استخدم أمر PowerShell
`A parameter cannot be found that matches 'fsSL'`	نفّذت أمر macOS/Linux داخل PowerShell	استخدم `irm ... \| iex`
`bash is not recognized`	نفّذت أمر Linux داخل Windows	استخدم PowerShell أو CMD
ظهر نص Script فقط دون تثبيت	شغّلت جزءًا من أمر CMD ولم تحفظ الملف	نفّذ الأمر الكامل المخصص لـCMD

يمكنك التمييز بين الواجهتين من بداية السطر: يظهر PS C:\ داخل PowerShell، بينما يظهر C:\ فقط داخل CMD.

حل خطأ HTML أو 403 أثناء التثبيت

إذا ظهر خطأ مثل syntax error near unexpected token '<' أو بدأت الرسالة بعلامات HTML وCSS، فهذا يعني أن رابط التثبيت لم يُرجع Script، بل أعاد صفحة ويب أو صفحة حظر أو خطأ. وقد يظهر بدلًا من ذلك curl: (22) ... 403.

اختبر الوصول إلى خادم التنزيل:

macOS وLinux

curl -sI https://downloads.claude.ai/claude-code-releases/latest

Windows PowerShell

curl.exe -sI https://downloads.claude.ai/claude-code-releases/latest

200: الخادم قابل للوصول؛ أعد محاولة التثبيت.
403: قد تكون هناك قيود منطقة أو Proxy أو Firewall.
5xx: مشكلة مؤقتة من جهة الخدمة؛ انتظر وأعد المحاولة.
Could not resolve host أو Timeout: الشبكة أو DNS يمنع الاتصال.

إذا كان التثبيت المباشر محظورًا، جرّب Homebrew على macOS أو WinGet على Windows بدل إعادة المحاولة بنفس الأمر.

حل أخطاء Proxy وTLS وSELF_SIGNED_CERT_IN_CHAIN

تظهر أخطاء مثل TLS connect error وunable to get local issuer certificate وSELF_SIGNED_CERT_IN_CHAIN عادة عندما تفحص شبكة الشركة اتصال HTTPS باستخدام شهادة داخلية، أو عندما تكون شهادات النظام قديمة. لا يُنصح بتعطيل التحقق من SSL أو استخدام خيارات تتجاهل الشهادة؛ عالج سلسلة الثقة نفسها.

ضبط Proxy على macOS أو Linux

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

ضبط Proxy في Windows PowerShell

$env:HTTP_PROXY = 'http://proxy.example.com:8080'
$env:HTTPS_PROXY = 'http://proxy.example.com:8080'
irm https://claude.ai/install.ps1 | iex

إضافة شهادة الشركة لـClaude Code بعد التثبيت

export NODE_EXTRA_CA_CERTS=/path/to/company-ca.pem

على Windows، يعتمد PowerShell Installer على مخزن شهادات Windows، لذلك قد يحتاج فريق تقنية المعلومات إلى إضافة شهادة الشركة إلى مخزن النظام. أما Claude Code نفسه فيمكن ضبطه لاستخدام حزمة CA المناسبة عند إرسال الطلبات.

حل EACCES وPermission denied أثناء التثبيت

غالبًا يظهر خطأ EACCES عند استخدام npm بتثبيت عالمي داخل مجلد لا يملكه المستخدم، أو بعد استخدام sudo npm install -g. لا تستخدم sudo لتثبيت حزمة Claude Code عبر npm، لأن ذلك قد يسبب مشكلات صلاحيات ومخاطر أمنية.

الحل الأبسط هو إزالة تثبيت npm والانتقال إلى Native Installer:

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

إذا كان التثبيت الأصلي نفسه يواجه مشكلة صلاحيات على macOS أو Linux، تحقق من إمكانية الكتابة داخل المجلدات:

test -w ~/.local/bin && echo "writable" || echo "not writable"
test -w ~/.claude && echo "writable" || echo "not writable"

إذا كان المالك خاطئًا بسبب تثبيت قديم، أصلح ملكية مجلد التثبيت الخاص بالمستخدم بدل تشغيل Claude Code كله بصلاحيات Administrator أو Root.

أخطاء npm وNode.js عند تثبيت Claude Code

يمكن تثبيت Claude Code باستخدام npm، لكنه لم يعد المسار الأبسط لمعظم المستخدمين. التوثيق الرسمي الحالي يوصي بالتثبيت الأصلي، بينما تتطلب حزمة npm Node.js 22 أو أحدث بدءًا من الإصدار 2.1.198. الملف التنفيذي الناتج نفسه Native Binary ولا يستدعي Node عند التشغيل.

فحص إصدار Node.js

node -v
npm -v

إذا كنت لا تحتاج إلى npm لسبب محدد، استخدم Native Installer بدل تغيير بيئة Node الخاصة بمشروعاتك.

خطأ claude native binary not installed

يعني هذا الخطأ أن npm ثبّت الحزمة الأساسية، لكنه لم ينزّل Optional Dependency الخاصة بنظامك أو لم يشغّل Postinstall Script. يحدث ذلك عند استخدام إعدادات مثل --ignore-scripts أو --omit=optional.

npm uninstall -g @anthropic-ai/claude-code
npm install -g @anthropic-ai/claude-code@latest

تأكد من أن إعدادات npm أو pnpm لا تمنع Scripts أو Optional Dependencies. أو انتقل إلى Native Installer لتجنب هذه الطبقة بالكامل.

خطأ ENOTEMPTY أثناء التحديث أو إعادة التثبيت

يحدث ENOTEMPTY عندما يترك تثبيت npm سابق مجلدًا مؤقتًا أو يعجز عن نقل مجلد الحزمة القديمة. ابدأ بإزالة الحزمة بالطريقة العادية، ثم أعد تثبيتها. إذا استمر الخطأ، استخدم المسار الذي يظهر في سطر npm error path لتحديد المجلد المتبقي بدل حذف مجلدات عشوائية. توثق Anthropic خطوات إزالة مجلد الحزمة والمجلدات المؤقتة ثم إعادة التثبيت.

running scripts is disabled on this system

هذه مشكلة خاصة بملفات .ps1 التي ينشئها npm على Windows، وليست مشكلة في Native Installer. الخيارات الآمنة هي استخدام ملف claude.cmd، أو السماح بالـScripts المحلية للمستخدم، أو الانتقال إلى PowerShell Native Installer.

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

الخيار الأسهل: إذا لم تكن تحتاج إلى npm، استخدم الأمر الرسمي الخاص بـPowerShell؛ فهو يثبت ملفًا تنفيذيًا بدل Launcher من نوع PS1.

حل تعارض أكثر من تثبيت أو ظهور إصدار قديم

قد يكون لديك Claude Code مثبتًا في أكثر من مكان: Native Installer وnpm وHomebrew أو WinGet، بالإضافة إلى نسخة خاصة داخل إضافة VS Code. عندها قد يشغّل Terminal نسخة قديمة بينما تستخدم الإضافة نسخة أخرى.

macOS وLinux

which -a claude
claude --version
npm -g ls @anthropic-ai/claude-code 2>/dev/null

Windows PowerShell

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

إذا ظهر أكثر من مسار، احتفظ بطريقة واحدة فقط. التثبيت الأصلي في .local/bin هو الخيار الموصى به لمعظم المستخدمين.

إزالة npm: npm uninstall -g @anthropic-ai/claude-code
إزالة Homebrew: brew uninstall --cask claude-code
إزالة WinGet: winget uninstall Anthropic.ClaudeCode

بعد إزالة النسخ الزائدة، افتح Terminal جديدًا، ثم نفّذ claude --version وclaude doctor.

أخطاء Claude Code على Windows وWSL

يمكن تشغيل Claude Code بصورة أصلية على Windows أو داخل WSL. لا يحتاج Windows Native إلى صلاحيات Administrator، كما أن Git for Windows اختياري: عند وجوده يستخدم Claude Code Git Bash لأداة Bash، وعند عدم وجوده يمكنه استخدام PowerShell. أما WSL2 فيناسب أدوات Linux ويدعم Sandboxing، بينما لا يدعمه Native Windows أو WSL1.

Claude Code لا يجد Git Bash

إذا كان Git for Windows مثبتًا لكن Claude Code لا يعثر عليه، يمكنك تحديد المسار في settings.json:

{
  "env": {
    "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe"
  }
}

Exec format error داخل WSL

قد يظهر هذا الخطأ إذا كنت تستخدم WSL1 مع ملف تنفيذي غير متوافق، أو إذا نُزّلت معمارية لا تطابق النظام. استخدم WSL2 أو شغّل Claude Code بصورة أصلية على Windows، ثم أعد التثبيت من داخل البيئة التي ستشغله فيها.

WSL يستخدم Node الخاص بـWindows

هذه المشكلة تخص غالبًا تثبيت npm القديم. افحص المسارات:

which node
which npm

إذا بدأ المسار بـ/mnt/c/، فأنت تستخدم برنامج Windows من داخل WSL. ثبّت Node داخل WSL نفسه أو انتقل إلى Native Installer الذي لا يعتمد على Node.

البحث بطيء داخل مشروع موجود على C:

قد تؤدي قراءة ملفات Windows من WSL عبر /mnt/c/ إلى أداء بحث أبطأ ونتائج أقل من المتوقع. انقل المشروع إلى نظام ملفات Linux داخل /home/، أو شغّل Claude Code بصورة أصلية على Windows.

طريقة إعادة ضبط Claude Code Login

عندما لا يكون سبب Claude Code Login Error واضحًا، توصي الوثائق الرسمية بإجراء مصادقة نظيفة قبل حذف أي ملفات.

من داخل Claude Code شغّل /logout.
أغلق Claude Code بالكامل.
نفّذ claude update.
أغلق Terminal وافتحه مجددًا.
شغّل claude.
اختر الحساب وطريقة الدخول الصحيحة.

إذا لم يفتح المتصفح تلقائيًا، اضغط c داخل شاشة الدخول لنسخ رابط OAuth، ثم افتحه يدويًا في المتصفح.

Claude Code login troubleshooting for OAuth errors, 403 Forbidden, and ANTHROPIC_API_KEY conflicts

حل OAuth error: Invalid code

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

اضغط Enter لإعادة المحاولة.
اضغط c لنسخ رابط OAuth كاملًا.
افتح الرابط في المتصفح الذي تستخدمه للحساب الصحيح.
أكمل الدخول بسرعة.
انسخ الكود كاملًا دون مسافات أو علامات إضافية.

إذا كنت تعمل عبر SSH أو WSL أو Container، افتح الرابط على جهازك المحلي، ثم الصق الكود في Terminal البعيد. ويمكنك أيضًا استخدام:

claude auth login

توضح الوثائق أن Redirect المحلي قد لا يصل إلى Claude Code في WSL2 أو SSH أو الحاويات، ولذلك توفر عملية الدخول اليدوي بالكود.

المتصفح يقول إن الدخول نجح لكن Terminal ما زال ينتظر

تحدث هذه الحالة عادة عندما لا يصل Localhost Callback من المتصفح إلى العملية التي تعمل داخل Terminal، خصوصًا في Remote SSH وDev Containers والشبكات ذات الجدار الناري الصارم. استخدم المسار اليدوي: انسخ الرابط، أكمل الدخول في أي متصفح، ثم الصق الكود الناتج في Terminal.

إذا لم يفتح المتصفح من WSL، يمكنك تحديد متصفح Windows:

export BROWSER="/mnt/c/Program Files/Google/Chrome/Application/chrome.exe"
claude

حل خطأ 403 Forbidden بعد تسجيل الدخول

خطأ 403 بعد الدخول يختلف عن خطأ 403 أثناء تنزيل برنامج التثبيت. هنا نجحت المصادقة، لكن الحساب أو الشبكة أو المؤسسة لا تسمح بتنفيذ الطلب.

Pro أو Max: تحقق من أن الاشتراك نشط وأنك دخلت بالبريد نفسه.
Console: تأكد من أن دورك داخل المؤسسة يسمح باستخدام Claude Code أو Developer.
Team أو Enterprise: تحقق من اختيار حساب العمل الصحيح وطريقة الدخول الخاصة بالمؤسسة.
شبكة شركة: افحص Proxy وFirewall وسياسات السماح بالنطاقات.
منطقة غير مدعومة: تحقق من توفر Claude Code في بلد الحساب.

بعد المراجعة، شغّل /status لمعرفة الحساب ووسيلة المصادقة التي يستخدمها Claude Code بالفعل.

Claude Max or Pro is required رغم وجود Team أو Enterprise

إذا كان لديك وصول من خلال Team أو Enterprise وظهرت رسالة تطلب Pro أو Max، فقد تكون اخترت طريقة تسجيل دخول غير صحيحة أو حسابًا شخصيًا بدل حساب العمل. توصي Anthropic بإعادة تشغيل /login واختيار الحساب المرتبط ببريد العمل الأساسي.

شغّل /logout.
أغلق الجلسة.
شغّل claude update.
افتح Terminal جديدًا.
شغّل claude.
اختر حساب المؤسسة الصحيح.

اشتراك Pro أو Max نشط لكن Claude Code يستخدم API Key

هذه واحدة من أهم مشكلات المصادقة: عندما يكون متغير ANTHROPIC_API_KEY موجودًا ومقبولًا، يمكن أن تكون له أولوية على تسجيل الدخول بالاشتراك. قد يؤدي ذلك إلى استخدام حساب Console قديم، أو ظهور رسالة أن المؤسسة معطلة، أو احتساب الاستخدام بأسعار API بدل حصة اشتراكك.

فحص المفتاح على macOS وLinux

echo $ANTHROPIC_API_KEY

فحص المفتاح على Windows PowerShell

echo $env:ANTHROPIC_API_KEY

إزالة المفتاح مؤقتًا على macOS وLinux

unset ANTHROPIC_API_KEY
claude

إزالته مؤقتًا من Windows PowerShell

Remove-Item Env:ANTHROPIC_API_KEY
claude

إذا عاد المفتاح بعد فتح Terminal جديد، احذفه من .zshrc أو .bashrc أو PowerShell Profile أو من User Environment Variables في Windows. ثم استخدم /status لتأكيد أن Login Method هو الاشتراك المقصود.

حل Not logged in أو Claude.ai login expired

إذا انتهت جلسة OAuth، شغّل /login وأكمل المصادقة من جديد. إذا تكرر انتهاء الجلسة، تحقق من دقة الوقت والتاريخ والمنطقة الزمنية في جهازك، لأن التحقق من الرموز يعتمد على توقيت صحيح.

على macOS، قد تفشل عملية حفظ بيانات الدخول إذا كان Login Keychain مغلقًا أو كانت كلمة مروره غير متزامنة مع كلمة مرور الحساب. استخدم claude doctor لفحص الوصول إلى Keychain، ويمكن فتحه يدويًا بالأمر التالي عند الحاجة:

security unlock-keychain ~/Library/Keychains/login.keychain-db

حل API Error 429 وبلوغ حدود الاستخدام

لا يعني خطأ 429 أن Claude Code غير مثبت أو أن كلمة المرور خاطئة. قد يعني بلوغ حد الجلسة أو الحد الأسبوعي في الاشتراك، أو تجاوز Rate Limit في API، أو بلوغ حد الإنفاق أو نفاد الرصيد. يميز مرجع الأخطاء الرسمي بين Request rejected (429) ورسائل حدود الجلسة والحد الأسبوعي والرصيد.

شغّل /status.
تحقق هل تستخدم الاشتراك أم API Key.
أوقف الجلسات المتوازية أو Scripts التي ترسل طلبات كثيرة.
انتظر إعادة ضبط الحد إذا كنت تريد البقاء داخل الاشتراك.
راجع الرصيد وحد الإنفاق إذا كنت تستخدم Console API.

تشترك استخدامات Claude وClaude Code في حدود Pro وMax، لذلك قد تصل إلى الحد حتى لو لم تستخدم Terminal وحده بكثافة.

حل API Error 500 أو 529 أو Request timed out

تشير أخطاء 500 و529 Overloaded غالبًا إلى مشكلة مؤقتة من جهة خادم النموذج أو مزود الخدمة، بينما قد تنتج المهلة الزمنية عن الخدمة أو الشبكة المحلية. لا تبدأ بإعادة تثبيت Claude Code.

افتح صفحة حالة Claude.
أعد إرسال الطلب مرة واحدة بعد الانتظار.
تحقق من استقرار الإنترنت والـVPN والـProxy.
اختبر جلسة صغيرة بدل الطلب الكبير.
شغّل claude update إذا كنت تستخدم إصدارًا قديمًا.
إذا استمر الخطأ داخل IDE، جرّب Claude Code من Terminal مباشر.

لا تنشئ Retry Loop سريعًا: التكرار المتواصل قد يحول عطلًا مؤقتًا إلى خطأ 429 إضافي.

Claude Code process exited with code 1 داخل VS Code

هذه الرسالة لا تشرح السبب. إنها تعني أن البرنامج الذي أطلق Claude Code، مثل إضافة VS Code أو تطبيق يعتمد على Agent SDK، استلم Exit Code غير صفري من عملية claude. الخطأ الحقيقي يكون في Output أو سجل العملية.

اضغط على رابط View output logs داخل VS Code.
انسخ الرسالة الموجودة قبل Exit Code أو بعده.
افتح Terminal داخل المشروع نفسه.
شغّل claude يدويًا.
شغّل claude doctor.
قارن PATH داخل VS Code مع PATH داخل Terminal الخارجي.

إذا عمل Claude Code في Terminal ولم يعمل داخل VS Code، فالمشكلة غالبًا في البيئة التي ورثتها الإضافة أو في PATH أو متغيرات البيئة داخل الـIDE، وليست في تثبيت Claude Code نفسه.

Claude Code يتوقف أو لا يستجيب

إذا بدا Claude Code متجمدًا، اضغط Ctrl+C لإلغاء العملية الحالية. وإذا لم يستجب، أغلق Terminal ثم استأنف الجلسة من المجلد نفسه باستخدام:

claude --resume

إعادة التشغيل لا تعني بالضرورة فقدان المحادثة المحفوظة.

عند ارتفاع الذاكرة أو المعالج

استخدم /compact لتقليل السياق.
ابدأ جلسة جديدة بين المهام الكبيرة.
أضف مجلدات Build الضخمة إلى .gitignore.
جرّب claude --safe-mode لتعطيل Plugins وMCP وHooks والتخصيصات مؤقتًا.
قسّم الملفات أو النتائج الضخمة إلى أجزاء أصغر.

إذا اختفت المشكلة في Safe Mode، فسببها غالبًا Plugin أو MCP Server أو Hook أو إعداد مخصص، وليس الملف التنفيذي الأساسي.

Claude Code لا يجد الملفات أو نتائج البحث ناقصة

يعتمد البحث المحلي على ripgrep. إذا لم تعمل النسخة المدمجة على نظامك، قد تفشل Search Tool و@file وSkills وSubagents في العثور على ملفات موجودة.

ثبّت ripgrep من مدير الحزم الخاص بنظامك، ثم اضبط Claude Code لاستخدام نسخة النظام:

{
  "env": {
    "USE_BUILTIN_RIPGREP": "0"
  }
}

بعد ذلك شغّل:

claude doctor

وتحقق من أن سطر Search يعرض مسار نسخة النظام. وفي WSL، احتفظ بالمشروع داخل /home/ بدل /mnt/c/ عندما يكون أداء البحث مهمًا.

التثبيت يتوقف بسبب الذاكرة أو داخل Docker

على خوادم Linux الصغيرة، يعني Exit Code 137 عادة أن النظام أنهى عملية التثبيت بسبب نقص الذاكرة. يحتاج التثبيت إلى نحو 512 MB من الذاكرة الحرة، بينما تتطلب عملية التشغيل ذاكرة أكبر وتوصي المتطلبات الرسمية بإجمالي 4 GB على الأقل.

أغلق العمليات الأخرى.
أضف Swap Space إذا كان الخادم محدودًا.
استخدم خادمًا أكبر.
داخل Docker، لا تشغّل المثبت من المجلد الجذر /.
حدد WORKDIR صغيرًا قبل تشغيل Script التثبيت.

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

كيفية إعادة تثبيت Claude Code دون حذف إعداداتك

لا تبدأ بحذف ~/.claude. هذا المجلد قد يحتوي على إعداداتك، وأذونات الأدوات، وMCP Servers، وسجل الجلسات، كما تستخدمه إضافات VS Code وJetBrains وتطبيق Desktop. حذف المجلد خطوة أخيرة وليست طريقة تحديث عادية.

المسار الآمن

شغّل claude doctor.
حدّث الأداة باستخدام claude update.
افحص التثبيتات المتعارضة بواسطة which -a claude أو where.exe claude.
أزل npm أو Homebrew أو WinGet إذا كانت نسخة زائدة.
أزل الملف التنفيذي Native فقط إذا كان تالفًا.
أعد تشغيل Native Installer.
لا تحذف مجلد الإعدادات.

إزالة Native Install على macOS وLinux وWSL

rm -f ~/.local/bin/claude
rm -rf ~/.local/share/claude

إزالته على Windows PowerShell

Remove-Item -Path "$env:USERPROFILE\.local\bin\claude.exe" -Force
Remove-Item -Path "$env:USERPROFILE\.local\share\claude" -Recurse -Force

هذه الأوامر تزيل البرنامج والإصدارات المثبتة، لكنها لا تحذف مجلد إعدادات المستخدم .claude. بعد ذلك أعد تنفيذ أمر Native Installer الخاص بنظامك.

اختبار إعدادات نظيفة دون حذف الأصلية

قبل حذف إعداداتك، يمكنك تشغيل Claude Code باستخدام مجلد إعدادات مؤقت. إذا اختفت المشكلة، يكون السبب داخل إعداداتك أو Plugins أو MCP أو Hooks، ويمكنك إعادة العناصر واحدًا تلو الآخر بدل خسارتها كلها.

cd /tmp
CLAUDE_CONFIG_DIR=/tmp/claude-clean claude

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

مسار تشخيص Claude Code Error بالترتيب

انسخ نص الخطأ كاملًا ولا تعتمد على آخر سطر فقط.
افحص صفحة حالة Claude لاستبعاد العطل العام.
نفّذ claude --version لمعرفة هل PATH والملف التنفيذي يعملان.
نفّذ claude doctor لفحص التثبيت والإعدادات.
شغّل /status إذا كان Claude Code يفتح، وتحقق من الحساب والمصادقة.
حدد الطبقة: تثبيت، شبكة، تسجيل دخول، API، IDE، بحث أو إعدادات.
جرّب الحل الأقل تأثيرًا مثل فتح Terminal جديد أو إعادة الدخول.
حدّث Claude Code قبل الاعتماد على حلول تخص إصدارًا قديمًا.
استخدم Safe Mode لعزل Plugins وMCP وHooks.
افحص التثبيتات المتعددة قبل إعادة التثبيت.
أعد تثبيت الملف التنفيذي فقط مع إبقاء الإعدادات.
لا تحذف ~/.claude إلا بعد نسخة احتياطية وفهم ما سيُحذف.

قائمة الوقاية من مشكلات Claude Code

استخدم Native Installer بوصفه المسار الأساسي.
لا تستخدم أكثر من طريقة تثبيت على الجهاز نفسه دون حاجة.
افتح Terminal جديدًا بعد التثبيت أو تعديل PATH.
لا تستخدم sudo npm install -g.
لا تعطّل التحقق من شهادات SSL لحل خطأ مؤقت.
استخدم أمر التثبيت المناسب لـPowerShell أو CMD.
شغّل claude doctor بعد التثبيت والتحديثات الكبيرة.
شغّل /status دوريًا للتحقق من وسيلة المصادقة.
اترك ANTHROPIC_API_KEY غير مضبوط إذا كنت تريد استخدام اشتراكك فقط.
حدّث Claude Code عند ظهور مشكلة مصادقة متكررة.
استخدم WSL2 بدل WSL1 عند الحاجة إلى بيئة Linux.
ضع مشاريع WSL داخل نظام ملفات Linux لتحسين البحث.
احتفظ بنسخة من settings.json وملفات MCP قبل التعديلات.
سجّل نظام التشغيل وأمر التثبيت والإصدار ونص الخطأ عند طلب الدعم.

الأسئلة الشائعة

ما أسرع حل لمشكلة Claude Code لا يعمل بعد التثبيت؟

أغلق Terminal وافتح نافذة جديدة، ثم شغّل claude --version وclaude doctor. إذا ظهر command not found، أصلح PATH. وإذا ظهر الإصدار بصورة طبيعية، انتقل إلى فحص المصادقة أو خطأ التشغيل نفسه.

هل يحتاج Claude Code إلى Node.js؟

لا يحتاج Native Installer إلى Node.js. إذا اخترت التثبيت عبر npm، فالتوثيق الحالي يذكر أن الحزمة تتطلب Node.js 22 أو أحدث بدءًا من إصدار 2.1.198، رغم أن الملف التنفيذي المثبت لا يعتمد على Node عند التشغيل.

هل يحتاج Claude Code إلى Git for Windows؟

لا يُعد Git for Windows شرطًا للتثبيت الأصلي على Windows، لكنه يتيح استخدام Git Bash وأداة Bash. عند عدم وجوده، يستطيع Claude Code استخدام PowerShell. أما WSL فلا يحتاج إلى Git for Windows.

هل يجب تشغيل PowerShell كمسؤول؟

لا. يمكن تثبيت Claude Code Native داخل حساب المستخدم دون تشغيل PowerShell كمسؤول. استخدام صلاحيات مرتفعة دون حاجة قد ينشئ ملفات يملكها Administrator ويصعّب التحديث لاحقًا.

لماذا يعمل Claude Code في VS Code ولا يعمل في Terminal؟

لأن إضافة VS Code تحتوي على نسخة CLI خاصة بها، لكنها لا تضيف أمر claude إلى PATH. ثبّت Claude Code بصورة مستقلة لاستخدامه من Terminal.

لماذا يستخدم Claude Code رصيد API رغم وجود Pro؟

قد يكون متغير ANTHROPIC_API_KEY مضبوطًا في بيئة التشغيل، وله أولوية على تسجيل الدخول بالاشتراك بعد اعتماده. أزل المتغير ثم شغّل /status للتأكد من استخدام اشتراك Pro أو Max.

هل إعادة التثبيت تحذف محادثات Claude Code؟

إزالة الملف التنفيذي وإعادة تثبيته لا تتطلب حذف مجلد ~/.claude. لكن حذف هذا المجلد يحذف الإعدادات وأذونات الأدوات وMCP وسجل الجلسات المحلي، لذلك لا تنفذ هذه الخطوة إلا كحل أخير وبعد نسخة احتياطية.

هل خطأ 529 يعني أن التثبيت تالف؟

غالبًا لا. خطأ 529 يعني أن الخدمة أو مزود النموذج تحت ضغط مؤقت. افحص صفحة الحالة وانتظر ثم أعد المحاولة. إعادة التثبيت لا تعالج عادة هذا النوع من الأخطاء.

ماذا أفعل إذا لم يظهر الخطأ في هذا الدليل؟

نفّذ claude doctor، ثم استخدم /feedback إذا كانت الجلسة تفتح. وإذا كانت المشكلة مرتبطة بالحساب أو الاشتراك أو المؤسسة، تواصل مع دعم Anthropic. توصي الوثائق عند فتح بلاغ بإرفاق نظام التشغيل، وأمر التثبيت، وإصدار Claude Code، ونص الخطأ الكامل.

الخلاصة

أشهر أخطاء Claude Code لا تحتاج غالبًا إلى حذف البرنامج بالكامل. يبدأ الإصلاح الصحيح بتحديد المرحلة التي فشلت: هل لا يستطيع النظام العثور على الأمر؟ هل استخدمت أمر Windows داخل Shell خاطئ؟ هل تمنع الشبكة التنزيل؟ هل فشل OAuth؟ هل يتغلب API Key قديم على اشتراكك؟ أم أن الخطأ 429 أو 529 صادر من الخدمة وليس من جهازك؟

ابدأ دائمًا بـclaude --version وclaude doctor، ثم استخدم /status لفحص الحساب. فضّل Native Installer، وتجنب sudo npm وتعطيل SSL وحذف ~/.claude بصورة عشوائية. وإذا احتجت إلى إعادة التثبيت، أزل الملف التنفيذي فقط واحتفظ بإعداداتك وسجل جلساتك.

القاعدة العملية: أصلح رسالة الخطأ التي تراها، لا المشكلة التي تتوقعها.

المصادر الرسمية

Claude Code Docs — Advanced setup and installation.
Claude Code Docs — Troubleshoot installation and login.
Claude Code Docs — Error reference.
Claude Code Docs — Authentication.
Claude Code Docs — Troubleshooting performance and stability.
Claude Code Docs — Debug your configuration.
Claude Support — Troubleshoot Claude Code installation and authentication.
Claude Support — Use Claude Code with Pro or Max.
Claude Support — Manage API key environment variables.
Claude Support — Claude Code FAQ.

آخر تحقق: 22 أغسطس 2026

الإجابة السريعة: ما أول حل يجب تجربته؟

قبل الإصلاح: هل المشكلة من جهازك أم من خدمة Claude؟

ما الطريقة الصحيحة حاليًا لتثبيت Claude Code؟

macOS وLinux وWSL

Windows PowerShell

Windows CMD

Homebrew على macOS

WinGet على Windows

حل خطأ claude: command not found

الحل السريع

إضافة المسار على macOS باستخدام Zsh

إضافة المسار على Linux باستخدام Bash

إضافة المسار على Windows PowerShell

ثبّتُّ إضافة Claude Code في VS Code لكن أمر claude غير موجود

أخطاء أوامر التثبيت على Windows

حل خطأ HTML أو 403 أثناء التثبيت

macOS وLinux

Windows PowerShell

حل أخطاء Proxy وTLS وSELF_SIGNED_CERT_IN_CHAIN

ضبط Proxy على macOS أو Linux

ضبط Proxy في Windows PowerShell

إضافة شهادة الشركة لـClaude Code بعد التثبيت

حل EACCES وPermission denied أثناء التثبيت

أخطاء npm وNode.js عند تثبيت Claude Code

فحص إصدار Node.js

خطأ claude native binary not installed

خطأ ENOTEMPTY أثناء التحديث أو إعادة التثبيت

running scripts is disabled on this system

حل تعارض أكثر من تثبيت أو ظهور إصدار قديم

macOS وLinux

Windows PowerShell

أخطاء Claude Code على Windows وWSL

Claude Code لا يجد Git Bash

Exec format error داخل WSL

WSL يستخدم Node الخاص بـWindows

البحث بطيء داخل مشروع موجود على C:

طريقة إعادة ضبط Claude Code Login

حل OAuth error: Invalid code

المتصفح يقول إن الدخول نجح لكن Terminal ما زال ينتظر

حل خطأ 403 Forbidden بعد تسجيل الدخول

Claude Max or Pro is required رغم وجود Team أو Enterprise

اشتراك Pro أو Max نشط لكن Claude Code يستخدم API Key

فحص المفتاح على macOS وLinux

فحص المفتاح على Windows PowerShell

إزالة المفتاح مؤقتًا على macOS وLinux

إزالته مؤقتًا من Windows PowerShell

حل Not logged in أو Claude.ai login expired

حل API Error 429 وبلوغ حدود الاستخدام

حل API Error 500 أو 529 أو Request timed out

Claude Code process exited with code 1 داخل VS Code

Claude Code يتوقف أو لا يستجيب

عند ارتفاع الذاكرة أو المعالج

Claude Code لا يجد الملفات أو نتائج البحث ناقصة

التثبيت يتوقف بسبب الذاكرة أو داخل Docker

كيفية إعادة تثبيت Claude Code دون حذف إعداداتك

المسار الآمن

إزالة Native Install على macOS وLinux وWSL

إزالته على Windows PowerShell

اختبار إعدادات نظيفة دون حذف الأصلية

مسار تشخيص Claude Code Error بالترتيب

قائمة الوقاية من مشكلات Claude Code

الأسئلة الشائعة

ما أسرع حل لمشكلة Claude Code لا يعمل بعد التثبيت؟

هل يحتاج Claude Code إلى Node.js؟

هل يحتاج Claude Code إلى Git for Windows؟

هل يجب تشغيل PowerShell كمسؤول؟

لماذا يعمل Claude Code في VS Code ولا يعمل في Terminal؟

لماذا يستخدم Claude Code رصيد API رغم وجود Pro؟

هل إعادة التثبيت تحذف محادثات Claude Code؟

هل خطأ 529 يعني أن التثبيت تالف؟

ماذا أفعل إذا لم يظهر الخطأ في هذا الدليل؟

الخلاصة

المصادر الرسمية

اترك ردّاًإلغاء الرد