Claude Code가 Clash Verge를 필요로 하는 상황
Claude Code는 터미널에서 자연어로 작업을 지시하고, 프로젝트 파일을 읽거나 수정하며, 명령어 실행과 코드 검토까지 이어 가는 AI 개발 도구입니다. 브라우저에서만 사용하는 서비스와 달리 터미널 프로세스, 패키지 매니저, Git, 원격 API 호출이 동시에 움직이기 때문에 네트워크 경로가 하나라도 어긋나면 증상이 복잡하게 나타납니다. 로그인 페이지는 열리는데 질문을 보낸 뒤 멈추거나, 짧은 요청은 성공하지만 큰 코드 변경에서 연결이 끊기는 경우가 대표적입니다.
이때 Clash Verge는 단순히 “인터넷을 우회하는 버튼”이 아니라, Claude Code가 생성하는 연결을 어떤 규칙과 노드로 보낼지 관리하는 제어판 역할을 합니다. 다만 Claude Code 자체가 시스템 프록시를 항상 자동으로 인식한다고 가정해서는 안 됩니다. 운영체제 프록시를 따르는 부분과 셸 환경 변수를 읽는 부분, 별도의 네트워크 라이브러리를 사용하는 부분이 서로 다를 수 있기 때문입니다.
초보자라면 처음부터 TUN과 복잡한 커스텀 규칙을 모두 켜기보다, Clash Verge의 혼합 포트 확인 → 시스템 프록시 적용 → 터미널 변수 설정 → 로그 검증 순서로 접근하는 편이 안전합니다. 이 순서를 지키면 노드 문제와 애플리케이션 설정 문제를 빠르게 분리할 수 있습니다.
Clash Verge에서 먼저 확인할 기본 항목
Clash Verge를 실행한 뒤 가장 먼저 확인할 것은 현재 활성화된 프로필입니다. 프로필 목록에 여러 구독이나 로컬 YAML이 있다면, 편집한 파일과 실제 코어가 읽는 파일이 다를 수 있습니다. 화면에서 수정한 것처럼 보여도 다른 프로필이 활성화되어 있으면 규칙과 프록시 그룹은 전혀 바뀌지 않습니다. Claude Code 설정을 시작하기 전에 사용할 프로필을 하나 선택하고, 해당 프로필이 정상적으로 업데이트되었는지 확인하세요.
- 코어 상태: Mihomo 코어가 실행 중이며 오류 없이 프로필을 읽었는지 확인합니다.
- 혼합 포트: HTTP와 SOCKS 요청을 함께 받을 수 있는 로컬 포트 번호를 확인합니다. 일반적으로 주소는
127.0.0.1입니다. - 모드: 처음에는 Global보다 Rule 모드를 권장합니다. 개발 패키지 저장소와 사내 Git까지 모두 우회하는 실수를 줄일 수 있습니다.
- 노드 그룹: Claude Code용으로 사용할 그룹을 선택하고, 연결이 끊길 때 비교할 수 있도록 두세 개의 후보 노드를 준비합니다.
- 시스템 프록시: 브라우저와 운영체제에서 프록시가 실제로 켜졌는지 확인합니다.
노드 이름에 “자동”, “저지연”, “Fallback” 같은 표현이 있어도 실제 Claude API 응답 속도와 항상 일치하지는 않습니다. 웹 페이지 로딩은 빠르지만 스트리밍 응답이 불안정한 노드도 있고, 속도 측정은 느려 보여도 긴 연결을 안정적으로 유지하는 노드도 있습니다. 따라서 이름보다 실제 요청 결과와 코어 로그를 기준으로 판단해야 합니다.
터미널에 프록시 환경 변수를 적용하는 방법
시스템 프록시를 켜면 브라우저는 정상적으로 접속되지만, 터미널에서 실행한 Claude Code가 같은 경로를 사용하지 않을 수 있습니다. 특히 Node.js 기반 CLI, Python 스크립트, Go 바이너리, 패키지 설치 명령은 운영체제 프록시 설정 대신 환경 변수나 자체 옵션을 우선하는 경우가 있습니다. 이때는 현재 셸에 Clash Verge의 혼합 포트를 직접 알려 주는 것이 효과적입니다.
Windows PowerShell에서는 다음처럼 현재 터미널 세션에만 변수를 적용할 수 있습니다. 포트 번호는 Clash Verge 화면에 표시된 실제 값으로 바꾸세요.
$env:HTTP_PROXY="http://127.0.0.1:7890"
$env:HTTPS_PROXY="http://127.0.0.1:7890"
$env:ALL_PROXY="socks5://127.0.0.1:7891"
macOS, Linux 또는 WSL의 Bash 계열 셸에서는 다음과 같이 설정합니다.
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
export ALL_PROXY=socks5://127.0.0.1:7891
모든 프로그램이 세 변수를 동일하게 해석하는 것은 아닙니다. 일부 도구는 대문자만 읽고, 일부는 소문자 변수를 요구하며, 일부 HTTP 클라이언트는 ALL_PROXY를 무시합니다. 문제가 계속되면 아래처럼 소문자 변수도 함께 지정해 보는 것이 좋습니다.
export http_proxy="$HTTP_PROXY"
export https_proxy="$HTTPS_PROXY"
export all_proxy="$ALL_PROXY"
환경 변수를 설정한 뒤에는 같은 터미널에서 Claude Code를 다시 실행해야 합니다. 이미 실행 중인 터미널이나 IDE는 이전 환경을 계속 가지고 있을 수 있습니다. 또한 회사 VPN, 보안 에이전트, 다른 프록시 프로그램이 함께 실행 중이라면 포트 충돌이 발생할 수 있으므로, 127.0.0.1:7890이 실제로 연결을 받고 있는지도 확인해야 합니다.
Claude Code 도메인과 규칙을 좁게 관리하기
Claude Code가 사용하는 정확한 호스트는 계정 유형, 로그인 방식, API 경로, 업데이트 방식에 따라 달라질 수 있습니다. 따라서 인터넷에서 본 도메인 목록을 그대로 복사해 광범위하게 우회하기보다, 실제 실행 시 코어 로그와 터미널 오류에 나타난 호스트를 먼저 기록하는 방식이 좋습니다. 로그인, API 요청, 설치 파일 다운로드가 각각 다른 도메인을 사용할 수 있다는 점도 기억해야 합니다.
개념적으로는 다음과 같이 전용 프록시 그룹을 만들 수 있습니다. 아래 예시는 구조를 설명하기 위한 것이며, 실제 호스트와 그룹 이름은 사용 중인 프로필에 맞춰 수정해야 합니다.
proxy-groups:
- name: CLAUDE-CODE
type: select
proxies:
- AUTO
- DIRECT
rules:
- DOMAIN-SUFFIX,anthropic.com,CLAUDE-CODE
- DOMAIN-SUFFIX,claude.ai,CLAUDE-CODE
- MATCH,GLOBAL
DOMAIN-KEYWORD,claude처럼 키워드 하나로 처리하면 예상하지 못한 정적 파일이나 다른 서비스까지 같은 그룹에 들어갈 수 있습니다. 더 넓은 규칙 세트를 이미 사용하고 있다면 사용자 정의 규칙이 해당 세트보다 위에 배치되는지 확인하세요. Mihomo 규칙은 위에서 아래로 내려가며 처음 일치한 줄에서 멈추므로, 구체적인 DOMAIN-SUFFIX 줄을 뒤에 배치하면 원하는 그룹을 타지 않을 수 있습니다.
모든 트래픽을 Global 모드로 보내면 일시적으로 문제가 사라지는 것처럼 보일 수 있지만, 국내 웹사이트와 패키지 레지스트리까지 멀리 우회해 전체 개발 속도가 떨어질 수 있습니다. Claude Code 관련 연결만 전용 그룹으로 보내고 나머지는 기존 규칙을 유지하는 방식이 장기적으로 관리하기 쉽습니다.
시스템 프록시와 TUN 모드의 선택 기준
Claude Code를 처음 설정하는 단계에서는 시스템 프록시와 환경 변수만으로 충분한지 먼저 확인하는 것이 좋습니다. 브라우저 로그인과 간단한 API 호출이 정상이고, 터미널만 실패한다면 TUN을 바로 켜기보다 셸 변수 주입 문제를 먼저 살펴야 합니다. 반대로 애플리케이션이 프록시 옵션을 전혀 제공하지 않고, 환경 변수도 무시하며, 운영체제의 일반 프록시 설정도 읽지 않는다면 TUN이 더 적합할 수 있습니다.
TUN은 운영체제 네트워크 계층에서 트래픽을 가로채므로 “프록시를 모르는” 프로그램에도 일관된 경로를 제공할 수 있습니다. 하지만 다른 VPN, 회사의 보안 프로그램, Docker 네트워크, WSL 가상 어댑터와 충돌할 가능성이 있습니다. TUN을 켠 뒤 인터넷 전체가 느려지거나 DNS가 반복해서 실패한다면 Claude Code 설정 문제가 아니라 네트워크 스택 충돌일 수 있습니다.
| 상황 | 먼저 시도할 방법 | 주의할 점 |
|---|---|---|
| 브라우저와 Claude Code 모두 실패 | Clash Verge 프로필, 노드, 시스템 프록시 확인 | 규칙보다 연결 자체를 먼저 점검 |
| 브라우저는 성공하지만 터미널만 실패 | HTTP_PROXY와 HTTPS_PROXY 설정 | 새 터미널에서 다시 실행 |
| 환경 변수를 넣어도 CLI가 직접 연결 | TUN 모드 검토 | VPN과 가상 어댑터 충돌 확인 |
| 짧은 요청은 성공하지만 긴 응답이 끊김 | 다른 노드와 스트리밍 안정성 비교 | 단순 핑이나 속도만 믿지 않기 |
브라우저, 터미널, Clash 로그를 함께 검증하기
설정이 제대로 되었는지 확인할 때는 한 가지 테스트만으로 결론을 내리지 않는 것이 중요합니다. 첫 번째로 브라우저에서 Claude 관련 로그인 페이지를 열고, 로그인 리다이렉트가 반복되지 않는지 확인합니다. 두 번째로 환경 변수가 적용된 같은 터미널에서 간단한 HTTPS 요청을 실행합니다. 세 번째로 Clash Verge의 연결 로그에서 요청 호스트, 매칭된 규칙, 선택된 프록시 그룹을 확인합니다.
- Clash Verge에서 현재 노드와 혼합 포트가 활성 상태인지 확인합니다.
- 새 터미널을 열고
HTTP_PROXY와HTTPS_PROXY값이 비어 있지 않은지 확인합니다. - 터미널에서
curl -v https://claude.ai/와 같은 간단한 요청을 실행합니다. - 로그에서 해당 요청이 DIRECT로 빠졌는지, 의도한 그룹을 통과했는지 확인합니다.
- Claude Code에서 짧은 질문, 파일 읽기, 작은 수정 순서로 테스트합니다.
브라우저는 성공하지만 curl만 실패한다면 프록시 변수가 적용되지 않았거나 셸 프로그램이 다른 인증서를 사용하고 있을 가능성이 있습니다. 반대로 curl은 성공하지만 Claude Code만 실패한다면 CLI 내부의 인증 토큰, 자체 HTTP 클라이언트, 스트리밍 처리, 프로젝트 권한을 확인해야 합니다. 이처럼 테스트 결과를 계층별로 나누면 노드만 계속 바꾸는 시행착오를 줄일 수 있습니다.
DNS 모드도 함께 살펴보세요. fake-ip 환경에서 특정 애플리케이션이 반환된 주소를 제대로 처리하지 못하거나, IPv6를 우선 선택해 실제 연결이 다른 경로로 나가는 경우가 있습니다. 모든 설정을 한 번에 바꾸지 말고, 먼저 현재 DNS 모드와 TUN 상태를 기록한 뒤 하나씩 변경해야 어떤 선택이 문제를 해결했는지 알 수 있습니다.
자주 나타나는 오류와 해결 순서
로그인 화면이 반복되는 경우
인증 페이지와 API 요청이 서로 다른 출구를 사용하면 세션 쿠키가 예상과 다르게 처리될 수 있습니다. 로그인 관련 호스트가 DIRECT로 빠지는지, 혹은 한 로그인 과정에서 노드가 자동으로 변경되는지 확인하세요. 우선 자동 노드 선택을 잠시 고정 노드로 바꾸고, 브라우저 쿠키를 정리한 뒤 새 터미널에서 다시 시도하는 것이 좋습니다.
응답 중간에 멈추거나 시간 초과가 나는 경우
짧은 웹 요청이 성공한다고 해서 긴 스트리밍 연결도 안정적인 것은 아닙니다. 같은 프록시 그룹에서 다른 노드를 선택해 긴 응답을 비교하고, 연결 유지 시간이 긴 노드를 사용하세요. Clash 로그에 재연결, EOF, TLS handshake timeout이 반복되면 API 키를 새로 만드는 것보다 노드와 DNS 경로를 먼저 바꾸는 편이 합리적입니다.
패키지나 업데이트 다운로드만 실패하는 경우
Claude Code 실행 자체와 설치 파일 다운로드는 서로 다른 호스트를 사용할 수 있습니다. 문서 페이지가 열린다는 이유로 CDN과 패키지 저장소도 정상이라고 판단하면 안 됩니다. 터미널의 다운로드 오류에 표시된 도메인을 기록하고, 해당 도메인이 실제 규칙에 매칭되는지 확인하세요. 패키지 매니저가 별도의 프록시 설정을 갖고 있다면 셸 변수와 별도로 설정해야 할 수도 있습니다.
자주 묻는 질문
시스템 프록시만 켜면 Claude Code를 사용할 수 있나요?
환경에 따라 가능합니다. 하지만 CLI가 운영체제 프록시를 읽지 않는다면 시스템 프록시만으로는 부족하며, HTTP_PROXY와 HTTPS_PROXY 환경 변수를 추가해야 합니다. 브라우저는 되는데 터미널만 안 되는 경우에는 이 차이를 먼저 의심하세요.
처음부터 Global 모드를 사용해도 되나요?
문제 원인을 빠르게 확인하는 임시 테스트로는 사용할 수 있습니다. 다만 모든 개발 트래픽이 같은 노드를 통과해 패키지 다운로드와 사내 저장소까지 느려질 수 있으므로, 원인이 확인되면 Rule 모드와 전용 그룹으로 되돌리는 편이 좋습니다.
TUN 모드는 반드시 켜야 하나요?
반드시 그렇지는 않습니다. Claude Code가 환경 변수나 시스템 프록시를 정상적으로 사용한다면 TUN 없이도 충분합니다. 프록시를 전혀 인식하지 않는 프로세스가 계속 DIRECT로 연결될 때만 TUN을 검토하고, 다른 VPN이나 보안 프로그램과의 충돌 가능성을 먼저 확인하세요.
어떤 노드를 선택해야 하나요?
단순 다운로드 속도보다 로그인 성공률, TLS 연결 안정성, 긴 스트리밍 응답 유지 시간을 기준으로 선택하세요. 같은 요청을 여러 노드에서 반복하고 Clash 로그의 재연결 횟수와 응답 중단 여부를 기록하면 개인 환경에 맞는 노드를 찾기 쉽습니다.
일부 단순 프록시 도구는 브라우저 트래픽만 쉽게 처리하고 터미널 변수, 규칙优先순위, TUN 충돌 상황을 세밀하게 확인하기 어렵습니다. 반면 Clash Verge는 시스템 프록시, 전용 프록시 그룹, Mihomo 규칙, 코어 로그를 한 흐름에서 확인할 수 있어 Claude Code처럼 로그인과 스트리밍 API가 함께 필요한 도구를 단계적으로 진단하기 좋습니다. 설정을 한 번에 복잡하게 만들지 않고 필요한 도메인과 프로세스만 좁혀 관리하고 싶다면 Clash의 방식이 더 재현성 있는 선택이 될 수 있습니다.