Gemini CLI에 로그인하거나 VS Code에서 Gemini Code Assist 확장을 사용할 때 FAILED_PRECONDITION: User location is not supported와 같은 오류가 발생하면, 이는 귀하의 계정이나 코드에 문제가 있는 것이 아닙니다. Google AI Studio와 Gemini API는 국가별로 불균형하게 배포되며, 일부 지역은 지원 목록에서 제외됩니다. 이는 허용된 국가의 IP 주소를 가진 프록시를 설정함으로써 해결할 수 있으며, 이후에는 터미널, VS Code 및 환경 변수 수준에서 이를 올바르게 설정하는 방법을 알아보겠습니다.
Gemini CLI 및 Gemini Code Assist란?
Gemini CLI는 Google의 콘솔 도구로, 터미널에서 직접 Gemini 모델과 상호작용할 수 있게 해줍니다: 코드를 작성하고, 명령을 생성하며, 프로젝트 파일을 분석하고, 작업 환경을 벗어나지 않고 에이전트 작업을 수행할 수 있습니다. 이는 generativelanguage.googleapis.com 도메인 또는 Vertex AI를 통해 API에 접근하며, 사용하는 인증 방법에 따라 Google AI Studio 키 또는 Google Cloud 계정을 사용합니다.
Gemini Code Assist는 VS Code(및 JetBrains IDE)용 확장으로, 코드 편집기 내에서 모델과의 채팅, 자동 완성 및 힌트를 통합합니다. 본질적으로 이는 동일한 API이지만, 명령줄이 아닌 IDE에서 확장을 통해 호출됩니다. 두 도구는 동일한 백엔드를 사용하므로, 지역 차단 문제는 두 경우 모두 동일하게 나타납니다 — 확장이 세션을 설정할 수 없거나 모델에 대한 첫 요청에서 오류를 반환합니다.
중요한 점: 두 도구 모두 API 생성뿐만 아니라 Google의 인증 서비스(OAuth, Identity Toolkit)에도 네트워크 요청을 합니다. 프록시가 하나의 엔드포인트에만 설정되어 있다면, 인증은 통과할 수 있지만 생성은 실패하거나 그 반대의 경우도 발생할 수 있습니다. 따라서 프록시는 시스템 환경 변수 수준에서 설정해야 하며, 특정 위치에서만 설정해서는 안 됩니다.
왜 Gemini가 귀하의 지역에서 사용할 수 없나요?
Google은 전통적으로 새로운 AI 제품을 단계적으로 배포합니다: 먼저 미국과 일부 유럽 국가, 이후 나머지 국가들로 진행됩니다. Gemini의 경우, 이는 API 수준에서 지리적 제한으로 나타납니다 — 서버는 들어오는 요청의 IP 주소(때로는 Google 계정의 청구 주소도 확인)와 허용된 위치 목록을 비교합니다. 만약 국가가 목록에 없다면, 요청은 precondition 오류와 함께 중단되거나 명확한 설명 없이 타임아웃됩니다.
이는 일반적인 의미의 차단이 아닙니다 — 귀하의 국가의 공급자가 아무것도 차단하지 않으며, 이는 Google 측의 지오 필터에 관한 것입니다. 따라서, 공용 IP를 사용하는 VPN은 종종 도움이 되지 않습니다: 이러한 주소는 수천 명의 사람들이 대량으로 사용하므로 Google은 이를 의심스럽게 표시하고, CAPTCHA를 요구하거나 IP 범위가 공식적으로 다른 국가에 등록되어 있다면 여전히 지오로 차단합니다. 지원되는 지역의 일반적인 가정용 또는 모바일 IP처럼 보이는 주소가 필요합니다 — 즉, 이는 레지던트 및 모바일 프록시가 해결하는 문제와 동일합니다.
Gemini API와 함께 사용할 프록시는 어떤 것인가요?
Gemini CLI와 같은 개발 도구의 경우, 프록시의 주요 매개변수는 세션의 안정성(긴 응답 생성을 중단하지 않도록), 속도 및 Google의 안티 프로드 시스템에서 IP가 얼마나 "깨끗하게" 보이는지입니다. 다음은 세 가지 유형의 비교입니다:
| 프록시 유형 | 속도 | 지오 차단 위험 | 언제 사용해야 하나요 |
|---|---|---|---|
| 데이터 센터 프록시 | 높음 | 중간-높음 | 빠른 테스트, API에 대한 일회성 요청 |
| 레지던트 프록시 | 중간-높음 | 낮음 | Gemini CLI 및 Code Assist와의 일상적인 작업 |
| 모바일 프록시 | 중간 | 최소 | 레지던트 IP가 지오 필터에 의해 차단될 때 |
실제로 개발자가 매일 작업하기에 가장 편리한 것은 레지던트 프록시로, 특정 국가에 바인딩되고 10-30분의 스티키 세션을 갖는 것이 좋습니다 — 이는 OAuth 인증이 중단되지 않고 터미널 세션이 코드 생성 중간에 끊어지지 않도록 충분합니다. 데이터 센터 프록시는 더 저렴하고 빠르지만, Google은 이미 일부 IP 범위를 알고 있으며, 이러한 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를 화이트리스트에 추가하세요.
Code Assist를 위한 VS Code에서 프록시 설정하기
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에 로그인과 비밀번호를 전달하는 것을 차단하며, 이 경우 자격 증명을 base64로 인코딩된 Proxy-Authorization 헤더를 통해 전달해야 합니다.
별도의 점은, 기업 VPN 클라이언트 및 트래픽 가로채기(SSL 검사)와 같은 진단 확장을 일시적으로 비활성화하세요. 이들은 종종 인증서를 즉석에서 변경하며, Google의 인증서 체인을 엄격하게 검증하는 Gemini Code Assist는 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)을 통해 인증하는 경우, 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 API로 트래픽을 전달하는지 확인하세요. 가장 빠른 방법은 curl을 통한 직접 요청입니다:
curl -x http://login:password@proxy_host:port \
"https://generativelanguage.googleapis.com/v1beta/models?key=귀하의_API_KEY"
응답으로 모델 목록이 포함된 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_KEY"}
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로 전환하는 것입니다.
긴 응답 생성 시 타임아웃은 대부분 불안정한 프록시 세션과 관련이 있습니다 — IP가 요청 중간에 변경되어 연결이 끊어집니다. 일반적으로 요청보다 긴 시간(보통 10-15분) 동안 지속되는 스티키 세션이 필요합니다.
SSL/TLS 핸드셰이크 실패 오류는 거의 항상 안티바이러스, 기업 방화벽 또는 VS Code에서 잘못 설정된 proxyStrictSSL에 의해 발생합니다. SSL 검사를 수행하는 소프트웨어가 설치되어 있는지 확인하고, 진단을 위해 일시적으로 비활성화하세요.
CLI는 작동하지만 VS Code의 확장은 작동하지 않거나 그 반대의 경우는 환경 변수가 VS Code 프로세스에 전달되지 않았음을 의미합니다. 이는 Linux 및 macOS에서 자주 발생하는 상황으로, VS Code가 변수가 내보내진 터미널이 아닌 시스템 메뉴의 아이콘에서 실행될 때 발생합니다. 이 경우, 변수를 settings.json을 통해 설정해야 하며, 셸에서 상속되는 것을 기대해서는 안 됩니다.
API 키의 지역에 대한 IP 바인딩 및 보안
자주 잊어버리는 별도의 세부 사항: API 키 또는 Google Cloud 프로젝트가 특정 청구 지역에 바인딩되어 생성된 경우, 프록시 IP 변경이 예상 위치와 실제 위치의 불일치로 이어질 수 있으며, Google은 때때로 SMS 또는 이메일을 통해 재인증을 요구합니다. 이러한 확인 빈도를 줄이기 위해, 동일한 국가에서 고정된(각 요청마다 변경되지 않는) IP를 가진 프록시를 사용하는 것이 좋습니다 — 이는 Google의 보호 시스템에 일반적인 사용자 행동으로 보이며, 의심스러운 활동으로 간주되지 않습니다.
여러 프로젝트나 키를 동시에 작업하고 있으며, Gemini 통합을 다양한 브라우저 환경에서 테스트하는 경우, 각 프로필에 대해 고정된 지리적 위치의 개별 프록시를 바인딩하세요 — 이렇게 하면 한 프로젝트가 다른 프로젝트의 혼합된 IP로 인해 의심을 "끌어당길" 위험이 줄어듭니다.
또한 Gemini와 동시에 높은 부하의 다른 작업을 위해 동일한 무료 또는 공용 프록시를 사용하지 마세요 — 동일한 IP에서 많은 병렬 세션이 생성되면 Google 수준에서 비율 제한 또는 임시 차단에 걸릴 확률이 높아지며, 이는 지역 문제와 유사하게 보이지만 원인은 전혀 다릅니다.
결론
Gemini CLI 및 Gemini Code Assist의 지역 제한은 네트워크 수준에서 해결됩니다: 프록시는 시스템 환경 변수, VS Code 설정 및 Google Cloud를 사용할 경우 gcloud 구성에 동시에 설정해야 합니다 — 그래야만 모든 세 가지 진입점(CLI, IDE 확장 및 OAuth 인증)이 동일한 IP를 통해 작동하며 동기화되지 않습니다. 전체 작업을 시작하기 전에 간단한 curl 요청으로 연결을 항상 확인하세요 — 이는 코드에 문제가 없고 프록시 국가에 문제가 있을 때 진단 시간을 절약합니다.
Gemini CLI와의 안정적인 일상 작업을 위해서는 고정된 지리적 위치와 긴 스티키 세션을 가진 레지던트 프록시가 가장 적합합니다 — 이는 일반 가정용 IP처럼 보이며 Google의 추가 검사를 거의 유발하지 않습니다. 만약 레지던트 주소가 지오 필터에 걸린다면, 모바일 프록시를 시도해 보세요. API에 대한 빠른 일회성 테스트에는 데이터 센터 프록시가 충분합니다.