Claude Code 국내 사용법과 Clash 터미널 접속 설정 가이드

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

Claude Code를 설치한 뒤 브라우저에서는 Claude가 정상적으로 열리는데 터미널에서만 로그인 화면이 반복되거나 모델 요청이 멈추는 경우가 있습니다. 특히 국내 네트워크, 회사 VPN, 보안 프로그램이 설치된 개발 PC에서는 npm 설치부터 인증 콜백, 모델 API 호출까지 서로 다른 호스트와 연결 방식을 사용하기 때문에 단순히 브라우저 프록시만 켜는 것으로 해결되지 않을 수 있습니다.

겉으로 보이는 오류는 대개 “인증 실패”, “로그인 시간 초과”, “네트워크 오류”처럼 단순하지만 실제 원인은 여러 갈래입니다. 설치 과정에서 npm 레지스트리나 GitHub 릴리스 파일에 접근하지 못할 수 있고, 로그인 과정에서는 브라우저가 열린 뒤 터미널 프로세스로 인증 결과가 돌아오지 않을 수 있습니다. 로그인에 성공한 뒤에도 Claude API 요청을 실행하는 Node.js 프로세스가 Clash를 통과하지 않으면 모델 호출 단계에서 다시 멈춥니다.

이 글에서는 Clash Verge를 기준으로 Claude Code를 국내 개발 환경에서 사용할 때 필요한 흐름을 정리합니다. 특정 서비스의 이용 제한을 우회하는 방법이 아니라, 사용이 허용된 프록시 환경에서 터미널 애플리케이션의 연결 경로를 점검하고 안정화하는 기술 가이드입니다. 회사나 학교 장비라면 먼저 네트워크 관리자 정책과 Claude 서비스 약관을 확인하세요.

먼저 확인할 것: 구독 URL은 본인 계정의 관리 화면에서 복사하고, URL에 포함된 토큰을 공개 저장소나 터미널 녹화 화면에 남기지 마세요. 알 수 없는 실행 파일이나 타인의 구독을 사용하는 방식은 피해야 합니다.

Clash Verge 설치와 구독 프로필 준비

Claude Code의 터미널 연결을 확인하기 전에 Clash Verge 자체가 정상적으로 실행되는지부터 분리해서 점검하는 것이 좋습니다. 이미 다른 Clash 계열 클라이언트가 실행 중이면 혼합 포트나 시스템 프록시 설정이 서로 덮어쓸 수 있으므로, 테스트할 때는 하나의 클라이언트만 남겨 두세요. Windows에서는 Clash Verge Rev, macOS에서는 Clash Verge Rev 또는 사용 중인 호환 GUI를 이용할 수 있습니다.

설치 파일은 프로젝트의 공식 릴리스나 신뢰할 수 있는 다운로드 페이지에서 받아야 합니다. CPU 아키텍처가 나뉘는 경우 Windows x64, macOS Apple Silicon, macOS Intel처럼 자신의 장치에 맞는 패키지를 선택합니다. 설치 후 대시보드가 열리고 커널 상태가 정상으로 표시되는지 확인한 다음 구독을 가져옵니다.

Clash Verge를 실행하고 Profiles 또는 프로필 관리 메뉴를 엽니다.
제공업체에서 받은 구독 URL을 입력한 뒤 가져오기 또는 업데이트를 실행합니다.
프로필 목록에 생성된 YAML 프로필을 선택하고 활성화합니다.
Proxies 메뉴에서 실제로 사용할 프록시 그룹과 노드를 선택합니다.
대시보드에서 혼합 포트가 열려 있는지 확인합니다. 흔히 7890 또는 7897이 사용되지만, 설치 환경에 따라 다를 수 있으므로 화면에 표시된 값을 기준으로 합니다.

구독을 가져왔는데 노드가 비어 있거나 프로필이 즉시 사라진다면 Claude Code 문제로 넘어가기 전에 구독 URL, 프로필 형식, 만료 여부를 확인해야 합니다. Clash 로그에서 YAML 파싱 오류가 보이는지도 살펴보세요. 프로필이 활성화되어도 실제 노드가 연결되지 않으면 터미널 설정을 바꿔도 결과는 달라지지 않습니다.

권장 순서: 먼저 Clash 대시보드에서 프록시 노드가 연결되는지 확인하고, 그 다음 브라우저 테스트, 마지막으로 Claude Code 테스트를 진행하세요. 세 단계를 한꺼번에 바꾸면 어느 지점에서 실패했는지 찾기 어렵습니다.

터미널에 HTTP·HTTPS 프록시 연결하기

Clash의 시스템 프록시를 켜면 브라우저나 일부 GUI 앱은 바로 프록시를 사용할 수 있습니다. 그러나 터미널에서 실행되는 Node.js 프로세스는 운영체제의 시스템 프록시를 자동으로 따르지 않는 경우가 있습니다. 따라서 Claude Code가 연결되지 않을 때는 터미널 프록시 환경 변수를 명시적으로 설정하는 방법이 가장 먼저 시도할 만합니다.

Clash Verge의 설정 화면에서 현재 HTTP 또는 혼합 포트 번호를 확인합니다. 예를 들어 HTTP 프록시 포트가 7890이라면 macOS·Linux의 셸에서 다음과 같이 설정할 수 있습니다.

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

새 터미널을 열 때마다 입력하기 번거롭다면 사용하는 셸 설정 파일에 추가할 수 있습니다. Zsh를 사용한다면 ~/.zshrc, Bash라면 ~/.bashrc 또는 배포판에서 사용하는 프로필 파일을 확인합니다. 설정을 추가한 뒤에는 source ~/.zshrc처럼 다시 불러오고, 현재 셸에 값이 들어갔는지 출력해 보세요.

echo $HTTP_PROXY
echo $HTTPS_PROXY
npm config get proxy
npm config get https-proxy

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의 시스템 환경 변수 메뉴를 사용하거나 PowerShell 프로필에 추가할 수 있지만, 회사 PC에서는 보안 정책과 충돌할 수 있으므로 개인 세션 설정부터 테스트하는 편이 안전합니다. 또한 프록시가 SOCKS5 전용이라면 HTTP 주소로 잘못 입력하지 말고 Clash Verge에 표시된 프로토콜과 포트를 맞춰야 합니다.

Claude Code 설치 단계에서 확인할 항목

Claude Code를 npm으로 설치할 때 ETIMEDOUT, ECONNRESET, fetch failed가 반복되면 아직 Claude 인증 문제가 아닐 가능성이 큽니다. npm은 메타데이터와 패키지 tarball을 서로 다른 경로로 가져올 수 있으며, 의존성에 따라 GitHub나 별도 CDN에 접속하기도 합니다. 설치 명령을 실행하면서 Clash 연결 로그를 열어 실제 요청 도메인과 매칭된 규칙을 확인하세요.

npm install -g @anthropic-ai/claude-code
claude --version

npm이 프록시 값을 별도로 저장하고 있다면 셸 환경 변수와 충돌할 수 있습니다. 예를 들어 오래된 프록시 주소가 npm 설정에 남아 있으면 Clash 포트를 바꾼 뒤에도 npm만 이전 주소로 접속할 수 있습니다. 현재 값을 확인하고 필요할 때만 수정합니다.

npm config list
npm config delete proxy
npm config delete https-proxy

환경에 따라 npm 자체 설정을 삭제하는 것이 항상 정답은 아닙니다. 회사 내부 레지스트리를 사용하거나 인증 프록시가 필요한 조직에서는 기존 값을 유지해야 할 수 있습니다. 핵심은 실제로 Claude Code를 실행하는 동일한 터미널에서 npm과 Claude 명령이 같은 프록시 경로를 사용하는지 확인하는 것입니다.

인증·API 요청을 Clash 규칙으로 점검하기

Claude Code의 로그인은 한 번의 웹 요청으로 끝나지 않습니다. 터미널에서 인증 명령을 실행하면 브라우저가 열리고, 인증 페이지와 계정 서비스에 접근한 다음, 성공 결과가 로컬 콜백이나 터미널 세션으로 돌아옵니다. 이 과정에서 브라우저는 프록시를 사용하지만 터미널 프로세스는 DIRECT로 나가면 “브라우저 로그인은 완료됐는데 CLI는 계속 로그인하라고 함”이라는 현상이 생깁니다.

정확한 도메인은 Claude Code 버전, 인증 방식, 운영체제, 계정 상태에 따라 달라질 수 있습니다. 따라서 인터넷에서 오래된 도메인 목록을 그대로 복사하기보다는 로그인 직후 Clash의 연결 로그를 확인하세요. Anthropic 관련 API 호스트, 인증 호스트, 브라우저 콜백에 사용된 로컬 연결을 각각 구분하고, 무관한 전체 도메인을 키워드로 묶어 과도하게 프록시 처리하지 않는 것이 좋습니다.

설치 축: npm 레지스트리, 패키지 저장소, 필요할 경우 GitHub 릴리스 호스트.
인증 축: Claude 계정 로그인 페이지와 인증 제공자에 연결되는 호스트.
API 축: Claude Code가 모델 요청을 보내는 Anthropic API 호스트.
로컬 축: 브라우저 인증 결과를 CLI로 돌려보내는 localhost 콜백과 로컬 포트.

규칙을 만들 때는 먼저 전용 프록시 그룹을 두고 로그로 확인한 도메인만 추가합니다. DOMAIN-KEYWORD,anthropic처럼 넓은 키워드 규칙은 관련 없는 요청까지 같은 노드로 보낼 수 있으므로 초기 진단용으로만 사용하고, 안정화한 뒤에는 가능한 한 구체적인 DOMAIN-SUFFIX 또는 개별 도메인 규칙으로 줄이는 편이 낫습니다.

rules:
  - DOMAIN-SUFFIX,anthropic.com,CLAUDE
  - DOMAIN-SUFFIX,claude.ai,CLAUDE
  - MATCH,DIRECT

위 예시는 구조를 이해하기 위한 단순한 예시일 뿐이며, 실제 구독 프로필의 그룹 이름과 서비스 도메인에 맞춰 수정해야 합니다. 이미 제공업체가 관리하는 규칙이 있다면 같은 도메인을 중복으로 추가하기보다 규칙 순서를 먼저 확인하세요. Clash 규칙은 위에서부터 평가되므로 넓은 GEOIP 또는 MATCH,DIRECT가 앞에 있으면 뒤의 Claude 규칙에 도달하지 않을 수 있습니다.

규칙 순서 주의: Claude 전용 규칙보다 앞에서 전체 해외 트래픽을 DIRECT로 보내거나, 반대로 모든 트래픽을 한 노드로 보내면 원인 분석이 어려워집니다. 로그인 시각의 Clash 로그에서 도메인, 정책 그룹, 최종 노드를 함께 기록하세요.

TUN 모드가 필요한 경우와 단계별 장애 해결

환경 변수를 설정했는데도 Claude Code가 프록시를 무시한다면 TUN 모드를 고려할 수 있습니다. TUN은 애플리케이션이 프록시 환경 변수를 따르는지와 관계없이 운영체제의 네트워크 트래픽을 가상 인터페이스로 받아 Clash 규칙에 전달하는 방식입니다. Docker, WSL, IDE 내장 터미널, 별도 런타임처럼 프록시 변수를 상속하지 않는 환경에서 특히 유용할 수 있습니다.

Clash Verge에서 Settings 또는 일반 설정을 열고 TUN 기능을 찾습니다.
운영체제가 요청하는 네트워크 확장, 관리자 권한, 서비스 모드 설치를 허용합니다.
TUN을 켠 뒤 DNS 모드와 자동 라우트 옵션이 정상적으로 적용되었는지 확인합니다.
Claude Code를 실행하는 터미널과 IDE를 완전히 종료한 뒤 다시 열어 새 네트워크 상태를 적용합니다.
Clash 로그에서 API 요청이 실제 프록시 그룹으로 매칭되는지 확인하고, 필요하면 환경 변수를 잠시 제거해 TUN 방식만 비교합니다.

TUN을 켠 뒤 인터넷 전체가 느려지거나 사내 시스템이 열리지 않는다면 바로 모든 트래픽을 프록시로 보내기보다 분기 규칙을 조정하세요. 국내 업무 사이트, 사내 도메인, 프린터와 NAS 같은 로컬 네트워크는 DIRECT가 필요할 수 있습니다. 반대로 Claude API만 TUN에서 프록시로 보내고 나머지는 기존 경로를 유지하는 구성이 관리하기 쉽습니다.

오류별로는 다음 순서로 접근하면 시간을 줄일 수 있습니다. 설치 실패라면 npm 프록시와 Clash 로그를 확인하고, 로그인 반복이라면 브라우저와 CLI가 동일한 경로를 쓰는지 확인합니다. 로그인은 되지만 요청 실패라면 API 호스트의 규칙 매칭과 노드 상태를 확인해야 합니다. 간헐적인 중단은 규칙보다 노드 품질, 연결 재사용, 회사 방화벽의 장시간 연결 제한에서 발생할 수 있으므로 다른 노드와 비교 테스트를 진행하세요.

테스트 결과를 기록할 때는 오류 문구만 저장하지 말고 실행 시각, 운영체제, Clash 모드, 프록시 포트, 매칭된정책 그룹, 노드 이름, HTTP 상태 코드를 함께 남기는 것이 좋습니다. 단, 인증 토큰과 API 키는 로그에 포함하지 마세요. 문제를 재현한 직후 한 번의 연결 로그만 확보해도 무작정 YAML을 고치는 것보다 훨씬 빠르게 원인을 좁힐 수 있습니다.

일부 터미널 프록시 도구는 설치가 간단하지만, 앱별 환경 변수 관리가 불편하거나 TUN·DNS·규칙 로그를 한 화면에서 확인하기 어렵고, 한국어 설명이 부족해 인증 반복 문제를 해결하는 과정이 길어질 수 있습니다. 반면 Clash 공식 사이트는 Clash Verge를 중심으로 구독 가져오기, 터미널 프록시 변수, TUN 전환, 연결 로그 확인을 한 흐름으로 정리해 초보자도 단계별로 점검하기 쉽습니다. 이 글의 순서대로 Claude Code 연결을 직접 확인해 보고 싶다면 Clash 공식 사이트 다운로드 페이지에서 환경에 맞는 Clash 클라이언트를 받아 차근차근 설정해 보세요.