Gemini CLI 중국 접속 설정, Clash Verge로 시작하는 방법

Gemini CLI 요청이 실패하는 이유

Gemini CLI는 브라우저에서 사용하는 웹 서비스가 아니라 터미널에서 외부 API 서버로 직접 HTTPS 요청을 보내는 명령줄 도구입니다. 따라서 브라우저에서 Gemini 웹 페이지가 열리더라도 CLI 요청이 반드시 성공하는 것은 아닙니다. 브라우저는 운영체제의 시스템 프록시나 확장 프로그램을 따를 수 있지만, Node.js 기반 도구나 Python·Go로 작성된 명령줄 프로그램은 별도의 프록시 환경 변수를 읽거나 자체 네트워크 라이브러리를 사용할 수 있습니다. 이 차이를 이해하지 못하면 Clash Verge 화면에는 연결된 것으로 표시되는데 Gemini CLI에서는 시간 초과, 인증 실패, 연결 거부가 반복되는 상황이 생깁니다.

중국 네트워크에서 특히 확인해야 할 부분은 DNS 해석, HTTPS 연결 경로, 터미널 프로세스의 프록시 상속 여부입니다. Clash Verge가 실행 중이고 노드가 선택되어 있어도 터미널이 127.0.0.1의 로컬 포트를 사용하지 않으면 요청은 직접 연결됩니다. 반대로 터미널이 프록시를 사용하더라도 선택한 노드가 해당 API 도메인에 적합하지 않거나 Clash 규칙이 DIRECT로 분류하면 기대한 결과를 얻지 못합니다.

이 글에서는 특정 서비스 제공업체의 링크나 노드를 추천하지 않습니다. 사용 중인 합법적인 프록시 서비스에서 발급한 Clash 호환 구독을 기준으로, 클라이언트와 명령줄 도구 사이의 연결을 점검하는 일반적인 방법을 설명합니다. API 키는 설정 파일이나 로그에 노출하지 말고, 문제가 해결된 뒤에도 자격 증명은 환경 변수나 안전한 비밀 저장소로 관리하는 것이 좋습니다.

시작 전 준비사항

설정을 시작하기 전에 세 가지를 준비하세요. 첫째, 운영체제에 맞는 Clash 클라이언트입니다. 이 글에서는 Windows와 macOS에서 사용할 수 있는 Clash Verge 계열 인터페이스를 기준으로 설명하지만, 메뉴 이름은 버전에 따라 조금 다를 수 있습니다. 둘째, 프록시 제공업체에서 발급한 Clash 구독 URL입니다. 일반적인 SS, VLESS, Trojan 단일 링크가 아니라 Clash 또는 Clash Meta용 YAML 프로필을 내려받을 수 있는 링크인지 확인해야 합니다. 셋째, Gemini CLI와 Node.js 등 CLI 실행 환경이 정상적으로 설치되어 있어야 합니다.

회사나 학교 네트워크처럼 자체 보안 장비가 있는 환경에서는 프록시 사용이 정책상 제한될 수 있습니다. 이 경우 우회 설정을 무리하게 적용하기보다 네트워크 관리자에게 허용된 개발 환경과 API 사용 방법을 문의해야 합니다. 또한 Gemini API 및 관련 서비스의 이용 가능 여부는 지역, 계정 유형, 서비스 약관에 따라 달라질 수 있으므로 기술적으로 연결된다는 사실과 서비스 이용 권한을 혼동하지 마세요.

1단계: Clash Verge 설치 및 기본 화면 확인

먼저 Clash Verge를 설치하고 실행합니다. 설치가 끝난 뒤 트레이 아이콘이나 메인 창이 표시되는지 확인하세요. 클라이언트가 백그라운드에서 실행되고 있어야 로컬 HTTP 또는 SOCKS 포트가 열리고, Gemini CLI가 해당 포트로 요청을 전달할 수 있습니다. 프로그램을 처음 실행할 때 운영체제 방화벽이 네트워크 접근을 물어보면 사용 중인 네트워크 정책에 맞게 허용 여부를 결정합니다.

화면에서 Profiles, Proxies, Rules, Connections, Settings와 비슷한 메뉴를 찾습니다. Profiles는 구독 프로필을 관리하고, Proxies는 실제로 사용할 노드를 선택하는 곳입니다. Rules는 도메인과 트래픽이 DIRECT 또는 프록시 그룹 중 어디로 가는지 보여 주며, Connections는 현재 연결을 진단할 때 유용합니다. Settings 또는 General 화면에서는 HTTP 포트, SOCKS 포트, 혼합 포트와 시스템 프록시 상태를 확인할 수 있습니다.

이 단계에서 바로 시스템 프록시를 켜도 되지만, 먼저 클라이언트의 로컬 포트 번호를 기록해 두는 것이 좋습니다. 기본값으로 7890이나 7897이 사용되는 경우가 있지만, 설치 버전과 기존 프로그램에 따라 달라질 수 있습니다. 화면에 표시된 값을 기준으로 해야 하며, 인터넷에서 본 예시 포트를 무조건 복사해서는 안 됩니다.

2단계: Clash 구독 프로필 가져오기

Profiles 메뉴를 열고 구독 URL 입력란을 찾습니다. 제공업체 대시보드에서 Clash용 링크를 복사한 뒤 입력란에 붙여넣고 다운로드 또는 가져오기 버튼을 누릅니다. 주소가 길더라도 임의로 줄이거나 URL 인코딩을 다시 적용하지 마세요. 일부 대시보드는 링크 끝에 토큰이 포함되어 있으므로 한 글자만 빠져도 인증 실패가 발생합니다. 다운로드가 완료되면 프로필 이름, 노드 수, 마지막 업데이트 시간이 표시되는지 확인합니다.

1. 대시보드에서 Clash 구독 또는 이에 해당하는 전용 링크를 복사합니다.
2. Clash Verge의 Profiles 화면에 URL을 붙여넣고 프로필을 가져옵니다.
3. YAML 구문 오류나 HTTP 오류가 없다면 가져온 프로필을 선택해 활성화합니다.
4. 노드 목록이 비어 있지 않은지 확인하고 필요하면 구독 업데이트를 한 번 실행합니다.

프로필이 내려받아지지 않으면 브라우저에서 같은 URL을 열어 보는 것만으로도 원인을 좁힐 수 있습니다. 브라우저에서도 403이나 404가 표시되면 링크 만료, 사용량 초과, 계정 인증 문제가 의심됩니다. 브라우저에서는 파일이 내려받아지지만 Clash에서 실패한다면 TLS 인증서, User-Agent, 시스템 시간, 클라이언트 버전 또는 YAML 형식을 확인해야 합니다. 토큰이 포함된 구독 URL은 다른 사람에게 전달하지 않는 것이 안전합니다.

3단계: 노드 선택과 라우팅 모드 점검

프로필을 활성화한 다음 Proxies 화면에서 노드 또는 프록시 그룹을 선택합니다. 처음부터 가장 빠른 수치만 보고 선택하기보다는 연결 안정성과 API 도메인 접근 가능성을 함께 확인하는 편이 좋습니다. 지연 시간 측정이 낮아도 특정 HTTPS 서비스에 대한 연결이 불안정할 수 있으며, 반대로 수치가 조금 높아도 요청이 안정적으로 완료되는 노드가 CLI 작업에는 더 적합할 수 있습니다.

문제를 진단할 때는 먼저 Global 모드로 짧게 테스트할 수 있습니다. Global 모드는 대부분의 요청을 선택한 프록시 그룹으로 보내므로 규칙 문제와 노드 문제를 분리하는 데 도움이 됩니다. Global에서 성공하고 Rule에서 실패한다면 Rules 화면에서 Gemini 관련 도메인이 DIRECT 또는 잘못된 그룹으로 분류되는지 확인하세요. 평상시에는 국내 서비스까지 모두 프록시로 보내는 Global보다 필요한 트래픽만 분리하는 Rule 모드가 속도와 관리 측면에서 유리합니다.

모드	진단 목적	일상적인 사용
Rule	도메인과 규칙에 따라 연결을 분리	권장
Global	노드 자체와 기본 연결을 빠르게 확인	임시 테스트
Direct	프록시 없이 직접 연결	비교 테스트

Rules 화면에서 특정 도메인의 최종 매칭 결과를 확인할 수 있다면 반드시 기록하세요. 규칙은 위에서 아래로 평가되는 경우가 많고, 마지막 MATCH 규칙이 예상과 다른 그룹을 가리킬 수 있습니다. 또한 프로필에 여러 프록시 그룹이 있다면 그룹 안에서 실제 노드를 선택해야 합니다. 그룹 이름만 선택하고 내부 노드가 자동 선택될 것이라고 생각하면 죽은 노드나 만료된 노드가 계속 사용될 수 있습니다.

4단계: Clash 로컬 포트와 시스템 프록시 확인

Gemini CLI를 설정하기 전에 Clash Verge의 로컬 포트를 확인합니다. 가장 이해하기 쉬운 방식은 HTTP 프록시 포트 또는 mixed 포트를 사용하는 것입니다. 예를 들어 화면에 HTTP 포트가 7890으로 표시되고 주소가 127.0.0.1이라면 터미널은 해당 주소를 프록시 서버로 사용합니다. SOCKS5 포트만 알고 있다면 도구가 SOCKS5를 지원하는지 확인해야 하며, 지원하지 않는 프로그램에는 HTTP 또는 mixed 포트를 사용하는 편이 간단합니다.

시스템 프록시 스위치를 켜면 브라우저와 일부 GUI 앱이 자동으로 프록시를 사용할 수 있습니다. 그러나 시스템 프록시가 켜졌다는 사실만으로 터미널의 모든 명령이 프록시를 사용한다고 보장할 수는 없습니다. 셸 프로세스와 Node.js 라이브러리, 패키지 매니저마다 프록시를 읽는 방식이 다르기 때문입니다. 따라서 시스템 프록시와 함께 환경 변수도 명시적으로 설정하는 것이 재현 가능한 개발 환경을 만드는 데 도움이 됩니다.

5단계: 터미널에 프록시 환경 변수 적용

터미널 프로그램에 프록시를 적용하는 가장 일반적인 방법은 HTTP_PROXY, HTTPS_PROXY, ALL_PROXY 변수를 설정하는 것입니다. Gemini CLI가 내부적으로 사용하는 라이브러리가 이 변수를 읽는다면 별도의 애플리케이션 설정 없이 요청 경로가 바뀝니다. 다만 모든 프로그램이 모든 변수를 지원하는 것은 아니므로, 먼저 curl로 동작을 확인하고 그 다음 Gemini CLI를 실행하는 순서가 안전합니다.

macOS 또는 Linux의 Bash·Zsh에서는 다음처럼 현재 터미널 세션에만 적용할 수 있습니다. 포트 번호는 Clash Verge 화면의 실제 값으로 바꾸세요.

export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
export ALL_PROXY=http://127.0.0.1:7890

Windows PowerShell에서는 환경 변수 문법이 다릅니다. 아래 설정은 현재 PowerShell 창에만 적용되며, 창을 닫으면 사라집니다.

$env:HTTP_PROXY="http://127.0.0.1:7890"
$env:HTTPS_PROXY="http://127.0.0.1:7890"
$env:ALL_PROXY="http://127.0.0.1:7890"

Windows 명령 프롬프트에서는 set을 사용합니다. 셸별 문법을 섞으면 변수에 따옴표가 포함되거나 값이 적용되지 않을 수 있으므로 현재 사용하는 터미널에 맞는 명령만 실행하세요. 설정 후에는 새 터미널을 열어야 하는 경우도 있습니다. 특히 IDE 내장 터미널은 IDE가 시작될 때의 환경을 상속하므로, IDE를 재시작해야 변경 사항이 반영될 수 있습니다.

6단계: curl로 연결 경로 분리 테스트

Gemini CLI를 바로 반복 실행하기보다 먼저 단순한 HTTPS 요청으로 프록시가 실제 사용되는지 확인합니다. 프록시 환경 변수를 설정한 터미널에서 curl을 실행하고, Clash Verge의 Connections 또는 Logs 화면에 해당 연결이 나타나는지 함께 살펴보세요. 로그에 전혀 연결이 없다면 환경 변수가 적용되지 않았거나 포트가 잘못된 것입니다. 로그에는 연결이 표시되지만 실패한다면 노드, DNS, TLS 또는 원격 서버 응답을 확인해야 합니다.

curl -I https://generativelanguage.googleapis.com

이 명령이 200이 아닌 다른 HTTP 상태 코드를 반환하더라도 DNS와 TCP·TLS 경로가 열렸다는 의미일 수 있습니다. 반대로 Could not resolve host는 이름 해석 단계의 문제이고, Connection refused는 로컬 포트가 열려 있지 않거나 주소가 틀린 경우가 많습니다. Operation timed out은 노드 품질, 방화벽, 원격 응답 지연 또는 잘못된 라우팅을 모두 포함할 수 있으므로 로그와 함께 판단해야 합니다.

프록시를 명시한 테스트와 직접 연결 테스트를 비교하면 원인 파악이 쉬워집니다. 직접 연결이 실패하고 프록시 연결이 성공한다면 CLI가 프록시를 사용해야 하는 환경이라는 뜻입니다. 두 방식 모두 실패한다면 Clash 노드나 구독 자체를 먼저 점검해야 합니다. 반대로 두 방식 모두 성공하는데 Gemini CLI만 실패하면 CLI 버전, 인증 설정, API 엔드포인트, Node.js의 프록시 지원 여부를 확인하세요.

7단계: Gemini CLI 실행과 인증 확인

네트워크 테스트가 통과하면 같은 터미널에서 Gemini CLI를 실행합니다. 처음에는 짧고 단순한 요청을 보내고, 긴 프롬프트나 파일 업로드는 나중에 시험하는 것이 좋습니다. 그래야 인증 오류와 네트워크 오류를 구분할 수 있습니다. CLI가 요구하는 로그인 방식이나 API 키 환경 변수 이름은 버전에 따라 달라질 수 있으므로, 해당 도구의 공식 문서에서 현재 버전을 기준으로 확인하세요.

1. 프록시 환경 변수가 설정된 동일한 터미널에서 Gemini CLI를 실행합니다.
2. 짧은 테스트 프롬프트를 보내고 응답 시간과 오류 메시지를 기록합니다.
3. Clash의 Connections에서 API 도메인이 선택한 노드 또는 그룹으로 연결되는지 확인합니다.
4. 인증 오류라면 API 키와 계정 권한을, 시간 초과라면 노드와 라우팅을 다시 확인합니다.
5. 정상 응답 후 새 터미널에서도 같은 설정이 필요한지 확인합니다.

오류 메시지에 API 키가 포함되어 있지 않은지 먼저 살펴본 뒤 필요한 부분만 기록합니다. 401이나 403은 네트워크가 도달했지만 인증 또는 권한이 거부된 경우가 많고, 429는 요청 한도나 계정 사용량과 관련될 수 있습니다. ENOTFOUND, ECONNRESET, ETIMEDOUT처럼 네트워크 라이브러리에서 발생하는 오류는 각각 DNS, 연결 재설정, 시간 초과를 의미할 가능성이 높습니다.

DNS와 규칙이 CLI 결과에 미치는 영향

Gemini CLI가 사용하는 도메인을 Clash가 올바르게 해석하고 적절한 규칙으로 보낼 수 있어야 합니다. DNS가 로컬 통신사나 공유기에서 직접 처리되고, 실제 HTTPS 연결은 다른 경로로 나가면 브라우저와 CLI의 결과가 달라질 수 있습니다. Clash의 DNS 설정을 변경할 때는 구독 프로필이 제공하는 기본값을 먼저 확인하고, 여러 설정을 한 번에 덮어쓰지 않는 것이 좋습니다.

fake-ip와 redir-host는 작동 방식이 다릅니다. fake-ip은 클라이언트에 가상 주소를 제공한 뒤 도메인 정보를 바탕으로 연결을 매핑하므로 규칙 기반 분류에 유리하지만, 일부 개발 도구나 특수 네트워크 라이브러리와 호환성 문제가 생길 수 있습니다. redir-host는 실제 주소에 가까운 형태로 처리하여 일부 프로그램의 호환성 확인에 도움이 될 수 있습니다. 어느 모드가 절대적으로 더 좋은 것은 아니며, 현재 프로필과 사용하는 클라이언트의 권장 설정을 우선해야 합니다.

자주 발생하는 문제와 해결 방법

Clash 로그에 아무 연결도 나타나지 않음

이 경우 CLI가 환경 변수를 읽지 않았거나, 다른 터미널·IDE 프로세스에서 실행되고 있을 가능성이 큽니다. 현재 셸에서 변수가 설정되어 있는지 안전하게 확인하고, 프록시 주소의 스킴이 http://인지 확인하세요. SOCKS 포트에 HTTP 주소를 넣거나 HTTP 포트에 잘못된 SOCKS 형식을 넣으면 연결이 기록되지 않을 수 있습니다. IDE 내장 터미널을 사용한다면 IDE를 재시작한 뒤 다시 실행하세요.

로그에는 연결이 있지만 시간 초과가 발생함

먼저 선택한 노드를 다른 노드로 바꾸고 Global 모드에서 동일한 curl 테스트를 수행합니다. 다른 노드에서 성공한다면 기존 노드의 품질이나 목적지별 차단 문제일 수 있습니다. 모든 노드에서 실패한다면 DNS, 방화벽, 시스템 시간, Clash 코어 버전과 프로필의 호환성을 확인하세요. 회사 네트워크에서는 외부 프록시 자체가 차단될 수도 있으므로 다른 네트워크에서 비교하는 것도 도움이 됩니다.

네트워크는 정상인데 인증 오류가 발생함

401이나 403은 프록시 설정이 해결해 주는 문제가 아닐 수 있습니다. API 키가 만료되었거나 잘못된 프로젝트에 연결되어 있는지, 계정과 지역 정책이 해당 API 사용을 허용하는지 확인해야 합니다. 셸에 오래된 키가 남아 있으면 새 키를 입력해도 이전 값이 사용될 수 있으므로 현재 셸과 IDE의 환경 변수를 각각 확인하세요. 키를 변경한 뒤에는 실행 중인 CLI 프로세스를 종료하고 새로 시작합니다.

안정적인 개발 환경을 위한 운영 팁

Gemini CLI를 자주 사용한다면 매번 긴 환경 변수 명령을 입력하기보다 셸 프로필에 별칭이나 별도 스크립트를 만들 수 있습니다. 다만 프로필 파일에 API 키를 평문으로 저장하는 것은 권장하지 않습니다. 프록시 변수만 셸 설정에 두고 인증 정보는 운영체제의 환경 변수 관리자, 비밀 저장소 또는 CLI가 제공하는 안전한 로그인 기능을 사용하는 편이 좋습니다.

구독 프로필은 정기적으로 업데이트하되, 업데이트 직후에는 노드 수와 규칙 변경을 확인하세요. 제공업체가 포트, DNS, 규칙 구조를 변경하면 기존에 잘 작동하던 CLI가 갑자기 실패할 수 있습니다. 문제가 발생한 날에는 클라이언트 버전, 프로필 업데이트 시간, 선택 노드, 오류 메시지를 함께 기록하면 재현과 복구가 쉬워집니다.

• 변경을 한 번에 하나씩: 노드, DNS, 모드, 환경 변수를 동시에 바꾸지 않습니다.
• Rule 모드 유지: 정상 작동 후에는 필요한 도메인만 프록시로 보내 불필요한 지연을 줄입니다.
• 로그 최소화: 인증 정보나 프롬프트 내용이 저장될 수 있는 상세 로그는 필요할 때만 켭니다.
• 버전 기록: Clash Verge, 코어, Gemini CLI의 버전을 함께 기록하면 업데이트 후 문제를 빠르게 되돌릴 수 있습니다.
• 정책 준수: 네트워크와 API 서비스의 이용약관, 지역 법률, 조직의 보안 정책을 반드시 확인합니다.

자주 묻는 질문

Clash Verge가 연결되어 있는데 Gemini CLI가 실패하는 이유는 무엇인가요?

시스템 프록시와 터미널 프록시는 서로 다를 수 있기 때문입니다. Clash Verge가 노드를 사용 중이어도 CLI 프로세스가 프록시 환경 변수를 읽지 않으면 직접 연결을 시도합니다. HTTP_PROXY와 HTTPS_PROXY를 설정하고 curl 요청이 Clash 로그에 나타나는지 먼저 확인하세요.

Rule 모드와 Global 모드 중 어느 것을 사용해야 하나요?

처음 문제를 진단할 때는 Global 모드가 유용합니다. 규칙을 거치지 않고 선택한 그룹으로 요청을 보내므로 노드와 기본 네트워크를 빠르게 확인할 수 있습니다. 정상 작동을 확인한 뒤에는 Rule 모드로 돌아가 필요한 도메인만 프록시를 통과시키는 것이 일반적으로 더 효율적입니다.

환경 변수를 설정했는데도 요청이 실패합니다. 무엇을 확인해야 하나요?

현재 셸에 변수가 적용되었는지, 포트가 Clash 화면과 일치하는지, HTTP 포트와 SOCKS 포트를 혼동하지 않았는지 확인하세요. 그 다음 다른 노드와 Global 모드를 비교하고 Clash 로그의 오류 유형을 확인합니다. 연결은 성공하지만 401이나 403이 나온다면 프록시보다 API 키와 계정 권한을 점검해야 합니다.

관련 글

Clash의 기본 개념은 《Clash 초보자 가이드》에서 확인할 수 있으며, 연결은 되었지만 인터넷이 작동하지 않는 경우에는 《Clash 연결됨 표시 후 인터넷이 안 될 때 DNS와 fake-ip 점검》을 참고하세요. 여러 장치에서 프록시를 공유하려면 《Clash LAN 프록시와 mixed-port 설정》도 도움이 됩니다.

정리

일부 GUI 프록시 도구는 시스템 프록시 전환은 간단하지만 터미널별 환경 변수, 규칙 로그, 프로필 업데이트 상태를 한 화면에서 확인하기 어렵습니다. 반대로 명령줄 전용 프록시는 자동화에는 편리해도 처음 사용하는 사람에게 노드 선택과 DNS 문제를 진단하기 어렵고, 운영체제별 설정 방법도 달라질 수 있습니다.

Clash는 구독 프로필, 노드 그룹, 규칙 모드, 연결 로그와 로컬 포트를 한 곳에서 관리할 수 있어 이런 문제를 단계적으로 분리하기 좋습니다. 특히 브라우저와 Gemini CLI처럼 서로 다른 프로그램의 트래픽 경로를 비교하면서 원인을 찾을 수 있다는 점이 실용적입니다. 안전한 네트워크 환경에서 직접 설정을 확인해 보고 싶다면 Clash 무료 다운로드 페이지에서 운영체제에 맞는 클라이언트를 확인해 보세요.