Claude Code가 로그인되지 않거나 명령 실행 중 멈추나요? 초보자도 따라 할 수 있도록 Clash Verge에 프록시를 등록하고 터미널 트래픽을 연결하는 방법, 모드 선택과 자주 발생하는 오류 해결법을 정리했습니다.

Claude Code 국내 사용법: Clash Verge 프록시 설정 가이드

Claude Code와 Clash Verge의 역할부터 구분하기

Claude Code는 터미널에서 코드베이스를 읽고 명령을 실행하며, 외부 API와 통신하는 개발 도구입니다. 반면 Clash Verge는 로컬 컴퓨터에 프록시 포트를 열고, 그 포트로 들어온 요청을 설정된 노드와 규칙에 따라 전달하는 클라이언트입니다. Claude Code 자체에 노드 목록을 넣는 것이 아니라, 터미널이 Clash Verge의 로컬 프록시 주소를 사용하도록 연결하는 구조입니다.

이 구분을 먼저 이해해야 문제를 빠르게 좁힐 수 있습니다. Clash Verge 화면에서 노드 지연 테스트가 성공해도 터미널이 자동으로 프록시를 사용하는 것은 아닙니다. 브라우저에서 웹페이지가 열리는 것도 Claude Code의 연결이 정상이라는 뜻은 아닙니다. 브라우저는 시스템 프록시를 따르지만, 터미널 프로그램은 환경 변수나 자체 옵션을 요구하는 경우가 있기 때문입니다.

• Clash Verge: 로컬 HTTP, SOCKS5 또는 혼합 포트를 열고 실제 출구 노드를 선택합니다.
• 시스템 프록시: 운영체제에 프록시 주소를 등록해 이를 따르는 앱의 요청을 전달합니다.
• 터미널 환경 변수: Claude Code와 패키지 관리자 같은 명령줄 프로그램에 프록시 주소를 직접 알려줍니다.
• TUN 모드: 애플리케이션이 프록시 설정을 읽지 않아도 네트워크 계층에서 트래픽을 가로채는 방식입니다.

Clash Verge에서 프록시 준비하기

먼저 Clash Verge 또는 Clash Verge Rev를 실행하고, 사용할 설정 프로필을 불러옵니다. Profiles 또는 설정 화면에서 구독을 추가한 뒤 업데이트를 실행하고, 노드와 정책 그룹이 정상적으로 표시되는지 확인합니다. 프로필을 선택했는데 프록시 그룹이 비어 있거나 노드 수가 0개라면 터미널 설정을 진행해도 연결되지 않으므로, 먼저 구독 응답과 설정 파일 로드 상태를 점검해야 합니다.

그다음 Proxies 화면에서 실제로 사용할 정책 그룹을 선택합니다. select 그룹이라면 특정 노드를 직접 선택하고, url-test 그룹이라면 지연 테스트 결과를 바탕으로 자동 선택하도록 둘 수 있습니다. Claude Code처럼 로그인과 API 요청의 안정성이 중요한 작업에서는 숫자가 가장 낮은 노드만 고르기보다, 반복 테스트에서 시간 초과가 발생하지 않고 응답이 일정한 노드를 선택하는 편이 낫습니다.

Settings 또는 General 화면에서 로컬 포트도 확인합니다. 일반적인 mihomo 설정에서는 mixed-port가 HTTP와 SOCKS5 요청을 함께 받을 수 있는 포트로 사용됩니다. 기본값이 항상 동일하다고 단정할 수는 없으므로, 화면에 표시된 실제 값을 확인해야 합니다. 예를 들어 설정 파일에 다음과 같이 표시되어 있다면 터미널에서 사용할 주소는 127.0.0.1:7890입니다.

mixed-port: 7890
allow-lan: false
mode: rule
log-level: info

allow-lan: false는 다른 기기의 접근을 허용하지 않고 현재 컴퓨터에서만 로컬 포트를 사용한다는 의미입니다. 같은 컴퓨터의 Claude Code를 연결하는 목적이라면 보안상 기본값인 로컬 바인딩을 유지하는 것이 좋습니다. 다른 기기에서 이 프록시를 사용해야 하는 경우에는 방화벽, 인증, LAN 노출 범위를 별도로 검토해야 하며 단순히 allow-lan만 켜는 방식은 권장하지 않습니다.

터미널에 Claude Code 프록시 연결하기

가장 먼저 시도할 방법은 터미널 세션에 HTTP와 HTTPS 프록시 환경 변수를 설정하는 것입니다. Claude Code가 사용하는 API 요청뿐 아니라, 해당 셸에서 실행되는 패키지 관리자와 기타 HTTPS 명령에도 같은 설정이 적용될 수 있습니다. Clash Verge의 혼합 포트가 7890인 경우 다음처럼 입력합니다.

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

macOS와 Linux의 Bash 또는 Zsh에서는 위 명령이 현재 터미널 창에만 적용됩니다. 새 터미널을 열 때마다 자동으로 사용하려면 사용하는 셸의 설정 파일에 추가할 수 있습니다. 다만 회사 네트워크, 공유 컴퓨터, 원격 서버에서는 프록시 주소가 의도하지 않은 명령까지 적용될 수 있으므로 영구 등록 전에 범위를 확인하세요.

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"

Windows 명령 프롬프트에서는 다음과 같이 설정합니다.

set HTTP_PROXY=http://127.0.0.1:7890
set HTTPS_PROXY=http://127.0.0.1:7890
set ALL_PROXY=http://127.0.0.1:7890

환경 변수를 설정한 뒤에는 먼저 Claude Code를 실행하기 전에 간단한 HTTPS 요청으로 프록시 경로를 확인하는 것이 좋습니다. 시스템에 설치된 curl로 테스트할 수 있습니다.

curl -I https://api.anthropic.com

이 명령의 결과만으로 인증 성공 여부를 판단할 수는 없습니다. 목적은 DNS 실패, 연결 거부, TLS 시간 초과처럼 네트워크 계층의 오류가 발생하는지 확인하는 것입니다. 응답이 반환되거나 서버 측 HTTP 상태 코드가 보인다면 적어도 해당 주소까지 연결은 도달한 것입니다. 반대로 Connection refused가 나오면 포트 번호가 틀렸거나 Clash Verge 코어가 실행되지 않은 상태일 가능성이 큽니다.

시스템 프록시와 TUN 모드 중 무엇을 선택할까

터미널 환경 변수만 설정할지, Clash Verge의 시스템 프록시를 켤지, TUN 모드를 사용할지는 사용하는 도구의 특성에 따라 결정하면 됩니다. Claude Code를 한 개의 터미널에서만 사용할 예정이라면 환경 변수 방식이 가장 범위가 좁고 원상 복구도 쉽습니다. 브라우저와 여러 GUI 프로그램까지 함께 연결하려면 시스템 프록시가 편리합니다.

• 환경 변수 방식: 현재 셸의 요청에만 적용하기 쉽고, 개발 프로젝트별로 켜고 끌 수 있습니다. 단, 환경 변수를 읽지 않는 프로그램에는 적용되지 않습니다.
• 시스템 프록시: 운영체제 프록시를 따르는 브라우저와 일반 앱을 한 번에 연결합니다. 일부 터미널 도구나 자체 네트워크 라이브러리는 이를 무시할 수 있습니다.
• TUN 모드: 프록시 환경 변수를 설정하지 않는 프로그램까지 네트워크 계층에서 포착합니다. 관리자 권한, 가상 어댑터, DNS 설정이 필요할 수 있어 문제 발생 시 확인할 항목이 더 많습니다.

TUN을 사용할 때는 먼저 Clash Verge의 TUN 기능을 켜고, 운영체제가 권한 요청을 표시하면 허용합니다. mihomo 계열 설정에서는 일반적으로 다음과 같은 항목이 관련됩니다.

tun:
  enable: true
  stack: system
  auto-route: true
  auto-detect-interface: true
  dns-hijack:
    - any:53

클라이언트의 UI가 위 YAML을 그대로 노출하지 않더라도 내부적으로 비슷한 옵션을 제공합니다. auto-route는 시스템 라우팅 경로를 자동으로 조정하고, dns-hijack은 DNS 요청을 Clash 코어가 처리하도록 유도합니다. TUN을 켠 뒤 인터넷이 전혀 되지 않는다면 바로 여러 설정을 동시에 바꾸지 말고, TUN을 끈 상태에서 시스템 프록시 또는 환경 변수 방식이 정상인지 먼저 비교하세요.

처음 설정하는 사용자에게는 다음 순서를 권장합니다.

1. Clash Verge의 코어와 선택한 노드가 정상인지 확인합니다.
2. 혼합 포트 번호를 확인합니다.
3. 현재 터미널에 프록시 환경 변수를 설정합니다.
4. curl로 HTTPS 연결을 테스트합니다.
5. Claude Code를 실행해 로그인 또는 간단한 읽기 작업을 시도합니다.
6. 환경 변수 방식으로 해결되지 않을 때만 시스템 프록시와 TUN을 차례로 검토합니다.

로그인 실패와 명령 중단 문제 해결하기

로그인 화면이 계속 돌아가거나 인증 콜백이 완료되지 않을 때는 브라우저와 터미널이 서로 다른 네트워크 경로를 사용하는지 먼저 확인하세요. 브라우저는 시스템 프록시를 사용하지만, Claude Code를 실행한 터미널에는 환경 변수가 없을 수 있습니다. 반대로 터미널은 프록시를 사용하지만 브라우저가 다른 프록시를 사용하면 로그인 완료 후 로컬 콜백이나 인증 페이지의 동작이 엇갈릴 수 있습니다.

다음 항목을 순서대로 확인하면 됩니다.

• Clash Verge 로그: Claude Code를 다시 실행하면서 Logs 또는 Connections 화면을 열고 대상 도메인 요청이 생성되는지 확인합니다. 아무 요청도 없다면 터미널이 프록시 포트를 사용하지 않는 것입니다.
• 정책 규칙: 해당 도메인이 DIRECT로 처리되는지, 선택한 프록시 그룹으로 전달되는지 확인합니다. 규칙 모드에서는 도메인별 결과가 다를 수 있습니다.
• 포트 점유: curl에서 연결 거부가 발생하면 Clash 포트가 실제로 열려 있는지 확인합니다. 포트를 변경했다면 환경 변수도 새 번호로 바꿔야 합니다.
• DNS와 TUN 중복: 시스템 프록시와 TUN을 동시에 켠 뒤 문제가 생겼다면 하나만 남겨 비교합니다. 여러 네트워크 계층을 동시에 바꾸면 원인 추적이 어려워집니다.
• 인증·인증서 오류: TLS handshake, 인증서 검증, 시간 초과 오류는 노드의 TLS 연결이나 시스템 시간, 보안 프로그램의 HTTPS 검사와 관련될 수 있습니다.

명령 실행 중 멈추는 현상은 연결이 완전히 끊긴 경우와 응답이 늦은 경우를 구분해야 합니다. Connections 화면에서 연결이 계속 유지되지만 데이터가 오지 않는다면 노드 지연, 업스트림 서버 응답 지연, 정책 그룹의 불안정한 선택을 의심합니다. 짧은 시간마다 노드를 자동 변경하는 url-test 그룹을 사용 중이라면 작업 중 연결이 바뀌지 않도록 안정적인 select 그룹에서 노드를 직접 선택해 비교해 보세요.

설정을 초기화할 때는 한 번에 모든 파일을 삭제하기보다, 현재 셸의 환경 변수 제거, Clash Verge의 시스템 프록시 해제, TUN 해제 순서로 되돌리는 편이 안전합니다. 이후 하나의 방식만 다시 켜고 curl 테스트와 Claude Code 실행을 반복하면 어느 단계에서 문제가 재발하는지 기록할 수 있습니다. 프록시 포트, 선택한 모드, 정책 그룹, 발생한 오류 문구를 함께 메모해 두면 다음 점검도 훨씬 빨라집니다.