Gemini CLI 연결 시간 초과? Clash 설정으로 해결하는 방법

왜 브라우저는 되는데 Gemini CLI만 멈출까요?

Gemini CLI에서 요청을 보냈을 때 아무런 응답이 없거나 ETIMEDOUT, ECONNRESET, fetch failed와 같은 오류가 나타나는 상황은 생각보다 흔합니다. 특히 브라우저에서 Gemini 웹사이트가 정상적으로 열리는 상태라면 네트워크 전체가 끊긴 것이 아니라 CLI 프로세스의 트래픽 경로가 브라우저와 다르다고 보는 것이 정확합니다.

브라우저는 운영 체제의 시스템 프록시 설정을 자동으로 읽습니다. 반면 Node.js 기반 도구나 터미널 프로그램은 시스템 프록시를 무시하고 직접 연결하는 경우가 많습니다. Clash에서 시스템 프록시를 켰더라도 Gemini CLI가 해당 설정을 읽지 않으면 요청은 프록시 포트가 아닌 일반 네트워크 인터페이스로 나갑니다. 이때 대상 API에 직접 접근할 수 없는 네트워크에서는 연결이 오래 대기하다가 시간 초과로 종료됩니다.

또 다른 원인은 프록시 주소의 형식입니다. Clash의 HTTP 포트와 SOCKS 포트는 서로 다른 프로토콜을 사용하므로, HTTP 프록시를 요구하는 환경 변수에 SOCKS 포트를 넣으면 연결이 실패할 수 있습니다. 포트 번호가 맞아 보인다는 이유만으로 정상이라고 판단하지 말고, 실제 리스닝 서비스와 프로토콜을 함께 확인해야 합니다.

이 글은 Gemini CLI의 네트워크 연결 문제를 다룹니다. API 키, 계정 권한, 모델 이름, 할당량 오류는 프록시 연결이 정상화된 뒤 별도로 확인해야 합니다.

먼저 Clash의 상태와 포트를 확인하기

문제 해결을 시작하기 전에 Clash 자체가 실행 중이고 실제로 사용할 수 있는 노드가 있는지 확인하세요. 프로필이 활성화되지 않았거나 모든 노드가 오프라인이면 환경 변수를 올바르게 설정해도 요청은 성공하지 않습니다.

프로필과 노드 점검

Clash 클라이언트를 열고 현재 프로필이 활성화되어 있는지 확인합니다. 프로필 카드가 선택 상태가 아니면 먼저 구독 또는 로컬 설정을 활성화하세요.
프록시 페이지에서 사용할 정책 그룹을 확인합니다. 그룹에 노드가 하나도 없거나 모든 노드의 지연 테스트가 타임아웃이면 정상적인 노드로 변경해야 합니다.
홈 화면에서 시스템 프록시를 켭니다. 이 단계는 브라우저 테스트에는 도움이 되지만, CLI에는 환경 변수 또는 TUN 모드가 추가로 필요할 수 있습니다.
Clash의 일반 설정에서 HTTP 또는 혼합 포트 번호를 확인합니다. 많은 설정에서 HTTP 포트는 7890, SOCKS5 포트는 7891이지만 사용자가 변경했을 수 있으므로 숫자를 추측하지 마세요.

로컬 포트가 열려 있는지 테스트

터미널에서 아래 명령을 실행하면 HTTP 프록시 포트가 실제로 응답하는지 확인할 수 있습니다. 포트가 다르면 자신의 Clash 설정에 맞게 숫자를 바꾸세요.

curl -I -x http://127.0.0.1:7890 https://generativelanguage.googleapis.com

응답 헤더가 반환되거나 최소한 TLS 연결 단계까지 진행된다면 로컬 프록시가 요청을 받고 있다는 뜻입니다. 반대로 Connection refused가 나오면 환경 변수 문제가 아니라 포트 번호, Clash 실행 상태, 방화벽 또는 외부 컨트롤러 설정을 먼저 해결해야 합니다. 이 테스트는 Gemini CLI를 실행하기 전에 가장 빠르게 범위를 좁히는 방법입니다.

127.0.0.1은 현재 컴퓨터를 의미합니다. 원격 서버나 Docker 컨테이너 안에서 Gemini CLI를 실행한다면 그 환경의 localhost는 데스크톱의 Clash가 아니므로 별도의 프록시 주소를 사용해야 합니다.

터미널에 Clash 프록시 환경 변수 설정하기

대부분의 CLI 도구는 HTTP_PROXY, HTTPS_PROXY, ALL_PROXY 같은 표준 환경 변수를 확인합니다. HTTPS 요청이라도 프록시 서버와의 초기 연결은 HTTP CONNECT 방식으로 처리되는 경우가 많으므로, 먼저 Clash의 HTTP 또는 mixed 포트를 사용하는 것이 호환성이 좋습니다.

macOS와 Linux에서 임시 설정

현재 터미널 세션에서만 적용하려면 다음 명령을 실행하세요. 이 방법은 설정 변경의 영향을 쉽게 되돌릴 수 있어 진단 단계에 적합합니다.

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

gemini

일부 네트워크 라이브러리는 소문자 변수만 읽으므로 대문자와 소문자를 함께 지정하는 것도 방법입니다.

export http_proxy="$HTTP_PROXY"
export https_proxy="$HTTPS_PROXY"
export all_proxy="$ALL_PROXY"

설정이 적용되었는지 확인하려면 env | grep -i proxy를 실행합니다. 값에 오래된 포트, 다른 VPN의 주소, 존재하지 않는 호스트가 남아 있으면 제거하세요. 특히 NO_PROXY에 Gemini 관련 도메인을 넣어 두면 해당 요청만 프록시를 우회할 수 있으므로 진단 중에는 불필요한 예외를 잠시 비우는 것이 좋습니다.

Windows PowerShell에서 설정

PowerShell에서는 $env: 형식으로 현재 창에 환경 변수를 추가합니다.

$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"

gemini

명령 프롬프트를 사용한다면 다음과 같이 입력합니다.

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

새 터미널을 열 때마다 입력하는 것이 번거롭다면 PowerShell 프로필이나 운영 체제의 사용자 환경 변수에 저장할 수 있습니다. 다만 회사 네트워크, 다른 프로젝트, 사내 저장소를 사용할 때 모든 트래픽이 Clash로 전송될 수 있으므로 전역 저장보다는 CLI 전용 스크립트를 사용하는 편이 안전합니다.

프록시 포트 확인

Clash의 설정 화면에서 HTTP 또는 mixed 포트를 확인하고 예시의 7890을 실제 번호로 교체합니다.

환경 변수 적용

현재 운영 체제에 맞는 명령을 실행한 뒤 같은 터미널에서 Gemini CLI를 시작합니다. 다른 터미널 창에는 자동으로 적용되지 않습니다.

간단한 HTTPS 요청 확인

CLI를 다시 실행하기 전에 curl로 동일한 프록시 주소를 테스트하여 환경 변수 문제가 아닌지 분리합니다.

HTTP와 SOCKS5 프록시 선택 기준

Clash는 보통 HTTP, SOCKS5, 그리고 두 프로토콜을 함께 처리하는 mixed 포트를 제공합니다. Gemini CLI가 사용하는 라이브러리가 SOCKS를 명시적으로 지원한다면 다음처럼 사용할 수 있습니다.

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

그러나 모든 Node.js 네트워크 모듈이 ALL_PROXY를 자동으로 처리하는 것은 아닙니다. 환경 변수를 넣었는데도 변화가 없다면 HTTP 포트로 통일해 보세요. SOCKS5 포트를 HTTP 프록시 변수에 넣는 방식은 작동하지 않습니다. 반대로 SOCKS 주소를 요구하는 애플리케이션에는 socks5:// 스킴을 명시해야 합니다.

프록시 인증을 사용하는 경우에는 사용자 이름과 비밀번호를 주소에 포함할 수 있지만, 셸 기록이나 프로세스 목록에 자격 증명이 노출될 수 있습니다. 로컬 Clash 포트에 별도 인증이 없다면 인증 정보를 억지로 추가하지 마세요. 공유 컴퓨터에서 API 키나 프록시 비밀번호를 명령줄에 직접 입력하는 것도 피해야 합니다.

Clash 규칙과 DNS 라우팅 점검

환경 변수를 올바르게 설정했는데도 요청이 시간 초과된다면 Clash가 Gemini 관련 도메인을 잘못된 정책으로 보내고 있을 수 있습니다. 규칙 모드에서는 규칙의 위에서부터 아래로 매칭하며, 먼저 일치한 규칙이 최종 경로를 결정합니다. 특정 도메인을 DIRECT로 보내는 규칙이 프록시 규칙보다 위에 있으면 CLI는 프록시를 거치지 않습니다.

Clash의 연결 화면에서 Gemini CLI를 실행한 순간 새로운 요청이 나타나는지 확인하세요. 요청이 보이지 않으면 CLI가 프록시를 사용하지 않는 것입니다. 요청은 보이지만 연결이 실패한다면 해당 요청의 정책 그룹, 선택된 노드, DNS 결과를 차례로 확인합니다.

설정 파일을 직접 관리한다면 Gemini API 도메인에 대한 규칙을 정책 그룹 앞에 배치할 수 있습니다.

rules:
  - DOMAIN-SUFFIX,generativelanguage.googleapis.com,PROXY
  - DOMAIN-SUFFIX,googleapis.com,PROXY
  - MATCH,DIRECT

실제 정책 그룹 이름은 설정 파일마다 다르므로 예시의 PROXY를 자신의 그룹 이름으로 바꿔야 합니다. 마지막 MATCH 규칙은 모든 미매칭 트래픽에 적용되므로, 기본값이 직접 연결인지 프록시인지도 반드시 확인하세요.

DNS 문제가 의심될 때

도메인 이름을 IP 주소로 바꾸는 DNS 단계에서 막히면 프록시 환경 변수만으로 해결되지 않을 수 있습니다. 터미널에서 nslookup generativelanguage.googleapis.com 또는 dig generativelanguage.googleapis.com을 실행해 응답 여부를 확인하세요. DNS 응답이 없거나 지역 네트워크에서 잘못된 주소를 돌려준다면 Clash의 DNS 설정과 모드, 가상 주소 범위를 확인해야 합니다.

Clash의 DNS 기능을 사용하는 경우 DNS 서버에 대한 요청도 적절한 정책으로 처리되는지 확인하세요. fake-ip 모드와 redir-host 모드를 바꿀 때는 기존 캐시가 남아 결과가 즉시 달라지지 않을 수 있습니다. 설정을 바꾼 뒤 Clash를 재시작하고 운영 체제의 DNS 캐시도 정리한 다음 다시 테스트하는 것이 좋습니다.

환경 변수로 해결되지 않을 때 TUN 모드 사용

일부 CLI 또는 Node.js 라이브러리는 표준 프록시 변수를 무시합니다. 이 경우 애플리케이션 내부 설정을 계속 찾기보다 Clash의 TUN 모드를 사용하는 것이 효과적일 수 있습니다. TUN은 가상 네트워크 인터페이스를 만들고 운영 체제의 패킷을 네트워크 계층에서 Clash로 전달하므로, 프록시 인식 기능이 없는 프로그램도 라우팅 대상에 포함할 수 있습니다.

Clash Verge Rev에서는 설정 또는 홈 화면에서 TUN 모드를 활성화한 뒤 운영 체제의 관리자 권한 요청을 승인합니다. 그 다음 모드를 Rule로 두고 Gemini 관련 트래픽이 프록시 정책으로 이동하는지 확인하세요. 처음부터 Global 모드를 사용할 필요는 없습니다. 규칙 모드가 유지 관리와 예외 처리에 유리하며, 필요한 도메인만 프록시로 보낼 수 있기 때문입니다.

TUN 모드는 시스템 전체 트래픽에 영향을 주며 관리자 권한이 필요합니다. VPN, 다른 가상 네트워크 도구, 회사 보안 프로그램과 충돌할 수 있으므로 문제가 해결된 뒤에는 필요 여부를 다시 판단하세요.

TUN 활성화 후 확인할 항목

TUN 서비스가 실행 중이고 가상 인터페이스가 생성되었는지 확인합니다.
DNS 처리 모드가 현재 운영 체제와 충돌하지 않는지 확인합니다.
Clash 연결 목록에 Gemini CLI의 프로세스 트래픽이 표시되는지 확인합니다.
시스템 프록시와 TUN을 동시에 켰을 때 순환 라우팅이 생기지 않는지 확인합니다.
문제 해결 후 직접 연결이 필요한 로컬 네트워크와 사내 도메인이 정상적으로 접속되는지 확인합니다.

시간 초과 원인을 단계별로 분리하는 방법

여러 설정을 한꺼번에 바꾸면 무엇이 해결했는지 알 수 없고 새로운 오류가 생겼을 때 되돌리기도 어렵습니다. 다음 순서를 지키면 원인을 빠르게 좁힐 수 있습니다.

Clash 없이 브라우저를 테스트합니다. 브라우저에서도 대상 서비스가 열리지 않는다면 먼저 노드 또는 계정 문제가 아닌지 확인합니다.
로컬 포트를 curl로 테스트합니다. 연결 거부가 나오면 CLI 설정을 바꾸기 전에 Clash 포트를 수정합니다.
환경 변수만 적용해 CLI를 실행합니다. 이 단계에서 연결 목록에 요청이 나타나는지 확인합니다.
정책 그룹과 규칙을 확인합니다. 요청이 DIRECT로 처리되거나 REJECT에 걸리지 않았는지 살펴봅니다.
TUN을 켜고 다시 실행합니다. 환경 변수를 전혀 읽지 않는 프로그램인지 판단할 수 있습니다.
노드를 교체합니다. 한 노드만 시간 초과를 일으킨다면 클라이언트 설정이 아니라 해당 노드의 경로, 지역 제한, 과부하 문제일 수 있습니다.

브라우저 성공 여부는 프록시 연결의 일부만 증명합니다. 가장 신뢰할 수 있는 확인 방법은 Gemini CLI를 실행하는 동시에 Clash 연결 목록에 해당 프로세스의 요청이 나타나는지 확인하는 것입니다.

자주 발생하는 오류와 해결책

Connection refused

로컬 포트에 연결할 수 없다는 뜻입니다. Clash가 종료되었거나 포트 번호가 바뀌었을 가능성이 가장 큽니다. 설정 화면의 포트를 다시 확인하고, 다른 프로그램이 같은 포트를 사용하고 있지 않은지 점검하세요.

인증서 또는 TLS 오류

시스템 시간이 크게 어긋났거나, 보안 소프트웨어가 HTTPS를 검사하거나, 프록시 체인의 인증서가 올바르지 않을 때 발생할 수 있습니다. 운영 체제의 날짜와 시간 동기화를 확인하고, 원인을 모른 채 TLS 검증을 끄지는 마세요. 인증서 검증을 비활성화하면 중간자 공격을 감지하지 못할 수 있습니다.

환경 변수를 넣었지만 아무 변화가 없음

CLI가 해당 변수를 읽지 않거나, 실행 스크립트가 환경 변수를 덮어쓰거나, 이미 실행 중인 데몬 프로세스가 이전 환경을 유지하고 있을 수 있습니다. 터미널에서 변수 값을 출력하고, CLI 프로세스를 완전히 종료한 뒤 다시 시작하세요. 그래도 연결 목록에 요청이 나타나지 않으면 TUN 모드를 테스트합니다.

연결은 되지만 응답이 느리거나 제한됨

이 경우는 네트워크 시간 초과가 아니라 API 할당량, 인증, 노드 품질, 요청 빈도 문제일 수 있습니다. Clash 연결이 정상인 것을 확인한 뒤 CLI의 로그인 상태와 프로젝트 설정, 모델 접근 권한, API 사용량을 확인하세요. 여러 번 반복 요청하기 전에 로그를 저장하면 원인 분석에 도움이 됩니다.

API 키와 프록시 설정을 안전하게 관리하기

Gemini CLI를 테스트할 때 환경 변수에 API 키를 함께 저장하는 경우가 많지만, 셸 기록과 CI 로그에 비밀 값이 남지 않도록 주의해야 합니다. 키를 명령줄 인자로 전달하면 프로세스 목록에 노출될 수 있고, 디버그 로그를 그대로 공유하면 인증 정보가 외부에 공개될 수 있습니다.

API 키는 프로젝트의 비밀 저장소나 운영 체제의 안전한 자격 증명 저장소를 사용합니다.
문제 재현 로그를 공유하기 전에 키, 프록시 인증 정보, 구독 URL을 삭제합니다.
구독 URL은 계정 권한과 연결될 수 있으므로 공개 이슈나 채팅에 붙여 넣지 않습니다.
문제 해결을 위해 TLS 검증을 끄거나 모든 도메인을 무조건 Global 프록시로 보내는 설정을 장기간 유지하지 않습니다.

정리: 가장 안정적인 Gemini CLI 연결 구성

Gemini CLI의 연결 시간 초과는 대개 Gemini 서비스 자체보다 터미널 프로세스가 Clash 프록시를 사용하지 않는 문제에서 시작합니다. 먼저 Clash 프로필과 노드를 확인하고, 실제 HTTP 포트를 curl로 테스트한 다음, 운영 체제에 맞는 환경 변수를 적용하세요. 연결 목록에 요청이 나타나지 않으면 CLI가 프록시 변수를 무시하는지 확인하고 TUN 모드로 패킷을 가로채면 됩니다.

브라우저와 CLI의 프록시 경로가 다를 수 있다는 점을 먼저 이해합니다.
HTTP 포트와 SOCKS5 포트를 혼동하지 않고 실제 Clash 설정값을 사용합니다.
환경 변수, Clash 연결 목록, 규칙 정책, DNS 순서로 차근차근 진단합니다.
필요할 때만 TUN 모드를 사용하고 다른 VPN이나 가상 네트워크 도구와의 충돌을 확인합니다.
API 키와 구독 링크를 로그나 명령줄에 노출하지 않습니다.

Clash를 아직 설치하지 않았거나 현재 버전의 클라이언트를 준비해야 한다면 다운로드 페이지에서 운영 체제에 맞는 패키지를 확인할 수 있습니다. 설치 후에는 이 글의 포트 테스트와 환경 변수 설정을 순서대로 진행하면 대부분의 Gemini CLI 연결 문제를 빠르게 분리할 수 있습니다.

Gemini CLI Clash 문제 해결 연결 시간 초과

Gemini CLI 연결 시간 초과?Clash 설정으로 해결하는 방법