Claude Code를 처음 실행했는데 로그인 페이지가 열리지 않거나, 인증은 완료됐지만 터미널에서 요청이 멈추는 경우가 있습니다. 이때는 Claude Code 자체와 Clash Verge를 한꺼번에 의심하기보다, 구독 설정 → 노드 선택 → Clash 모드 → 터미널의 프록시 환경 변수 → 로그 순서로 범위를 좁히는 것이 가장 빠릅니다. 이 글에서는 Clash Verge Rev와 mihomo 계열 코어를 기준으로 설명하지만, 메뉴 이름이 조금 다른 Clash Verge, Clash for Windows에서도 같은 원리를 적용할 수 있습니다.
| 확인 항목 | 정상 상태 | 문제가 있을 때 |
|---|---|---|
| 프로필 | 구독 설정이 선택되어 있고 노드 목록이 표시됨 | 구독 업데이트 또는 새 프로필 가져오기 |
| 노드 | 지연 테스트 결과가 나오고 실제 연결 가능 | 다른 노드로 교체한 뒤 직접 접속 테스트 |
| Clash 모드 | Rule 또는 진단 목적의 Global | Direct로 되어 있으면 외부 요청이 우회되지 않음 |
| 터미널 환경 변수 | HTTP_PROXY, HTTPS_PROXY가 로컬 포트를 가리킴 | 변수 오타, 잘못된 포트, 오래된 프록시 값 수정 |
| 로그 | Claude 관련 도메인 요청이 특정 정책 그룹으로 전달됨 | DNS, TLS, 연결 거부, timeout 원인을 구분 |
1. 시작 전에 알아둘 연결 구조
Claude Code는 터미널에서 실행되는 개발 도구이므로 브라우저와 연결 방식이 항상 같지는 않습니다. 브라우저는 운영체제의 시스템 프록시 설정을 자동으로 따르는 경우가 많지만, 터미널 프로그램은 환경 변수나 자체 네트워크 라이브러리 설정을 사용하는 경우가 많습니다. 따라서 Clash Verge에서 시스템 프록시를 켰는데도 Claude Code가 연결되지 않는다면, 터미널 프로세스가 로컬 프록시 주소를 전달받았는지 별도로 확인해야 합니다.
일반적인 흐름은 다음과 같습니다. Claude Code가 HTTPS 요청을 만들면 터미널 환경에 지정된 프록시 주소로 요청을 보냅니다. Clash의 혼합 포트는 HTTP 프록시와 SOCKS5 요청을 함께 받을 수 있고, mihomo 코어는 현재 선택된 정책 그룹과 규칙에 따라 직접 연결하거나 노드를 거칩니다. 여기서 포트 번호는 클라이언트마다 다를 수 있습니다. Clash Verge Rev에서 흔히 보이는 기본값이 7897이라고 해도 모든 설치 환경이 같지는 않으므로, 반드시 화면의 포트 설정을 기준으로 사용하세요.
Clash의 시스템 프록시를 켜는 것과 Claude Code의 터미널 프록시를 설정하는 것은 서로 다른 단계입니다. 브라우저가 정상이라고 해서 터미널도 자동으로 정상이라고 판단하지 마세요.
2. Clash Verge에서 구독과 노드 확인하기
먼저 Clash Verge를 열고 설정 또는 Profiles 화면으로 이동합니다. 사용하는 구독 프로필이 목록에 존재하고 현재 선택된 상태인지 확인하세요. 프로필이 보이지 않거나 마지막 업데이트 시간이 오래됐다면 구독 주소를 다시 입력하기보다 먼저 업데이트 버튼을 눌러 보십시오. 업데이트가 실패하면 주소가 잘렸거나 만료됐을 가능성이 있으므로 서비스 제공 화면에서 구독 URL을 다시 복사해야 합니다.
- 프로필 선택설정 목록에서 실제로 사용할 구독을 선택합니다. 목록에 이름만 있고 노드가 없다면 프로필을 정상적으로 읽지 못한 상태입니다.
- 노드 목록 열기프록시 화면에서 수동 선택, 노드 선택, PROXY와 같은 그룹을 찾습니다. 구독에 따라 그룹 이름은 달라질 수 있습니다.
- 노드 테스트지연 테스트를 실행하고 timeout이 아닌 노드를 하나 선택합니다. 숫자가 가장 낮은 노드가 항상 가장 안정적인 것은 아니므로 실제 요청도 확인해야 합니다.
- 정책 그룹 확인현재 선택된 노드가 Claude 관련 트래픽을 처리하는 정책 그룹에 연결되어 있는지 확인합니다. 그룹을 선택하지 않으면 노드 목록이 있어도 요청이 원하는 출구로 나가지 않을 수 있습니다.
모든 노드가 timeout이면 Claude Code 설정부터 수정하지 마세요. 먼저 구독 만료 여부, 시스템 시간, 로컬 네트워크, 다른 노드의 연결 상태를 차례로 확인해야 합니다. 특정 노드만 실패한다면 노드 문제일 가능성이 높고, 모든 노드에서 실패한다면 구독이나 네트워크 경로를 의심하는 편이 합리적입니다.
3. Rule, Global, Direct 중 어떤 모드를 선택할까
첫 설정에서는 Rule 모드를 기본값으로 권장합니다. Rule 모드는 도메인, IP, GeoSite 등의 규칙을 위에서부터 대조해 각 연결을 정책 그룹으로 보냅니다. 구독이 제공하는 규칙에 Claude 관련 도메인이 포함되어 있다면 해당 요청은 지정된 프록시 그룹으로 전달되고, 규칙에 없으면 마지막 MATCH 정책이 적용됩니다.
연결 원인을 빠르게 확인해야 할 때는 잠시 Global 모드로 전환할 수 있습니다. 이 모드에서는 일반적인 분류 규칙을 건너뛰고 GLOBAL 그룹에서 선택한 노드로 대부분의 연결을 보냅니다. Rule 모드에서는 실패하지만 Global 모드에서는 성공한다면 규칙 또는 정책 그룹의 문제일 수 있습니다. 반대로 Global에서도 실패하면 노드, DNS, 인증, 네트워크 자체를 더 집중적으로 확인해야 합니다.
Direct 모드는 모든 연결을 직접 전송하는 진단용 대조군입니다. Direct에서 Claude Code가 정상적으로 연결되지 않는다고 해서 반드시 Clash가 고장난 것은 아닙니다. Direct는 우회 경로를 사용하지 않으므로 해당 서비스가 현재 네트워크에서 직접 접근 가능한지 확인하는 용도로만 사용하세요.
| 모드 | Claude Code 진단에서의 용도 | 주의점 |
|---|---|---|
| Rule | 평상시 사용. 규칙과 정책 그룹에 따라 요청 처리 | Claude 도메인이 올바른 그룹에 매칭되는지 확인 |
| Global | 노드 자체와 전체 우회 경로를 빠르게 테스트 | 모든 트래픽이 노드를 거치므로 테스트 후 Rule로 복귀 |
| Direct | 프록시 없이 직접 접근 가능한지 비교 | 접속 제한 환경에서는 실패하는 것이 정상일 수 있음 |
4. 터미널에 프록시 환경 변수 설정하기
Clash Verge의 시스템 프록시가 켜져 있어도 Claude Code가 사용하는 터미널 세션에 프록시 변수가 없을 수 있습니다. 이 경우 Clash의 혼합 포트 또는 SOCKS 포트를 환경 변수에 지정합니다. 아래 예시의 7897은 예시일 뿐이며, Clash Verge의 일반 설정에서 실제 Mixed Port 값을 확인해 바꾸세요.
Windows PowerShell에서 설정
PowerShell을 새로 열고 다음 명령을 실행합니다. 새로 실행하는 Claude Code 프로세스가 이 값을 상속받도록 하는 방식입니다.
$env:HTTP_PROXY="http://127.0.0.1:7897"
$env:HTTPS_PROXY="http://127.0.0.1:7897"
$env:ALL_PROXY="socks5://127.0.0.1:7898"혼합 포트만 사용할 경우 HTTP_PROXY와 HTTPS_PROXY만 먼저 지정해도 됩니다. SOCKS 포트는 클라이언트 설정에서 실제 값을 확인해야 하며, 존재하지 않는 포트를 입력하면 연결이 즉시 거부됩니다. 영구 환경 변수로 등록할 수도 있지만, 회사 네트워크나 다른 프록시를 사용할 때 예상치 못한 영향을 줄 수 있으므로 먼저 현재 터미널 세션에서만 테스트하는 편이 안전합니다.
macOS와 Linux 셸에서 설정
zsh 또는 bash 터미널에서는 다음처럼 입력합니다.
export HTTP_PROXY="http://127.0.0.1:7897"
export HTTPS_PROXY="http://127.0.0.1:7897"
export ALL_PROXY="socks5://127.0.0.1:7898"환경 변수 이름의 대소문자를 구분하는 프로그램도 있으므로 필요하면 소문자 변수도 함께 설정할 수 있습니다.
export http_proxy="$HTTP_PROXY"
export https_proxy="$HTTPS_PROXY"
export all_proxy="$ALL_PROXY"설정이 적용됐는지는 다음 명령으로 확인합니다.
echo $HTTPS_PROXYWindows PowerShell에서는 $env:HTTPS_PROXY를 입력합니다. 결과가 비어 있거나 예전 포트가 표시되면 Claude Code를 다시 실행하기 전에 변수를 수정해야 합니다. 이미 열려 있던 터미널은 이전 환경을 유지할 수 있으므로, Clash를 켠 뒤 새 터미널 창을 열어 테스트하는 것이 좋습니다.
프록시 주소에 사용자 이름이나 비밀번호를 직접 포함하지 말고, 터미널 기록과 공유 스크립트에 구독 URL을 넣지 마세요. 문제가 해결된 뒤에는 더 이상 필요하지 않은 임시 환경 변수를 제거하는 것도 잊지 마세요.
5. Claude Code 요청이 실제로 Clash를 통과하는지 확인
환경 변수를 설정한 뒤 바로 복잡한 프로젝트 명령을 실행하기보다, 먼저 간단한 HTTPS 요청으로 경로를 확인하세요. PowerShell에서는 다음처럼 프록시를 명시해 테스트할 수 있습니다.
curl.exe -I -x http://127.0.0.1:7897 https://api.anthropic.commacOS와 Linux에서도 비슷한 curl 명령을 사용할 수 있습니다. 응답 코드가 401 또는 404처럼 인증과 관련된 결과로 돌아오는 것은 네트워크 연결 자체가 성립했다는 뜻일 수 있습니다. 반대로 연결 거부, timeout, 프록시 터널 생성 실패가 표시되면 포트나 노드 경로를 먼저 확인해야 합니다. 단순히 상태 코드만 보고 API 키 문제와 네트워크 문제를 섞어 판단하지 마세요.
그다음 Clash Verge의 로그 화면을 열어 테스트 시각에 새로운 연결 기록이 생기는지 봅니다. 로그에서 대상 도메인, 매칭된 규칙, 사용된策略 그룹, 오류 유형을 확인할 수 있습니다. 요청이 로그에 전혀 나타나지 않으면 터미널이 다른 프록시 설정을 사용하거나 프록시를 전혀 사용하지 않는 상태일 수 있습니다. 요청은 보이지만 timeout이라면 노드 또는 원격 연결 문제에 가깝습니다. 특정 도메인이 DIRECT로 처리되고 있다면 Rule 모드의 규칙과 마지막 MATCH 정책을 점검하세요.
Claude Code를 실행할 때 인증 브라우저가 열리지 않는 경우에는 브라우저 로그인과 터미널 API 요청을 분리해서 확인해야 합니다. 브라우저 인증이 끝났더라도 터미널 프로세스가 별도의 환경 변수를 사용하면 후속 요청은 실패할 수 있습니다. 인증 후에는 같은 터미널에서 환경 변수가 유지되는지 확인하고, 필요하면 Claude Code를 종료한 뒤 프록시 변수가 설정된 새 터미널에서 다시 실행하세요.
6. 오류 유형별로 원인 좁히기
연결 시간 초과 또는 connection refused
timeout은 노드가 응답하지 않거나 중간 구간에서 패킷이 돌아오지 않았다는 뜻입니다. 먼저 다른 노드를 선택하고 Global 모드에서 동일한 HTTPS 요청을 반복합니다. connection refused는 대상 포트에 연결할 수 없다는 의미일 수 있지만, 로컬 Clash 포트가 틀렸을 때도 발생합니다. 127.0.0.1과 포트 번호가 실제 설정과 일치하는지 확인하세요.
TLS 또는 인증서 관련 오류
시스템 시간이 크게 어긋났거나, 네트워크가 HTTPS 연결을 중간에서 변경하거나, 노드가 불안정하면 TLS 핸드셰이크가 실패할 수 있습니다. 먼저 운영체제의 날짜와 시간을 자동 동기화하고, 다른 노드에서 재시험합니다. 보안 검증을 무조건 끄는 방식으로 해결하려 하지 마세요. 원인을 확인하지 않은 채 인증서 검증을 약화하면 개발 도구의 통신 안전성이 떨어질 수 있습니다.
401, 403 또는 인증 실패
이 응답은 프록시 경로가 살아 있어도 계정 인증이나 API 권한이 유효하지 않을 때 나타날 수 있습니다. 환경 변수와 Clash 노드가 정상이라면 Claude Code 로그인 상태, API 키의 만료 여부, 사용 중인 계정과 서비스 권한을 확인하세요. 프록시를 바꾸는 것만으로 인증 정보가 복구되지는 않습니다.
DNS 조회 실패
도메인 이름을 IP 주소로 바꾸는 단계에서 실패하면 요청이 노드까지 도달하지 못할 수 있습니다. Clash의 DNS 설정, fake-ip 또는 redir-host 동작, 현재 네트워크의 DNS 응답을 로그에서 확인합니다. DNS 모드를 바꾼 뒤에는 코어를 다시 로드하고, 브라우저 캐시가 아니라 터미널에서 다시 테스트해야 합니다.
Rule 모드에서 실패하면 Global 모드와 다른 노드로 비교합니다. Global에서도 실패하면 로컬 포트, 노드, DNS를 확인합니다. HTTPS 요청은 성공하지만 Claude Code만 실패하면 인증 상태와 터미널 환경 변수를 확인합니다.
7. 자주 묻는 질문
Clash Verge에서 시스템 프록시를 켰는데 Claude Code는 왜 연결되지 않나요?
터미널 프로그램이 운영체제의 시스템 프록시를 자동으로 사용하지 않을 수 있기 때문입니다. Clash의 실제 혼합 포트를 확인한 뒤 HTTP_PROXY와 HTTPS_PROXY를 현재 터미널 세션에 설정하고, 새 터미널에서 Claude Code를 다시 실행하세요.
Rule 모드와 Global 모드 중 어느 것을 계속 사용해야 하나요?
평소에는 Rule 모드를 권장합니다. 규칙에 따라 필요한 요청만 프록시를 통과시키기 때문입니다. Global은 노드와 우회 경로를 진단할 때 잠시 사용하고, 테스트가 끝나면 Rule로 되돌리세요.
프록시 포트는 7890으로 고정하면 되나요?
아닙니다. 클라이언트와 설치 환경에 따라 7890, 7897 등 값이 다를 수 있습니다. Clash Verge의 일반 설정에서 Mixed Port와 SOCKS Port를 직접 확인하고, 환경 변수에도 같은 값을 입력해야 합니다.
브라우저는 정상인데 터미널 요청만 실패하면 무엇을 먼저 확인하나요?
새 터미널에서 프록시 환경 변수의 값과 포트를 확인한 뒤, curl로 HTTPS 요청을 테스트하세요. Clash 로그에 요청이 나타나는지 함께 보면 터미널 설정 문제와 노드 문제를 빠르게 구분할 수 있습니다.
Clash Verge 설정을 시작하기
구독과 노드를 준비한 뒤, 사용하는 운영체제에 맞는 Clash 클라이언트를 내려받아 연결 절차를 진행하세요. 포트와 프록시 모드는 클라이언트 화면에 표시된 실제 값을 기준으로 설정하면 됩니다.