Claude Code가 터미널에서만 연결되지 않는 이유

Claude Code는 브라우저에서 사용하는 일반적인 채팅 서비스와 달리, 개발자의 터미널에서 실행되는 CLI 에이전트입니다. 프로젝트 폴더의 파일을 읽고, 명령을 실행하고, 코드 변경 사항을 확인하는 과정에서 여러 웹 주소와 API 연결을 연속적으로 사용합니다. 그래서 브라우저에서 Claude가 정상적으로 열리더라도 claude 명령만 멈추거나, 로그인 브라우저는 떴지만 터미널 세션으로 돌아오지 못하는 문제가 생길 수 있습니다.

특히 Clash Verge에서 시스템 프록시만 켠 상태라면 브라우저는 프록시를 타지만 터미널 프로세스는 HTTP_PROXY·HTTPS_PROXY 환경 변수를 읽지 못하거나, Node.js 런타임의 인증서·소켓 연결 방식 때문에 별도의 경로를 사용할 수 있습니다. 이때 나타나는 증상은 ETIMEDOUT, ECONNRESET, fetch failed, 로그인 페이지 무한 대기, 모델 응답 전 멈춤 등으로 다양합니다.

이 글에서는 특정 우회 서비스를 소개하는 것이 아니라, 이미 사용이 허용된 네트워크와 합법적인 구독 환경에서 Clash Verge와 Claude Code를 안정적으로 연결하는 방법을 설명합니다. 핵심은 구독을 먼저 정상적으로 활성화하고, 로컬 혼합 포트를 확인한 뒤, 터미널에 프록시를 명시하고, 그래도 적용되지 않는 애플리케이션에는 TUN 모드를 단계적으로 사용하는 것입니다.

준비할 것: 최신 버전의 Clash Verge Rev 또는 사용하는 Clash Verge 클라이언트, 유효한 Clash 형식 구독 URL, Claude 계정, 그리고 터미널에서 환경 변수를 설정할 수 있는 권한이 필요합니다. 회사·학교 네트워크에서는 먼저 관리자의 프록시 및 AI 서비스 이용 정책을 확인하세요.

Claude Code와 Clash Verge의 연결 구조 이해하기

Clash Verge는 자체적으로 인터넷 서비스를 제공하는 프로그램이 아니라, 로컬 컴퓨터에 프록시 포트를 열고 규칙에 따라 트래픽을 전달하는 클라이언트입니다. 일반적으로 하나의 혼합 포트가 HTTP와 SOCKS5 요청을 함께 받아 주므로, 애플리케이션이 지원하는 프록시 형식에 맞춰 같은 포트를 사용할 수 있습니다. 기본값은 설치 버전이나 사용자가 수정한 설정에 따라 달라질 수 있으므로 숫자를 외워서 입력하지 말고 Clash Verge 화면에서 직접 확인해야 합니다.

구성 요소 역할 점검할 내용
구독 프로필 노드, 프록시 그룹, 규칙을 제공 프로필이 최신 상태이며 활성화되어 있는가
프록시 모드 요청을 어떤 규칙으로 보낼지 결정 현재 모드가 전부 직접 연결로 고정되어 있지 않은가
혼합 포트 터미널이 접속할 로컬 HTTP/SOCKS5 입구 127.0.0.1 주소와 포트가 실제로 열려 있는가
환경 변수 Claude Code 프로세스에 프록시 사용을 전달 대문자·소문자 변수와 주소 형식이 올바른가
TUN 모드 프록시를 인식하지 못하는 앱의 트래픽을 가상 인터페이스로 처리 권한, DNS, 서비스 모드가 정상적으로 설정되었는가

Claude Code를 실행하는 셸이 프록시 변수를 전혀 전달하지 않는다면 Clash Verge의 연결 로그에 해당 요청이 나타나지 않을 수 있습니다. 반대로 로그에 도메인이 보이지만 계속 실패한다면, 프록시 적용 자체보다 잘못된 규칙, 불안정한 노드, DNS 응답, 인증 세션 만료를 조사해야 합니다. 따라서 “인터넷이 되느냐”보다 Claude Code 실행 직후 Clash 로그에 어떤 호스트와정책가 기록되는지를 확인하는 것이 정확합니다.

구독 URL 보호: 구독 주소에는 계정 식별 정보나 갱신 토큰이 포함될 수 있습니다. 터미널 출력, 화면 녹화, Git 저장소, 이슈 게시물에 URL 전체를 붙여 넣지 마세요. 노출이 의심되면 제공업체에서 구독 링크를 재발급하는 편이 안전합니다.

Clash Verge에서 먼저 확인할 설정

터미널 설정을 시작하기 전에 Clash Verge 자체가 정상적으로 동작하는지 확인합니다. GUI 단계에서 문제가 남아 있으면 환경 변수나 TUN을 추가해도 원인을 더 복잡하게 만들 뿐입니다. 먼저 Clash Verge를 실행하고 프로필 또는 Profiles 메뉴에서 구독 URL을 가져옵니다. URL을 붙여넣은 뒤 프로필 생성이 완료되면 해당 프로필을 활성화하고, 프록시 그룹에서 연결 가능한 노드를 선택합니다.

  1. 프로필을 가져옵니다. Clash Verge의 프로필 화면에서 구독 URL을 추가하고 새로고침을 실행합니다. 오류가 표시되면 URL 만료, 제공업체의 접속 제한, 잘못된 형식을 먼저 확인합니다.
  2. 활성 프로필을 확인합니다. 여러 프로필이 등록되어 있다면 실제로 체크 표시가 된 프로필이 Claude Code용 규칙을 포함하는지 확인합니다. 비활성 프로필을 수정해도 실행 중인 커널에는 반영되지 않을 수 있습니다.
  3. 프록시 그룹을 선택합니다. Proxies 화면에서 자동 선택 또는 수동 노드를 고릅니다. 지연 시간이 낮다는 이유만으로 선택하기보다 연속 요청과 HTTPS 연결이 안정적인 노드를 우선합니다.
  4. 모드를 확인합니다. Rule 모드는 도메인과 규칙에 따라 연결을 나누고, Global 모드는 대부분의 요청을 선택한 프록시로 보냅니다. 진단 단계에서는 Global로 단순화한 뒤 성공하면 Rule 모드로 돌아가 원인을 좁힐 수 있습니다.
  5. 혼합 포트를 기록합니다. Settings 또는 General 화면에서 HTTP·SOCKS5 혼합 포트 값을 확인합니다. 예시로 127.0.0.1:7890을 사용할 수 있지만, 실제 값은 반드시 자신의 화면에 표시된 숫자를 사용해야 합니다.

이제 브라우저에서 Claude 관련 로그인 페이지가 열리는지 확인하고, Clash Verge의 Connections 또는 Logs 화면을 동시에 띄워 둡니다. 로그인 버튼을 눌렀을 때 관련 연결이 전혀 기록되지 않으면 터미널이나 브라우저가 Clash를 통과하지 않는 것입니다. 연결이 기록되지만 실패한다면 같은 요청이 매번 같은 프록시 그룹으로 나가는지, 중간에 DIRECT로 바뀌지 않는지 살펴보세요.

로컬 포트가 실제로 열려 있는지 테스트하기

운영체제에 따라 터미널에서 로컬 포트에 접근할 수 있는지 간단히 확인할 수 있습니다. 아래 명령의 포트 번호는 예시이므로 Clash Verge에서 확인한 값으로 바꾸세요.

curl -I -x http://127.0.0.1:7890 https://example.com

응답 헤더가 돌아오면 적어도 로컬 HTTP 프록시 입구는 접근 가능한 상태입니다. Connection refused가 나타나면 포트 번호가 다르거나 Clash Verge가 종료되었거나, 다른 프로그램이 설정을 덮어쓴 경우입니다. 407 Proxy Authentication Required가 나온다면 로컬 프록시에 인증을 요구하도록 설정했는지 확인하고, 인증 정보를 모르는 상태에서 임의로 주소를 계속 바꾸지 않는 것이 좋습니다.

터미널에 Claude Code 프록시를 적용하는 방법

Claude Code를 설치하거나 실행할 때는 명령을 입력한 셸이 프록시 환경 변수를 가지고 있어야 합니다. 일회성 테스트에는 명령 앞에 변수를 붙이는 방식이 가장 안전합니다. 현재 셸의 다른 작업에 영향을 주지 않기 때문에 먼저 이 방법으로 성공 여부를 확인하세요.

HTTP_PROXY=http://127.0.0.1:7890 \
HTTPS_PROXY=http://127.0.0.1:7890 \
ALL_PROXY=socks5://127.0.0.1:7890 \
claude

모든 런타임이 ALL_PROXY를 동일하게 처리하는 것은 아니므로, 우선 HTTP_PROXY와 HTTPS_PROXY를 중심으로 확인하는 편이 좋습니다. SOCKS5를 사용할 때는 애플리케이션이 DNS를 프록시 측에서 처리하는지에 따라 socks5://와 socks5h://의 동작이 달라질 수 있습니다. 지원하지 않는 형식을 무작정 추가하면 오류 메시지가 더 모호해질 수 있으므로, HTTP 혼합 포트부터 테스트하고 필요한 경우 SOCKS5로 바꾸세요.

macOS나 Linux에서 매번 입력하기 번거롭다면 사용하는 셸의 설정 파일에 변수를 추가할 수 있습니다. Bash는 ~/.bashrc, Zsh는 ~/.zshrc를 주로 사용합니다. 다만 회사망과 개인망에서 프록시 사용 여부가 다르다면 고정 export보다 별도의 시작 스크립트나 alias가 안전합니다.

export HTTP_PROXY="http://127.0.0.1:7890"
export HTTPS_PROXY="http://127.0.0.1:7890"
export NO_PROXY="localhost,127.0.0.1"

Windows PowerShell에서는 다음처럼 현재 세션에만 적용할 수 있습니다.

$env:HTTP_PROXY="http://127.0.0.1:7890"
$env:HTTPS_PROXY="http://127.0.0.1:7890"
$env:NO_PROXY="localhost,127.0.0.1"
claude

설정 후 새 터미널을 열었거나 IDE 내장 터미널을 사용한다면 환경 변수가 실제로 전달되었는지 먼저 확인합니다. macOS·Linux에서는 env | grep -i proxy, PowerShell에서는 Get-ChildItem Env: | Where-Object Name -match "PROXY"를 사용할 수 있습니다. 단, 프록시 주소나 인증 토큰이 출력될 수 있으므로 결과 화면을 그대로 공유하지 마세요.

진단 순서: 먼저 curl로 로컬 포트를 테스트하고, 그다음 환경 변수를 적용한 상태에서 Claude Code를 실행하세요. 두 단계를 한 번에 바꾸지 않으면 “포트 문제”와 “Claude 인증 문제”를 쉽게 구분할 수 있습니다.

환경 변수로 해결되지 않을 때 TUN 모드 사용하기

일부 터미널 도구, IDE 플러그인, 백그라운드 프로세스는 운영체제 환경 변수를 무시합니다. Claude Code를 터미널에서 직접 실행해도 내부에서 별도의 Node.js 프로세스를 만들거나, 인증 브라우저와 로컬 콜백을 다른 방식으로 열면 프록시 변수가 모든 연결에 적용되지 않을 수 있습니다. 이때 Clash Verge의 TUN 모드가 대안이 됩니다.

TUN은 가상 네트워크 인터페이스를 만들고 시스템 트래픽을 Clash 커널로 전달하는 방식입니다. 따라서 애플리케이션이 프록시를 지원하지 않아도 연결을 규칙에 따라 처리할 가능성이 높아집니다. 그러나 TUN은 단순한 토글 하나가 아니라 네트워크 라우팅과 DNS에 관여하므로, 문제를 해결한 뒤에도 로컬 개발 서버나 Docker, 사내 주소가 정상적으로 유지되는지 확인해야 합니다.

  1. Clash Verge 설정에서 TUN 메뉴를 엽니다. 클라이언트 버전에 따라 Settings, General, Kernel 또는 Service 메뉴 안에 위치할 수 있습니다.
  2. 서비스 모드 또는 관리자 권한을 준비합니다. TUN은 네트워크 인터페이스를 만들기 위해 운영체제 권한을 요구할 수 있습니다. 출처가 불분명한 권한 요청은 승인하지 말고, 공식 릴리스와 설치 경로를 다시 확인합니다.
  3. TUN을 활성화합니다. 스택은 기본값을 먼저 사용하고, 연결이 되지 않을 때만 다른 스택을 시험합니다. 한 번에 여러 옵션을 변경하면 어느 설정이 효과가 있었는지 알기 어렵습니다.
  4. DNS 모드를 점검합니다. TUN을 켠 뒤 웹사이트는 열리지만 Claude Code만 실패한다면 DNS 응답과 규칙 매칭을 확인합니다. fake-ip, redir-host 등 모드 차이는 운영체제와 네트워크 환경에 따라 결과가 달라질 수 있습니다.
  5. 기존 프록시 변수와 비교합니다. TUN을 켠 상태에서 환경 변수를 제거하고 Claude Code를 실행해 봅니다. 두 방식을 동시에 사용하면 이중 프록시나 예상하지 못한 우회 경로가 만들어질 수 있습니다.

TUN을 켠 직후에는 브라우저, 터미널, Git, Docker 같은 기존 작업을 하나씩 테스트합니다. 로컬호스트 요청은 NO_PROXY 또는 Clash의 프로세스·IP 규칙으로 직접 연결해야 할 수 있습니다. 사내 도메인이나 개발용 도메인이 외부 프록시로 나가면 인증서 오류, 느린 응답, 접근 차단이 발생할 수 있으므로 업무 환경에서는 예외 규칙을 별도로 관리하세요.

로그인 오류와 연결 실패를 단계별로 좁히기

Claude Code 로그인에서 브라우저가 열리지 않는 문제와 로그인 후 터미널에 세션이 돌아오지 않는 문제는 서로 다릅니다. 브라우저조차 열리지 않으면 CLI가 로컬 명령 실행이나 기본 브라우저 호출 단계에서 막힌 것일 수 있습니다. 브라우저는 열렸지만 인증이 끝나지 않으면 계정 서비스와 인증 콜백 경로가 서로 다른 연결 정책을 사용하고 있는지 확인해야 합니다.

  • 로그에 아무것도 없음: Claude Code 프로세스가 Clash를 사용하지 않는 상태입니다. 환경 변수 철자, IDE 터미널의 실행 환경, TUN 활성화 여부를 확인합니다.
  • 연결은 보이지만 시간 초과: 선택한 노드의 품질, 규칙 그룹, DNS 응답 지연을 확인합니다. 같은 노드에서 다른 HTTPS 사이트도 느린지 비교하면 서비스 문제와 일반 네트워크 문제를 구분할 수 있습니다.
  • 로그인 후 콜백 실패: localhost 예외가 프록시를 타고 있거나, 보안 프로그램이 로컬 콜백 포트를 차단하는지 확인합니다. localhost와 127.0.0.1을 직접 연결 대상으로 유지하세요.
  • 인증은 되었지만 명령 실행 실패: 로그인 문제가 아니라 모델 API 요청이나 권한 문제일 수 있습니다. Clash 로그에서 로그인 시점과 실제 요청 시점의 호스트 및 정책을 따로 비교합니다.
  • 가끔 성공하고 가끔 실패: 자동 노드 그룹이 요청마다 다른 노드를 선택하거나, 노드의 장시간 연결 품질이 불안정할 수 있습니다. 진단 중에는 고정 노드로 바꾸고 재현성을 확보합니다.

인증서 오류가 표시될 때는 시스템 시간을 먼저 확인하고, Clash Verge와 운영체제의 인증서 검사 기능을 함부로 끄지 마세요. “인증서 검증 비활성화”는 일시적으로 오류를 숨길 수 있지만 중간자 공격에 취약해지고 원인 분석도 어려워집니다. 또한 Claude Code, Node.js, Clash Verge를 동시에 업데이트한 직후 문제가 시작되었다면 세 구성 요소의 변경 이력을 확인하고 한 번에 하나씩 버전을 비교하는 것이 안전합니다.

재현 가능한 운영을 위한 체크리스트

연결에 성공한 뒤에는 설정을 무작정 더 추가하기보다, 다음 정보를 기록해 두면 다음 장애를 훨씬 빠르게 해결할 수 있습니다. 사용 중인 Clash Verge 버전, 활성 프로필의 갱신 시각, 혼합 포트 번호, 프록시 모드, TUN 사용 여부, Claude Code 실행 셸, 그리고 오류가 발생한 시각을 남기세요. 구독 URL 자체나 계정 정보는 기록하지 말고, 필요한 경우 도메인 이름과 오류 코드만 비식별화해 보관합니다.

  • Clash Verge의 프로필이 활성화되어 있는가?
  • 혼합 포트가 실제로 열려 있고 다른 프로그램과 충돌하지 않는가?
  • 환경 변수의 프록시 주소가 현재 포트와 일치하는가?
  • Claude Code 실행 직후 Connections 또는 Logs에 요청이 나타나는가?
  • 로그인 콜백용 localhost가 외부 프록시로 전달되지 않는가?
  • Rule 모드에서 관련 연결이 의도하지 않은 DIRECT로 빠지지 않는가?
  • TUN을 켠 뒤 Docker, Git, 사내 도메인 등 기존 업무 연결이 정상인가?

결국 가장 안정적인 구성은 모든 트래픽을 무조건 한 방식으로 보내는 구성이 아닙니다. 터미널이 환경 변수를 잘 따르는 환경에서는 로컬 HTTP 프록시만 사용하고, 프록시를 인식하지 못하는 앱이 있을 때만 TUN을 추가하는 식으로 범위를 최소화하는 편이 좋습니다. 설정 변경 후에는 반드시 Claude Code를 완전히 종료하고 새 셸에서 다시 실행해 캐시된 환경이나 이전 프로세스의 영향을 줄이세요.

시중의 일부 유사 도구는 구독을 가져오는 메뉴와 터미널 프록시 설정이 분리되어 있고, TUN 권한이나 로그 위치에 대한 문서가 부족해 초보자가 실패 원인을 찾기 어렵습니다. 반면 Clash 공식 사이트는 Clash Verge, 혼합 포트, 터미널 환경 변수, TUN 모드를 하나의 흐름으로 확인할 수 있도록 설명을 정리해 두어 운영체제가 달라도 단계별 비교가 쉽습니다. 특정 클라이언트에 종속되지 않고 설정 원리를 먼저 익히고 싶다면 다운로드 페이지 확인부터 시작해 자신에게 맞는 Clash 클라이언트를 설치해 보세요.