Claude Code를 Clash Verge로 쓰는 터미널 접속 설정 가이드

Claude Code는 터미널에서 실행되는 AI 코딩 도구이므로, 브라우저만 정상적으로 프록시를 사용한다고 해서 터미널 요청까지 자동으로 Clash를 통과하는 것은 아닙니다. 특히 Claude Code는 API 요청, 계정 로그인, 업데이트 확인, 패키지 다운로드처럼 서로 다른 네트워크 동작을 수행하며, 각 동작이 시스템 프록시나 셸 환경 변수를 읽는 방식도 다를 수 있습니다. 따라서 Clash Verge에서 노드를 선택한 뒤에도 인증이 반복해서 실패하거나, API 요청이 시간 초과되거나, 로그인 브라우저는 열리지만 터미널이 완료 상태를 감지하지 못하는 문제가 발생할 수 있습니다. 이 글에서는 Clash Verge에 구독을 가져오는 단계부터 프록시 포트 확인, macOS·Linux·Windows 터미널 환경 변수 설정, Claude Code 로그인과 API 오류 진단까지 실제 점검 순서에 맞춰 설명합니다.

Clash Verge 구독과 프록시 상태 준비

Claude Code 설정을 시작하기 전에 Clash Verge 자체가 정상적으로 실행되고, 사용할 수 있는 프록시 노드가 하나 이상 있는지 먼저 확인해야 합니다. 터미널 환경 변수만 올바르게 입력해도 Clash 코어가 실행되지 않았거나 로컬 포트가 다른 프로그램에 의해 점유되어 있으면 연결할 수 없습니다. Clash Verge를 열고 구독 관리 화면에서 제공받은 구독 URL을 추가한 다음, 구독 업데이트를 실행해 노드 목록이 정상적으로 표시되는지 확인합니다.

1. Clash Verge의 프로필 또는 구독 관리 화면에서 새 구독을 추가합니다.
2. 구독 제공처에서 받은 URL을 입력하고 업데이트를 실행합니다.
3. 프로필을 선택해 활성화하고, 프록시 그룹에서 실제로 사용할 노드를 지정합니다.
4. 모드가 규칙 모드인지 확인합니다. 특정 도메인을 모두 프록시로 보내려면 전역 모드로 잠시 테스트할 수도 있습니다.
5. 설정 화면에서 HTTP 또는 Mixed 포트 번호를 확인합니다. 예시로 많이 쓰이는 값은 7890이지만, 실제 포트는 반드시 현재 화면에 표시된 값을 사용해야 합니다.

터미널 도구에는 HTTP 프록시 주소를 제공하는 것이 가장 간단합니다. Clash Verge가 로컬 주소 127.0.0.1에서 HTTP 또는 Mixed 포트를 열고 있다면 일반적인 형식은 http://127.0.0.1:7890입니다. SOCKS 포트를 사용하는 경우에는 해당 포트 번호를 따로 확인하고, 프로그램이 SOCKS5 환경 변수를 지원하는지도 살펴봐야 합니다. HTTP 프록시와 SOCKS5 프록시의 포트를 혼동하면 브라우저는 작동하지만 Claude Code만 실패하거나, 연결 직후 프로토콜 오류가 나타날 수 있습니다.

프록시 포트와 노드 연결 확인

Clash Verge의 로그 화면에서 테스트 요청이 실제로 프록시 그룹으로 전달되는지 확인합니다. 노드 지연 시간 측정이 성공한다고 해서 모든 목적지에 연결할 수 있다는 의미는 아니지만, 모든 노드의 지연 측정이 실패한다면 Claude Code보다 먼저 구독, 로컬 네트워크 또는 노드 상태를 점검해야 합니다. 반대로 노드 테스트는 정상인데 터미널 요청만 실패한다면 셸 환경 변수나 인증서, 애플리케이션별 프록시 처리 방식에 초점을 맞추는 것이 효율적입니다.

터미널에 Clash 프록시 적용하기

Clash Verge의 시스템 프록시 스위치는 운영체제의 데스크톱 프록시 설정을 바꾸는 기능입니다. Chromium 기반 브라우저처럼 이 설정을 읽는 프로그램에는 바로 적용되지만, 모든 터미널 프로그램이 시스템 프록시를 자동으로 읽는 것은 아닙니다. Claude Code를 실행하는 셸에는 보통 HTTP_PROXY, HTTPS_PROXY, ALL_PROXY와 같은 환경 변수를 직접 설정하는 편이 명확합니다. 대소문자를 구분하는 프로그램도 있으므로 호환성을 위해 대문자와 소문자를 함께 지정할 수 있습니다.

macOS와 Linux 셸 설정

현재 터미널 세션에서만 임시로 적용하려면 다음과 같이 입력합니다. 포트 번호는 Clash Verge의 실제 HTTP 또는 Mixed 포트에 맞게 바꿔야 합니다.

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"
export http_proxy="$HTTP_PROXY"
export https_proxy="$HTTPS_PROXY"
export all_proxy="$ALL_PROXY"

환경 변수가 제대로 등록됐는지는 값 출력과 간단한 HTTP 요청으로 나누어 확인합니다.

env | grep -i proxy
curl -I https://example.com

curl이 응답 헤더를 반환하면 최소한 현재 셸에서 프록시를 이용한 HTTPS 요청이 가능한 상태입니다. 다만 curl이 성공했다고 Claude Code의 로그인이나 API 요청까지 반드시 성공하는 것은 아닙니다. Claude Code가 별도의 인증 흐름이나 자체 네트워크 라이브러리를 사용할 수 있기 때문에, 실제 Claude Code 명령을 실행한 뒤 Clash 로그에 대상 연결이 기록되는지도 함께 확인해야 합니다.

매번 변수를 입력하지 않으려면 사용하는 셸의 시작 파일에 추가할 수 있습니다. Bash는 ~/.bashrc 또는 로그인 셸 환경에 따라 ~/.bash_profile을 사용하고, Zsh는 보통 ~/.zshrc를 사용합니다. 파일에 값을 추가한 뒤 새 터미널을 열거나 다음 명령으로 다시 읽습니다.

source ~/.zshrc

공용 컴퓨터나 여러 계정이 사용하는 환경에서는 시작 파일에 API 키까지 함께 저장하지 않는 것이 좋습니다. 프록시 주소는 로컬 주소이므로 상대적으로 민감도가 낮지만, ANTHROPIC_API_KEY나 ANTHROPIC_AUTH_TOKEN은 셸 기록과 백업 파일에 남을 수 있습니다.

Windows PowerShell과 CMD 설정

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"
$env:http_proxy=$env:HTTP_PROXY
$env:https_proxy=$env:HTTPS_PROXY
$env:all_proxy=$env:ALL_PROXY

설정 결과는 다음 명령으로 확인할 수 있습니다.

Get-ChildItem Env: | Where-Object { $_.Name -match "proxy" }
curl.exe -I https://example.com

Windows의 curl은 PowerShell에서 별칭 문제를 피하기 위해 curl.exe로 실행하는 것이 안전합니다. CMD를 사용한다면 현재 창에서 다음과 같이 지정합니다.

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를 실행하기 직전에 설정하거나, 별도의 PowerShell 프로필·배치 파일에서 필요한 범위로 제한하는 편이 관리하기 쉽습니다.

Claude Code 로그인과 API 인증 설정

Claude Code의 인증 방식은 사용 중인 계정 유형과 배포 환경에 따라 달라질 수 있습니다. 대화형 로그인은 터미널에서 인증 절차를 시작한 뒤 브라우저를 열어 계정을 확인하고, 완료 결과를 다시 로컬 애플리케이션이나 터미널 세션에 전달하는 방식입니다. 이때 브라우저는 시스템 프록시를 사용하지만 터미널은 환경 변수를 사용하지 않는 상황이 생길 수 있으므로, 두 경로가 모두 Clash를 통해 외부 인증 서비스에 접근 가능한지 확인해야 합니다.

먼저 Clash Verge에서 시스템 프록시를 켜고 터미널에도 앞서 설명한 환경 변수를 설정한 상태로 Claude Code의 로그인 명령을 실행합니다. 브라우저가 열리지 않거나 인증 페이지가 로드되지 않으면 브라우저 자체의 프록시 적용 여부를 확인합니다. 브라우저 인증은 완료됐지만 터미널이 계속 대기하거나 로그인 실패를 표시한다면, 터미널 프로세스가 인증 콜백 주소에 접근하지 못했을 가능성이 있습니다. 이 경우 Clash 로그에서 인증 시각에 발생한 연결을 찾아 차단, DNS 실패, 연결 거부가 있었는지 확인합니다.

API 키 또는 토큰을 사용하는 환경에서는 프로젝트 문서가 요구하는 변수 이름을 정확히 사용해야 합니다. 일반적으로 다음과 같은 형태의 변수를 사용하지만, 실제 변수명과 인증 방식은 Claude Code 버전 및 계정 정책에 맞춰 공식 안내를 확인해야 합니다.

export ANTHROPIC_API_KEY="발급받은_키"
# 또는 조직 환경에서 요구하는 인증 변수
export ANTHROPIC_AUTH_TOKEN="발급받은_토큰"

키를 입력한 뒤에는 터미널 기록, CI 로그, 화면 공유에 값이 노출되지 않았는지 확인합니다. 인증 오류가 발생했다고 해서 API 키를 여러 번 재발급할 필요는 없습니다. 먼저 키 변수의 이름이 올바른지, 현재 실행한 셸에 실제로 전달됐는지, 키 앞뒤에 공백이나 따옴표가 잘못 포함되지 않았는지, 계정이 해당 API 사용 권한을 갖는지 순서대로 확인합니다. 프록시가 정상이어도 인증 서버가 반환한 401 또는 403은 네트워크 문제가 아니라 자격 증명이나 권한 문제일 수 있습니다.

API 오류와 연결 실패를 진단하는 순서

오류 메시지를 보고 곧바로 노드를 바꾸기보다, 같은 조건에서 한 항목씩 바꾸며 원인을 좁히는 것이 좋습니다. 첫 번째로 Clash Verge에서 선택한 노드가 실제로 살아 있는지 확인하고, 두 번째로 curl을 이용해 현재 셸의 HTTPS 프록시 요청을 테스트합니다. 세 번째로 Claude Code를 실행하면서 Clash 로그에 대상 연결이 생성되는지 확인합니다. 로그에 아무 기록도 없다면 요청이 Claude Code에서 프록시 변수로 전달되지 않았거나, 애플리케이션이 다른 네트워크 경로를 사용하고 있을 가능성이 있습니다.

로그에 연결 시도는 보이지만 DNS 해석 실패가 나타나면 Clash의 DNS 설정과 규칙 모드를 점검합니다. fake-ip 또는 redir-host 설정, DNS 하이재킹, 프록시 DNS 서버의 접근 경로가 서로 맞지 않으면 브라우저와 터미널에서 결과가 다르게 나타날 수 있습니다. 연결이 성립한 뒤 TLS 핸드셰이크 시간 초과가 발생하면 노드의 전송 설정, 로컬 네트워크의 포트 제한, 인증서 검증 문제를 확인합니다. 이때 skip-cert-verify를 무조건 켜는 것은 해결책이 아닙니다. 인증서 문제를 좁히기 위한 일시적인 테스트 외에는 검증을 유지해야 합니다.

특정 노드에서만 실패하는지 모든 노드에서 실패하는지도 중요한 기준입니다. 하나의 노드에서만 실패하면 해당 서버의 상태나 프로토콜 매개변수 문제일 가능성이 높습니다. 모든 노드에서 동일하게 실패하면서 일반적인 curl 요청도 실패한다면 Clash 포트, 구독, DNS 또는 로컬 네트워크를 먼저 점검해야 합니다. 반대로 curl은 성공하고 Claude Code만 실패한다면 환경 변수 상속, 애플리케이션의 프록시 지원 여부, 인증 변수, 버전 호환성을 확인하는 순서가 적절합니다.

TUN 모드를 사용할 때의 주의점

터미널 프로그램이 프록시 환경 변수를 전혀 읽지 않거나, 여러 하위 프로세스가 서로 다른 프록시 설정을 사용해 관리가 어려운 경우에는 Clash Verge의 TUN 모드를 고려할 수 있습니다. TUN은 가상 네트워크 인터페이스를 통해 시스템 트래픽을 가로채므로 애플리케이션별 환경 변수 의존도를 낮춰 줍니다. 다만 TUN은 관리자 권한, 라우팅 테이블, DNS 하이재킹 설정의 영향을 받으며, 기존 VPN·보안 프로그램과 충돌할 수 있습니다.

TUN을 켠 뒤에도 기존에 설정한 HTTP_PROXY와 HTTPS_PROXY를 무조건 함께 유지하면 트래픽이 중복 처리되거나 루프처럼 보이는 문제가 생길 수 있습니다. 먼저 환경 변수를 제거한 깨끗한 셸에서 테스트하고, Clash 로그와 실제 응답을 비교합니다. 문제가 해결되면 시스템 프록시, 환경 변수, TUN 중 어떤 경로를 사용할지 하나로 정해 운영하는 것이 안정적입니다.

안정적인 운영을 위한 최종 체크리스트

설정을 마친 뒤에는 새 터미널을 열어 환경 변수가 예상대로 상속되는지 확인하고, Clash Verge에서 선택한 노드와 모드가 유지되는지 살펴봅니다. 셸 시작 파일에 저장한 값이 오래된 포트를 가리키고 있지 않은지도 확인해야 합니다. Clash Verge의 포트 번호를 변경했는데 시작 파일의 값은 그대로 남아 있으면 브라우저는 정상인데 Claude Code만 계속 연결에 실패할 수 있습니다.

• 구독이 최신 상태이고 사용할 노드가 실제로 연결되는가?
• Clash Verge의 HTTP 또는 Mixed 포트와 환경 변수의 포트가 일치하는가?
• curl 테스트가 성공하고, Clash 로그에 요청이 기록되는가?
• Claude Code가 실행되는 동일한 터미널 세션에 프록시 변수가 존재하는가?
• 401·403은 인증 값과 계정 권한, 429는 사용량 제한으로 구분했는가?
• TUN, 시스템 프록시, 환경 변수를 불필요하게 중복 적용하고 있지 않은가?
• API 키와 구독 URL이 셸 기록이나 로그에 노출되지 않았는가?

여러 도구를 함께 사용하는 개발 환경에서는 전역 설정을 무작정 늘리기보다, 먼저 한 터미널 세션에서 재현 가능한 설정을 만든 뒤 필요한 범위만 영구화하는 방식이 안전합니다. Clash Verge는 노드 선택과 트래픽 분기를 담당하고, 터미널 환경 변수는 Claude Code가 사용할 로컬 프록시 경로를 명시하는 역할을 합니다. 두 계층을 분리해 확인하면 로그인 실패, API 인증 오류, DNS 문제, 노드 시간 초과를 각각 정확히 구분할 수 있습니다.