اگر هنگام تلاش برای ورود به Gemini CLI یا استفاده از افزونه Gemini Code Assist در VS Code خطایی مانند FAILED_PRECONDITION: User location is not supported مشاهده میکنید، مشکل از حساب کاربری شما یا کد نیست. Google AI Studio و Gemini API به طور نامتوازن در کشورهای مختلف توزیع میشوند و برخی مناطق به سادگی از لیست پشتیبانی حذف شدهاند. این مشکل با تنظیم پروکسی با آدرس IP از یک کشور مجاز حل میشود — و در ادامه بررسی خواهیم کرد که چگونه این کار را به درستی در ترمینال، در VS Code و در سطح متغیرهای محیطی انجام دهیم.
Gemini CLI و Gemini Code Assist چیستند
Gemini CLI یک ابزار کنسولی گوگل است که به شما اجازه میدهد با مدلهای Gemini به طور مستقیم از ترمینال ارتباط برقرار کنید: کد بنویسید، دستورات تولید کنید، فایلهای پروژه را تحلیل کنید و وظایف نمایندگی را بدون خروج از محیط کاری انجام دهید. این ابزار به API در دامنههای generativelanguage.googleapis.com یا از طریق Vertex AI متصل میشود، بسته به اینکه از کدام روش احراز هویت استفاده میکنید — کلید Google AI Studio یا حساب Google Cloud.
Gemini Code Assist یک افزونه برای VS Code (و همچنین برای JetBrains IDE) است که پیشنهادات، تکمیل خودکار و چت با مدل را به طور مستقیم در ویرایشگر کد قرار میدهد. در واقع، این همان API است، اما از IDE از طریق افزونه فراخوانی میشود، نه از خط فرمان. هر دو ابزار از یک backend مشابه استفاده میکنند، بنابراین مشکل مسدودسازی منطقهای به طور مشابه در هر دو مورد بروز میکند — افزونه به سادگی نمیتواند جلسهای را برقرار کند یا در اولین درخواست به مدل خطا برمیگرداند.
نکته مهم: هر دو ابزار درخواستهای شبکهای را نه تنها به خود API تولید، بلکه به خدمات احراز هویت Google (OAuth، Identity Toolkit) نیز ارسال میکنند. اگر پروکسی فقط برای یک endpoint تنظیم شده باشد، ممکن است احراز هویت انجام شود، اما تولید انجام نشود، یا برعکس. بنابراین پروکسی باید در سطح متغیرهای محیطی سیستم تنظیم شود، نه فقط در یک نقطه خاص.
چرا Gemini در منطقه شما در دسترس نیست
گوگل به طور سنتی محصولات جدید AI را به تدریج توزیع میکند: ابتدا در ایالات متحده و بخشی از اروپا، سپس در سایر کشورها. برای Gemini، این به شکل محدودیتهای جغرافیایی در سطح API بروز میکند — سرور آدرس IP درخواست ورودی را بررسی میکند (و گاهی اوقات آدرس صورتحساب حساب Google را نیز) و آن را با لیست مکانهای مجاز مقایسه میکند. اگر کشور در لیست نباشد، درخواست با خطای precondition قطع میشود یا به سادگی بدون توضیح واضح زمانبر میشود.
این یک مسدودسازی به معنای رایج کلمه نیست — ارائهدهنده کشور شما هیچ چیزی را قطع نمیکند، بلکه در واقع یک فیلتر جغرافیایی در سمت Google است. بنابراین، VPN با IP عمومی معمولاً نجاتدهنده نیست: چنین آدرسهایی به طور گسترده توسط هزاران نفر استفاده میشوند، گوگل آنها را به عنوان مشکوک علامتگذاری میکند و یا از شما CAPTCHA میخواهد، یا به هر حال بر اساس جغرافیا آنها را قطع میکند، اگر دامنه IP به طور رسمی در آن کشور ثبت نشده باشد. به یک آدرس نیاز دارید که به عنوان یک IP خانگی یا موبایل عادی از منطقه پشتیبانی شده به نظر برسد — بنابراین وظیفه دقیقاً همان چیزی است که پروکسیهای مسکونی و موبایل حل میکنند.
کدام پروکسی را برای کار با Gemini API انتخاب کنیم
برای ابزارهای توسعهای مانند Gemini CLI، پارامترهای کلیدی پروکسی شامل ثبات جلسه (تا اتصال در وسط تولید پاسخ طولانی قطع نشود)، سرعت و اینکه IP چقدر «پاک» به نظر میرسد برای سیستمهای ضد تقلب Google است. در اینجا مقایسه سه نوع پروکسی آورده شده است:
| نوع پروکسی | سرعت | ریسک مسدودسازی جغرافیایی | چه زمانی استفاده کنیم |
|---|---|---|---|
| پروکسی دیتاسنتر | بالا | متوسط-بالا | آزمونهای سریع، درخواستهای یکباره به API |
| پروکسیهای مسکونی | متوسط-بالا | پایین | کار روزانه با Gemini CLI و Code Assist |
| پروکسیهای موبایل | متوسط | حداقل | زمانی که IP مسکونی به هر دلیلی مسدود شده است |
در عمل، برای کار روزانه توسعهدهنده، راحتترین گزینه پروکسیهای مسکونی با پیوند به یک کشور خاص و ترجیحاً با جلسه چسبنده 10-30 دقیقهای است — این مدت زمان کافی است تا احراز هویت OAuth قطع نشود و جلسه ترمینال در وسط تولید کد از بین نرود. پروکسیهای دیتاسنتر ارزانتر و سریعتر هستند، اما برخی از دامنهها گوگل قبلاً آنها را میشناسد و گاهی اوقات هنگام ورود از طریق چنین IP از شما تأییدیه اضافی میخواهد. پروکسیهای موبایل باید به عنوان پشتیبان نگهداری شوند — اگر آدرس مسکونی به هر دلیلی در لیست مشکوک قرار گیرد، شبکه موبایل اپراتور معمولاً بدون سوال از فیلتر جغرافیایی عبور میکند.
تنظیم پروکسی در ترمینال: لینوکس، macOS، ویندوز
Gemini CLI، مانند بیشتر ابزارهای کنسولی در Node.js (که به همین زبان نوشته شده است)، به متغیرهای محیطی استاندارد HTTP_PROXY و HTTPS_PROXY احترام میگذارد. این کافی است تا تمام ترافیک CLI را از طریق پروکسی بدون نیاز به ویرایش پیکربندیهای برنامه هدایت کنید.
برای macOS و لینوکس (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 دوباره راهاندازی کنید.
برای ویندوز در 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") استفاده کنید — این متغیر در پروفایل کاربری ویندوز ذخیره میشود.
اگر پروکسی شما نیاز به احراز هویت جداگانهای بدون ورود به URL (برای مثال، از طریق IP whitelist) دارد، فقط نام کاربری و رمز عبور را از رشته اتصال حذف کنید و IP سرور یا ماشین کاری خود را در whitelist در پنل ارائهدهنده پروکسی اضافه کنید.
تنظیم پروکسی در 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 کار نمیکند، اطمینان حاصل کنید که پروکسی به طور کلی ترافیک را به API 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 پروکسی سرور یا در یک کشور غیر پشتیبانی شده است یا گوگل آن را به عنوان دیتاسنتری شناسایی کرده و بررسی اضافی را اعمال کرده است. راه حل — تغییر به IP مسکونی یا موبایل از ایالات متحده یا کشور دیگری با پشتیبانی کامل از Gemini.
تایماوتها در هنگام تولید پاسخهای طولانی بیشتر اوقات به دلیل عدم ثبات جلسه پروکسی است — IP در وسط درخواست تغییر میکند و اتصال قطع میشود. به یک جلسه چسبنده نیاز است که زمان آن بیشتر از درخواست معمولی باشد (معمولاً 10-15 دقیقه با احتیاط برای تولیدات حجیم کد کافی است).
خطای SSL/TLS handshake failed تقریباً همیشه به وجود تداخل ترافیک توسط آنتیویروس، فایروال شرکتی یا تنظیم نادرست proxyStrictSSL در VS Code اشاره دارد. بررسی کنید که آیا نرمافزاری با بازرسی SSL بر روی ماشین وجود دارد و برای عیبیابی به طور موقت آن را خاموش کنید.
CLI کار میکند، اما افزونه در VS Code کار نمیکند (یا برعکس) به این معنی است که متغیرهای محیطی به فرآیند VS Code منتقل نشدهاند. این یک وضعیت رایج در لینوکس و macOS است، اگر VS Code از ترمینالی که متغیرها در آن صادر شدهاند، اجرا نشده باشد، بلکه از آیکون در منوی سیستم. در این صورت، متغیرها باید دقیقاً از طریق settings.json تنظیم شوند، همانطور که در بالا توضیح داده شد، نه اینکه به ارثبرداری از shell تکیه کنید.
پیوند IP به منطقه API-key و امنیت
نکته جداگانهای که اغلب فراموش میشود: اگر API-key یا پروژه Google Cloud با پیوند به یک منطقه صورتحساب خاص ایجاد شده باشد، تغییر IP پروکسی ممکن است منجر به عدم تطابق مکان مورد انتظار و واقعی شود و گوگل گاهی اوقات نیاز به تأیید مجدد از طریق SMS یا ایمیل دارد. برای کاهش فراوانی چنین بررسیهایی، سعی کنید از پروکسی با IP ثابت (غیر چرخشی برای هر درخواست) از یک کشور مشابه استفاده کنید — این برای سیستمهای حفاظتی گوگل به عنوان رفتار عادی کاربر به نظر میرسد که به سادگی در این کشور زندگی میکند، نه به عنوان فعالیت مشکوک.
اگر همزمان با چندین پروژه یا کلید کار میکنید و از مرورگر ضد شناسایی مانند 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 خانگی عادی به نظر میرسند و به ندرت نیاز به بررسیهای اضافی گوگل دارند. اگر آدرس مسکونی به هر دلیلی تحت فیلتر جغرافیایی قرار گیرد، بهتر است پروکسیهای موبایل را امتحان کنید، و برای آزمایشهای سریع یکباره API بدون جلسه طولانی، پروکسیهای دیتاسنتر کاملاً کافی است.