Gemini CLI 연결 시간 초과? Clash 프록시 오류 해결법

Gemini CLI가 Clash를 통해 요청을 보내지 못하고 connection timed out, fetch failed, socket hang up 같은 오류를 표시한다면 단순히 인터넷이 느린 문제가 아닐 수 있습니다. 잘못 선택된 프록시 모드, Gemini 관련 도메인을 직접 연결로 보내는 규칙, DNS 해석 실패, 노드의 TLS 또는 전송 불안정이 함께 원인이 될 수 있습니다. 이 글에서는 Gemini CLI 연결 시간 초과 문제를 노드 확인부터 환경 변수, Clash 규칙, DNS, TUN 모드, 복구 검증 순서로 점검하는 방법을 설명합니다.

Gemini CLI 연결 시간 초과의 주요 원인

Gemini CLI는 브라우저처럼 화면에 프록시 설정 버튼이 있는 프로그램이 아닙니다. 터미널에서 실행되는 프로세스이므로 운영체제의 프록시 환경 변수, 애플리케이션이 사용하는 HTTP 클라이언트, Clash의 시스템 프록시 또는 TUN 모드에 의존합니다. Clash의 대시보드가 정상적으로 열려도 Gemini CLI가 반드시 같은 경로를 사용하는 것은 아닙니다.

먼저 오류 메시지를 원인별로 분류하면 불필요한 설정 변경을 줄일 수 있습니다. 명령을 실행하자마자 프록시 연결 오류가 발생하면 환경 변수나 로컬 포트가 문제일 가능성이 높습니다. 수십 초 동안 멈춘 뒤 타임아웃이 발생하면 노드, 라우팅 규칙, DNS, TLS 연결을 우선 의심해야 합니다. 인증 오류나 API 응답 코드가 표시된다면 네트워크 경로는 대체로 정상이며 계정, API 키 또는 사용 권한을 확인해야 합니다.

문제를 해결할 때는 한 번에 여러 항목을 바꾸지 않는 것이 좋습니다. 먼저 Clash 자체에서 외부 연결이 가능한지 확인하고, 다음으로 CLI가 로컬 프록시 포트에 접속하는지 확인한 뒤, 마지막으로 규칙과 DNS를 조정하세요. 각 단계에서 명령을 다시 실행하면 어느 계층에서 문제가 발생했는지 쉽게 좁힐 수 있습니다.

노드와 프록시 포트부터 확인하기

가장 먼저 Clash 대시보드에서 현재 선택된 프록시 그룹과 실제 사용 노드를 확인합니다. 노드 이름만 표시되고 지연 시간이 비어 있거나 테스트가 반복해서 실패한다면 Gemini CLI 설정을 수정해도 해결되지 않습니다. 다른 노드를 선택하고 일반적인 HTTPS 사이트 또는 대시보드의 연결 테스트를 통해 노드가 살아 있는지 확인하세요.

Clash는 설치 방식과 클라이언트에 따라 HTTP 포트와 SOCKS 포트가 다를 수 있습니다. 많은 환경에서 HTTP 프록시는 7890, SOCKS5는 7891을 사용하지만 이 값은 고정된 규칙이 아닙니다. 설정 파일의 mixed-port, port, socks-port 값을 확인하고 현재 실행 중인 Clash 프로세스와 일치하는지 살펴보세요.

# HTTP 또는 mixed 포트를 사용하는 경우
curl -I -x http://127.0.0.1:7890 https://generativelanguage.googleapis.com

# SOCKS5 포트를 사용하는 경우
curl -I --proxy socks5h://127.0.0.1:7891 https://generativelanguage.googleapis.com

socks5h에서 마지막 h는 DNS 조회까지 SOCKS 프록시를 통해 수행한다는 의미입니다. socks5만 사용하면 일부 도구가 로컬 DNS를 먼저 조회할 수 있으므로, 도메인 해석 문제를 점검할 때는 socks5h가 더 적합합니다. 위 명령이 성공하면 노드와 로컬 포트는 작동하는 것이며, 다음 단계는 Gemini CLI가 같은 프록시를 사용하도록 만드는 것입니다.

Gemini CLI가 Clash를 사용하도록 설정하기

터미널 프로그램은 보통 HTTP_PROXY, HTTPS_PROXY, ALL_PROXY 환경 변수를 통해 프록시를 인식합니다. HTTPS 요청을 보내더라도 프록시 주소 자체는 HTTP 형식으로 지정하는 경우가 많습니다. 이는 목적지 연결이 암호화되지 않는다는 뜻이 아니라, 로컬 HTTP 프록시에게 HTTPS 목적지로 터널을 만들어 달라고 요청한다는 의미입니다.

export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
export ALL_PROXY=socks5h://127.0.0.1:7891
export NO_PROXY=localhost,127.0.0.1

gemini

현재 셸에서 변수에 값이 들어갔는지도 확인하세요. 값이 비어 있거나 오래된 포트를 가리키면 CLI는 Clash가 아닌 존재하지 않는 프록시로 접속합니다.

printf '%s\n' "$HTTP_PROXY"
printf '%s\n' "$HTTPS_PROXY"
printf '%s\n' "$ALL_PROXY"

Windows PowerShell에서는 다음과 같이 설정할 수 있습니다.

$env:HTTP_PROXY="http://127.0.0.1:7890"
$env:HTTPS_PROXY="http://127.0.0.1:7890"
$env:ALL_PROXY="socks5h://127.0.0.1:7891"
$env:NO_PROXY="localhost,127.0.0.1"

gemini

환경 변수 이름의 대소문자 처리 방식은 운영체제와 라이브러리에 따라 다를 수 있습니다. 특정 환경에서 계속 무시된다면 대문자와 소문자 변수를 함께 지정해 볼 수 있습니다. 다만 HTTP_PROXY와 HTTPS_PROXY에 서로 다른 포트를 넣으면 요청별 경로가 달라져 진단이 어려워지므로, 처음에는 동일한 HTTP 포트를 사용하는 편이 좋습니다.

Clash 규칙과 DNS 문제 해결

Gemini CLI가 사용하는 도메인이 규칙 목록에서 DIRECT로 매칭되면 프록시를 설정했더라도 직접 연결됩니다. 대시보드의 연결 페이지를 열고 Gemini CLI를 실행한 다음 목적지 도메인과 매칭된 규칙, 사용된 프록시 그룹을 확인하세요. 규칙이 DIRECT, REJECT, 또는 의도하지 않은 그룹으로 표시되면 규칙 순서를 수정해야 합니다.

규칙은 위에서 아래로 평가되며 먼저 일치한 항목이 적용됩니다. 넓은 GEOIP 또는 MATCH 규칙을 앞에 두면 뒤에 작성한 Gemini 도메인 규칙은 실행되지 않습니다. 서비스 도메인에는 우선순위가 높은 명시적 규칙을 배치하고, 마지막에 일반적인 기본 규칙을 두는 것이 안전합니다.

rules:
  - DOMAIN-SUFFIX,googleapis.com,Proxy
  - DOMAIN-SUFFIX,generativelanguage.googleapis.com,Proxy
  - DOMAIN-SUFFIX,googleusercontent.com,Proxy
  - DOMAIN-SUFFIX,accounts.google.com,Proxy
  - MATCH,DIRECT

사용 중인 클라이언트가 그룹 이름으로 Proxy를 제공하지 않는다면 실제 그룹 이름으로 바꿔야 합니다. 예를 들어 그룹 이름이 Auto라면 규칙 마지막 필드를 Auto로 작성합니다. 설정을 저장한 뒤 Clash가 새 구성을 정상적으로 로드했는지 확인하고, 기존 연결을 닫은 후 CLI를 다시 실행하세요.

DNS 오류도 자주 발생합니다. 로컬 DNS가 Gemini 도메인을 잘못 해석하거나 응답하지 않으면 규칙 평가 전에 연결이 중단될 수 있습니다. Mihomo 계열에서는 fake-ip 모드가 도메인 기반 규칙과 잘 결합되지만, 일부 프로그램은 가짜 IP를 처리하지 못하므로 문제 발생 시 fake-ip-filter를 무작정 늘리기보다 연결 로그와 DNS 동작을 함께 확인해야 합니다.

TUN 모드가 필요한 경우와 주의점

환경 변수를 설정했는데도 Gemini CLI가 계속 직접 연결한다면 TUN 모드를 고려할 수 있습니다. TUN은 운영체제의 가상 네트워크 인터페이스를 통해 애플리케이션의 트래픽을 Clash로 전달하므로, 프록시 환경 변수를 지원하지 않는 프로그램에도 적용할 수 있습니다. 특히 Node.js 런타임, 일부 패키지 관리자, 서브프로세스로 실행되는 인증 도구처럼 프록시 변수 전달이 불안정한 경우에 유용합니다.

다만 TUN을 켠다고 모든 문제가 자동으로 해결되는 것은 아닙니다. TUN의 시스템 권한, IPv4와 IPv6 경로, DNS 하이재킹, 운영체제 방화벽이 서로 영향을 줍니다. 처음에는 IPv6를 별도로 사용하지 않는 환경에서 IPv4 중심으로 테스트하고, Clash 로그에서 요청이 실제로 TUN 인터페이스를 통해 들어오는지 확인하세요.

tun:
  enable: true
  stack: mixed
  auto-route: true
  auto-detect-interface: true

관리자 권한이 필요한 시스템에서는 Clash를 권한 없이 실행하면 TUN 인터페이스가 생성되지 않을 수 있습니다. 또한 다른 VPN, 보안 프로그램, 가상 머신 네트워크가 이미 기본 라우트를 변경하고 있으면 라우팅 루프가 생길 수 있습니다. TUN을 테스트할 때는 다른 VPN을 잠시 끄고, 문제가 해결된 뒤 하나씩 다시 활성화해 충돌 여부를 확인하세요.

복구 후 검증 및 로그 분석

설정을 변경한 후에는 곧바로 Gemini CLI 전체 기능을 시험하기보다 작은 네트워크 요청부터 확인하는 것이 좋습니다. 다음 순서를 따르면 DNS, 프록시, 라우팅, 인증 문제를 구분하기 쉽습니다.

1. Clash 대시보드에서 선택된 노드의 지연 시간과 상태를 확인합니다.
2. curl로 로컬 HTTP 또는 SOCKS 포트에 접속해 외부 HTTPS 연결을 테스트합니다.
3. Gemini 관련 도메인이 대시보드 연결 로그에 표시되는지 확인합니다.
4. 해당 연결의 규칙이 원하는 프록시 그룹으로 매칭되는지 살펴봅니다.
5. 환경 변수를 적용한 새 터미널에서 Gemini CLI를 다시 실행합니다.
6. 짧은 입력으로 응답을 확인한 뒤 긴 프롬프트나 파일 분석을 테스트합니다.

로그에서 dial tcp 오류가 보이면 목적지 연결 단계의 문제이고, lookup 또는 no such host가 보이면 DNS를 우선 확인해야 합니다. context deadline exceeded는 하나의 원인만 의미하지 않으므로 노드 지연, 규칙, DNS, TLS를 순서대로 살펴봐야 합니다. 반대로 401, 403 같은 HTTP 응답이 반환되면 서버까지 도달한 것이므로 Clash 연결 자체는 성공한 상태입니다.

문제가 간헐적으로만 발생한다면 url-test 또는 fallback 프록시 그룹을 사용하는 것도 방법입니다. 단, 헬스 체크 URL이 실제 Gemini 경로의 품질을 보장하지는 않습니다. 테스트 URL은 응답하지만 특정 API 도메인만 실패할 수 있으므로, 여러 노드에서 실제 목적지 연결 로그를 비교하는 것이 가장 정확합니다.

자주 묻는 질문

브라우저는 정상인데 Gemini CLI만 실패하는 이유는 무엇인가요?

브라우저는 Clash의 시스템 프록시 설정을 자동으로 읽지만 CLI는 그렇지 않을 수 있습니다. HTTP_PROXY, HTTPS_PROXY, ALL_PROXY를 현재 터미널에 설정하고 새 프로세스로 CLI를 실행하세요. 그래도 무시된다면 TUN 모드로 애플리케이션 트래픽을 가로채는 방법을 검토할 수 있습니다.

HTTP 프록시와 SOCKS5 중 무엇을 사용해야 하나요?

Gemini CLI가 HTTP 프록시 환경 변수를 안정적으로 지원한다면 http://127.0.0.1:7890처럼 mixed 또는 HTTP 포트를 사용하는 것이 간단합니다. DNS까지 프록시로 보내야 하거나 HTTP 포트에서 계속 실패한다면 socks5h://127.0.0.1:7891을 시도하세요. 실제 포트는 사용 중인 Clash 설정에서 확인해야 합니다.

규칙을 추가했는데도 timeout이 계속됩니다. 어떻게 해야 하나요?

규칙이 실제 연결 도메인에 매칭되는지와 올바른 그룹으로 전달되는지를 확인하세요. 규칙 순서상 MATCH나 넓은 GEOIP 규칙이 먼저 실행되면 새 규칙이 무시될 수 있습니다. 규칙이 정상인데도 실패하면 다른 노드를 선택하고 DNS 및 TLS 로그를 함께 비교하세요.

TUN 모드를 켜면 항상 해결되나요?

아닙니다. TUN은 프록시 변수를 지원하지 않는 프로그램을 라우팅하는 데 도움을 주지만, 권한 부족, 다른 VPN과의 충돌, DNS 하이재킹, IPv6 경로 문제를 새로 만들 수 있습니다. 환경 변수와 일반 프록시 포트 테스트를 먼저 진행한 뒤 필요한 경우에만 TUN을 활성화하는 것이 안전합니다.

Gemini CLI의 연결 시간 초과는 노드만 교체해서 해결되는 경우도 있지만, 실제로는 “CLI가 Clash를 사용하고 있는가”, “Gemini 도메인이 어떤 규칙으로 처리되는가”, “DNS와 TUN 경로가 일치하는가”를 함께 확인해야 재발을 막을 수 있습니다. 위 순서대로 작은 연결 테스트부터 로그 검증까지 진행하면 설정을 무작정 초기화하지 않고도 원인을 정확히 찾아 안정적인 Gemini CLI 환경을 만들 수 있습니다.