كيفية إعداد HTTPS_PROXY لـ Cursor و Claude Code في الشبكة المؤسسية

إذا كانت شركتك تغلق حركة المرور الصادرة عبر بروكسي مؤسسي، فإن مساعدي الذكاء الاصطناعي مثل Cursor و Claude Code يتوقفون ببساطة عن الاستجابة: يتجمد الإكمال التلقائي، ويظهر CLI ETIMEDOUT أو SSL certificate problem. دعونا نناقش كيفية كتابة متغيرات البيئة HTTPS_PROXY بشكل صحيح، وضبط المصادقة وتجنب الأخطاء الشائعة التي تجعل المطورين يقضون ساعات في تصحيح إعدادات الشبكة بدلاً من الكود.

لماذا يحتاج مساعدو الذكاء الاصطناعي إلى بروكسي في الشبكة المؤسسية

Cursor و Claude Code ليست نماذج محلية. إنهما يتواصلان باستمرار مع واجهات برمجة التطبيقات الخارجية: يقوم Cursor بالاتصال بخوادم فهرسة الكود الخاصة به وواجهات برمجة التطبيقات للنماذج (OpenAI، Anthropic، Google حسب مزود الخدمة المختار)، بينما يتصل Claude Code مباشرة بواجهة برمجة التطبيقات الخاصة بـ Anthropic عبر HTTPS. في الشبكة المؤسسية، يتم عادةً إغلاق الوصول المباشر إلى الإنترنت بواسطة جدار ناري، ويجب أن تمر جميع حركة المرور الصادرة عبر خادم بروكسي (Squid، Zscaler، Blue Coat، Fortinet FortiProxy أو بوابة داخلية مؤسسية). بدون إعداد متغيرات البيئة بشكل صحيح، لا يعرف التطبيق ببساطة أن حركة المرور يجب أن تمر عبر البروكسي، ويحاول الوصول إلى الإنترنت مباشرةً - مما يؤدي إلى حدوث مهلات.

تكمن الصعوبة الإضافية في أن Cursor مبني على Electron (وهو في الأساس Chromium + Node.js)، بينما Claude Code هو تطبيق CLI يعتمد على Node.js. لكل منهما منطق خاص به لقراءة إعدادات البروكسي: يرث Electron جزئيًا إعدادات النظام، بينما تقرأ عمليات Node.js متغيرات البيئة HTTP_PROXY/HTTPS_PROXY مباشرة أو عبر مكتبات مثل undici و node-fetch. وهذا يسبب الارتباك: تم إعداد الإعدادات، لكن الأداة "لا تراها".

متغيرات HTTP_PROXY و HTTPS_PROXY و NO_PROXY: كيف تعمل

الطريقة التقليدية لتحديد البروكسي لتطبيقات Node.js و Python و Go في وحدة التحكم هي عبر متغيرات البيئة. الفرق بين HTTP_PROXY و HTTPS_PROXY جوهري: الأولى تُستخدم لطلبات بروتوكول HTTP، والثانية - لطلبات HTTPS (حيث أن معظم حركة مرور مساعدي الذكاء الاصطناعي تتم عبر HTTPS). يجب تحديد كلاهما، حتى لو كانت حركة المرور الفعلية هي HTTPS فقط - بعض المكتبات تقوم بعمل طلبات HTTP خدمية عند البدء.

export HTTP_PROXY="http://proxy.company.local:8080"
export HTTPS_PROXY="http://proxy.company.local:8080"
export NO_PROXY="localhost,127.0.0.1,.company.local"

لاحظ أنه حتى لحركة مرور HTTPS، يتم تحديد المخطط في عنوان البروكسي كـ http://, وليس https:// - هذا هو عنوان خادم البروكسي نفسه، وليس المورد المستهدف. الاتصال بالبروكسي عبر HTTP هو أمر طبيعي، حيث يعمل التشفير حتى الخادم النهائي عبر آلية نفق CONNECT.

متغير NO_PROXY ضروري، لاستبعاد العناوين الداخلية للشركة من البروكسي - وإلا ستذهب الطلبات إلى مستودعات git الداخلية، Jira أو خدمات التطوير المحلية أيضًا عبر البروكسي الخارجي، مما قد يؤدي إلى عدم العثور عليها أو تباطؤها. نقطة مهمة: بعض المكتبات حساسة لحالة الأحرف في المتغيرات. للتأكد، قم بتحديد كلا الخيارين - بالأحرف الكبيرة والصغيرة:

export http_proxy="$HTTP_PROXY"
export https_proxy="$HTTPS_PROXY"
export no_proxy="$NO_PROXY"

إعداد البروكسي لـ Cursor

يستخدم Cursor جزئيًا إعدادات البروكسي النظامية (خصوصًا على macOS و Windows)، لكن من الأفضل لضمان عمله بشكل مستقر في الشبكة المؤسسية إعدادها بوضوح عبر متغيرات البيئة، وعند الحاجة، عبر ملف إعدادات التطبيق.

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

# ~/.zshrc أو ~/.bash_profile
export HTTP_PROXY="http://user:[email protected]:8080"
export HTTPS_PROXY="http://user:[email protected]:8080"
export NO_PROXY="localhost,127.0.0.1,*.company.local"

بعد تعديل ملف التعريف، نفذ source ~/.zshrc وأعد تشغيل Cursor بالكامل (لا تقم فقط بتقليص النافذة - أنهي العملية عبر Activity Monitor أو مدير المهام، حيث أن تطبيقات Electron تخزن البيئة عند البدء).

على Windows، من الأسهل تعيين المتغيرات عبر إعدادات البيئة النظامية (لوحة التحكم → النظام → إعدادات النظام المتقدمة → المتغيرات البيئية) أو عبر PowerShell للحفظ الدائم:

[System.Environment]::SetEnvironmentVariable('HTTPS_PROXY','http://user:[email protected]:8080','User')
[System.Environment]::SetEnvironmentVariable('HTTP_PROXY','http://user:[email protected]:8080','User')
[System.Environment]::SetEnvironmentVariable('NO_PROXY','localhost,127.0.0.1','User')

إذا كان Cursor لا يزال لا يتصل بواجهة برمجة التطبيقات للنماذج بعد ذلك، تحقق من إعدادات البروكسي داخل التطبيق نفسه: الإعدادات → الشبكة (أو عام) - قد يكون هناك حقل منفصل لعنوان البروكسي، والذي يتجاوز المتغيرات النظامية. في بعض إصدارات Cursor، قد تحتاج أيضًا إلى تفعيل خيار "استخدام إعدادات البروكسي النظامية" بشكل صريح.

إعداد البروكسي لـ Claude Code

Claude Code هو أداة CLI تعتمد على Node.js، يتم تشغيلها عبر npm/npx، لذلك يقرأ المتغيرات البيئية مباشرة من جلسة الترمينال التي تم استدعاؤها منها. هذا يبسط الإعداد: يكفي تصدير المتغيرات قبل التشغيل.

export HTTPS_PROXY="http://user:[email protected]:8080"
export HTTP_PROXY="http://user:[email protected]:8080"
claude

إذا كنت تقوم بتشغيل Claude Code كجزء من خط أنابيب CI أو من سكربت، قم بتمرير المتغيرات بشكل صريح إلى أمر التشغيل، لتجنب الاعتماد على البيئة العامة للصدفة:

HTTPS_PROXY="http://proxy.company.local:8080" \
HTTP_PROXY="http://proxy.company.local:8080" \
claude --print "تحقق من الاختبارات في المشروع"

لتكوين دائم، من الأفضل تثبيت المتغيرات في ملف .env في جذر المشروع والتقاطه عبر direnv أو الدعم المدمج لـ dotenv، إذا كانت صدفتك تدعمه. هذا مفيد بشكل خاص عندما تتطلب المشاريع المختلفة إعدادات بروكسي مختلفة (على سبيل المثال، يعمل مشروع واحد مع واجهة برمجة التطبيقات الداخلية، بينما يعمل الآخر مع خدمات خارجية).

المصادقة على البروكسي المؤسسي

تتطلب معظم البروكسي المؤسسية المصادقة - Basic Auth، Digest أو NTLM. بالنسبة لـ Basic Auth، يمكن تضمين اسم المستخدم وكلمة المرور مباشرة في عنوان بروكسي، كما هو موضح أعلاه: http://user:[email protected]:8080. نقطة مهمة - إذا كانت كلمة المرور تحتوي على رموز خاصة (@، #، %), يجب ترميزها في عنوان URL، وإلا سيتعطل محلل سلسلة البروكسي عند حدود اسم المستخدم والمضيف.

# إذا كانت كلمة المرور P@ssw0rd#2024، نقوم بترميز الرموز الخاصة:
# @ -> %40، # -> %23
export HTTPS_PROXY="http://user:P%40ssw0rd%[email protected]:8080"

الأمر أكثر تعقيدًا مع مصادقة NTLM (تستخدم غالبًا مع Microsoft ISA Server، Forefront TMG أو Fortinet) - لا تدعم Node.js ومعظم عملاء HTTP NTLM "من الصندوق". في هذه الحالة، الحل القياسي هو رفع بروكسي محلي يتولى مصافحة NTLM، ثم يقدم بروكسي HTTP "نظيف" للتطبيق. غالبًا ما يتم استخدام cntlm أو px (بروكسي NTLM محلي على Python). المخطط بسيط: Cursor/Claude Code → localhost:3128 (cntlm) → بروكسي NTLM المؤسسي → الإنترنت.

# مثال على تكوين cntlm (/etc/cntlm.conf)
Username    your_login
Domain      COMPANY
Password    your_password_or_hash
Proxy       proxy.company.local:8080
Listen      3128

# بعد تشغيل cntlm، نحدد العنوان المحلي:
export HTTPS_PROXY="http://127.0.0.1:3128"
export HTTP_PROXY="http://127.0.0.1:3128"

الشهادات و MITM: مشكلة SSL في الشبكة المؤسسية

إذا كان هناك منتج من فئة Zscaler أو Netskope أو أي فلتر ويب آخر مع فحص SSL في الشركة، يتم فك تشفير حركة المرور على البروكسي وتوقيعها بشهادة CA الجذرية المؤسسية. تثق Node.js (وبالتالي Claude Code، ومعظم وحدات Cursor الداخلية) افتراضيًا فقط بمجموعة الشهادات الجذرية المدمجة الخاصة بها وستظهر خطأ UNABLE_TO_VERIFY_LEAF_SIGNATURE أو self signed certificate in certificate chain.

الحل هو تصدير شهادة CA المؤسسية (يمكن عادةً الحصول عليها من قسم تكنولوجيا المعلومات أو استخراجها من مستودع الشهادات في المتصفح) وتحديد مسارها لـ Node.js عبر متغير NODE_EXTRA_CA_CERTS:

export NODE_EXTRA_CA_CERTS="/etc/ssl/certs/company-root-ca.pem"

من غير المستحسن على الإطلاق تعطيل التحقق من الشهادات عالميًا عبر NODE_TLS_REJECT_UNAUTHORIZED=0 - فهذا يزيل الحماية من هجمات MITM عن العملية بأكملها، بما في ذلك الاتصالات الشرعية. استخدم هذا العلم فقط للتشخيص لمرة واحدة وارجع الحماية مرة أخرى.

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

الخطأ	السبب	الحل
ETIMEDOUT / ECONNREFUSED	لم يتم تصدير متغيرات البروكسي في الجلسة التي تم تشغيل التطبيق فيها	تحقق من echo $HTTPS_PROXY في نفس الترمينال، وأعد تشغيل التطبيق بالكامل
407 Proxy Authentication Required	اسم المستخدم/كلمة المرور غير محددين أو قديمة	تحديث بيانات الاعتماد في عنوان البروكسي، وترميز الرموز الخاصة في كلمة المرور
self signed certificate in certificate chain	يقوم بروكسي MITM المؤسسي بتغيير الشهادة	تحديد NODE_EXTRA_CA_CERTS مع CA الجذرية المؤسسية
يعمل البروكسي في الترمينال، لكن لا يعمل في Cursor	تم تشغيل Cursor من ترمينال غير صحيح أو عبر اختصار بدون البيئة	قم بتشغيل Cursor باستخدام الأمر من الترمينال مع المتغيرات المصدرة، أو قم بتحديد المتغيرات على مستوى النظام
NTLM authentication failed	العميل لا يدعم مصافحة NTLM	قم برفع بروكسي وسيط cntlm أو px بين التطبيق والبروكسي المؤسسي

التحقق من الاتصال عبر curl

قبل البحث عن سبب عدم عمل Cursor أو Claude Code، تأكد من أن البروكسي نفسه متاح ويقوم بتمرير حركة مرور HTTPS بشكل صحيح. استخدم curl لهذا الغرض - فهو يقرأ نفس متغيرات البيئة و يسمح بتحديد المشكلة بسرعة دون تشغيل تطبيقات ثقيلة.

# التحقق من توفر البروكسي والمصادقة
curl -v -x "http://user:[email protected]:8080" https://api.anthropic.com

# التحقق مع الأخذ في الاعتبار الشهادة المؤسسية
curl -v --cacert /etc/ssl/certs/company-root-ca.pem \
  -x "http://user:[email protected]:8080" \
  https://api.anthropic.com

إذا حصل curl على استجابة ناجحة (حتى 401 أو 403 - هذا طبيعي، مما يعني أن مصافحة TLS قد تمت)، بينما لا يزال Claude Code لا يتصل - فإن المشكلة ليست في الشبكة، بل في أن العملية لا ترى متغيرات البيئة. إذا كان curl أيضًا يفشل بخطأ في الشهادة أو مهلة - فإن المشكلة على مستوى الشبكة أو البروكسي، والأدوات هنا ليست لها علاقة.

متى تحتاج إلى بروكسي خارجي بدلاً من المؤسسي

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

لجلسات اختبار مستقرة وطويلة الأمد مع الحد الأدنى من خطر الحظر حسب IP، فإن البروكسي السكنية هي الأنسب - حيث تستخدم عناوين IP حقيقية من مزودي الخدمة المنزلية وتبدو كحركة مرور مستخدم عادية، وهو أمر مهم عند التحقق من استجابات واجهة برمجة التطبيقات المعتمدة على الموقع. إذا كنت بحاجة إلى إعادة إنتاج سلوك عميل الهاتف المحمول أو اختبار سيناريوهات حساسة لنوع الشبكة، يجب النظر في البروكسي المحمولة. وللاختبار المتوازي الضخم للطلبات إلى واجهات برمجة التطبيقات العامة، حيث تكون السرعة وتكلفة حركة المرور أكثر أهمية من التمويه كمستخدم عادي، عادة ما تكون بروكسي مراكز البيانات كافية.

من المهم: يتم إعداد هذا البروكسي الخارجي بنفس الطريقة عبر متغيرات HTTPS_PROXY/HTTP_PROXY, ولكن لبيئة اختبارية أو ملف تعريف ترمينال منفصل، لتجنب خلطه مع حركة المرور العملية الرئيسية عبر البوابة المؤسسية. إذا كانت سياسة الشركة تتطلب أن تمر جميع حركة المرور عبر البروكسي الداخلي فقط، يجب أن يكون استخدام الخارجي متفقًا عليه مع قسم تكنولوجيا المعلومات/الأمان - حيث أن العديد من الشركات تحظر صراحة تجاوز البوابة المؤسسية بدون إذن.

قائمة التحقق للإعدادات

الخاتمة

معظم المشاكل مع Cursor و Claude Code خلف البروكسي المؤسسي تتلخص في ثلاث نقاط: متغيرات البيئة لا تصل إلى العملية، أو تم إعداد المصادقة بشكل غير صحيح، أو لم تتم إضافة شهادة MITM المؤسسية إلى الموثوق بها. من خلال التحقق من هذه النقاط الثلاث بالترتيب - عبر curl, وليس مباشرة عبر التطبيق نفسه - يمكنك توفير ساعات من التصحيح وتحديد السبب بسرعة.

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