استكشاف رموز أخطاء Claude Code

أولًا، حدد الطبقة التي يقع فيها الخطأ

INSTALL

التثبيت / بيئة التشغيل

مشكلات command not found، وإصدار Node، وأذونات npm، ومسار WSL، والمثبت الأصلي.

AUTH

تسجيل الدخول / المصادقة

مشكلات رد استدعاء OAuth، ومفتاح API، والمؤسسة في Console، وSSO، وحالة المصادقة المحلية.

NETWORK

الشبكة / البروكسي

بروكسي الشركة، وجدار الحماية، والشهادات، وانتهاء المهلة، و403/429، وتعذر الوصول إلى النطاقات المطلوبة.

الأخطاء الشائعة وحلولها

claude: command not found

السبب الشائع: مجلد التثبيت غير مضاف إلى PATH، أو لم يعد shell الحالي تحميل إعداداته.

الحل: افتح طرفية جديدة، أو أضف مجلد تثبيت Claude Code إلى PATH ثم أعد تحميل إعدادات shell.

export PATH="$PATH:$HOME/.local/bin"
source ~/.zshrc

Node version not supported / silent crash

السبب الشائع: إصدار Node أقدم من المتطلب الرسمي، أو أن WSL يستدعي Node المثبت على جانب Windows.

الحل: قم بترقية Node، أو استخدم المثبت الأصلي الرسمي. في WSL، تحقق من المسار عبر which node / which npm للتأكد من أنه من بيئة Linux.

node -v
which node
which npm

EACCES / permission denied

السبب الشائع: مجلد npm العام مملوك للمستخدم root، أو أن تثبيتًا سابقًا عبر sudo أفسد الأذونات.

الحل: لا تثبت Claude Code باستخدام sudo. انقل بادئة npm (prefix) إلى مجلد خاص بالمستخدم، أو استخدم المثبت الأصلي.

npm config set prefix ~/.npm-global
export PATH="$HOME/.npm-global/bin:$PATH"

Waiting for authentication...

السبب الشائع: رد استدعاء OAuth من المتصفح لا يصل إلى CLI المحلي — وهذا شائع مع SSH البعيد وdevcontainers وجدران الحماية الصارمة أو حظر ردود الاستدعاء إلى localhost.

الحل: تأكد من أن المتصفح وCLI يستطيعان التواصل على الجهاز نفسه. وعند الحاجة، سجل الخروج وأعد تشغيل Claude Code ثم أكمل المصادقة مجددًا.

/logout
# 关闭 Claude Code 后重新运行
claude

SELF_SIGNED_CERT_IN_CHAIN / certificate error

السبب الشائع: يحقن بروكسي الشركة أو بوابة أمنية شهادة CA موقعة ذاتيًا لا يثق بها Node افتراضيًا.

الحل: اطلب من قسم تقنية المعلومات حزمة CA الخاصة بالشركة وحددها عبر NODE_EXTRA_CA_CERTS.

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

proxy connection failed / timeout

السبب الشائع: متغيرات البروكسي مضبوطة بشكل خاطئ، أو بروتوكول البروكسي غير مدعوم، أو أن NO_PROXY يتجاوز النطاق المستهدف، أو أن جدار حماية الشركة يحظر الوصول.

الحل: يستخدم Claude Code متغيرات بيئة البروكسي القياسية HTTP/HTTPS؛ وتنص الوثائق على أن بروكسي SOCKS غير مدعوم. أعد الاختبار باستخدام HTTPS_PROXY أولًا.

export HTTPS_PROXY=http://proxy.example.com:8080
echo $HTTPS_PROXY
echo $NO_PROXY

403 Forbidden

السبب الشائع: لم تفعل المؤسسة Claude Code، أو أن قائمة السماح في الشركة لا تشمل نقطة الخروج الحالية، أو توجد قيود على الحساب/المنطقة/السياسة، أو أن البروكسي مرفوض.

الحل: في الحسابات الشخصية، تحقق أولًا من المناطق المدعومة وحالة الحساب؛ وفي حسابات الشركات، اطلب من المسؤول فحص أذونات Claude Code وSSO وقائمة السماح لعناوين IP وقواعد جدار الحماية.

429 / rate limit

السبب الشائع: الطلبات متكررة جدًا، أو التزامن مرتفع جدًا، أو بلغت خطة الحساب أو المؤسسة حد المعدل.

الحل: اخفض التزامن الخارجي، وأوقف حلقات إعادة المحاولة، وانتظر إعادة تعيين الحد. لا تغلف Claude Code بعدة عمليات worker لفرض السرعة.

API key not recognized / SSO mismatch

السبب الشائع: مفتاح API مصدره shell آخر، أو أن مفتاح Console يتعارض مع جلسة OAuth، أو أن المؤسسة تشترط تسجيل الدخول عبر SSO.

الحل: تحقق مما إذا كان ANTHROPIC_API_KEY مضبوطًا في shell الحالي. وينبغي لحسابات الشركات اتباع مسار تسجيل الدخول عبر Console/SSO الذي يشترطه المسؤول.

echo $ANTHROPIC_API_KEY

أساسيات البروكسي وشبكة الشركة

تنص الوثائق الرسمية على أن Claude Code يدعم متغيرات البيئة القياسية HTTPS_PROXY / HTTP_PROXY / NO_PROXY، لكنه لا يدعم بروكسي SOCKS. وبالنسبة إلى الشهادات الموقعة ذاتيًا في الشركات، حدد حزمة CA عبر NODE_EXTRA_CA_CERTS.

export HTTPS_PROXY=http://proxy.example.com:8080
export NO_PROXY="localhost,127.0.0.1"
export NODE_EXTRA_CA_CERTS=/path/to/company-ca.pem

خطوات الحد الأدنى لإعادة إنتاج المشكلة

تأكد من أن `node -v` يفي بالمتطلب الرسمي، أو استخدم مثبت Claude Code الأصلي.
أغلق أي سكربتات مغلفة وعمليات worker، وشغل `claude` في نافذة طرفية واحدة فقط.
استخدم `echo $HTTPS_PROXY` و`echo $NO_PROXY` للتأكد من ضبط متغيرات البروكسي بشكل صحيح.
تحقق مما إذا كان جدار الحماية يسمح بالوصول إلى api.anthropic.com وclaude.ai وstatsig.anthropic.com وsentry.io.
إذا تعلق تسجيل الدخول، فشغل `/logout` وأعد تشغيل Claude Code، وامسح ملفات المصادقة المحلية عند الحاجة قبل تسجيل الدخول مجددًا.

المراجع الرسمية

إعداد شبكة الشركات في Claude Code

البروكسي وCA وmTLS وعناوين URL المطلوبة للوصول.

استكشاف مشكلات التثبيت والمصادقة في Claude Code

القائمة الرسمية للمشكلات الشائعة في التثبيت وNode والأذونات والبروكسي وتسجيل الدخول.

البيانات والقياس عن بعد في Claude Code

Statsig وSentry و/bug ومتغيرات البيئة لتعطيل حركة المرور غير الضرورية.

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

بروكسي الشركات، ومؤسسات Console، ومشكلات الأذونات الشائعة.