Claude Code를 설치한 뒤 로그인 화면이 열리지 않거나 명령 실행이 멈춘다면, 먼저 Clash Verge의 노드 상태와 터미널 프록시 설정을 확인해야 합니다. 브라우저에서 웹페이지가 열리는 것만으로는 Claude Code가 프록시를 사용한다고 보장할 수 없습니다. Claude Code는 터미널 프로세스에서 실행되며, 운영체제의 시스템 프록시보다 HTTP_PROXY, HTTPS_PROXY, ALL_PROXY 같은 환경 변수를 우선적으로 참조하는 경우가 많기 때문입니다.
이 글에서는 2026년 기준으로 Clash Verge에 구독을 가져온 뒤, 시스템 프록시와 TUN 모드의 차이를 확인하고, Windows PowerShell·macOS 터미널·Linux 셸에서 Claude Code 트래픽을 프록시로 보내는 순서를 설명합니다. 특정 노드나 서비스 제공자를 전제로 하지 않고, 실제 연결 여부를 명령어와 로그로 확인하는 데 초점을 맞춥니다.
Claude Code 연결이 실패하는 구조부터 이해하기
Claude Code의 연결은 단순히 프로그램을 설치하는 한 단계가 아닙니다. 터미널에서 명령을 실행하면 먼저 운영체제가 프로세스를 만들고, Claude Code가 인증 정보와 API 엔드포인트를 확인한 다음, DNS 조회와 HTTPS 연결을 수행합니다. 이 중 하나라도 프록시 경로를 사용하지 못하면 로그인 페이지가 열리지 않거나, 인증 코드는 표시되지만 최종 확인 단계에서 시간 초과가 발생할 수 있습니다.
Clash Verge에서 확인해야 할 경로는 다음과 같습니다.
- 구독 링크가 정상적으로 다운로드되고 노드 목록이 표시되는지 확인합니다.
- 프록시 그룹에서 실제로 사용할 노드를 선택합니다.
- 시스템 프록시 또는 TUN 모드를 켭니다.
- 터미널이 Clash의 수신 포트로 연결되는지 확인합니다.
- Claude Code를 실행하고 Clash 연결 로그에서 해당 요청을 확인합니다.
Clash Verge의 버전과 프로필에 따라 혼합 포트가 7890, 7897 등으로 다를 수 있습니다. 포트를 추측하지 말고 Clash Verge의 설정 화면에서 현재 HTTP 또는 혼합 포트를 확인해야 합니다. 포트가 잘못되면 환경 변수를 올바르게 입력해도 Connection refused 또는 연결 시간 초과가 발생합니다.
| 확인 항목 | 정상 상태 | 문제 발생 시 증상 |
|---|---|---|
| 구독 프로필 | 노드와 전략 그룹이 표시됨 | 노드 0개, 파싱 실패 |
| 현재 프록시 그룹 | 사용 가능한 노드가 선택됨 | DIRECT 또는 연결 불가 노드 선택 |
| 혼합 포트 | 로컬 포트가 LISTEN 상태 | 포트 거부, 연결 시간 초과 |
| 터미널 환경 변수 | Claude Code 프로세스가 프록시 주소를 읽음 | 브라우저는 되지만 터미널만 실패 |
| Clash 연결 로그 | 도메인 요청과 선택 노드가 표시됨 | 요청 자체가 로그에 나타나지 않음 |
Clash Verge에 구독을 가져오고 노드 선택하기
먼저 Clash Verge의 「구독」 또는 프로필 관리 화면에서 서비스 제공자가 발급한 Clash Meta 호환 구독 링크를 추가합니다. 링크를 붙여넣은 뒤 이름을 지정하고 저장한 다음 업데이트를 실행하세요. 정상적으로 처리되면 프로필 안에 프록시 노드, proxy-groups, 규칙이 표시됩니다. Claude Code용으로는 단순히 노드가 보이는 것보다 전략 그룹이 실제 노드를 가리키는지가 중요합니다.
구독 업데이트가 실패하면 브라우저에서 링크를 직접 열어 응답을 확인합니다. YAML 설정이나 Base64로 인코딩된 구독 내용이 반환되어야 하며, 로그인 HTML 페이지나 만료 안내가 반환되면 Clash Verge의 문제가 아닙니다. 또한 공급자가 sing-box 전용 형식만 제공하는 경우에는 Clash Meta 형식으로 변환된 링크를 요청해야 합니다. 클라이언트가 구독을 읽었더라도 노드 수가 0개라면 변환 형식과 만료 상태를 다시 확인하세요.
프로필을 활성화한 뒤 「프록시」 화면에서 전략 그룹을 열고 연결 가능한 노드를 직접 선택합니다. 처음부터 자동 선택에 의존하면 장애 원인을 구분하기 어렵습니다. 지연 시간이 짧은 노드가 항상 인증에 성공하는 것은 아니므로, 하나의 노드에서 실패하면 다른 노드로 바꾼 뒤 같은 테스트를 반복해야 합니다.
curl -I -x http://127.0.0.1:7897 https://example.com위 명령에서 7897은 예시 포트입니다. 실제 포트로 바꿔 사용하세요. 응답 헤더가 반환되면 로컬 HTTP 프록시가 요청을 받고 있다는 뜻입니다. 이것은 Claude 서비스의 인증 성공을 보장하는 테스트는 아니지만, 최소한 Clash의 포트와 선택한 노드가 동작하는지 확인하는 데 유용합니다.
터미널에서 프록시 환경 변수 설정하기
시스템 프록시를 켜도 모든 터미널 도구가 자동으로 이를 따르는 것은 아닙니다. 브라우저는 운영체제 프록시 설정을 읽는 경우가 많지만, curl, npm, git, Node.js 기반 CLI는 환경 변수나 자체 네트워크 설정을 사용할 수 있습니다. 따라서 Claude Code를 시스템 프록시 모드에서 사용할 때는 실행하는 셸에 프록시 변수를 명시하는 것이 가장 확실합니다.
Windows PowerShell 설정
Clash Verge의 혼합 포트가 7897이라고 가정하면 PowerShell에서 다음을 실행합니다.
$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:7897"
$env:NO_PROXY="localhost,127.0.0.1"
claude대부분의 HTTPS CLI 요청은 HTTPS_PROXY를 사용하므로 이 변수가 핵심입니다. ALL_PROXY는 SOCKS5를 지원하는 라이브러리에 대한 보조 설정입니다. SOCKS5 주소를 지정했는데 해당 프로그램이 SOCKS5를 지원하지 않으면 실패할 수 있으므로, 처음에는 HTTP 형식의 HTTP_PROXY와 HTTPS_PROXY부터 테스트하는 편이 안전합니다.
현재 셸에 변수가 적용됐는지는 다음처럼 확인할 수 있습니다.
Get-ChildItem Env:HTTP_PROXY
Get-ChildItem Env:HTTPS_PROXY
curl.exe -I https://example.comPowerShell의 curl은 환경에 따라 Invoke-WebRequest 별칭으로 해석될 수 있으므로, 실제 curl 바이너리를 호출하려면 curl.exe라고 입력하는 것이 혼동을 줄입니다. 새 PowerShell 창을 열면 $env: 방식으로 설정한 값은 사라집니다. 매번 적용하려면 PowerShell 프로필에 넣거나 Claude Code를 실행할 때만 사용하는 별도 스크립트를 만들 수 있습니다.
macOS와 Linux 셸 설정
zsh 또는 bash에서는 export로 환경 변수를 등록합니다.
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:7897
export NO_PROXY=localhost,127.0.0.1
claude환경 변수 이름은 일부 프로그램에서 대문자와 소문자를 다르게 처리할 수 있습니다. 호환성을 높이려면 다음처럼 소문자 변수도 함께 지정할 수 있습니다.
export http_proxy="$HTTP_PROXY"
export https_proxy="$HTTPS_PROXY"
export all_proxy="$ALL_PROXY"
curl -I https://example.com테스트가 끝난 뒤 프록시를 끄고 일반 연결로 되돌리려면 셸에서 다음을 실행합니다.
unset HTTP_PROXY HTTPS_PROXY ALL_PROXY
unset http_proxy https_proxy all_proxyTUN 모드를 사용할 때도 기존 환경 변수는 남아 있을 수 있습니다. TUN이 이미 모든 IP 트래픽을 처리하는 상태에서 잘못된 프록시 포트를 계속 지정하면 요청이 이중으로 전달되거나, Clash가 자기 자신에게 다시 연결하는 루프가 생길 수 있습니다. TUN 모드로 전환한 뒤에는 환경 변수를 일단 해제하고 직접 연결 테스트를 다시 수행하세요.
시스템 프록시와 TUN 모드 중 어떤 방식을 선택할까
시스템 프록시는 설정이 간단하고 문제 발생 시 되돌리기 쉽습니다. Clash Verge에서 시스템 프록시를 켜면 운영체제의 프록시 주소가 변경되고, 해당 설정을 읽는 브라우저나 Electron 앱이 Clash 포트를 사용합니다. 반면 터미널 프로그램이 시스템 프록시를 읽지 않으면 별도의 환경 변수 설정이 필요합니다.
TUN 모드는 가상 네트워크 인터페이스와 라우팅 규칙을 사용해 애플리케이션이 프록시를 지원하는지와 관계없이 IP 트래픽을 Clash로 전달합니다. 따라서 환경 변수 설정을 놓친 CLI, 일부 개발 도구, UDP 연결까지 처리할 수 있습니다. 대신 관리자 권한, TUN 서비스, DNS 처리, LAN 예외 규칙이 함께 필요하므로 시스템 프록시보다 영향 범위가 큽니다.
| 항목 | 시스템 프록시 | TUN 모드 |
|---|---|---|
| 터미널 CLI | 환경 변수 설정 필요할 수 있음 | 대체로 별도 설정 없이 처리 |
| 브라우저 | 대부분 바로 적용 | 애플리케이션과 관계없이 적용 |
| UDP 트래픽 | 제한적 | 규칙과 스택에 따라 처리 가능 |
| 권한 요구 | 낮음 | 관리자 또는 시스템 권한 필요 |
| 문제 격리 | 범위가 작아 진단하기 쉬움 | DNS와 라우팅까지 함께 확인해야 함 |
처음 설정할 때는 시스템 프록시와 터미널 환경 변수를 이용해 Claude Code 연결을 검증하는 순서를 권장합니다. 이 방식으로 연결 로그가 확인되지 않거나 여러 CLI가 반복해서 실패하면 TUN 모드로 전환하세요. TUN을 켠 뒤에는 시스템 프록시와 환경 변수 중복을 피하고, 「설정」에서 DNS와 가상 네트워크 어댑터 상태를 확인해야 합니다.
실행 결과와 Clash 로그로 원인 좁히기
설정을 완료했다면 곧바로 로그인만 반복하지 말고 단계별로 테스트합니다. 먼저 로컬 프록시 포트가 열려 있는지 확인하고, 그다음 일반 HTTPS 요청을 보낸 뒤, 마지막으로 Claude Code를 실행합니다. 각 단계 사이에 Clash Verge의 연결 로그를 열어 요청이 어느 노드로 전달됐는지 확인하세요.
- Clash Verge에서 프로필을 활성화하고 프록시 그룹의 노드를 선택합니다.
- 혼합 포트 주소를 확인합니다. 일반적으로 주소는
127.0.0.1이며 포트는 설치 환경에 따라 다릅니다. curl에-x옵션을 지정해 로컬 프록시 연결을 시험합니다.- 터미널에 환경 변수를 등록하고 같은 요청을 다시 수행합니다.
- Clash 로그에 요청이 나타난 뒤 Claude Code를 실행합니다.
인증 토큰, API 키, 구독 토큰은 로그나 화면 캡처에 포함하지 마세요. 오류를 공유할 때는 도메인과 오류 유형만 남기고 토큰·쿠키·Authorization 헤더는 반드시 삭제해야 합니다.
브라우저는 정상인데 Claude Code만 실패하고 Clash 로그에 요청이 없다면 환경 변수가 현재 셸에 적용되지 않은 것입니다. 로그에는 요청이 있지만 연결이 시간 초과되면 선택한 노드, DNS, 원격 서버 접근성을 확인합니다. 407 Proxy Authentication Required가 표시되면 로컬 Clash 포트에 인증을 설정했는지, 환경 변수에 사용자 이름과 비밀번호가 필요한지 확인하세요. ECONNREFUSED는 대부분 포트 번호 오류나 mihomo 코어 미실행을 의미합니다.
인증 단계에서만 멈추는 경우에는 시스템 시간도 확인해야 합니다. HTTPS 인증서 검증과 로그인 세션은 로컬 시간이 크게 어긋나면 실패할 수 있습니다. 또한 회사나 학교 네트워크에서 TLS 검사, 방화벽, 보안 프로그램이 터미널 프로세스의 외부 연결을 차단할 수 있으므로, 같은 환경에서 브라우저와 CLI의 결과가 다른지 비교하세요.
마지막으로 DNS를 무조건 변경하기보다 실제 증상을 기준으로 조정합니다. TUN 모드에서 도메인 해석이 반복해서 실패하면 Clash의 DNS 활성화 여부, dns-hijack, fake-ip 예외 목록을 확인합니다. 반대로 시스템 프록시만 사용하는 동안 DNS가 정상인데 HTTPS 연결만 실패한다면 DNS보다 노드 또는 터미널 프록시 환경 변수가 우선 점검 대상입니다.
안정적으로 사용하는 최종 점검 순서
Claude Code와 Clash Verge를 함께 사용할 때 가장 재현성이 높은 순서는 구독 갱신, 노드 수동 선택, 로컬 포트 확인, 터미널 프록시 적용, 연결 로그 검증입니다. 처음부터 여러 설정을 동시에 바꾸지 말고 한 번에 하나씩 확인해야 어느 단계에서 문제가 해결됐는지 알 수 있습니다.
- 구독 프로필이 최신 상태이고 노드 수가 0이 아닌지 확인합니다.
- 전략 그룹에서 실제로 응답하는 노드를 선택합니다.
- Clash Verge에 표시된 혼합 포트를 그대로 사용합니다.
- 시스템 프록시만으로 부족하면 셸의
HTTP_PROXY와HTTPS_PROXY를 설정합니다. - TUN 모드를 켠 뒤에는 기존 환경 변수를 해제해 이중 프록시를 방지합니다.
- Clash 연결 로그에서 Claude Code 관련 요청과 선택 노드를 확인합니다.
- 작업이 끝난 뒤 공용 컴퓨터에서는 토큰과 프록시 환경 변수를 제거합니다.
이 순서를 따르면 「로그인은 되지만 명령 실행이 안 되는 경우」, 「브라우저는 되지만 터미널만 실패하는 경우」, 「TUN을 켠 뒤 연결이 더 불안정해진 경우」를 서로 구분할 수 있습니다. 핵심은 Clash Verge를 켜는 것 자체가 아니라, Claude Code가 실행되는 프로세스가 실제로 어느 프록시 포트와 DNS 경로를 사용하는지 확인하는 것입니다.