جدول المحتويات

هل حاولت استخدام Claude Code على جهاز خاص بالعمل أو عبر VPN، فلم يتصل وظهرت لك أخطاء مثل هذه؟

Unable to connect to API. Check your internet connection
Unable to connect to API (ECONNREFUSED)
Unable to connect to API: SSL certificate verification failed.
  Check your proxy or corporate SSL certificates
fetch failed

هذه أخطاء شبكية تعني «أن Claude Code لا يستطيع الوصول إلى خادم Anthropic (api.anthropic.com).» وهي ليست خطأ مصادقة (401/403)، ولا تحميلاً زائداً على الخادم (529/500)، ولا حدّ معدل (429) — فالطلب لم يصل إلى الخادم إطلاقاً. الأسباب المعتادة هي البروكسيات المؤسسية، وفحص TLS (الشهادات)، والجدران النارية، وهو ما يجعل هذا الخطأ شائعاً بصفة خاصة في شبكات المؤسسات. يتناول هذا المقال إعداد البروكسي، وشهادات CA المؤسسية، والنطاقات الواجب السماح بها، وخطوات التشخيص — استناداً إلى المعلومات الرسمية.

النقاط الأساسية أولاً. (1) خلف بروكسي، اضبط HTTPS_PROXY. (2) لخطأ شهادة ناتج عن فحص TLS (مثل Zscaler)، وجّه NODE_EXTRA_CA_CERTS إلى شهادة CA المؤسسية — ولا تعطّل التحقق أبداً عبر NODE_TLS_REJECT_UNAUTHORIZED=0 (فذلك يعرّض كل حركة المرور للاعتراض). (3) ابدأ بتشغيل curl -I https://api.anthropic.com للتحقق من «هل يمكنه الوصول أصلاً؟» — وهذا هو أساس عملية الفرز.

CLAUDE CODE · NETWORK / PROXY

إنه لا يصل إلى الخادم أبداً

— موضع توقّفه هو ما يحدد طريقة الإصلاح

Claude Code
طلب
→✗
بروكسي / TLS / جدار ناري
يُحجب هنا غالباً
→
api.anthropic.com
بروكسي
HTTPS_PROXY
شهادة TLS
NODE_EXTRA_CA_CERTS
جدار ناري
api.anthropic.com وغيره

شغّل أولاً curl -I https://api.anthropic.com للتحقق مما إذا كان يستطيع الوصول.
بمجرد أن تعرف أين يتوقف (بروكسي / TLS / جدار ناري)، يتحدد الإعداد الواجب تطبيقه.

1. ماذا يخبرك هذا الخطأ بالفعل

إن Unable to connect to API وfetch failed وECONNREFUSED / ETIMEDOUT تعني «أن الطلب لم يصل إلى خادم Anthropic» = أنه فشل في مكان ما ضمن TCP/TLS/DNS. وهذا هو الفرق الحاسم عن الأخطاء الأخرى: المصادقة (401/403)، والخادم (529/500)، والمعدل (429) كلها استجابات بعد الوصول إلى الخادم، بينما الأخطاء الشبكية تعني أنه لم يصل إليه قط.

في شبكات المؤسسات، تنقسم العوائق النمطية إلى ثلاث طبقات. (1) البروكسي — لا يمكنك الخروج مباشرة، ويجب التوجيه عبر بروكسي مؤسسي غير مُعَدّ. (2) فحص TLS (الشهادات) — يقوم بروكسي فحص مثل Zscaler باستبدال الشهادات، لذا عليك الوثوق بشهادة الجذر CA المؤسسية. (3) الجدار الناري — النطاقات المطلوبة غير مسموح بها. أول ما ينبغي فعله هو التأكد من «هل يمكنه الوصول؟» عبر curl -I https://api.anthropic.com — فهذا الفحص وحده يفصل «مشكلة شبكية» عن «كل شيء آخر.»

3 LAYERS

موضع التوقّف = الإعداد الواجب تطبيقه

1) لا بروكسي مضبوط
ECONNREFUSED/ETIMEDOUT/fetch failed. يجب التوجيه عبر البروكسي المؤسسي → اضبط HTTPS_PROXY.
2) خطأ شهادة من فحص TLS
SSL certificate verification failed/self-signed → ضع شهادة CA المؤسسية في NODE_EXTRA_CA_CERTS. لا تعطّل التحقق أبداً.
3) نطاق محجوب بالجدار الناري
النطاقات المطلوبة غير مسموح بها → اسمح بـ api.anthropic.com وغيره (§4).
4) DNS / VPN / أدوات محلية
Could not resolve host/ENOTFOUND. تعطّل DNS، أو بقايا VPN قديمة، أو اعتراض Docker لحركة المرور.

إذا نجح curl -I https://api.anthropic.com، تنحصر المشكلة في ما بين Claude Code والشبكة.

2. إعداد البروكسي (HTTPS_PROXY)

عندما يتعيّن عليك التوجيه عبر بروكسي مؤسسي، اضبط متغيرات بيئة البروكسي القياسية. فإن Claude Code يحترمها.

# Recommended: HTTPS proxy
export HTTPS_PROXY=http://proxy.example.com:8080
# If HTTPS isn't available, HTTP_PROXY
export HTTP_PROXY=http://proxy.example.com:8080
# Destinations that bypass the proxy (space- or comma-separated)
export NO_PROXY="localhost,127.0.0.1,.internal.example.com"

# Authenticating proxy (avoid hardcoding passwords)
export HTTPS_PROXY=http://username:password@proxy.example.com:8080

محاذير: بروكسيات SOCKS غير مدعومة. أما بروكسيات NTLM / Kerberos، فالتوصية الرسمية هي إقامة بوابة LLM gateway في الوسط وتوجيه ANTHROPIC_BASE_URL إليها. كذلك إذا كنت تستخدم خوادم MCP، فيجب أن تضبط HTTPS_PROXY وNODE_EXTRA_CA_CERTS صراحةً في env الخاص بكل خادم (فهي لا تُورَّث من الأصل). ويمكن أيضاً وضع هذه المتغيرات في كتلة env داخل settings.json.

3. شهادات TLS وشهادات CA المؤسسية (الأهم، بأمان)

أكثر العوائق المؤسسية شيوعاً هو خطأ شهادة سببه قيام بروكسي فحص TLS (مثل Zscaler وNetskope وPalo Alto) باستبدال الشهادات. الرسائل النمطية هي unable to get local issuer certificate وSELF_SIGNED_CERT_IN_CHAIN.

وللتوضيح، فإن إصدارات Claude Code الحديثة تثق بمجموعة CA المُضمّنة وبمخزن الثقة في نظام التشغيل معاً. لذا إذا كانت شهادة الجذر CA المؤسسية موجودة في مخزن شهادات نظام التشغيل، فإنها تعمل غالباً دون أي إعداد إضافي (يختلف السلوك حسب الإصدار، فتحقّق من الأحدث). وإن لم تكن في مخزن نظام التشغيل، فـوجّه NODE_EXTRA_CA_CERTS إلى حزمة CA (بصيغة PEM) التي تلقّيتها من قسم تقنية المعلومات:

# The correct, secure way: trust the corporate CA
export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem

# If the proxy requires a client certificate (mTLS)
export CLAUDE_CODE_CLIENT_CERT=/path/to/client-cert.pem
export CLAUDE_CODE_CLIENT_KEY=/path/to/client-key.pem

⚠️ لا تفعل: تعطيل التحقق من TLS

إن إيقاف التحقق من الشهادة عبر NODE_TLS_REJECT_UNAUTHORIZED=0 يبدو وكأنه «يحلّ» المشكلة، لكن لا تفعل هذا أبداً. فهو يعطّل التحقق من TLS للعملية بأكملها، بحيث تصبح كل حركة المرور — بما فيها إلى api.anthropic.com — معرّضة لهجمات الوسيط (التنصّت/التلاعب). وهذا يهدّد بتسريب بيانات الاعتماد والشيفرة. الجواب الصحيح دائماً هو «الوثوق بشهادة CA المؤسسية بشكل سليم عبر NODE_EXTRA_CA_CERTS.»

إذا واجهت خطأ شهادة وقت التثبيت (قبل وجود الملف التنفيذي)، مرّر شهادة CA إلى curl: curl --cacert /path/to/corporate-ca.pem -fsSL https://claude.ai/install.sh | bash.

4. النطاقات المسموح بها في الجدار الناري

إذا كان جدارك الناري يقيّد الوجهات، فـاسمح بهذه النطاقات عبر HTTPS (443) (وفقاً لمتطلبات الشبكة الرسمية).

النطاقالاستخدام
api.anthropic.comطلبات Claude API (مطلوب)
claude.aiمصادقة حساب claude.ai
platform.claude.comمصادقة حساب Console
downloads.claude.aiالمثبّت، التحديث التلقائي، الإضافات
raw.githubusercontent.comملاحظات الإصدار، المتجر

القياس عن بُعد (statsig.anthropic.com) والإبلاغ عن الأخطاء (*.sentry.io) اختياريان ويمكن تعطيلهما (لا حاجة لإدراجهما في قائمة السماح المطلوبة). وإذا كنت تدير عمليات التثبيت بنفسك عبر npm، فقد لا تحتاج إلى downloads.claude.ai. النطاقات ونطاقات IP الدقيقة قد تُراجَع، لذا تحقّق من الأحدث في صفحة إعدادات الشبكة الرسمية.

5. سير عمل التشخيص

حين يتعذّر الاتصال، اعمل من الأعلى إلى الأسفل. أول curl يحدد الاتجاه.

DIAGNOSE

اعزل المشكلة من الأعلى إلى الأسفل

1
curl -I https://api.anthropic.com (في Windows: curl.exe) لـاختبار إمكانية الوصول. إذا نجح، فالمشكلة من جهتك.
2
/doctor (أو claude doctor إن لم يبدأ التشغيل) وافحص متغيرات بيئة البروكسي.
3
خطأ شهادة → طبّق NODE_EXTRA_CA_CERTS؛ لا بروكسي مضبوط → طبّق HTTPS_PROXY.
4
جرّب اتصالاً مباشراً (خارج VPN/البروكسي) للتأكد من أن البروكسي هو السبب. اطلب من قسم تقنية المعلومات رابط البروكسي وشهادة CA.
5
إذا نجح curl لكن Claude Code فشل، فاشتبه في DNS (WSL resolv.conf)، أو بقايا VPN قديمة، أو Docker يعترض حركة المرور.

القاعدة: «اختبر إمكانية الوصول (curl) أولاً، ثم طبّق إعداد الطبقة التي توقفت عندها.»
عالج الشهادات بـ NODE_EXTRA_CA_CERTS. لا تعطّل التحقق أبداً.

6. تمييزه عن الأخطاء المشابهة

«توقّف الاتصال» قد لا يكون شبكياً أيضاً. الانقسام الكبير هو «هل وصل إلى الخادم؟»

العَرَضما هو في الحقيقةالإصلاح الرئيسي
Unable to connect / fetch failed / خطأ شهادةهذا المقال = شبكي (لم يصل إلى الخادم قط)HTTPS_PROXY / NODE_EXTRA_CA_CERTS / السماح في الجدار الناري
401 / 403 / Invalid API keyمصادقة (وصل، لكن مشكلة في بيانات الاعتماد)أخطاء المصادقة / تسجيل الدخول
529 / 500من جانب الخادم (وصل، لكنه محمّل بشكل زائد / خطأ داخلي)أخطاء 529/500
429 Request rejectedحدّ معدل (وصل، لكن حركة المرور كثيرة جداً)خفّض الوتيرة، وانتظر

طريقة للتذكّر: الأخطاء الشبكية تعني «أنه لم يصل إلى الخادم قط» (TCP/TLS/DNS)، وHTTPS_PROXY أو NODE_EXTRA_CA_CERTS لا ينفعان إلا في هذه الطبقة. أما 401/403 و529/500 و429 فهي «استجابات بعد الوصول»، لذا فإن تعديل البروكسي أو شهادة CA لن يصلحها. ونجاح curl من عدمه هو أفضل دليل وحيد يفصل بين الحالتين. وللاطّلاع على أخطاء شائعة أخرى، راجع مجموعة الأخطاء.

الخلاصة

إن أخطاء الشبكة/البروكسي في Claude Code (Unable to connect / fetch failed / SSL certificate verification failed، إلخ) تعني أن الطلب لم يصل إلى الخادم قط = فشل في TCP/TLS/DNS. وهي مختلفة عن المصادقة (401/403)، والخادم (529/500)، والمعدل (429)، والأسباب المعتادة هي البروكسي المؤسسي، وفحص TLS، والجدار الناري.

الإصلاحات: (1) خلف بروكسي، اضبط HTTPS_PROXY (SOCKS غير مدعوم؛ NTLM/Kerberos عبر بوابة)، (2) لأخطاء الشهادات ضع شهادة CA المؤسسية في NODE_EXTRA_CA_CERTS — لا NODE_TLS_REJECT_UNAUTHORIZED=0 أبداً، (3) اسمح بـ api.anthropic.com وغيره في الجدار الناري. شخّص المشكلة بـاختبار إمكانية الوصول أولاً عبر curl -I https://api.anthropic.com ← /doctor وفحص البروكسي ← إعدادات الشهادة/البروكسي ← اتصال مباشر للتأكيد ← DNS/VPN/Docker. المفتاح هو فصل الشبكي عن المصادقة/الخادم/المعدل بسؤال «هل وصل إلى الخادم؟» ذو صلة: أخطاء المصادقة / تسجيل الدخول، أخطاء 529/500، مجموعة أخطاء Claude Code.

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

Q. على جهاز شركتي يظهر «Unable to connect to API» ولا أستطيع الاتصال.
A. غالباً يتعيّن عليك التوجيه عبر بروكسي مؤسسي غير مُعَدّ. تحقّق أولاً من إمكانية الوصول عبر curl -I https://api.anthropic.com؛ فإن فشل، اضبط بروكسي مثل export HTTPS_PROXY=http://proxy.example.com:8080 (أضف user:password@ لبروكسي يتطلب مصادقة). لاحظ أن SOCKS غير مدعوم، وأن التوصية الرسمية لبروكسيات NTLM/Kerberos هي المرور عبر بوابة LLM gateway.

Q. يظهر لي «SSL certificate verification failed».
A. هذا عادةً ناتج عن بروكسي فحص TLS مؤسسي (مثل Zscaler) يستبدل الشهادات. احصل على شهادة الجذر CA المؤسسية (بصيغة PEM) من قسم تقنية المعلومات واضبط export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem. وإذا كانت شهادة CA المؤسسية موجودة بالفعل في مخزن شهادات نظام التشغيل، فقد يعمل دون أي إعداد. لا تعطّل التحقق أبداً عبر NODE_TLS_REJECT_UNAUTHORIZED=0 — فذلك يعرّض كل حركة المرور للاعتراض.

Q. ضبطُ NODE_TLS_REJECT_UNAUTHORIZED=0 أصلح المشكلة. هل هذا مقبول؟
A. لا — تراجع عنه الآن. فهو يعطّل التحقق من شهادة TLS للعملية بأكملها، تاركاً كل حركة المرور — بما فيها إلى api.anthropic.com — بلا حماية أمام هجمات الوسيط (التنصّت/التلاعب). وهذا خطر أمني جسيم قد يسرّب بيانات الاعتماد والشيفرة المصدرية. الإصلاح الصحيح الوحيد هو الوثوق بشهادة CA المؤسسية بشكل سليم عبر NODE_EXTRA_CA_CERTS.

Q. أي النطاقات ينبغي السماح بها في الجدار الناري؟
A. عبر HTTPS (443)، اسمح كحدّ أدنى بـ api.anthropic.com (API)، وclaude.ai وplatform.claude.com (المصادقة)، وdownloads.claude.ai (المثبّت/التحديثات)، وraw.githubusercontent.com. أما القياس عن بُعد (statsig) والإبلاغ عن الأخطاء (sentry) فاختياريان. النطاقات/عناوين IP الدقيقة قد تُراجَع، لذا تحقّق من الأحدث في صفحة إعدادات الشبكة الرسمية.

Q. curl يعمل، لكن Claude Code وحده لا يتصل.
A. السبب غالباً بين Claude Code ونظام التشغيل. الحالات الشائعة: ملف /etc/resolv.conf في WSL يشير إلى DNS معطّل، أو بقايا VPN قديمة (مثل واجهات utun القديمة في macOS)، أو أداة مقيمة مثل Docker تعترض حركة المرور. جرّب اتصالاً مباشراً خارج VPN، وأوقف الأدوات المقيمة، وراجع DNS، بهذا الترتيب. لاحظ أن أخطاء 5xx العابرة تُعاد محاولتها تلقائياً حتى 10 مرات، فإذا رأيت خطأً بينما ينجح curl، فإن المحاولات المتكررة قد استُنفدت بالفعل.