서론: Gemini CLI 연결 시간 초과의 원인
Gemini CLI는 터미널에서 Gemini 모델을 호출하고 코드 분석, 문서 요약, 프로젝트 자동화 등을 수행할 수 있는 강력한 도구입니다. 그러나 Clash를 함께 사용하는 환경에서는 브라우저의 Gemini 웹사이트는 정상적으로 열리는데도 CLI 명령만 멈추거나, 요청을 보낸 뒤 오랫동안 응답이 없다가 timeout, ETIMEDOUT, ECONNRESET과 같은 오류를 표시하는 경우가 있습니다.
이 문제는 Gemini CLI 자체의 고장이라기보다 터미널 프로세스의 프록시 미적용, Gemini API 도메인에 대한 규칙 누락, DNS 해석 실패, 인증 요청과 스트리밍 연결의 경로 불일치 때문에 발생하는 경우가 많습니다. 특히 브라우저에서만 Clash의 시스템 프록시를 사용하고 CLI는 별도의 환경 변수를 읽도록 구성되어 있다면, 두 환경의 연결 결과가 서로 다르게 나타날 수 있습니다.
이 가이드의 목표
Clash의 모드, 규칙, DNS, 환경 변수와 노드 품질을 순서대로 점검하여 Gemini CLI의 시간 초과 원인을 빠르게 좁히고 안정적인 연결을 구성합니다.
1먼저 CLI와 기본 네트워크 확인
Clash 설정을 수정하기 전에 문제가 Gemini CLI에만 있는지, 아니면 현재 네트워크 전체에 있는지 구분해야 합니다. 터미널에서 CLI 버전과 인증 상태를 먼저 확인하세요. 명령어 이름은 설치 방식과 패키지 버전에 따라 다를 수 있으므로, 사용 중인 문서에 맞는 실행 파일을 사용해야 합니다.
버전 명령도 실행되지 않거나 인증 상태 확인 단계에서 즉시 실패한다면 CLI 설치, Node.js 또는 Python 런타임, 운영체제 권한 문제를 먼저 살펴보세요. 반대로 버전과 로컬 명령은 정상이고 실제 프롬프트를 전송할 때만 멈춘다면 프록시나 원격 API 연결을 점검할 가능성이 높습니다.
오류 증상별 1차 판단
| 증상 | 가능성이 높은 원인 | 우선 점검할 항목 |
|---|---|---|
| 명령 실행 직후 연결 시간 초과 | CLI가 프록시를 사용하지 않음 | HTTP_PROXY, HTTPS_PROXY 환경 변수 |
| 인증은 되지만 응답 스트리밍이 멈춤 | 웹소켓 또는 장시간 연결 차단 | TUN 모드, 노드 품질, 규칙 순서 |
| 도메인을 찾을 수 없음 | DNS 오류 또는 fake-ip 충돌 | Clash DNS 모드와 터미널의 DNS 결과 |
| 노드를 바꾸면 일시적으로 정상화 | IP 품질 또는 서버 혼잡 | 노드 지연 시간, 패킷 손실, IP 평판 |
2Clash 모드와 CLI 프록시 연결 확인
Gemini CLI가 브라우저와 같은 경로를 사용하도록 하려면 Clash의 현재 모드와 CLI의 프록시 인식 방식을 일치시켜야 합니다. Global 모드에서는 대부분의 트래픽이 선택한 노드를 통과하지만, Rule 모드에서는 도메인별 규칙에 따라 DIRECT 또는 프록시가 결정됩니다. 문제를 진단하는 동안에는 잠시 Global 모드로 바꾸어 규칙 누락 여부를 분리해서 확인할 수 있습니다.
Clash의 포트 번호는 클라이언트 설정 화면에서 확인해야 합니다. 일반적으로 HTTP 및 mixed 포트가 별도로 표시되며, CLI는 대개 http://127.0.0.1:포트 형식의 프록시 주소를 사용합니다. 예를 들어 mixed 포트가 7890이라면 다음처럼 환경 변수를 설정할 수 있습니다.
Windows PowerShell에서는 다음과 같이 입력합니다.
환경 변수의 함정
터미널을 새로 열면 일회성으로 설정한 환경 변수가 사라질 수 있습니다. 지속적으로 사용하려면 셸 설정 파일이나 Windows 사용자 환경 변수에 등록하고, 잘못된 포트가 남아 있지 않은지도 확인하세요.
프록시 적용 여부는 Gemini CLI를 바로 재실행하기 전에 간단한 HTTPS 요청으로 테스트하는 것이 좋습니다. 아래 명령이 응답을 반환하면 해당 셸에서 최소한 프록시 경로가 열려 있다는 뜻입니다.
3직접 따라 하는 단계별 복구 절차
이제 여러 설정을 한꺼번에 바꾸지 말고, 아래 순서대로 한 단계씩 확인하세요. 각 단계가 끝날 때마다 Gemini CLI에 짧은 요청을 보내 결과를 기록하면 어떤 변경이 효과가 있었는지 쉽게 알 수 있습니다.
- Clash 실행 확인: 시스템 트레이 또는 메뉴 막대에서 Clash가 실행 중인지 확인하고, 현재 HTTP 또는 mixed 포트를 기록합니다.
- 노드 교체: 지연 시간이 낮고 최근 연결 성공률이 높은 일본, 싱가포르 또는 미국 노드를 선택합니다. 자동 선택 그룹이 불안정하면 잠시 수동 선택을 사용하세요.
- Global 모드 테스트: Rule 모드에서 문제가 생긴다면 일시적으로 Global 모드로 전환한 뒤 CLI를 다시 실행합니다.
- CLI 환경 변수 설정: 현재 터미널에
HTTP_PROXY와HTTPS_PROXY를 지정하고,echo명령으로 값이 적용되었는지 확인합니다. - DNS 확인: 도메인 조회가 실패하면 Clash의 DNS 설정을 확인하고, fake-ip 필터에 필요한 도메인이 잘못 제외되어 있지 않은지 살펴봅니다.
- 규칙 모드 복귀: Global 모드에서 정상화되었다면 Rule 모드로 돌아가 Gemini 관련 규칙을 추가한 뒤 다시 테스트합니다.
테스트 프롬프트는 복잡한 코드 작업보다 짧은 문장을 사용하는 것이 좋습니다. 예를 들어 “현재 연결 상태를 한 문장으로 설명해 줘”처럼 응답이 빠르게 끝나는 요청을 사용하면 연결 수립과 응답 생성 문제를 구분하기 쉽습니다.
정상화 판단 기준
짧은 요청이 반복해서 10~20초 안에 완료되고, 긴 출력에서도 중간에 연결이 끊기지 않으면 기본 프록시 경로는 정상으로 볼 수 있습니다.
4Gemini 관련 규칙과 DNS 최적화
Rule 모드에서 Gemini CLI가 멈춘다면 관련 도메인이 프록시 그룹으로 전달되는지 확인해야 합니다. 실제 사용 중인 Clash 배포판이나 공급자 설정에 따라 그룹 이름은 다르므로, 아래의 Gemini-Group를 자신의 프록시 그룹 이름으로 바꾸어 사용하세요.
규칙은 일반적인 GEOIP, FINAL 또는 광고 차단 규칙보다 위에 배치해야 합니다. 특정 도메인이 이미 DIRECT로 결정된 뒤에는 아래쪽에 추가한 프록시 규칙이 적용되지 않기 때문입니다. Clash의 연결 로그에서 실제 요청 도메인과 선택된 정책 그룹을 확인하면 규칙이 제대로 매칭되는지 알 수 있습니다.
DNS 오류와 fake-ip 점검
DNS가 로컬 네트워크를 통해 처리되면 도메인 조회는 성공하더라도 이후 연결이 잘못된 주소로 향하거나, 특정 API 도메인만 간헐적으로 실패할 수 있습니다. Clash의 DNS 설정에서 원격 DNS를 사용하고, nameserver와 fallback을 한 곳에만 의존하지 않도록 구성하세요. 다만 모든 환경에 동일한 DNS 값이 최선인 것은 아니므로 현재 네트워크에서 응답이 빠르고 안정적인 서버를 선택해야 합니다.
fake-ip 모드에서 특정 Google 서비스가 비정상적으로 동작한다면 fake-ip-filter에 해당 도메인을 무조건 추가하기보다, 로그를 확인한 뒤 필요한 항목만 예외 처리하세요. 설정을 바꾼 후에는 Clash의 DNS 캐시를 비우고 CLI 프로세스를 완전히 종료한 다음 새 터미널에서 다시 실행하는 것이 안전합니다.
5TUN 모드와 노드 안정성 점검
일부 Gemini CLI는 일반 브라우저처럼 시스템 프록시만 따르지 않거나, 하위 프로세스가 별도의 네트워크 라이브러리를 사용합니다. 이때 TUN 모드를 활성화하면 터미널과 하위 프로세스의 트래픽까지 Clash 규칙에 포함할 수 있습니다. Windows, macOS, Linux에서 TUN 모드를 켤 때는 가상 네트워크 인터페이스 설치와 관리자 권한이 필요할 수 있습니다.
- Windows: TUN 모드를 켠 뒤 관리자 권한 승인 창이 표시되는지 확인하고, 다른 VPN 어댑터와 충돌하지 않는지 점검합니다.
- macOS: 시스템 확장 또는 네트워크 권한을 허용하고, 회사 보안 프로그램이 가상 인터페이스를 차단하지 않는지 확인합니다.
- Linux: TUN 장치 권한과 라우팅 테이블을 확인합니다. 기존 VPN 서비스가 실행 중이면 우선 종료한 뒤 테스트하세요.
노드 품질도 시간 초과에 직접적인 영향을 줍니다. 단순히 표시된 핑이 낮다고 좋은 노드는 아닙니다. Gemini CLI는 인증, API 요청, 스트리밍 응답을 계속 유지하므로 순간적인 패킷 손실과 연결 재설정에 민감합니다. 같은 지역의 노드를 두세 개 비교하고, 짧은 요청과 긴 응답을 모두 테스트하는 것이 현실적인 방법입니다.
| 비교 항목 | 양호한 상태 | 교체를 고려할 상태 |
|---|---|---|
| 초기 연결 | 연속 테스트에서 빠르게 연결됨 | 첫 요청만 유난히 오래 걸림 |
| 스트리밍 | 출력이 끊김 없이 이어짐 | 중간에 멈춘 뒤 재연결 반복 |
| IP 품질 | 인증과 API 요청이 모두 정상 | 일부 Google 서비스만 반복 차단 |
| 공유 부하 | 시간대가 바뀌어도 속도 일정 | 저녁 시간에 지연과 손실 증가 |
6자주 하는 실수와 최종 확인
설정이 맞는데도 문제가 계속된다면 다음 실수를 확인하세요. 첫째, HTTPS_PROXY에 HTTPS 주소를 넣어야 한다고 생각하는 경우가 있지만, 로컬 Clash의 HTTP 프록시 포트는 HTTPS 요청도 처리할 수 있으므로 보통 http://127.0.0.1:7890 형식을 사용합니다. 둘째, ALL_PROXY와 HTTPS_PROXY에 서로 다른 잘못된 포트를 넣으면 라이브러리마다 다른 경로를 선택할 수 있습니다.
셋째, Clash의 연결 로그를 확인하지 않고 노드만 계속 바꾸는 것도 비효율적입니다. 로그에서 Gemini 또는 Google API 요청이 DIRECT로 나가는지, 올바른 그룹으로 전달되는지, DNS 단계에서 실패하는지를 먼저 살펴보세요. 넷째, 여러 VPN과 Clash TUN을 동시에 실행하면 라우팅 우선순위가 꼬일 수 있으므로 진단 중에는 하나의 프록시 도구만 남기는 것이 좋습니다.
- Clash가 실행 중이고 CLI가 사용하는 포트가 실제 포트와 일치하는가?
- 현재 터미널에
HTTP_PROXY와HTTPS_PROXY가 올바르게 적용되었는가? - Global 모드에서는 정상이며 Rule 모드에서만 실패하는가?
- Gemini 및 Google API 도메인이 올바른 프록시 그룹으로 전달되는가?
- DNS 캐시를 삭제한 뒤 새 터미널에서 다시 테스트했는가?
- TUN 모드와 다른 VPN 또는 가상 네트워크 어댑터가 충돌하지 않는가?
- 짧은 요청뿐 아니라 스트리밍이 긴 요청에서도 연결이 유지되는가?
대부분의 Gemini CLI 시간 초과 문제는 한 가지 설정만의 문제가 아니라 프록시 적용 범위, 규칙 우선순위, DNS 응답, 노드 안정성이 겹쳐서 발생합니다. Global 모드와 다른 노드로 기준선을 만든 뒤, 환경 변수와 규칙을 하나씩 되돌리는 방식으로 접근하면 불필요한 설정 변경을 줄일 수 있습니다. 그래도 특정 계정이나 특정 요청에서만 실패한다면 네트워크 문제가 아니라 API 할당량, 인증 토큰, 서비스 측 제한일 가능성도 함께 확인하세요.