Claude Code Clash Verge 설정법, 터미널 연결과 안정적인 사용 팁

이 글이 필요한 상황

Claude Code를 설치한 뒤 터미널에서 명령을 실행했는데 로그인 화면이 열리지 않거나, 요청을 보내는 순간 connection refused, ETIMEDOUT, TLS handshake timeout 같은 오류가 나타나는 경우가 있습니다. 브라우저에서 Anthropic 계정 페이지는 정상적으로 열리고 다른 웹사이트도 문제없는데, 유독 Claude Code만 응답하지 않는다면 애플리케이션 자체보다 터미널 프로세스가 Clash Verge의 프록시를 사용하지 않는 상황을 먼저 확인해야 합니다.

이 글은 Clash Verge 또는 Clash Verge Rev를 이미 설치했거나 새로 설치하려는 개발자를 대상으로 합니다. 구독 프로필을 가져오는 단계부터 시작해, 혼합 포트와 시스템 프록시의 차이, macOS·Linux·Windows 터미널에서 사용하는 환경 변수, Claude Code 관련 도메인의 규칙 분기, 로그를 이용한 원인 확인까지 순서대로 설명합니다. 특정 구독 서비스나 노드 이름을 전제로 하지 않으므로, 사용 중인 프로필의 메뉴 명칭이 조금 달라도 핵심 원리는 그대로 적용할 수 있습니다.

다만 프록시는 네트워크 경로를 바꾸는 도구일 뿐입니다. API 키, 계정 권한, 사용량 한도, 결제 상태, 조직 정책으로 발생한 오류까지 해결해 주지는 않습니다. 따라서 프록시 연결을 먼저 확인한 뒤에도 401, 403, 429 같은 HTTP 응답이 계속된다면 인증 정보와 서비스 측 제한을 별도로 점검해야 합니다.

Claude Code와 Clash Verge가 연결되는 방식

Claude Code는 터미널에서 실행되는 개발 도구이므로, 브라우저처럼 항상 운영체제의 시스템 프록시 설정을 자동으로 따르지는 않습니다. 실행되는 런타임과 HTTP 라이브러리에 따라 HTTPS_PROXY, HTTP_PROXY, ALL_PROXY 같은 환경 변수를 읽거나, 별도의 네트워크 설정을 사용합니다. 반면 Clash Verge는 로컬 컴퓨터에 mixed-port를 열어 HTTP와 SOCKS 요청을 받을 수 있습니다. 이 두 부분을 연결하는 것이 이번 설정의 핵심입니다.

예를 들어 Clash Verge의 혼합 포트가 7890이라면, 터미널 프로그램은 다음과 같은 로컬 주소로 프록시를 요청할 수 있습니다.

http://127.0.0.1:7890

여기서 127.0.0.1은 현재 컴퓨터 자신을 뜻합니다. 포트 번호는 앱의 기본값과 다를 수 있으므로 화면에 표시된 실제 값을 사용해야 합니다. Clash Verge에서 포트를 7897로 변경했는데 셸에는 예전 7890을 남겨 두면, 브라우저는 정상이어도 Claude Code만 연결에 실패할 수 있습니다.

또 하나 중요한 부분은 규칙 모드입니다. 시스템 프록시가 켜져 있어도 Claude 관련 호스트가 규칙에 의해 DIRECT로 처리되면 터미널 요청은 일반 회선으로 빠져나갑니다. 반대로 모든 트래픽을 글로벌 프록시로 보내면 설정은 간단하지만, 사내 Git 서버나 일반 패키지 레지스트리까지 불필요하게 프록시를 거치게 됩니다. 개발 환경에서는 필요한 도메인만 프록시 그룹에 연결하는 방식이 관리와 문제 분석에 유리합니다.

1단계: Clash Verge 프로필과 포트 준비하기

먼저 Clash Verge를 열고 현재 사용 중인 프로필이 실제로 활성화되어 있는지 확인합니다. 구독 URL을 처음 넣는다면 Profiles 또는 이에 해당하는 프로필 화면에서 제공자가 안내한 URL을 추가한 다음, 다운로드가 끝날 때까지 기다립니다. 파일을 직접 가져오는 경우에는 YAML 형식이 현재 코어와 호환되는지 확인해야 합니다. 프로필 이름만 목록에 보이고 노드나 규칙이 로드되지 않았다면, Claude Code 설정을 바꾸기 전에 프로필 파싱 문제부터 해결하는 편이 빠릅니다.

프로필을 선택한 뒤에는 코어 상태가 실행 중인지, 프록시 그룹에 사용할 노드가 표시되는지, 모드가 Rule로 설정되어 있는지 차례로 봅니다. 글로벌 모드는 진단용으로 잠시 사용할 수 있지만, 평소 개발 환경에서는 규칙 모드가 더 안전합니다. 국내 서비스, 회사 내부 도메인, 패키지 미러까지 하나의 외부 노드로 보내면 속도 저하와 인증 오류가 섞여 원인을 추적하기 어려워집니다.

다음으로 설정 화면에서 Mixed Port 값을 기록합니다. 포트가 꺼져 있거나 다른 프로그램이 이미 사용 중이라면, 환경 변수를 설정해도 연결되지 않습니다. 로컬 포트를 바꾼 뒤에는 시스템 프록시와 셸 환경 변수 모두 새 포트에 맞춰야 합니다. Clash Verge를 재시작했을 때 포트가 자동으로 바뀌는 구성이라면, 고정된 포트를 사용하거나 실행할 때마다 현재 값을 확인하는 습관을 들이세요.

2단계: Claude 트래픽을 규칙으로 분기하기

Claude Code가 실제로 접근하는 호스트는 버전, 로그인 방식, API 사용 여부, 조직용 게이트웨이 구성에 따라 달라질 수 있습니다. 일반적으로 Anthropic API 호출에는 api.anthropic.com 계열이 등장하지만, 인증이나 웹 기반 로그인 과정에서는 별도의 계정·콘솔 도메인이 추가될 수 있습니다. 따라서 인터넷에서 본 도메인 목록을 무조건 넓게 복사하기보다는 Claude Code를 한 번 실행한 직후 Clash Verge의 Connections 또는 연결 로그에서 실제 호스트를 확인해야 합니다.

확인한 호스트는 기존 프로필의 프록시 그룹 정책에 맞춰 추가합니다. 예를 들어 이미 제공자가 AI 서비스용 그룹을 운영한다면 해당 그룹에 연결하고, 직접 규칙을 관리하는 프로필이라면 API 호스트에 DOMAIN 또는 DOMAIN-SUFFIX 규칙을 적용할 수 있습니다. 단순히 DOMAIN-SUFFIX,anthropic.com,Proxy처럼 넓게 설정하면 관련 웹서비스와 API가 모두 같은 경로를 사용하므로, 필요한 범위인지 먼저 판단해야 합니다.

규칙의 순서도 중요합니다. 상단에 있는 광범위한 GEOIP, GEOSITE, 지역별 DIRECT 규칙이 Claude 호스트보다 먼저 매칭되면, 아래에 추가한 프록시 규칙은 실행되지 않습니다. 연결 로그에서 호스트 옆에 표시되는 최종 정책과 프록시 그룹을 확인하고, 의도한 규칙이 실제로 적용되는지 봐야 합니다. REJECT가 나타난다면 노드 품질보다 규칙 차단이나 광고 필터가 원인일 가능성이 높습니다.

반대로 여러 노드를 번갈아 선택하는 자동 그룹에서 긴 요청이 자주 끊긴다면, Claude Code 테스트 기간에는 안정성 중심의 고정 그룹을 사용하는 편이 좋습니다. 짧은 API 요청은 여러 노드에서 모두 성공해도, 스트리밍 응답이나 긴 컨텍스트 전송에서는 TLS 재협상, 패킷 손실, 연결 유지 시간 차이가 드러날 수 있습니다. 먼저 한 노드에서 반복 테스트를 진행한 뒤 자동 선택 그룹으로 되돌리면 변화가 더 분명하게 보입니다.

3단계: 터미널 환경 변수 연결하기

Clash Verge의 시스템 프록시 스위치를 켜는 것과 터미널 프로세스에 프록시를 알려 주는 것은 서로 다른 작업입니다. Claude Code가 시스템 설정을 읽지 않는 런타임에서 실행된다면, 셸에 환경 변수를 직접 지정해야 합니다. macOS·Linux의 Bash 또는 Zsh에서는 다음처럼 현재 터미널 세션에만 적용할 수 있습니다.

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
export NO_PROXY=localhost,127.0.0.1,::1

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"
$env:NO_PROXY="localhost,127.0.0.1"

포트 번호는 반드시 Clash Verge에 표시된 값으로 바꾸세요. 또한 현재 셸에서만 설정한 변수는 새 터미널을 열거나 IDE를 다시 시작하면 사라집니다. 매번 입력하기 싫다면 macOS·Linux에서는 ~/.zshrc, ~/.bashrc 같은 셸 설정 파일에 넣을 수 있지만, 회사 네트워크나 사내 Git 주소를 사용하는 경우에는 NO_PROXY 예외를 신중하게 구성해야 합니다.

환경 변수에는 프록시 주소만 넣고 API 키를 함께 적지 않는 것이 좋습니다. 셸 기록, 터미널 공유 화면, CI 로그에 비밀 값이 남을 수 있기 때문입니다. API 키나 로그인 토큰은 Claude Code가 권장하는 보안 저장 방식과 운영체제의 비밀 저장소를 사용하고, 프로젝트 디렉터리의 커밋 대상 파일이나 공개된 셸 설정에 평문으로 저장하지 마세요.

변수를 넣은 뒤에는 같은 터미널에서 Claude Code를 실행해야 합니다. 이미 실행 중인 VS Code나 JetBrains를 나중에 열었다면 IDE가 이전 환경을 물려받을 수 있으므로, IDE를 완전히 종료한 후 다시 시작해야 합니다. 통합 터미널에서 다음 명령으로 값이 기대한 포트인지 확인할 수 있습니다.

echo $HTTPS_PROXY
printenv | grep -i proxy

4단계: 연결 로그와 명령 결과를 교차 확인하기

이제 Claude Code를 실행하고 짧은 작업부터 테스트합니다. 처음부터 대규모 저장소를 분석하거나 여러 파일을 수정하게 하지 말고, 작은 프로젝트에서 상태 확인과 짧은 질문을 먼저 보내세요. 정상이라면 Clash Verge 연결 로그에 Claude 관련 호스트가 나타나고, 해당 연결에 선택한 프록시 그룹과 노드 이름이 표시됩니다. 터미널의 응답 시간과 Clash 로그의 연결 시작 시각을 함께 기록하면 문제 재현이 쉬워집니다.

로그에 아무것도 나타나지 않는 경우에는 Claude Code가 다른 프록시 설정을 사용하거나, 환경 변수가 실행 프로세스까지 전달되지 않았을 가능성이 큽니다. 셸에서 값이 보이더라도 Node.js·Python·IDE 태스크 러너가 별도 환경으로 실행될 수 있습니다. 반대로 로그에는 연결이 있는데 터미널에서 실패한다면, DNS 해결, TLS 협상, 노드의 원격 응답, 인증 단계 중 어디에서 끊겼는지 세부 로그를 확인해야 합니다.

DIRECT가 표시되면 규칙 순서와 호스트 매칭을 확인하고, REJECT라면 차단 규칙·광고 필터·보안 정책을 살펴봅니다. 프록시 그룹을 탔지만 계속 시간 초과가 발생하면 다른 노드를 하나씩 비교하세요. 여러 노드에서 같은 시점에 실패한다면 서비스 측 장애나 로컬 DNS, 포트 충돌을 의심하고, 한 노드에서만 실패한다면 해당 노드의 지연과 출구 정책이 원인일 수 있습니다.

안정적인 개발 환경을 유지하는 방법

Claude Code를 매일 사용한다면 프록시 설정을 필요할 때만 임시로 바꾸기보다, 개발 환경에 맞는 기준선을 정해 두는 것이 좋습니다. 첫째, 프로필을 갱신한 뒤에는 노드 목록만 보지 말고 규칙 프로바이더와 프록시 그룹이 정상적으로 다시 로드되었는지 확인하세요. 구독 제공자가 규칙 이름이나 그룹 구조를 바꾸면 기존에 수동으로 추가한 규칙이 무시될 수 있습니다. 수동 수정이 필요한 설정은 원본 구독 파일보다 별도의 오버라이드 또는 로컬 패치 방식으로 관리하는 편이 안전합니다.

둘째, 터미널용 프록시와 브라우저용 프록시를 같은 기준으로 점검하세요. 브라우저 확장 프로그램이 별도 프록시를 사용하면 웹 콘솔은 성공하지만 Claude Code는 다른 출구를 탈 수 있습니다. 반대로 TUN 모드를 켠 상태에서 환경 변수까지 동시에 사용하면 이중 프록시가 되어 DNS나 TLS 경로가 예상과 달라질 수 있습니다. 진단할 때는 시스템 프록시, TUN, 환경 변수 중 어떤 층을 사용할지 한 번에 명확히 정하고, 변경 후에는 Clash 연결 로그로 결과를 확인하세요.

셋째, 장시간 작업에서는 노드의 평균 속도보다 연결 안정성과 스트리밍 지속 시간을 우선합니다. Claude Code는 코드 검색, 파일 읽기, 도구 호출, 결과 생성이 연속으로 이어질 수 있어 짧은 웹 페이지 로딩보다 긴 연결에 민감합니다. 작업 중 갑자기 끊긴다면 프록시 그룹을 자주 자동 전환하는 설정을 잠시 끄고, 한 노드에서 동일 작업을 반복해 보세요. 네트워크가 안정된 후에만 자동 선택과 부하 분산을 다시 활성화하는 것이 원인 분리에 도움이 됩니다.

마지막으로 보안도 함께 관리해야 합니다. 프록시 로그에는 접속 호스트와 시간 정보가 남을 수 있으며, 디버그 수준을 높이면 요청 메타데이터가 더 많이 기록될 수 있습니다. 공유 컴퓨터에서는 작업이 끝난 뒤 환경 변수를 해제하고, API 키가 포함된 명령을 화면 녹화나 공개 이슈에 붙여 넣지 마세요. 팀 환경에서는 비밀 값과 프록시 설정을 분리하고, 프로젝트 저장소에는 재현 가능한 최소 설정만 남기는 것이 바람직합니다.

설정 완료 전 최종 점검

정상적인 기준선은 다음과 같습니다. Clash Verge에서 프로필과 코어가 실행 중이고, mixed-port가 실제로 열려 있습니다. Claude Code를 실행하는 동일한 셸에는 올바른 HTTPS_PROXY 값이 있으며, NO_PROXY에는 로컬·사내 주소만 필요한 범위로 들어 있습니다. 연결 로그에서는 Claude 관련 호스트가 의도한 프록시 그룹으로 매칭되고, 짧은 테스트와 실제 스트리밍 작업 모두 같은 경로를 사용합니다. 이 네 가지가 맞으면 이후 발생하는 401·403·429는 네트워크보다 계정 또는 사용량 문제로 분리해서 볼 수 있습니다.

한 번에 여러 설정을 바꾸지 않는 것도 중요합니다. 먼저 프록시 포트만 확인하고, 다음에 환경 변수를 맞춘 뒤, 마지막으로 규칙을 조정하세요. 각 단계마다 짧은 Claude Code 요청을 실행하고 연결 로그를 저장하면, 구독 갱신이나 노드 교체 후에도 이전 상태와 비교할 수 있습니다. 특히 팀 프로젝트에서는 개인 컴퓨터에서만 통하는 절대 경로와 비밀 키를 설정 파일에 넣지 말고, 운영체제와 셸에 맞는 안내를 따로 제공하는 것이 좋습니다.

일부 터미널 전용 프록시 도구는 빠르게 켜고 끌 수 있지만, 프로필 관리와 규칙 확인 화면이 단순해 실제로 어떤 호스트가 어느 경로를 탔는지 추적하기 어려운 경우가 있습니다. 반대로 Clash Verge는 구독·프록시 그룹·연결 로그·TUN과 mixed-port를 한 화면 흐름에서 점검할 수 있어, Claude Code처럼 인증과 장시간 스트리밍이 함께 필요한 개발 작업에서 원인을 단계적으로 좁히기 좋습니다. 이미 다른 도구에서 포트와 환경 변수를 따로 관리하느라 혼란을 겪었다면, 이 글의 기준선에 맞춰 Clash Verge 설정을 통일해 보는 것이 자연스러운 다음 단계입니다.

지금 Clash를 무료로 다운로드하고 자유로운 인터넷 경험을 →