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

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

# What you see now (examples)
Can't reach the API server — check your internet or DNS (ENOTFOUND)
Connection refused — a firewall or proxy may be blocking it (ConnectionRefused)
Unable to connect to API. Check your internet connection
Unable to connect to Anthropic services
fetch failed

# What older versions showed
Unable to connect to API (ECONNREFUSED)
Unable to connect to API: SSL certificate verification failed.
  Check your proxy or corporate SSL certificates

تختلف الصياغة باختلاف الإصدار. منذ الإصدار v2.1.227، صارت الرسائل التي كانت تكتفي بإلحاق رمز، مثل Unable to connect to API (ECONNREFUSED)، تبدأ بنوع الفشل بدلاً من ذلك، مثل Connection refused — أو Can't reach the API server — (جدول المقابلة في §2). وأياً كانت الصياغة التي تراها، فما يحدث وطريقة إصلاحه واحد.

هذه أخطاء شبكية تعني «أن 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 (ومنذ الإصدار v2.1.227 تظهر بصياغة مثل Connection refused —؛ انظر §2) تعني «أن الطلب لم يصل إلى خادم 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 وغيره (§5).
4) DNS / VPN / أدوات محلية
Could not resolve host/ENOTFOUND. تعطّل DNS، أو بقايا VPN قديمة، أو اعتراض Docker لحركة المرور.

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

2. ماذا تعني كل رسالة (الصياغة منذ الإصدار v2.1.227)

وفقاً لمرجع الأخطاء الرسمي، تعني رسائل هذه المجموعة أن اتصال TCP بالـ API فشل أو لم يكتمل. وبالنسبة إلى رموز الأخطاء الشائعة، تصف الرسالة نوع الفشل بالكلمات وتُبقي الرمز بين قوسين. هذا ما يظهر الآن:

Unable to connect to API. Check your internet connection
Connection refused — a firewall or proxy may be blocking it (ConnectionRefused)
Can't reach the API server — check your internet or DNS (ENOTFOUND)
No internet route — check your connection or VPN (EHOSTUNREACH)
Couldn't connect through your proxy (ERR_PROXY_TUNNEL) — the proxy refused the tunnel: check its credentials and that it allows this host
Connection dropped (ECONNRESET)
fetch failed
Request timed out. Check your internet connection and proxy settings

قبل الإصدار v2.1.227، كانت كل هذه الرسائل ذات الرموز تظهر بصيغة Unable to connect to API متبوعةً بالرمز (مثلاً Unable to connect to API (ECONNREFUSED)). وما زالت الرموز التي لا يتعرّف عليها Claude Code تظهر بهذه الصيغة. كما قد تحمل الرسالة نفسها رموزاً مختلفة: فقد تظهر Connection refused مع ConnectionRefused أو ECONNREFUSED، وقد تظهر Can't reach the API server مع ENOTFOUND أو FailedToOpenSocket.

بداية الرسالةما تقوله الرسالةما تتحقق منه أولاً
Connection refused —رُفض الاتصال؛ قد يكون جدار ناري أو بروكسي يحجبهقائمة السماح (§5) وHTTPS_PROXY (§3)
Can't reach the API server —تعذّر الوصول إلى خادم الـ API؛ اشتبه في الاتصال بالإنترنت أو في DNSإعدادات DNS والـ VPN؛ وفي WSL ملف /etc/resolv.conf (§6)
No internet route —لا يوجد مسار إلى الوجهةحالة خط الاتصال واتصال الـ VPN
Couldn't connect through your proxyرفض البروكسي إنشاء النفقبيانات اعتماد البروكسي، وهل يسمح بالمضيف المقصود
Connection droppedأُعيد تعيين الاتصال (ECONNRESET)استقرار البروكسي والشبكة

أياً كانت الرسالة، يُعاد تلقائياً تنفيذ الطلبات بعد الأعطال العابرة، لذا فحين تظهر على الشاشة تكون المحاولات المتكررة قد استُنفدت بالفعل. وإذا تكررت، فالسبب في شبكتك المحلية. ومن الأسباب الشائعة التي يذكرها المرجع الرسمي: عدم الوصول إلى الإنترنت، أو VPN يحجب api.anthropic.com، أو بروكسي مؤسسي إلزامي غير مُعَدّ. وطرق الإصلاح في §3–§6.

Unable to connect to Anthropic services (عند الإعداد الأولي)

أثناء إعداد التشغيل الأول، وقبل عرض خطوة تسجيل الدخول، يتحقق Claude Code من قدرته على الوصول إلى api.anthropic.com وplatform.claude.com. وإذا فشل أيّ من الفحصين، يعرض السبب ثم يخرج. المثال الرسمي:

Unable to connect to Anthropic services
Failed to connect to api.anthropic.com: ECONNREFUSED
Connection to api.anthropic.com timed out after 10 seconds
A proxy is configured via HTTPS_PROXY. Check that it allows connections to the host above.

يمرّ هذا الفحص عبر إعدادات البروكسي نفسها التي تمرّ بها طلبات الـ API، ويمنح كل محاولة 10 ثوانٍ. وإذا كانت المحاولة الفاشلة قد مرّت عبر بروكسي، تذكر الرسالة اسم متغير البيئة الذي ضبطه (مثل HTTPS_PROXY). ما العمل:

  • تحقّق من أن المتغير المذكور يشير إلى البروكسي الصحيح، واطلب من فريق الشبكة السماح عبره باتصالات HTTPS إلى المضيف المذكور في الرسالة (قائمة السماح في §5)
  • نفّذ فحص الوصول بـ curl الوارد في §6 من الـ shell نفسه
  • إذا توقف عند Checking connectivity... خلف بروكسي يبدأ عنوانه بـ https://، فقد يكون ذلك خللاً في الإصدارات السابقة لـ v2.1.222 (كان الفحص يسلك مساراً مختلفاً عن طلبات الـ API ولم تكن له مهلة). حدّث البرنامج
  • إذا كانت مؤسستك تسجّل الدخول عبر بوابة سحابية (Claude apps gateway) وظهر هذا الخطأ في التشغيل الأول، فحدّث إلى الإصدار v2.1.247 أو أحدث

إذا كانت شبكتك مفتوحة واستمر الفشل، يشير المرجع الرسمي إلى أن Claude Code قد لا يكون متاحاً في بلدك أو منطقتك. راجع قائمة البلدان والمناطق المدعومة.

Streaming response ended before any complete data was received

Streaming response ended before any complete data was received. Retrying without streaming. If this keeps happening, check any proxy or gateway between Claude Code and your model provider.

هذا التحذير لا يعني «لم يصل الطلب»، بل «جهاز في المنتصف غيّر الاستجابة». فقد انتهت استجابة متدفقة من مزوّد النموذج دون أن تحمل أي بيانات صالحة، فأعاد Claude Code إرسال الطلب دون تدفق لإكمال الدور. ويُرسَل كل طلب متأثر مرتين: محاولة التدفق الفارغة ثم الإعادة. ووفقاً للمرجع الرسمي، السبب المعتاد بروكسي أو بوابة تستهلك جسم الاستجابة المتدفقة أو تحوّله في الطريق، والحل ضبط أي بروكسي أو بوابة بين Claude Code ومزوّد النموذج بحيث تمرّر جسم الاستجابات المتدفقة وترويساتها دون تعديل. يظهر التحذير مرة واحدة في كل جلسة، وفي الجلسات التفاعلية فقط. وقبل الإصدار v2.1.239، كان Claude Code يعيد المحاولة دون تدفق بصمت.

3. إعداد البروكسي (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 إليها. ويمكن أيضاً وضع هذه المتغيرات في كتلة env داخل settings.json.

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

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

منذ الإصدار v2.1.273، تتضمّن رسائل Claude Code نفسه رمز الخطأ وطريقة الإصلاح. وأثناء الجلسة، تُظهر طلبات الـ API ما يلي:

Unable to connect to API: SSL certificate verification failed (UNABLE_TO_GET_ISSUER_CERT_LOCALLY). The certificate comes from an authority Claude Code doesn't trust, usually a TLS-inspecting corporate proxy or a gateway signed by a private CA: set NODE_EXTRA_CA_CERTS to that CA bundle, or add it to the system certificate store · see https://code.claude.com/docs/en/network-config
Unable to connect to API: Self-signed certificate detected (SELF_SIGNED_CERT_IN_CHAIN). The certificate comes from an authority Claude Code doesn't trust, usually a TLS-inspecting corporate proxy or a gateway signed by a private CA: set NODE_EXTRA_CA_CERTS to that CA bundle, or add it to the system certificate store · see https://code.claude.com/docs/en/network-config

وأثناء /login وفحص الاتصال عند بدء التشغيل، يُنتج الفشل نفسه رسالة مختلفة:

SSL certificate error (UNABLE_TO_GET_ISSUER_CERT_LOCALLY). If you are behind a corporate proxy or TLS-intercepting firewall, set NODE_EXTRA_CA_CERTS to your CA bundle path, or ask IT to allowlist *.anthropic.com. Run `claude doctor` for details.

قبل الإصدار v2.1.273، كانت الرسالتان الأوليان تنتهيان عند Check your proxy or corporate SSL certificates، دون الرمز ودون تلميح NODE_EXTRA_CA_CERTS (وهو الإخراج القديم في أول المقال). كذلك، منذ الإصدار v2.1.199 لا يُعاد تنفيذ الطلب عند فشل التحقق من الشهادة، فيظهر الخطأ من المحاولة الأولى (كانت الإصدارات الأقدم تقضي بضع دقائق في إعادة المحاولة أولاً). أما حالات TLS العابرة مثل انتهاء مهلة المصافحة فما زالت تُعاد.

وللتوضيح، فإن إصدارات 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.

OAuth error: SSL certificate error (CERT_HAS_EXPIRED)

في منتصف تسجيل الدخول (خطوة OAuth في /login) قد تظهر الرسالة التالية ويتوقف كل شيء. هذا هو النص الحرفي الذي أبلغ عنه المستخدمون في بلاغات GitHub:

OAuth error: SSL certificate error (CERT_HAS_EXPIRED). If you are behind a corporate proxy or TLS-intercepting firewall, set NODE_EXTRA_CA_CERTS to your CA bundle path, or ask IT to allowlist *.anthropic.com. Run /doctor for details.

هذه الرسالة غير موجودة في مرجع الأخطاء الرسمي. قسم SSL certificate errors الرسمي لا يعرض إلا الرمزين UNABLE_TO_GET_ISSUER_CERT_LOCALLY وSELF_SIGNED_CERT_IN_CHAIN؛ أما الشهادة المنتهية الصلاحية فلا تُذكر إلا عَرَضاً، كمثال على فشل التحقق من الشهادة في شرح إعادة المحاولة التلقائية. النص أعلاه مصدره مستخدمون في بلاغَي GitHub #71708 و#71727 (كلاهما في يونيو 2026).

معنى CERT_HAS_EXPIRED: هو أحد رموز أخطاء الشهادات التي تُعيدها طبقة TLS في Node.js، وتصفه وثائق Node.js الرسمية بعبارة «Certificate has expired» (انتهت صلاحية الشهادة). أي أن الشهادة المستلمة من الخادم فُحصت فاعتُبرت متجاوزة لتاريخ انتهاء صلاحيتها. وتُقارَن الصلاحية بساعة جهازك أنت.

ما تقوله البلاغات: كتب صاحبا البلاغين أنهما لا يستخدمان بروكسي ولا VPN، وأن curl وصل إلى المضيف نفسه دون مشكلة (وتحقق صاحب البلاغ #71708 أيضاً من أن ساعة الجهاز صحيحة). أي أن الخطأ يظهر أيضاً في بيئات لا ينطبق عليها ما تقترحه الرسالة نفسها (بروكسي مؤسسي، فحص TLS). وقد شكّ أصحاب البلاغات في بيئة التشغيل المضمّنة في Claude Code، وتقول عدة تعليقات إن الرجوع إلى إصدار أقدم حلّ المشكلة. لكن لا يوجد رد من Anthropic في أي من البلاغين، وأُغلق كلاهما بعد توقف النشاط. السبب لم يُؤكَّد رسمياً. وحتى 30 سبتمبر 2026 لا يحتوي CHANGELOG الرسمي كذلك على أي بند يقول إنه أصلح هذا العَرَض.

ما تتحقق منه بالترتيب:

  1. ساعة الجهاز: هل التاريخ والوقت والمنطقة الزمنية صحيحة؟ إذا كانت الساعة منحرفة كثيراً، فقد تُعتبر حتى الشهادة الصالحة منتهية.
  2. شهادة بروكسي الشركة: إذا كانت حركة المرور تمر عبر بروكسي أو منتج أمني يفحص TLS، فاسأل قسم تقنية المعلومات هل انتهت صلاحية الشهادة التي يُدرجها (بما فيها شهادة CA المؤسسية).
  3. NODE_EXTRA_CA_CERTS: إذا احتجت إلى الوثوق بشهادة CA مؤسسية، فوجّه NODE_EXTRA_CA_CERTS إلى حزمة CA التي يعطيك إياها قسم تقنية المعلومات، كما تشرح صفحة إعدادات الشبكة الرسمية (الخطوات أعلاه). وللتأكد من تحميلها، ابحث عن السطر CA certs: Appended extra certificates from NODE_EXTRA_CA_CERTS في سجل claude --debug.
  4. إذا استمر ظهوره: إذا كانت الساعة صحيحة ولا يوجد بروكسي وcurl -I https://platform.claude.com ينجح، فقد تكون في الوضع نفسه الذي تصفه بلاغات GitHub. حدّث Claude Code، ثم راجع البلاغات وسجل التغييرات. يقول أحد التعليقات إن NODE_TLS_REJECT_UNAUTHORIZED=0 جعله يعمل، لكن كما يوضح الإطار أعلاه، فهذا يُطفئ التحقق كلياً، فلا تستخدمه.

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

إذا كان جدارك الناري يقيّد الوجهات، فـاسمح بهذه النطاقات الرئيسية عبر HTTPS (443) (وفقاً لمتطلبات الشبكة الرسمية؛ وإذا كنت تستخدم موصلات MCP أو الإضافات ونحوها، فستحتاج أيضاً إلى مضيفين آخرين من القائمة الرسمية).

النطاقالاستخدام
api.anthropic.comطلبات Claude API (مطلوب)
claude.aiمصادقة حساب claude.ai
claude.comالصفحة التي يفتحها المتصفح عند تسجيل الدخول بحساب claude.ai (تُحوِّل إلى claude.ai)
platform.claude.comمصادقة حساب Console؛ وتستخدمه حسابات claude.ai أيضاً لإصدار الرموز المميزة وتجديدها (ويشمله فحص الاتصال عند الإعداد الأولي)
downloads.claude.aiالمثبّت، التحديث التلقائي، الإضافات
raw.githubusercontent.comسجل التغييرات لـ /release-notes

مضيفا القياس التشغيلي عن بُعد والإبلاغ عن الأخطاء (http-intake.logs.us5.datadoghq.com وbrowser-intake-us5-datadoghq.com) اختياريان، ويوقفهما معاً CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC (لا حاجة لإدراجهما في قائمة السماح المطلوبة). وإذا ثبّتَّ عبر npm، فلن تحتاج إلى استخدامَي المثبّت والتحديث التلقائي من downloads.claude.ai، لكنك ستحتاج إلى سجل الحزم registry.npmjs.org. النطاقات ونطاقات IP الدقيقة قد تُراجَع، لذا تحقّق من الأحدث في صفحة إعدادات الشبكة الرسمية.

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

حين يتعذّر الاتصال، اعمل من الأعلى إلى الأسفل. أول 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. لا تعطّل التحقق أبداً.

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

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

العَرَضما هو في الحقيقةالإصلاح الرئيسي
Unable to connect / Connection refused / Can't reach the API server / fetch failed / خطأ شهادةهذا المقال = شبكي (لم يصل إلى الخادم قط)HTTPS_PROXY / NODE_EXTRA_CA_CERTS / السماح في الجدار الناري
401 / 403 / Invalid API keyمصادقة (وصل، لكن مشكلة في بيانات الاعتماد)أخطاء المصادقة / تسجيل الدخول
529 / 500من جانب الخادم (وصل، لكنه محمّل بشكل زائد / خطأ داخلي)أخطاء 529/500
429 Request rejectedحدّ معدل (وصل، لكن حركة المرور كثيرة جداً)خفّض الوتيرة، وانتظر
Connection lost mid-response (قبل الإصدار v2.1.227: Connection closed mid-response)انقطاع أثناء البث (وصل وبدأ الرد بالتدفّق ثم أُغلق الاتصال)انقطاع الرد في منتصفه (مقال الصياغة القديمة)

طريقة للتذكّر: الأخطاء الشبكية تعني «أنه لم يصل إلى الخادم قط» (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، والجدار الناري. ومنذ الإصدار v2.1.227 تُصاغ بحيث تذكر نوع الفشل أولاً، مثل Connection refused — أو Can't reach the API server —، ويخرج الإعداد الأولي برسالة Unable to connect to Anthropic services.

الإصلاحات: (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.

الإعداد والتكلفة والملاحظات الخاصة بتوجيه ANTHROPIC_BASE_URL إلى نقطة الاتصال الخاصة بنماذج غير Claude (مثل DeepSeek وGLM وKimi) موضحة في مقال استخدام DeepSeek وGLM وKimi مع 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. هل «Can't reach the API server» و«Connection refused» أخطاء مختلفة عن «Unable to connect to API» القديمة؟
A. إنها من المجموعة نفسها؛ لم يتغير في الإصدار v2.1.227 سوى الصياغة. كانت الرسالة تكتفي بإلحاق رمز، مثل Unable to connect to API (ECONNREFUSED)؛ أما الآن فتذكر نوع الفشل أولاً، مثل Connection refused — a firewall or proxy may be blocking it (ConnectionRefused) أو Can't reach the API server — check your internet or DNS (ENOTFOUND). والرمز بين القوسين يلمّح إلى السبب، فراجع في جدول §2 ما يجب التحقق منه.

Q. عند التشغيل الأول تظهر «Unable to connect to Anthropic services» ثم يخرج البرنامج.
A. فشل البرنامج في الخطوة التي تتحقق، قبل تسجيل الدخول، من الاتصال بـ api.anthropic.com وplatform.claude.com. وإذا ذكرت الرسالة متغير بروكسي (مثل HTTPS_PROXY)، فتأكد من قيمته مع فريق الشبكة وتحقّق من أن الاتصالات بالمضيف المذكور في الرسالة مسموح بها. ويمكنك أيضاً فحص الوصول بالأمر curl -I https://api.anthropic.com. وإذا كانت شبكتك مفتوحة واستمر الخطأ، يشير المرجع الرسمي إلى أن Claude Code قد لا يكون متاحاً في بلدك أو منطقتك، ويمكنك التحقق من ذلك في القائمة الرسمية للبلدان المدعومة.

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 وclaude.com وplatform.claude.com (المصادقة)، وdownloads.claude.ai (المثبّت/التحديثات)، وraw.githubusercontent.com (سجل التغييرات). أما القياس التشغيلي عن بُعد والإبلاغ عن الأخطاء (Datadog) فاختياريان. النطاقات/عناوين IP الدقيقة قد تُراجَع، لذا تحقّق من الأحدث في صفحة إعدادات الشبكة الرسمية.

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