Claude Code가 Clash Verge를 필요로 하는 이유
Claude Code는 터미널에서 실행하는 AI 코딩 도구이지만, 실제 작업 중에는 한 번의 요청만 보내지 않습니다. 로그인 과정에서 계정 인증 페이지와 토큰 서버에 연결하고, 프로젝트를 분석할 때 모델 API와 파일 처리 서비스에 여러 번 요청하며, 응답을 받는 동안에는 스트리밍 연결을 오래 유지합니다. 따라서 브라우저에서 일반 웹사이트가 열리더라도 Claude Code만 로그인에 실패하거나 connection timeout이 반복될 수 있습니다.
특히 터미널 프로그램은 브라우저처럼 운영체제의 프록시 설정을 항상 자동으로 따르지 않습니다. Clash Verge를 실행하고 노드까지 선택했는데도 Claude Code가 직접 연결을 시도하면, 인증 창은 열리지 않거나 명령어가 멈춘 것처럼 보입니다. 반대로 모든 트래픽을 무조건 프록시로 보내면 국내 개발 사이트, 패키지 저장소, 사내 Git 서버까지 우회되어 속도가 떨어지거나 접근 정책이 바뀔 수 있습니다. 핵심은 Clash Verge의 실행 상태, 터미널이 사용하는 프록시 변수, Claude 관련 도메인의 분기 규칙을 각각 확인하는 것입니다.
Clash Verge 설치와 첫 실행 준비
Windows 또는 macOS에서 Clash Verge를 설치할 때는 출처가 분명한 배포 페이지의 설치 파일을 사용하세요. 운영체제와 CPU에 맞는 버전을 고르고, 이미 다른 Clash 계열 프로그램이나 시스템 VPN이 실행 중이라면 먼저 종료하는 편이 좋습니다. 여러 프로그램이 동시에 가상 네트워크 어댑터를 만들면 포트 충돌, DNS 응답 지연, 프록시 설정 덮어쓰기가 발생할 수 있습니다.
설치 후 처음 확인할 메뉴는 복잡한 고급 옵션이 아니라 Profiles, Proxies, Settings, Logs입니다. 서비스 제공자가 발급한 구독 URL을 Profiles 화면의 가져오기 입력란에 붙여 넣고 프로필을 추가합니다. 구독 주소에는 계정 토큰이 들어 있을 수 있으므로 공개 저장소, 업무 채팅방, 화면 공유에 그대로 노출하지 마세요. 가져오기가 실패하면 Clash Verge의 문제라고 단정하기보다 브라우저에서 해당 URL이 정상적으로 응답하는지, 로그인이나 캡차를 요구하지 않는지 먼저 확인해야 합니다.
프로필이 추가되면 해당 프로필을 활성화하고 Proxies 화면으로 이동합니다. 기본 프록시 그룹에서 실제로 사용할 노드를 선택한 다음, 노드 이름 옆의 지연 시간이 지나치게 높거나 반복적으로 실패하지 않는지 봅니다. url-test 그룹은 측정 URL에 대한 응답이 빠른 노드를 자동 선택하지만, Claude Code의 스트리밍 응답 품질과 완전히 같은 결과를 보장하지는 않습니다. 처음에는 수동으로 안정적인 노드를 고정하고, 로그인과 짧은 명령이 성공한 뒤 자동 선택을 시험하는 것이 문제 범위를 줄이는 데 유리합니다.
| 확인 단계 | 정상적인 상태 | 문제가 있을 때 |
|---|---|---|
| 프로필 가져오기 | 프로필 이름과 프록시 목록이 표시됨 | URL 만료, 인증 필요, 서버 응답 오류 확인 |
| 노드 선택 | 선택 표시와 지연 시간 측정 결과가 나타남 | 노드 연결 실패, 서버 과부하, 지역 제한 확인 |
| Clash 실행 | 시스템 트레이에 실행 상태와 포트가 표시됨 | 다른 VPN, 방화벽, 포트 충돌 확인 |
| 로그 확인 | 터미널 요청이 프록시 그룹으로 적중됨 | DIRECT, REJECT, 미적중 규칙 여부 확인 |
프록시 모드와 터미널 연결 방식 선택
Clash Verge의 모드는 보통 Rule, Global, Direct로 나뉩니다. Rule 모드는 도메인과 IP, 프로세스 등의 규칙에 따라 요청을 분기하므로 일상적인 사용에 가장 적합합니다. Global 모드는 대부분의 요청을 선택한 프록시로 보내 진단할 때 편리하지만, 패키지 레지스트리와 사내 서비스까지 우회할 수 있습니다. Direct는 원인 비교용으로 잠시 사용할 수 있으나, 우회 연결이 필요한 환경에서는 Claude Code의 인증 요청이 차단될 가능성이 큽니다.
처음 문제를 재현할 때는 Global 모드로 짧게 테스트해 보세요. Global에서 로그인과 간단한 질문이 성공하고 Rule에서 실패한다면 노드 품질보다 규칙 누락을 의심할 수 있습니다. 반대로 두 모드 모두 실패하면 구독 만료, 계정 상태, 시스템 시간, TLS 검사, 서비스 장애까지 범위를 넓혀야 합니다. 테스트가 끝나면 Rule 모드로 돌아가 필요한 서비스만 프록시로 보내는 구성이 안전합니다.
터미널에 HTTP 프록시 변수 설정하기
Clash Verge가 로컬에 HTTP 또는 mixed 포트를 열고 있다면, 터미널 프로세스가 해당 주소를 사용하도록 환경 변수를 지정할 수 있습니다. 실제 포트 번호는 Clash Verge의 Settings 화면에서 확인해야 하며, 아래 예시의 7890을 그대로 사용하면 안 됩니다. 셸 종류에 따라 명령어도 다르므로 현재 터미널에 맞는 형식을 선택하세요.
# macOS / Linux: 현재 셸 세션에만 적용
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
# 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"
# 프록시를 해제할 때
unset HTTP_PROXY HTTPS_PROXY ALL_PROXY모든 CLI가 모든 변수명을 동일하게 해석하는 것은 아닙니다. 어떤 도구는 대문자 변수를 읽고, 어떤 도구는 소문자 http_proxy와 https_proxy를 우선합니다. 따라서 설정 후에는 새 터미널을 열고 테스트해야 하며, 프록시를 해제했는데도 계속 우회된다면 셸 프로필 파일이나 Clash의 시스템 프록시 설정을 함께 확인하세요. 사내 Git, 로컬 주소, 패키지 미러를 직접 연결해야 한다면 NO_PROXY에 해당 호스트를 추가하는 방법도 고려할 수 있습니다.
127.0.0.1의 닫힌 포트로 접속하려고 합니다. 먼저 현재 세션에서만 테스트하고, 안정성이 확인된 뒤 필요한 셸에 제한적으로 적용하세요.
Claude Code용 분기 규칙과 연결 테스트
구독 프로필을 직접 수정할 수 있는 환경이라면 Claude Code가 실제로 접속하는 호스트를 기준으로 규칙을 보완합니다. 서비스 도메인을 추측해 긴 목록을 복사하기보다 Clash Verge의 연결 로그에서 실패 순간의 목적지, 포트, matched rule, 최종 프록시 그룹을 기록하는 방식이 정확합니다. 서비스가 변경되거나 인증과 모델 요청이 서로 다른 도메인을 사용할 수 있으므로, 한 호스트만 추가하고 끝내면 로그인은 되지만 실제 명령 실행이 실패할 수 있습니다.
규칙을 작성할 때는 먼저 서비스 전체 접미사를 묶는 DOMAIN-SUFFIX를 검토하고, 너무 넓은 규칙은 피하세요. 예를 들어 특정 서비스의 모든 하위 도메인을 프록시로 보내려는 목적이라면 해당 서비스의 공식 접미사만 사용해야 합니다. DOMAIN-KEYWORD는 이름이 비슷한 다른 사이트까지 적중할 수 있어 진단용 임시 규칙 외에는 신중하게 다루는 것이 좋습니다. 마지막에 MATCH가 있다면 앞선 규칙에 걸리지 않은 요청이 어디로 나가는지도 반드시 확인하세요.
rules:
- DOMAIN-SUFFIX,anthropic.com,AI
- DOMAIN-SUFFIX,claude.ai,AI
- DOMAIN-SUFFIX,github.com,Developer
- DOMAIN-SUFFIX,npmjs.org,DIRECT
- GEOIP,LAN,DIRECT
- MATCH,DIRECT위 YAML은 환경에 따라 달라지는 예시일 뿐이며, 구독 제공자가 관리하는 프로필에서는 수정 내용이 갱신 때 사라질 수 있습니다. 그룹 이름 AI와 Developer가 실제 프로필에 존재하는지 확인하고, 존재하지 않는 그룹을 참조하지 마세요. 또한 anthropic.com 또는 claude.ai 전체를 프록시로 보내는 것이 조직 정책이나 서비스 약관에 맞는지 확인해야 합니다.
테스트 순서는 짧고 분리해서 진행하는 것이 좋습니다. 먼저 Clash Verge에서 연결 로그를 열고 터미널을 새로 시작합니다. 그 다음 Claude Code의 로그인 명령을 실행하고, 브라우저 인증이 완료된 뒤 터미널로 돌아옵니다. 로그인만 성공한 상태와 실제 프로젝트에서 한 줄짜리 질문을 보낸 상태를 따로 기록하세요. 전자는 인증 경로가 정상이라는 뜻이고, 후자는 모델 API와 스트리밍 경로까지 통과했다는 뜻이므로 두 결과를 하나로 묶어 판단하면 안 됩니다.
| 증상 | 우선 확인할 항목 | 다음 조치 |
|---|---|---|
| 로그인 창이 열리지 않음 | 터미널 프록시 변수, 브라우저 인증 경로 | Global 테스트 후 새 터미널에서 재시도 |
| 인증 후 명령이 멈춤 | API 호스트의 matched rule과 스트리밍 연결 | 연결 로그에서 실제 목적지 규칙 보완 |
| 빠른 401 또는 403 | 계정, 구독, 조직 정책, 지역 제한 | 노드 변경보다 계정 상태와 공식 안내 확인 |
| 간헐적인 read timeout | 노드 품질, 장시간 연결, DNS와 MTU | 안정적인 노드로 고정하고 TUN·DNS 설정 비교 |
실패할 때의 점검 순서와 대안 비교
문제가 계속되면 한 번에 여러 설정을 바꾸지 말고 원인을 층별로 나누세요. 첫째, Clash Verge 자체가 실행 중이고 노드가 선택되었는지 확인합니다. 둘째, 터미널에서 환경 변수가 실제로 남아 있는지 확인합니다. 셋째, 연결 로그에서 Claude Code 요청이 DIRECT인지 프록시 그룹인지 확인합니다. 넷째, 같은 노드로 브라우저 인증과 터미널 명령을 각각 시험합니다. 마지막으로 다른 노드와 다른 DNS 모드를 비교합니다. 이 순서를 지키면 “프록시가 안 된다”는 막연한 결론 대신 포트, 규칙, 인증, 노드 중 어느 층이 문제인지 좁힐 수 있습니다.
브라우저 확장 프록시는 브라우저 탭에는 편하지만 터미널 프로세스와 공유되지 않는다는 한계가 있습니다. 운영체제 시스템 프록시는 설정이 단순하지만 애플리케이션에 따라 무시될 수 있고, 일부 회사 네트워크에서는 정책 충돌이 생깁니다. 반면 Clash Verge는 Rule·Global·Direct를 빠르게 전환하고, 연결 로그에서 실제 목적지와 최종 그룹을 확인할 수 있으며, TUN 모드와 환경 변수 방식을 상황에 맞게 선택할 수 있습니다. 다만 설정 항목이 많아 처음에는 포트와 모드의 관계를 이해해야 한다는 부담이 있습니다.
결국 특정 GUI만 설치한다고 문제가 자동으로 해결되지는 않습니다. ClashNote에서 안내하는 Clash 클라이언트 구성은 구독 가져오기, 노드 선택, 터미널 프록시, 도메인 분기, 연결 로그를 하나의 진단 흐름으로 묶어 시행착오를 줄이는 데 초점을 둡니다. 다른 클라이언트가 시스템 프록시만 제공하거나 로그를 단순화해 원인 파악이 어려운 경우에도, Clash Verge에서는 인증과 API 요청을 분리해 확인할 수 있습니다. 위 순서대로 최소 설정을 성공시킨 뒤 필요한 규칙만 추가하면 Claude Code를 안정적으로 터미널에서 사용할 수 있습니다.