إذا كنت ترى خطأ مثل FAILED_PRECONDITION: User location is not supported عند محاولة تسجيل الدخول إلى Gemini CLI أو استخدام ملحق Gemini Code Assist في VS Code، فالمشكلة ليست في حسابك أو في الكود. يتم طرح Google AI Studio و Gemini API في البلدان بشكل غير متساوٍ، وبعض المناطق مستبعدة ببساطة من قائمة المناطق المدعومة. يتم حل ذلك عن طريق إعداد بروكسي بعنوان IP من دولة مسموح بها - وسنستعرض كيفية القيام بذلك بشكل صحيح في الطرفية، في VS Code وعلى مستوى متغيرات البيئة.
ما هو Gemini CLI و Gemini Code Assist
Gemini CLI هو أداة سطر أوامر من Google تتيح لك التفاعل مع نماذج Gemini مباشرة من الطرفية: كتابة الكود، توليد الأوامر، تحليل ملفات المشروع، وتنفيذ المهام بدون الخروج من بيئة العمل. يتصل بواجهة برمجة التطبيقات على النطاقات generativelanguage.googleapis.com أو عبر Vertex AI، اعتمادًا على طريقة المصادقة التي تستخدمها - مفتاح Google AI Studio أو حساب Google Cloud.
Gemini Code Assist هو ملحق لـ VS Code (وكذلك لـ JetBrains IDE) يدمج الاقتراحات، الإكمال التلقائي، والدردشة مع النموذج مباشرة في محرر الكود. في الأساس، هو نفس واجهة برمجة التطبيقات، ولكن يتم استدعاؤه من IDE عبر الملحق، وليس من سطر الأوامر. كلا الأداتين تستخدمان نفس البنية التحتية، لذا فإن مشكلة حظر المناطق تظهر بنفس الطريقة في كلا الحالتين - الملحق ببساطة لا يمكنه إنشاء جلسة أو يرجع خطأ عند أول طلب للنموذج.
نقطة مهمة: كلا الأداتين تقومان بإجراء طلبات الشبكة ليس فقط إلى واجهة برمجة التطبيقات الخاصة بالتوليد، ولكن أيضًا إلى خدمات مصادقة Google (OAuth، Identity Toolkit). إذا تم إعداد البروكسي فقط لنقطة نهاية واحدة، قد تتم المصادقة، ولكن التوليد لا يحدث، أو العكس. لذلك يجب إعداد البروكسي على مستوى متغيرات البيئة النظامية، وليس بشكل موضعي في مكان واحد.
لماذا Gemini غير متاح في منطقتك
تقليديًا، تقوم Google بطرح منتجات الذكاء الاصطناعي الجديدة على مراحل: أولاً الولايات المتحدة وجزء من أوروبا، ثم بقية الدول. بالنسبة لـ Gemini، يتم التعبير عن ذلك في قيود جغرافية على مستوى واجهة برمجة التطبيقات - يتحقق الخادم من عنوان IP للطلب الوارد (وأحيانًا عنوان الفوترة لحساب Google) ويقارنها بقائمة المواقع المسموح بها. إذا لم تكن الدولة في القائمة، يتم قطع الطلب بخطأ precondition أو يتجاوز الوقت بدون تفسير واضح.
هذه ليست حظرًا بالمعنى التقليدي للكلمة - مزود الخدمة في بلدك لا يقوم بقطع أي شيء، بل يتعلق الأمر بفلتر جغرافي على جانب Google. وبالتالي، فإن VPN مع IP مشترك غالبًا لا ينقذ: هذه العناوين تُستخدم بشكل جماعي من قبل الآلاف من الأشخاص، وتقوم Google بتصنيفها على أنها مشبوهة، إما تتطلب CAPTCHA، أو تقطع الاتصال وفقًا للموقع الجغرافي، إذا كان نطاق IP مسجلاً بشكل رسمي في دولة غير صحيحة. تحتاج إلى عنوان يبدو كعنوان IP منزلي أو موبايل عادي من منطقة مدعومة - أي أن المهمة هي نفسها التي تحلها البروكسي السكنية والمحمولة.
أي بروكسي تختار للعمل مع Gemini API
بالنسبة لأدوات التطوير مثل Gemini CLI، فإن المعايير الأساسية للبروكسي هي استقرار الجلسة (حتى لا ينقطع الاتصال أثناء توليد استجابة طويلة)، السرعة ومدى "نظافة" IP بالنسبة لأنظمة مكافحة الاحتيال من Google. إليك مقارنة بين ثلاثة أنواع:
| نوع البروكسي | السرعة | خطر الحظر الجغرافي | متى تستخدمه |
|---|---|---|---|
| بروكسي مراكز البيانات | عالية | متوسطة-عالية | اختبارات سريعة، طلبات لمرة واحدة إلى واجهة برمجة التطبيقات |
| بروكسي سكنية | متوسطة-عالية | منخفضة | العمل اليومي مع Gemini CLI و Code Assist |
| بروكسي موبايل | متوسطة | أدنى | عندما يتم حظر IP السكني بواسطة الفلتر الجغرافي |
في الممارسة العملية، من الأسهل استخدام بروكسي سكنية مرتبطة بدولة معينة ويفضل أن تكون مع جلسة ثابتة لمدة 10-30 دقيقة - هذا يكفي حتى لا تنقطع المصادقة OAuth ولا تسقط جلسة الطرفية أثناء توليد الكود. بروكسي مراكز البيانات أرخص وأسرع، لكن بعض النطاقات تعرفها Google بالفعل وأحيانًا تطلب تحقق إضافي من الحساب عند الدخول عبر هذا IP. من الجيد الاحتفاظ ببروكسي موبايل كاحتياطي - إذا كان العنوان السكني قد تم وضعه في قائمة مشبوهة، فإن شبكة الموبايل لمزود الخدمة عادة ما تمر بالتحقق الجغرافي بدون مشاكل.
إعداد البروكسي في الطرفية: Linux، macOS، Windows
Gemini CLI، مثل معظم أدوات سطر الأوامر على Node.js (وهو مكتوب عليه)، يحترم متغيرات البيئة القياسية HTTP_PROXY و HTTPS_PROXY. هذا يكفي لتوجيه كل حركة مرور CLI عبر البروكسي بدون تعديل إعدادات التطبيق.
لـ macOS و Linux (bash/zsh)، أضف إلى الجلسة الحالية:
export HTTP_PROXY="http://login:password@proxy_host:port"
export HTTPS_PROXY="http://login:password@proxy_host:port"
export NO_PROXY="localhost,127.0.0.1"
gemini --version
لجعل البروكسي دائمًا، وليس فقط في الجلسة الحالية للطرفية، أضف هذه الأسطر إلى ~/.zshrc أو ~/.bashrc وأعد تشغيل الطرفية باستخدام الأمر source ~/.zshrc.
لـ Windows في PowerShell، يتم تعيين المتغيرات كما يلي:
$env:HTTP_PROXY = "http://login:password@proxy_host:port"
$env:HTTPS_PROXY = "http://login:password@proxy_host:port"
gemini --version
إذا كنت ترغب في أن تبقى المتغيرات بعد إعادة تشغيل PowerShell، استخدم [System.Environment]::SetEnvironmentVariable("HTTPS_PROXY", "http://login:password@proxy_host:port", "User") - سيتم تسجيل المتغير في ملف تعريف المستخدم في Windows.
إذا كان البروكسي الخاص بك يتطلب مصادقة منفصلة بدون تسجيل الدخول في URL (على سبيل المثال، عبر قائمة IP البيضاء)، فقط قم بإزالة اسم المستخدم وكلمة المرور من سلسلة الاتصال وأضف IP الخادم أو جهاز العمل الخاص بك إلى القائمة البيضاء على جانب لوحة مزود البروكسي.
إعداد البروكسي في VS Code لـ Code Assist
يحتوي VS Code على إعدادات بروكسي خاصة به، والتي لا تُورث تلقائيًا من متغيرات البيئة في النظام، إذا لم يتم تمكين الخيار المناسب. افتح settings.json (Ctrl+Shift+P → "Preferences: Open User Settings (JSON)") وأضف:
{
"http.proxy": "http://login:password@proxy_host:port",
"http.proxyStrictSSL": false,
"http.proxySupport": "override"
}
المعلمة http.proxySupport: "override" مهمة: بدونها، قد يستمر VS Code في استخدام البروكسي النظامي أو يتجاهل الإعدادات تمامًا للملحقات الفردية. بعد تعديل الإعدادات، أعد تشغيل VS Code بالكامل (ليس فقط إعادة تحميل النافذة)، لأن ملحق Gemini Code Assist يقوم بتهيئة عميل الشبكة مرة واحدة عند بدء التطبيق.
إذا كان الملحق لا يزال لا يرى البروكسي، تحقق من إعداد http.proxyAuthorization - في حالات نادرة، تقوم إصدارات VS Code المؤسسية بحظر تمرير اسم المستخدم وكلمة المرور في URL البروكسي لأسباب أمنية، وفي هذه الحالة يجب تمرير الاعتمادات عبر رأس Proxy-Authorization في base64.
نقطة منفصلة - قم بإيقاف تشغيل أدوات التشخيص مثل عملاء VPN المؤسسيين ومضادات الفيروسات التي تعترض حركة المرور (فحص SSL) لفترة. غالبًا ما يقومون بتغيير الشهادة في الوقت الحقيقي، و Gemini Code Assist، الذي يتحقق بدقة من سلسلة شهادات Google، سيقطع الاتصال بخطأ TLS، والذي يمكن الخلط بينه وبين مشكلة البروكسي نفسه.
إعداد البروكسي في Gemini CLI نفسه
بالإضافة إلى متغيرات البيئة، يمكنك تعيين البروكسي في Gemini CLI من خلال ملف تكوين المشروع أو إعدادات المستخدم العالمية - وهذا مفيد إذا كنت ترغب في استخدام بروكسيات مختلفة لمشاريع مختلفة دون تعديل المتغيرات النظامية. عادةً ما يتم تخزين التكوين في ~/.gemini/settings.json أو في ملف .env داخل دليل المشروع:
# .env في جذر المشروع
GEMINI_API_KEY=مفتاحك
HTTPS_PROXY=http://login:password@proxy_host:port
HTTP_PROXY=http://login:password@proxy_host:port
إذا كنت تقوم بتسجيل الدخول عبر حساب Google Cloud (Vertex AI)، وليس عبر مفتاح AI Studio، فستحتاج أيضًا إلى استخدام البروكسي مع الأداة gcloud، التي تمر عبر تدفق OAuth. يتم تعيين البروكسي لها بشكل منفصل:
gcloud config set proxy/type http
gcloud config set proxy/address proxy_host
gcloud config set proxy/port port
gcloud config set proxy/username login
gcloud config set proxy/password password
إذا بعد ذلك gcloud auth login لا يزال يفتح المتصفح بعنوان IP حقيقي (غير بروكسي) لتأكيد الدخول، تذكر: صفحة OAuth نفسها تفتح في متصفح النظام الخاص بك مباشرة، وإذا لم يكن المتصفح مضبوطًا على نفس البروكسي، فقد تحصل الجلسة النهائية للمصادقة على رمز مرتبط بعنوان IP الحقيقي الخاص بك. لتحقيق التوافق الكامل، من الأفضل إعداد البروكسي في المتصفح الذي تؤكد فيه الدخول - على سبيل المثال، عبر ملحق بروكسي أو إعدادات الشبكة النظامية أثناء المصادقة.
اختبار الاتصال: curl و Python
قبل أن تبحث في سبب عدم عمل Gemini CLI، تأكد من أن البروكسي يمرر حركة المرور إلى واجهة برمجة التطبيقات من Google. أسرع طريقة هي إجراء طلب مباشر عبر curl:
curl -x http://login:password@proxy_host:port \
"https://generativelanguage.googleapis.com/v1beta/models?key=مفتاح_API_الخاص_بك"
إذا جاء الرد بتنسيق JSON مع قائمة النماذج (gemini-1.5-flash، gemini-1.5-pro وما إلى ذلك) - فإن البروكسي يعمل والمنطقة مدعومة. إذا رأيت 403 أو FAILED_PRECONDITION - فالمشكلة على مستوى الفلتر الجغرافي، تحتاج إلى تغيير دولة البروكسي.
للتشخيص الأكثر تفصيلًا، من السهل استخدام Python مع تحديد البروكسي لجلسة:
import requests
proxies = {
"http": "http://login:password@proxy_host:port",
"https": "http://login:password@proxy_host:port",
}
url = "https://generativelanguage.googleapis.com/v1beta/models"
params = {"key": "مفتاح_API_الخاص_بك"}
response = requests.get(url, params=params, proxies=proxies, timeout=15)
print(response.status_code)
print(response.text[:500])
من السهل الاحتفاظ بهذا السكربت كاختبار سريع قبل بدء جلسة كاملة في CLI أو IDE - فهو يظهر في ثوانٍ ما إذا كانت الشبكة أو المفتاح أو المنطقة IP هي المسؤولة.
الأخطاء الشائعة وحلولها
خطأ "User location is not supported" حتى بعد الاتصال بالبروكسي يعني عادةً أن IP خادم البروكسي إما في دولة غير مدعومة، أو أن Google حددته كبروكسي مراكز بيانات وطبق تحقق إضافي. الحل هو التبديل إلى IP سكني أو موبايل من الولايات المتحدة أو دولة أخرى مدعومة بالكامل لـ Gemini.
تجاوزات عند توليد استجابات طويلة غالبًا ما ترتبط بجلسة البروكسي غير المستقرة - يتغير IP في منتصف الطلب، وينقطع الاتصال. تحتاج إلى جلسة ثابتة لفترة تتجاوز الطلب النموذجي (عادةً 10-15 دقيقة مع احتياطي يكفي حتى للتوليدات الكبيرة للكود).
خطأ SSL/TLS handshake failedproxyStrictSSL في VS Code بشكل غير صحيح. تحقق مما إذا كان هناك برنامج على الجهاز يقوم بفحص SSL، وقم بإيقاف تشغيله مؤقتًا للتشخيص.
يعمل CLI، لكن الملحق في VS Code لا يعمل (أو العكس)settings.json، كما هو موضح أعلاه، وليس الاعتماد على الوراثة من shell.
ربط IP بمنطقة مفتاح API والأمان
هناك نقطة دقيقة غالبًا ما تُنسى: إذا تم إنشاء مفتاح API أو مشروع Google Cloud مع ربطه بمنطقة فوترة معينة، فإن تغيير IP البروكسي قد يؤدي إلى عدم تطابق الموقع المتوقع والفعلي، وأحيانًا تتطلب Google إعادة التحقق عبر SMS أو البريد الإلكتروني. لتقليل تكرار هذه التحقق، حاول استخدام بروكسي مع IP ثابت (غير متغير مع كل طلب) من نفس الدولة - هذا يبدو لأنظمة حماية Google كتصرف عادي لمستخدم يعيش ببساطة في تلك الدولة، وليس كنشاط مشبوه.
إذا كنت تعمل على عدة مشاريع أو مفاتيح في نفس الوقت وتستخدم متصفحًا مضادًا للكشف مثل Dolphin Anty أو AdsPower لعزل الملفات الشخصية (وهذا مهم إذا كنت تختبر تكاملات Gemini في بيئات متصفح مختلفة)، اربط كل ملف شخصي ببروكسي منفصل مع موقع جغرافي ثابت - هذا يقلل من خطر أن "يسحب" مشروع واحد الشكوك بسبب IP مختلط من الآخر.
كما أنه لا ينبغي استخدام نفس البروكسي المجاني أو المشترك لـ Gemini وفي نفس الوقت لمهام أخرى ذات تحميل عالي - فإن العدد الكبير من الجلسات المتزامنة من نفس IP يزيد من فرصة الوقوع تحت حد المعدل أو الحظر المؤقت على مستوى Google، مما يبدو كأنه مشكلة في المنطقة، على الرغم من أن السبب مختلف تمامًا.
الخاتمة
يتم حل قيود Gemini CLI و Gemini Code Assist حسب المنطقة على مستوى الشبكة: يجب تعيين البروكسي في متغيرات البيئة النظامية، في إعدادات VS Code، وعند استخدام Google Cloud، في تكوين gcloud - فقط عندها ستعمل جميع نقاط الدخول الثلاث (CLI، ملحق IDE، ومصادقة OAuth) عبر نفس IP بدون عدم تزامن. قبل العمل الكامل، تحقق دائمًا من الاتصال بطلب curl بسيط - هذا يوفر ساعات من التشخيص عندما تكون المشكلة في الواقع ليست في الكود، بل في دولة البروكسي.
للعمل اليومي المستقر مع Gemini CLI، فإن أفضل خيار هو بروكسي سكنية مرتبطة بموقع جغرافي ثابت وجلسة ثابتة طويلة - فهي تبدو كعنوان IP منزلي عادي ونادرًا ما تتطلب تحقق إضافي من Google. إذا كان العنوان السكني لا يزال يقع تحت الفلتر الجغرافي، فحاول استخدام بروكسي موبايل، وللإختبارات السريعة لمرة واحدة على واجهة برمجة التطبيقات بدون جلسة طويلة، يكفي تمامًا استخدام بروكسي مراكز البيانات.