Claude Code 접속 문제, Clash Verge로 터미널 설정하는 법

Claude Code 접속 문제의 원인부터 구분하기

Claude Code를 설치했는데 로그인 요청이 멈추거나, 명령을 실행할 때 연결이 끊기거나, 응답이 지나치게 오래 걸린다면 먼저 애플리케이션 자체와 네트워크 경로를 나누어 확인해야 합니다. Claude Code는 터미널에서 실행되는 개발 도구이므로 브라우저에서 정상적으로 웹사이트가 열린다는 사실만으로는 충분하지 않습니다. 브라우저는 운영체제 프록시나 자체 네트워크 설정을 사용할 수 있지만, 터미널 프로그램은 프록시 환경 변수를 읽거나 별도의 네트워크 라이브러리를 사용할 수 있습니다.

Clash Verge는 로컬에서 HTTP, HTTPS, SOCKS5 또는 mixed 프록시 포트를 열고, 설정에 포함된 규칙에 따라 연결을 직접 처리합니다. 일반적으로 mixed 포트는 127.0.0.1:7890으로 지정되지만 실제 값은 사용 중인 프로필과 Clash Verge 설정을 기준으로 확인해야 합니다. 터미널에서 프록시를 사용하려면 이 포트에 맞춰 HTTP_PROXY, HTTPS_PROXY 또는 ALL_PROXY 환경 변수를 설정해야 합니다.

증상	우선 확인할 항목	가능성이 높은 원인
브라우저는 열리지만 Claude Code만 실패	터미널의 프록시 변수와 DNS	명령줄 프로그램이 시스템 프록시를 사용하지 않음
로그인 주소가 열리지 않음	Clash Verge 실행 상태와 노드 연결	코어 중지, 잘못된 노드 또는 규칙 분기
요청 중 timeout 또는 reset 발생	프록시 포트와 현재 정책	포트 불일치, 불안정한 노드, DNS 또는 네트워크 제한
프록시 설정 후 다른 명령까지 실패	환경 변수 제거와 예외 주소	잘못된 포트, SOCKS와 HTTP 형식 혼동

Clash Verge 설치와 구독 등록 확인

Clash Verge와 Clash Verge Rev는 화면 구성과 메뉴 이름이 버전에 따라 다를 수 있지만 기본 흐름은 비슷합니다. 먼저 운영체제에 맞는 설치 파일을 설치하고 프로그램을 실행한 다음, Profiles 또는 설정 목록에서 제공받은 Clash 또는 mihomo 형식의 구독 URL을 등록합니다. 구독 주소는 노드와 정책 그룹을 내려받는 인증 정보이므로 공개 채팅, 터미널 로그, 화면 녹화에 전체 주소가 노출되지 않도록 주의해야 합니다.

Clash Verge를 실행하고 프로필 또는 Profiles 화면을 엽니다.
URL 추가 또는 구독 추가 기능을 선택한 뒤 구독 주소를 붙여 넣습니다.
이름을 구분하기 쉬운 값으로 지정하고 업데이트를 실행합니다.
가져온 프로필을 선택한 뒤 코어가 실행 중인지 확인합니다.
프록시 목록에서 실제로 연결할 노드 또는 정책 그룹을 선택합니다.

구독 업데이트가 실패하면 Claude Code 설정을 먼저 수정하지 않는 것이 좋습니다. 브라우저에서 구독 주소가 로그인 화면이나 HTML 오류 페이지를 반환하는지, HTTP 상태 코드가 401, 403, 404 또는 429인지 확인하세요. 응답을 받았지만 YAML 파싱 오류가 발생한다면 일반 VPN용 링크나 JSON 응답을 Clash 설정으로 가져온 상황일 수 있습니다. 서비스 제공자가 “Clash”, “Clash Meta” 또는 “mihomo” 형식을 구분해 제공한다면 현재 코어에 맞는 항목을 선택해야 합니다.

프로필 활성화와 코어 포트 확인

프로필을 등록했다고 해서 곧바로 네트워크가 프록시를 통과하는 것은 아닙니다. 프로필을 활성화하고 코어를 시작한 뒤, Settings 또는 General 화면에서 mixed port 값을 확인하세요. 예를 들어 다음과 같이 표시된다면 터미널 프록시는 7890 포트를 사용합니다.

mixed-port: 7890
allow-lan: false
mode: rule
log-level: info

allow-lan: false는 다른 기기의 접속을 허용하지 않는 일반적인 로컬 설정입니다. 같은 컴퓨터의 터미널에서 127.0.0.1로 접속하는 데에는 문제가 없습니다. 반대로 터미널에 192.168.x.x:7890을 입력하려면 LAN 수신 허용과 방화벽 설정이 추가로 필요하므로, 단일 컴퓨터에서 사용하는 경우에는 먼저 로컬 주소를 선택하는 편이 안전합니다.

프록시 모드와 기본 분기 설정

Clash Verge의 전역 모드는 보통 Rule, Global, Direct로 나뉩니다. Claude Code의 접속 문제를 점검할 때는 먼저 Rule 모드를 권장합니다. Rule 모드에서는 설정 파일의 rules가 위에서부터 적용되며, 특정 도메인이나 IP가 어느 정책 그룹으로 전달되는지 확인할 수 있습니다. Global 모드는 대부분의 트래픽을 하나의 선택된 프록시로 보내므로 진단에는 편리하지만, 모든 연결을 같은 노드로 보내기 때문에 일반 웹사이트나 사내 주소까지 불필요하게 우회할 수 있습니다.

모드	동작	Claude Code 점검 시 사용법
Rule	도메인과 IP 규칙에 따라 정책 선택	일상적인 기본값으로 사용하고 로그에서 매칭 결과 확인
Global	선택한 하나의 프록시 또는 그룹을 우선 사용	규칙 문제인지 노드 문제인지 빠르게 분리
Direct	가능한 연결을 프록시 없이 직접 연결	현재 네트워크에서 직접 접속 가능한지 비교 테스트

처음에는 Rule 모드에서 노드 선택 그룹이 실제로 프록시 노드를 가리키는지 확인합니다. 정책 그룹 이름이 “Proxy”, “节点选择”, “자동 선택” 등으로 표시될 수 있으며, 그룹 안에 노드가 하나도 없거나 모두 지연 시간 측정에 실패하면 터미널 환경 변수를 설정해도 요청이 성공하지 않습니다. Clash Verge의 Logs 화면에서 요청이 보이지 않는다면 터미널이 프록시를 사용하지 않는 것이고, 요청은 보이지만 실패한다면 선택된 노드, DNS, 서버 응답을 추가로 확인해야 합니다.

터미널에서 Clash Verge 프록시 연결 시험하기

이제 실제로 손을 움직여 연결 경로를 확인합니다. 아래 예시의 포트 번호는 반드시 Clash Verge에서 확인한 mixed port로 바꾸세요. HTTP 프록시 포트에는 보통 http://127.0.0.1:7890 형식을 사용합니다. SOCKS5 포트를 별도로 사용하는 경우에는 socks5://127.0.0.1:7891처럼 실제 포트와 프로토콜을 일치시켜야 합니다.

macOS와 Linux 셸 환경 변수 설정

zsh 또는 bash를 사용하는 환경에서는 현재 터미널 세션에 다음 변수를 임시로 적용할 수 있습니다. 이렇게 설정하면 새로 연 터미널에는 자동으로 적용되지 않으므로 테스트 범위를 통제하기 쉽습니다.

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"

curl -I --connect-timeout 10 https://example.com

위 테스트가 성공하고 Clash Verge 로그에 요청이 나타난다면 터미널이 로컬 프록시를 사용하고 있는 것입니다. curl이 설치되어 있다면 응답 헤더의 상태 코드와 전체 소요 시간을 함께 확인할 수 있습니다. 407 Proxy Authentication Required가 나타나면 로컬 Clash 포트에 인증을 요구하는 설정이 있는지 확인하고, connection refused라면 코어가 꺼져 있거나 포트 번호가 잘못된 경우가 많습니다.

테스트가 끝난 뒤 프록시를 끄려면 현재 셸에서 변수를 제거합니다.

unset HTTP_PROXY HTTPS_PROXY ALL_PROXY
unset http_proxy https_proxy all_proxy

Windows PowerShell 환경 변수 설정

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

curl.exe -I --connect-timeout 10 https://example.com

PowerShell을 닫으면 이 설정은 사라집니다. 지속적으로 사용하려면 셸 프로필이나 운영체제 환경 변수에 추가할 수 있지만, 회사 네트워크와 내부 Git 서버까지 외부 프록시로 보내는 문제가 생길 수 있으므로 먼저 임시 설정으로 동작을 확인하세요. 회사나 학교의 내부 도메인은 NO_PROXY 예외 목록에 넣어야 할 수도 있습니다.

$env:NO_PROXY = "localhost,127.0.0.1,.internal.example"

Claude Code가 실행된 터미널은 환경 변수를 읽은 뒤 프로세스를 시작해야 합니다. 이미 실행 중인 세션이나 IDE 내장 터미널은 이전 환경을 유지할 수 있으므로, 변수를 설정한 후 새 터미널을 열거나 해당 프로세스를 다시 시작하세요. 반대로 시스템 전체 프록시를 켰더라도 명령줄 프로그램이 이를 읽는다는 보장은 없으므로, 환경 변수와 Clash 로그를 함께 확인하는 것이 정확합니다.

로그인 실패와 연결 끊김을 순서대로 해결하기

프록시를 지정한 뒤에도 로그인에 실패한다면 먼저 인증 상태와 네트워크 상태를 분리하세요. 로그인 페이지 자체가 열리지 않는다면 Clash 로그, DNS와 노드 연결을 우선 확인합니다. 로그인 페이지는 열리지만 인증 완료 후 터미널로 돌아오지 않는다면 브라우저 콜백, 로컬 포트, 보안 프로그램 또는 셸 세션 문제가 관련될 수 있습니다. 이 경우 오류 메시지 전체를 기록하고, 토큰이나 인증 코드가 포함된 화면은 공유하지 마세요.

Clash 로그에 요청이 없음: HTTP_PROXY와 HTTPS_PROXY 이름, 포트 번호, 프로세스 재시작 여부를 확인합니다.
요청은 기록되지만 timeout: 현재 정책 그룹의 노드를 바꾸고, Rule과 Global에서 결과가 달라지는지 비교합니다.
TLS 또는 인증서 오류: 시스템 시간, 운영체제 인증서 저장소, HTTPS 검사 기능과 보안 소프트웨어를 확인합니다.
로그인 후 요청만 실패: 인증 도메인과 API 도메인이 서로 다른 규칙을 사용하는지 확인하고, 관련 연결이 Direct로 빠지지 않는지 살펴봅니다.
간헐적인 연결 끊김: 하나의 노드만 반복해서 사용하지 말고 다른 노드의 패킷 손실과 응답 시간을 비교합니다.

설정 변경은 다음 순서로 진행하는 것이 안전합니다. 첫째, Clash Verge 코어와 mixed 포트가 실행 중인지 확인합니다. 둘째, curl로 동일한 터미널 세션에서 HTTPS 요청을 시험합니다. 셋째, Rule 모드의 정책 로그를 확인합니다. 넷째, Claude Code를 완전히 종료한 후 같은 셸에서 다시 실행합니다. 이 과정을 거치면 “프록시 자체의 문제”, “터미널이 프록시를 읽지 않는 문제”, “Claude Code 인증 단계의 문제”를 비교적 명확하게 나눌 수 있습니다.