국내 개발자를 위한 Gemini CLI와 Clash 안정 접속 설정법

Gemini CLI와 Clash의 역할부터 구분하기

Gemini CLI는 개발자가 터미널에서 자연어 명령을 입력하고 코드 분석, 파일 수정, 테스트 실행과 같은 작업을 수행하도록 돕는 AI 코딩 도구입니다. 브라우저에서 사용하는 웹 서비스와 달리 터미널 프로세스가 직접 네트워크 연결을 만들기 때문에, 운영체제 프록시 설정을 읽는지와 환경 변수에 지정된 프록시를 사용하는지가 중요합니다. 국내 네트워크에서 로그인 페이지, API 요청 또는 모델 응답 스트림이 간헐적으로 중단된다면 Gemini CLI 자체의 오류가 아니라 DNS, TLS 연결, 프록시 미적용 또는 Clash 규칙 문제일 수 있습니다.

Clash는 Gemini CLI를 대신하는 프로그램이 아닙니다. mihomo와 같은 코어가 로컬 포트에서 HTTP·HTTPS·SOCKS 연결을 받아 규칙에 따라 직접 연결하거나 프록시 노드로 전달하고, Gemini CLI는 그 로컬 포트를 사용하도록 설정하는 구조입니다. 따라서 먼저 Clash 코어가 정상적으로 실행 중인지 확인한 다음 Gemini CLI 프로세스에 프록시 주소를 전달해야 합니다. GUI에서 “시스템 프록시 사용”을 켰다고 해서 모든 명령줄 프로그램이 자동으로 프록시를 사용하는 것은 아닙니다.

Clash에서 안정적인 기본 프로필 준비하기

FlClash, Clash Verge Rev, Clash for Windows 계열 클라이언트에서 먼저 사용할 프로필을 활성화하고 mihomo 코어가 실행 중인지 확인합니다. 메뉴 이름은 클라이언트마다 다르지만 일반적으로 “프로필”, “설정”, “포트” 또는 “코어” 화면에서 현재 상태를 볼 수 있습니다. 이 글의 예시는 로컬 호스트의 7890 포트를 사용하는 경우입니다. 실제 포트가 7897, 7890 또는 다른 값으로 설정되어 있다면 모든 명령어에서 자신의 값을 사용해야 합니다.

mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
external-controller: 127.0.0.1:9090

mixed-port는 HTTP와 SOCKS5 요청을 모두 받을 수 있는 포트입니다. Gemini CLI가 HTTP 프록시 형식을 요구할 때도 이 포트를 사용할 수 있어, 처음 구성할 때 HTTP 전용 포트와 SOCKS 포트를 따로 구분하지 않아도 됩니다. external-controller는 클라이언트와 코어를 제어하기 위한 API 주소이므로 Gemini CLI의 프록시 주소로 사용하면 안 됩니다. 또한 allow-lan: false는 다른 기기가 컴퓨터의 프록시 포트를 임의로 사용하지 못하도록 하는 기본 보안값입니다.

AI 서비스 연결에 적용할 규칙

모든 트래픽을 무조건 프록시로 보내는 global 모드는 문제의 원인을 확인할 때는 편리하지만, 국내 개발 환경에서는 패키지 저장소, 사내 Git 서버, 로컬 도구까지 불필요하게 우회할 수 있습니다. 평소에는 rule 모드를 사용하고 필요한 도메인만 정책 그룹으로 보내는 편이 관리하기 쉽습니다. Gemini CLI가 실제로 접속하는 호스트는 인증 방식, CLI 버전과 서비스 변경에 따라 달라질 수 있으므로 특정 도메인을 영구적으로 단정하기보다 Clash 로그에서 확인한 호스트를 기준으로 규칙을 추가하세요.

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

위 예시의 AI는 실제로 존재하는 프록시 그룹 이름으로 바꿔야 합니다. 구독 설정에 “노드 선택”, “자동 선택” 또는 “Proxy”만 있다면 그 이름을 정확히 확인하세요. 규칙은 위에서부터 평가되므로 더 구체적인 도메인 규칙을 일반적인 규칙보다 위에 배치합니다. 다만 인증이나 API 요청에 사용되는 호스트가 로그에 나타나지 않는다면 규칙을 계속 추측하지 말고 연결 로그와 DNS 요청을 함께 확인해야 합니다.

터미널에서 Gemini CLI 프록시를 직접 설정하기

이제 동작을 재현할 수 있는 순서로 설정합니다. 한 번에 여러 값을 바꾸면 실패 원인을 찾기 어려우므로 Clash 포트 확인, 환경 변수 설정, 연결 테스트, Gemini CLI 실행 순서를 지키는 것이 좋습니다.

1. Clash 클라이언트에서 mihomo 코어를 시작하고 활성 프로필을 선택합니다.
2. 포트 화면에서 로컬 수신 주소가 127.0.0.1:7890인지 확인합니다. 포트가 다르면 실제 값을 기록합니다.
3. Clash의 연결 로그를 열어 새 요청이 표시되는지 확인할 준비를 합니다.
4. 현재 터미널 세션에만 프록시 환경 변수를 설정합니다.
5. 간단한 HTTPS 요청으로 DNS와 TLS 연결을 확인한 뒤 Gemini CLI를 실행합니다.

Windows PowerShell 설정

PowerShell에서는 다음과 같이 현재 창에만 변수를 지정할 수 있습니다. 이 방식은 다른 프로그램 전체에 영향을 주지 않으며 테스트 후 창을 닫으면 설정이 사라집니다.

$env:HTTP_PROXY="http://127.0.0.1:7890"
$env:HTTPS_PROXY="http://127.0.0.1:7890"
$env:NO_PROXY="127.0.0.1,localhost"
gemini

Windows에서 HTTP_PROXY와 HTTPS_PROXY를 모두 대문자로 지정하는 이유는 도구마다 읽는 환경 변수 이름이 다르기 때문입니다. 일부 런타임은 소문자 변수도 확인하므로 필요할 때 아래처럼 함께 지정할 수 있습니다.

$env:http_proxy=$env:HTTP_PROXY
$env:https_proxy=$env:HTTPS_PROXY

macOS와 Linux 설정

zsh 또는 bash에서는 export를 사용합니다. 영구 적용보다 먼저 현재 셸에서 테스트하는 것을 권장합니다.

export HTTP_PROXY="http://127.0.0.1:7890"
export HTTPS_PROXY="http://127.0.0.1:7890"
export NO_PROXY="127.0.0.1,localhost"
gemini

프록시를 해제하려면 다음 명령을 실행합니다. 여러 셸을 사용한다면 한 셸에서 해제했다고 다른 터미널의 환경 변수까지 바뀌지는 않습니다.

unset HTTP_PROXY HTTPS_PROXY http_proxy https_proxy
unset NO_PROXY no_proxy

Gemini CLI 실행 전 연결 확인

먼저 프록시 포트가 열려 있는지 확인합니다. Windows에서는 PowerShell의 Test-NetConnection, macOS와 Linux에서는 curl을 사용할 수 있습니다.

Test-NetConnection 127.0.0.1 -Port 7890

curl -I --connect-timeout 10 \
  -x "http://127.0.0.1:7890" \
  "https://generativelanguage.googleapis.com"

이 테스트의 목적은 특정 응답 본문을 받는 것이 아니라 로컬 포트가 요청을 받아 외부 HTTPS 연결을 시도하는지 확인하는 것입니다. HTTP 상태 코드가 401 또는 404로 반환되어도 네트워크 연결 자체는 성립했을 수 있습니다. 반대로 Could not connect to server, Connection refused가 나오면 Gemini CLI 설정을 수정하기 전에 Clash 코어, 포트 번호와 방화벽을 확인해야 합니다.

DNS, TUN, 인증을 함께 점검하는 방법

Gemini CLI의 연결이 시작되지만 응답 중간에 멈추거나 로그인 콜백이 실패한다면 DNS와 인증 경로를 분리해서 확인해야 합니다. Clash의 프록시 연결이 성공해도 로컬 DNS가 먼저 잘못된 주소를 반환하면 요청이 올바른 서버에 도달하지 못할 수 있습니다. 반대로 TUN을 켠 상태에서 시스템 DNS 하이재킹과 운영체제 VPN이 동시에 동작하면 같은 도메인이 서로 다른 경로로 해석될 수 있습니다.

처음에는 TUN을 끄고 환경 변수 기반의 시스템 프록시 모드로 테스트하는 편이 좋습니다. 이 방식은 Gemini CLI처럼 프록시 변수를 읽는 프로그램의 동작을 명확히 관찰할 수 있습니다. 시스템 프록시를 읽지 않는 보조 도구, Docker 컨테이너, 특정 개발 서버까지 같은 정책으로 보내야 할 때만 TUN을 고려하세요. TUN을 활성화할 경우 자동 라우팅, DNS 하이재킹, IPv6 처리와 운영체제의 다른 VPN 프로그램이 서로 충돌하지 않는지 확인해야 합니다.

인증 토큰과 API 키는 프록시 설정과 별개의 보안 항목입니다. 터미널 명령, 셸 기록, CI 로그, 화면 공유에 GEMINI_API_KEY나 OAuth 토큰이 노출되지 않도록 주의하세요. 구독 URL과 마찬가지로 토큰이 포함된 환경 변수 출력 결과를 그대로 공유하면 안 됩니다. 회사 프로젝트를 분석할 때는 소스 코드, 비밀 키, 내부 주소가 외부 AI 서비스로 전송될 수 있는지 조직의 정책을 먼저 확인해야 합니다.

안정적인 운영을 위한 최종 체크리스트

• 포트: Gemini CLI에 지정한 주소가 실제 Clash의 mixed-port와 일치하는지 확인합니다.
• 범위: NO_PROXY에 localhost, 127.0.0.1과 사내 개발 주소를 필요에 따라 추가합니다.
• 규칙: 로그에서 확인한 최소 도메인만 프록시로 보내고 나머지는 기존 정책을 유지합니다.
• 노드: 자동 선택만 믿지 말고 지연 시간, 패킷 손실, 장시간 응답 안정성을 비교합니다.
• DNS: TUN, 운영체제 DNS, 다른 VPN 앱을 동시에 변경하지 말고 한 번에 한 항목씩 테스트합니다.
• 인증: 로그인 실패 시 프록시를 무작정 바꾸기보다 브라우저 콜백, 시간 설정, 계정 정책과 토큰 상태를 확인합니다.
• 업데이트: Gemini CLI와 Clash 클라이언트를 업데이트하기 전 현재 환경 변수와 프로필을 백업합니다.
• 보안: API 키, OAuth 토큰, 회사 소스 코드를 로그와 공개 저장소에 남기지 않습니다.

자주 묻는 질문