Claude Code 국내 사용법과 Clash Verge 터미널 연결 설정

Claude Code가 터미널 프록시를 필요로 하는 경우

Claude Code는 터미널에서 명령을 입력해 소스 코드 분석, 파일 수정, 테스트 실행, 변경 사항 검토를 수행하는 개발 도구입니다. 실제 작업은 로컬 셸에서 실행되지만, 모델 응답을 받기 위한 인증과 API 통신은 별도의 네트워크 연결을 사용합니다. 따라서 브라우저에서 웹사이트가 정상적으로 열리는 것만으로는 Claude Code가 반드시 동작한다고 볼 수 없습니다. 브라우저가 사용하는 프록시와 터미널 프로세스가 사용하는 프록시는 서로 다를 수 있기 때문입니다.

Clash Verge에서 시스템 프록시를 켜도 모든 프로그램이 그 설정을 자동으로 따르는 것은 아닙니다. Windows나 macOS의 GUI 프로그램 중에는 운영체제 프록시 설정을 읽는 앱이 있지만, 터미널에서 실행되는 Node.js 기반 프로그램, Python 도구, 패키지 관리자, Git 클라이언트는 환경 변수나 자체 설정을 별도로 요구하는 경우가 많습니다. Claude Code를 실행하는 셸에도 프록시 주소를 직접 전달해야 하는 이유가 여기에 있습니다.

먼저 사용 중인 계정과 API 서비스의 공식 이용 가능 지역, 인증 방식, 서비스 약관을 확인해야 합니다. 네트워크 경로를 바꾸는 것은 연결 품질을 조정하는 방법일 뿐이며, 계정 지역 제한이나 결제 제한을 우회하는 수단으로 사용해서는 안 됩니다. 인증 실패가 발생했을 때 무조건 프록시 노드를 바꾸기보다 계정 상태, API 키 권한, 결제 상태, 시스템 시간부터 확인하는 편이 안전합니다.

Clash Verge에서 먼저 확인할 항목

Clash Verge를 실행한 뒤 현재 사용 중인 프로필과 코어가 정상적으로 로드되었는지 확인합니다. 최신 계열의 Clash Verge Rev는 보통 mihomo 코어를 사용하지만, 설치 버전과 프로필에 따라 화면의 명칭이 다를 수 있습니다. 프로필이 로드되지 않았거나 코어가 중지된 상태에서는 터미널에 올바른 프록시 주소를 입력해도 연결할 수 없습니다.

다음으로 Clash Verge의 포트 설정을 확인합니다. 일반적으로 mixed-port는 HTTP와 SOCKS5 연결을 한 포트에서 함께 받으며, http-port와 socks-port는 각 프로토콜을 분리합니다. 포트 번호는 설치 환경에 따라 달라지므로 예시 숫자를 그대로 사용하지 말고 Clash Verge 화면에 표시된 실제 값을 기준으로 해야 합니다.

처음 설정할 때는 TUN 모드보다 로컬 HTTP 또는 SOCKS 포트를 환경 변수로 지정하는 방식을 권장합니다. 어떤 프로세스가 프록시를 사용하는지 명확하고, 문제가 생겼을 때 원인을 좁히기 쉽기 때문입니다. TUN 모드는 DNS와 UDP를 포함한 더 넓은 트래픽을 처리할 수 있지만, 운영체제 권한, 가상 네트워크 인터페이스, 라우팅, DNS 예외가 함께 작동하므로 기초 연결을 확인한 뒤 선택하는 편이 좋습니다.

인증과 API 환경 변수 준비

Claude Code의 인증은 사용 중인 배포 방식과 계정 유형에 따라 달라질 수 있습니다. 대화형 로그인 방식이라면 공식 로그인 절차를 터미널에서 완료하고, API 키 방식이라면 해당 키를 셸의 환경 변수에 안전하게 등록합니다. 키를 설정 파일, 프로젝트 저장소, 셸 명령의 화면 기록에 직접 남기는 방식은 피해야 합니다. 특히 소스 코드를 공유하는 저장소에 키가 들어가면 프록시 설정이 정상이어도 계정 보안 문제가 발생합니다.

API 키를 사용하는 환경에서는 변수 이름이 도구의 현재 문서와 설치 버전에 맞는지 확인합니다. 일반적으로 Anthropic API 클라이언트는 ANTHROPIC_API_KEY와 같은 이름을 사용하지만, Claude Code의 인증 흐름은 버전이나 로그인 방식에 따라 달라질 수 있습니다. 이미 로그인한 상태에서 무작정 API 키를 추가하면 어느 자격 증명이 우선되는지 혼동될 수 있으므로, 한 번에 한 인증 방식을 사용하고 현재 세션의 인증 상태를 먼저 확인합니다.

셸에 키를 임시로 등록하는 예시는 다음과 같습니다. 아래 값은 실제 키로 바꾸되, 공유 화면이나 로그에 노출되지 않도록 주의합니다.

# macOS / Linux: 현재 터미널 세션에만 적용
export ANTHROPIC_API_KEY="여기에-실제-키"

# Windows PowerShell: 현재 PowerShell 세션에만 적용
$env:ANTHROPIC_API_KEY = "여기에-실제-키"

영구 등록은 편리하지만 여러 프로젝트에서 같은 인증 정보를 공유하게 된다는 위험이 있습니다. 개인 컴퓨터에서만 사용하고, 공용 PC나 CI 환경에서는 운영체제의 보안 저장소 또는 CI 제공 비밀 변수 기능을 사용하는 편이 적절합니다. 키를 교체하거나 폐기해야 할 상황을 고려해 생성 날짜와 사용 목적도 별도로 기록해 두면 관리가 쉬워집니다.

터미널에 Clash Verge 프록시 연결하기

이제 Clash Verge의 실제 포트가 7890이라고 가정하고 터미널에 프록시 환경 변수를 지정합니다. HTTP 기반 API 통신은 보통 HTTP_PROXY와 HTTPS_PROXY를 모두 설정하는 것이 무난합니다. 일부 런타임은 소문자 변수만 읽거나 대문자와 소문자 중 하나를 우선할 수 있으므로, 호환성을 높이려면 두 형태를 함께 지정할 수 있습니다.

# macOS / Linux
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="127.0.0.1,localhost,::1"

# Windows PowerShell
$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 = "127.0.0.1,localhost,::1"

ALL_PROXY는 모든 지원 가능한 연결의 기본 프록시로 사용될 수 있지만, 애플리케이션이 SOCKS5를 제대로 지원한다는 전제가 필요합니다. HTTPS API를 HTTP 프록시를 통해 연결할 때는 HTTPS_PROXY 값에도 http://를 쓰는 구성이 일반적입니다. 프록시 포트의 프로토콜과 환경 변수의 URL 스킴을 혼동하면 “프록시 서버에 연결할 수 없음” 또는 TLS 협상 오류가 발생할 수 있습니다.

환경 변수가 현재 셸에 적용되었는지 다음처럼 확인합니다.

# macOS / Linux
printf '%s\n' "$HTTP_PROXY" "$HTTPS_PROXY" "$NO_PROXY"

# PowerShell
$env:HTTP_PROXY
$env:HTTPS_PROXY
$env:NO_PROXY

설정한 변수는 해당 터미널에서 시작되는 자식 프로세스에 전달됩니다. 따라서 이미 실행 중인 IDE의 통합 터미널이나 별도의 터미널 탭에는 자동으로 반영되지 않을 수 있습니다. 환경 변수를 바꾼 뒤에는 새 터미널을 열거나, 현재 셸에서 값을 다시 설정하고 Claude Code를 새로 실행해야 합니다.

단계별 연결 검증

한 번에 Claude Code를 실행해 결과만 확인하면 인증 문제와 프록시 문제를 구분하기 어렵습니다. 다음 순서대로 각 계층을 따로 검사하면 실패 원인을 빠르게 좁힐 수 있습니다.

1. Clash Verge 상태 확인: 프로필이 활성화되어 있고 코어가 실행 중인지 확인합니다. 현재 선택된 정책 그룹에 실제로 사용할 수 있는 노드가 있는지도 확인합니다.
2. 로컬 포트 확인: 운영체제에서 해당 포트가 열려 있는지 점검합니다. macOS와 Linux에서는 nc -vz 127.0.0.1 7890, Windows PowerShell에서는 Test-NetConnection 127.0.0.1 -Port 7890를 사용할 수 있습니다.
3. 프록시 경유 HTTPS 확인: 환경 변수를 적용한 상태에서 curl 같은 도구로 공식 API 엔드포인트의 연결과 TLS 응답을 확인합니다. HTTP 상태 코드가 반환되면 네트워크 계층은 대체로 통과한 것이지만, 인증 성공을 의미하지는 않습니다.
4. 인증 상태 확인: Claude Code가 제공하는 로그인 또는 상태 확인 명령을 현재 설치 버전의 공식 도움말에 따라 실행합니다. 키가 만료되었거나 계정에 API 사용 권한이 없으면 프록시가 정상이어도 요청은 거부됩니다.
5. 작은 요청으로 테스트: 처음부터 큰 저장소를 분석하지 말고 짧은 질문이나 작은 디렉터리에서 실행합니다. 요청이 성공한 뒤에만 모델 설정, 권한 승인, 프로젝트 범위를 단계적으로 넓힙니다.

Clash Verge의 연결 로그도 함께 확인합니다. 요청이 로그에 전혀 나타나지 않는다면 Claude Code가 환경 변수를 읽지 않았거나, TUN과 직접 연결이 충돌했거나, 다른 터미널 세션에서 실행했을 가능성이 큽니다. 로그에는 요청이 보이지만 시간 초과가 발생한다면 선택한 노드의 품질, DNS 해석, TLS 연결, MTU 문제를 차례로 살펴봅니다. 인증 오류나 권한 오류가 기록된다면 네트워크보다 계정 설정을 먼저 확인해야 합니다.

# 현재 프록시 변수를 사용해 외부 HTTPS 연결을 점검하는 예시
curl -I https://api.anthropic.com

위 명령의 결과는 설치 환경과 엔드포인트 정책에 따라 달라질 수 있습니다. 응답 코드 자체를 성공·실패의 유일한 기준으로 삼지 말고, DNS 해석 실패, 연결 거부, TLS 오류, HTTP 인증 오류를 서로 다른 범주로 구분해서 기록합니다.

Claude Code 트래픽만 분리하는 규칙 설계

Clash Verge를 켰다고 해서 모든 트래픽을 동일한 노드로 보내야 하는 것은 아닙니다. 국내 사이트, 사내 서비스, 패키지 미러는 DIRECT로 두고 Claude Code가 사용하는 API 도메인만 별도의 정책 그룹으로 보내면 지연과 오작동을 줄일 수 있습니다. 다만 API 도메인은 서비스 구성이나 버전에 따라 추가될 수 있으므로, 단일 도메인만 영구적으로 가정하지 말고 Clash Verge의连接 로그에서 실제 요청 대상을 확인해야 합니다.

도메인 규칙은 일반 규칙보다 앞에 배치해야 합니다. 예를 들어 구독 설정의 넓은 GEOIP 또는 MATCH 규칙이 먼저 나오면 뒤에 추가한 API 도메인 규칙은 도달하기 전에 이미 다른 정책으로 처리될 수 있습니다. 오버라이드 기능을 사용한다면 최종 병합 결과에서 커스텀 규칙이 어느 위치에 삽입되는지 확인합니다.

proxy-groups:
  - name: Claude API
    type: select
    proxies:
      - 노드 선택
      - DIRECT

rules:
  # 실제 사용하는 공식 API 도메인을 확인한 뒤 필요한 범위만 추가
  - DOMAIN-SUFFIX,anthropic.com,Claude API
  - DOMAIN-SUFFIX,claude.ai,Claude API
  - GEOIP,KR,DIRECT
  - MATCH,노드 선택

위 예시는 구조를 설명하기 위한 골격입니다. anthropic.com이나 claude.ai의 모든 하위 도메인을 반드시 같은 방식으로 보내야 한다는 뜻은 아닙니다. 웹 서비스와 API, 인증, 업데이트 요청의 목적지가 서로 다를 수 있고, 서비스 제공자의 공식 안내에 따라 허용되는 엔드포인트가 달라질 수 있습니다. 필요 이상으로 넓은 DOMAIN-SUFFIX를 추가하면 일반 웹 브라우징까지 같은 정책으로 묶일 수 있으므로 로그를 보며 최소 범위로 관리합니다.

환경 변수 방식과 TUN 모드 비교

환경 변수 방식은 Claude Code처럼 특정 터미널 프로세스만 프록시로 보내고 싶을 때 적합합니다. 설정 범위가 명확하고 끄기도 쉽습니다. 반면 일부 프로그램이 프록시 환경 변수를 무시하거나, 자식 프로세스가 다른 런타임으로 실행되거나, UDP 기반 연결이 필요한 경우에는 적용 범위가 제한될 수 있습니다.

TUN 모드는 운영체제에 가상 네트워크 인터페이스를 만들고 시스템 트래픽을 mihomo로 전달합니다. 환경 변수를 읽지 않는 프로그램까지 처리할 수 있고 DNS 분기와 함께 사용할 수 있다는 장점이 있지만, 관리자 권한이 필요할 수 있으며 다른 VPN, 보안 소프트웨어, 가상화 네트워크와 충돌할 수 있습니다. 또한 TUN을 켠 뒤에도 터미널에 프록시 변수를 남겨두면 이중 경로가 만들어질 수 있으므로 한 가지 방식을 기준으로 테스트해야 합니다.

자주 발생하는 오류와 안전한 운영

“연결할 수 없음”이라는 메시지만으로는 원인을 판단할 수 없습니다. ECONNREFUSED나 연결 거부는 Clash Verge 포트가 닫혔거나 주소가 틀렸다는 뜻에 가깝습니다. 타임아웃은 노드 품질, DNS, 방화벽, 네트워크 경로를 의심할 수 있습니다. TLS 인증서 오류는 시스템 시간, 중간 프록시, 잘못된 HTTPS 프록시 스킴을 확인해야 합니다. HTTP 401 또는 403은 대개 인증 정보나 계정 권한 문제이며, 프록시 노드를 반복해서 바꾸는 것으로 해결되지 않습니다.

• 포트 오류: Clash Verge의 실제 mixed-port와 환경 변수의 포트가 같은지 확인합니다.
• 변수 미적용: 새 터미널에서 변수 값을 출력하고, IDE 통합 터미널이 별도 셸 설정을 사용하는지 확인합니다.
• DNS 오류: TUN과 fake-ip를 동시에 처음부터 사용하지 말고, 먼저 단순 환경 변수 구성으로 도메인 해석과 HTTPS 연결을 검증합니다.
• 규칙 오류: 연결 로그에서 목적지 도메인과 실제 선택된 정책을 확인하고, 커스텀 규칙이 MATCH보다 앞에 있는지 검사합니다.
• 인증 오류: API 키의 만료·권한·결제 상태와 로그인 계정을 확인하고 필요하면 키를 폐기한 뒤 새로 발급합니다.

API 키는 프록시 로그의 URL, 셸 히스토리, 디버그 출력, 화면 녹화에 노출되지 않도록 관리합니다. Clash Verge의 로그 수준을 필요 이상으로 높게 유지하지 말고, 공유해야 하는 로그에서는 Authorization 헤더와 민감한 요청 본문을 제거합니다. 프로젝트 폴더에 .env 파일을 둘 경우 버전 관리 제외 목록에 넣고, 실제 키 대신 예시 파일에는 더미 값만 적습니다.