Claude Code를 Clash Verge로 안정적으로 쓰는 설정 방법

Claude Code는 터미널에서 직접 실행되기 때문에 웹 브라우저만 프록시로 연결한 환경에서는 로그인이나 API 요청이 실패할 수 있습니다. 특히 인증 페이지는 열리지만 코드 생성 단계에서 멈추거나, 작업 중 연결이 끊기고 재시도만 반복되는 문제가 자주 발생합니다. Clash Verge를 시스템 프록시로 실행한 뒤 터미널 프로세스에도 프록시 환경 변수를 전달하면 Claude Code를 훨씬 안정적으로 사용할 수 있습니다. 이 글에서는 Clash Verge 설치와 구독 추가, 노드 선택, 터미널 프록시 설정, 도메인별 분할 라우팅, 문제 발생 시 점검 순서를 단계별로 설명합니다.

Clash Verge 설치와 기본 준비

Clash Verge는 Clash 계열 코어를 데스크톱 환경에서 쉽게 관리할 수 있는 클라이언트입니다. 운영체제의 시스템 프록시를 켜고 끄거나, 구독 URL을 추가하고, 프록시 그룹의 노드를 선택하는 작업을 GUI에서 처리할 수 있습니다. 2026년 현재 배포판에 따라 Clash Verge와 Clash Verge Rev의 화면 구성과 코어 이름이 조금 다를 수 있지만, 기본적인 설정 흐름은 거의 같습니다.

1. 사용 중인 운영체제에 맞는 Clash Verge 또는 Clash Verge Rev 설치 파일을 공식 배포 경로에서 다운로드합니다.
2. 프로그램을 설치한 뒤 실행하고, 방화벽 또는 네트워크 권한 요청이 표시되면 내용을 확인한 후 허용합니다.
3. Profiles 또는 프로필 메뉴에서 서비스 제공자가 발급한 구독 URL을 추가합니다.
4. 구독을 업데이트한 다음 목록에 표시된 설정 파일을 클릭해 활성 프로필로 지정합니다.
5. Proxies 메뉴에서 실제로 사용할 프록시 그룹과 노드를 선택합니다.
6. 마지막으로 대시보드 또는 일반 설정에서 System Proxy를 활성화합니다.

구독 URL은 계정 인증 정보와 연결되어 있으므로 공개 저장소, 채팅방, 화면 녹화 영상에 노출하지 않아야 합니다. 이미 외부에 유출했다면 제공 업체의 관리 페이지에서 구독 URL을 재발급하는 것이 안전합니다. 또한 구독을 추가했는데 노드가 표시되지 않는다면 URL의 앞뒤 공백, 만료 여부, 네트워크 연결 상태, 구독 형식의 호환성을 먼저 확인하세요.

안정적인 노드 선택 기준

Claude Code용 노드는 단순히 핑이 가장 낮은 노드보다 장시간 연결 안정성과 HTTPS 처리 품질이 중요합니다. Proxies 화면에서 여러 노드의 지연 시간을 테스트하되, 한 번의 측정값만 보고 결정하지 마세요. 같은 지역의 노드를 2~3개 비교하고, 실제로 로그인 페이지와 API 요청을 모두 시험하는 편이 정확합니다.

터미널에 프록시 연결하기

Claude Code가 실행되는 프로세스는 일반적으로 HTTP_PROXY, HTTPS_PROXY, ALL_PROXY 같은 환경 변수를 읽습니다. Clash Verge가 로컬에서 제공하는 포트 번호는 설치 버전과 설정에 따라 달라질 수 있습니다. 일반적으로 HTTP 프록시는 7890, SOCKS5 프록시는 7891 또는 유사한 포트를 사용하지만, 반드시 Clash Verge의 설정 화면에서 현재 값을 확인해야 합니다.

가장 먼저 Clash Verge의 Settings 또는 일반 설정에서 HTTP 포트와 SOCKS 포트를 확인합니다. Claude Code와 관련 명령줄 도구의 호환성을 고려하면 HTTP 프록시 포트를 HTTP_PROXY와 HTTPS_PROXY에 지정하는 방식이 이해하기 쉽습니다. HTTPS 요청도 로컬 HTTP 프록시의 CONNECT 기능을 통해 전달할 수 있습니다.

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

# 프록시가 적용되었는지 확인
env | grep -i proxy

# Claude Code 실행
claude

위 설정은 현재 터미널 세션에만 적용됩니다. 터미널을 닫으면 사라지므로 일시적인 진단이나 작업에 적합합니다. 먼저 이 방식으로 연결이 정상인지 확인한 뒤, 문제가 없을 때 셸 설정 파일에 영구적으로 추가하세요. macOS와 대부분의 Linux 배포판에서 Bash는 ~/.bashrc 또는 ~/.bash_profile, Zsh는 ~/.zshrc를 사용합니다.

# ~/.zshrc 또는 ~/.bashrc에 추가
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

# 로컬 주소는 프록시를 거치지 않도록 제외
export NO_PROXY=localhost,127.0.0.1,::1

# 설정 다시 읽기
source ~/.zshrc

Windows에서는 PowerShell의 환경 변수 문법이 다릅니다. 현재 창에서만 적용하려면 $env: 형식을 사용합니다. Windows용 Claude Code를 다른 터미널에서 실행한다면 해당 터미널의 환경 변수도 별도로 확인해야 합니다.

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

# 현재 값 확인
Get-ChildItem Env:*proxy*

# Claude Code 실행
claude

Claude Code 도메인별 분할 라우팅

모든 트래픽을 프록시로 보내는 Global 모드는 가장 간단하지만, 일반 개발 사이트나 사내 리소스까지 프록시를 통과하게 만들어 불필요한 지연과 인증 문제를 일으킬 수 있습니다. 반대로 Rule 모드에서는 Claude Code가 실제로 사용하는 도메인이 DIRECT로 처리되어 로그인 또는 API 요청이 실패할 수 있습니다. 따라서 평소에는 Rule 모드를 사용하고, 필요한 서비스 도메인만 프록시 그룹으로 보내는 구성이 실용적입니다.

정확한 도메인 목록은 클라이언트 버전, 인증 방식, 사용 지역에 따라 달라질 수 있습니다. 특정 도메인을 무조건 추가하기보다 연결 로그에서 실제 요청 대상을 확인하고 필요한 항목만 규칙에 넣으세요. 일반적으로 인증 서비스, API 엔드포인트, 계정 서비스, 업데이트 서버가 서로 다른 도메인을 사용할 수 있으므로 로그인만 성공했다고 설정이 끝난 것은 아닙니다.

proxy-groups:
  - name: Claude-Code
    type: fallback
    proxies:
      - Stable-Node
      - Backup-Node
    url: https://www.gstatic.com/generate_204
    interval: 180

rules:
  # 실제 서비스 도메인은 연결 로그를 확인해 필요한 항목만 추가
  - DOMAIN-SUFFIX,anthropic.com,Claude-Code
  - DOMAIN-SUFFIX,claude.ai,Claude-Code
  - DOMAIN-SUFFIX,github.com,Claude-Code
  - DOMAIN-SUFFIX,githubusercontent.com,Claude-Code

  # 로컬 및 사내 리소스는 직접 연결
  - DOMAIN-SUFFIX,local,DIRECT
  - IP-CIDR,127.0.0.0/8,DIRECT,no-resolve

  # 나머지 트래픽의 기본 경로
  - MATCH,DIRECT

위 예시는 개념을 설명하기 위한 템플릿입니다. 실제 설정 파일에서 Stable-Node, Backup-Node는 구독에 표시된 프록시 이름과 정확히 일치해야 합니다. 이름에 특수문자나 공백이 포함되어 있다면 YAML 문법에 맞게 따옴표를 사용하고, 들여쓰기는 탭이 아닌 공백으로 유지하세요.

Rule 모드에서 로그인은 되지만 코드 요청이 실패하는 경우에는 Clash Verge의 Connections 또는 Logs 화면을 열어 보세요. 실패 시각에 반복적으로 나타나는 도메인을 확인하고, 해당 도메인을 기존 규칙보다 위쪽에 추가해야 합니다. Clash 규칙은 위에서 아래 순서로 평가되므로, 먼저 MATCH,DIRECT가 나오면 그 아래에 추가한 프록시는 적용되지 않습니다.

TUN 모드가 필요한 경우

일부 CLI 프로그램은 시스템 프록시나 환경 변수를 무시하고 직접 소켓을 열 수 있습니다. 이때는 Clash Verge의 TUN 모드를 고려할 수 있습니다. TUN 모드는 가상 네트워크 인터페이스를 만들어 애플리케이션의 트래픽을 더 넓은 범위에서 가로채므로, 환경 변수를 지원하지 않는 프로그램에도 효과가 있습니다.

다만 TUN 모드는 관리자 권한, 네트워크 드라이버, DNS 모드와 관련된 변수가 늘어나므로 처음부터 무조건 활성화할 필요는 없습니다. 먼저 환경 변수 방식으로 Claude Code를 테스트하고, 특정 하위 프로세스만 우회하거나 프록시를 무시하는 것이 확인될 때 TUN을 켜는 순서가 좋습니다. TUN을 사용할 때는 기존 VPN, 기업 보안 프로그램, 다른 가상 네트워크 도구와 충돌할 수 있으므로 동시에 여러 터널을 실행하지 마세요.

연결 문제를 진단하는 순서

설정 후에도 Claude Code가 연결되지 않는다면 여러 값을 한꺼번에 변경하지 말고 아래 순서대로 확인하세요. 이렇게 하면 Clash 문제인지, 터미널 환경 변수 문제인지, 계정 인증 문제인지 빠르게 분리할 수 있습니다.

1. Clash Verge 자체 연결 확인: Proxies 화면에서 선택한 노드의 테스트 결과를 확인하고 브라우저에서 일반 HTTPS 사이트를 열어 봅니다.
2. 시스템 프록시 확인: System Proxy를 켠 뒤 브라우저의 IP 또는 연결 상태가 바뀌는지 확인합니다.
3. 터미널 변수 확인: env | grep -i proxy 또는 PowerShell의 Get-ChildItem Env:*proxy*로 값이 비어 있지 않은지 검사합니다.
4. 포트 확인: 환경 변수에 입력한 포트가 Clash Verge의 HTTP 또는 SOCKS 포트와 같은지 확인합니다.
5. 간단한 HTTPS 요청 테스트: 터미널에서 curl -I https://example.com을 실행해 프록시를 통한 기본 요청이 가능한지 봅니다.
6. Clash 로그 확인: 요청이 로그에 나타나는지, 연결 거부·TLS 오류·DNS 실패 중 어떤 유형인지 확인합니다.
7. 규칙과 노드 분리 테스트: 일시적으로 Global 모드에서 테스트한 후 정상이라면 Rule 모드의 도메인 규칙을 수정합니다.
8. 인증 세션 재시작: 프록시를 변경한 뒤 기존 Claude Code 프로세스를 완전히 종료하고 새 터미널에서 다시 로그인합니다.

장시간 작업에서는 노드 하나에만 의존하지 않는 것이 좋습니다. fallback 그룹을 사용하면 기본 노드가 헬스 체크에 실패했을 때 백업 노드로 전환할 수 있습니다. 단, 이미 실행 중인 요청이 반드시 중단 없이 이어진다는 뜻은 아닙니다. 새 연결부터 백업 노드가 사용될 수 있으므로, 중요한 변경은 자주 저장하고 작업 단위를 작게 나누는 습관도 함께 유지하세요.

정리하면 가장 안정적인 순서는 Clash Verge에서 구독과 노드를 먼저 정상화하고, 시스템 프록시와 터미널 환경 변수를 구분해 설정한 다음, Rule 모드의 연결 로그를 기반으로 Claude Code 관련 도메인을 보완하는 것입니다. 이 과정을 따르면 무작정 Global 모드에 의존하지 않고도 필요한 요청만 프록시로 전달하면서 개발 환경의 예측 가능성과 연결 안정성을 높일 수 있습니다.