Claude Code와 Clash Verge 연결 설정 및 터미널 사용법

Clash Verge와 Claude Code 연결 구조 확인하기

Clash Verge Rev 또는 mihomo 코어를 사용하는 Clash Verge 계열 클라이언트에는 보통 구독, 프로필, 코어, 포트, 시스템 프록시를 각각 관리하는 메뉴가 있습니다. 구독은 노드와 규칙을 제공하는 설정 원본이고, 프로필은 실제로 선택해 실행하는 설정입니다. 구독 URL을 추가했다고 해서 즉시 프록시 연결이 시작되는 것은 아니므로, 프로필을 업데이트한 뒤 활성화해야 합니다.

Claude Code의 터미널 요청은 일반적으로 웹 브라우저의 시스템 프록시 설정만으로 전달된다고 가정해서는 안 됩니다. 특히 macOS의 터미널, Windows PowerShell, WSL, 원격 SSH 셸은 서로 다른 환경을 사용합니다. Clash Verge가 호스트 운영체제에서 실행 중이어도 WSL이나 원격 서버 안에서 실행한 Claude Code가 호스트의 127.0.0.1 포트에 접근할 수 없는 경우가 있습니다.

가장 먼저 Clash Verge에서 현재 활성 프로필을 선택하고 코어가 실행 중인지 확인하세요. 노드 지연 시간 표시가 계속 실패하거나 로그에 포트 바인딩 오류가 있다면 터미널 설정을 변경하기 전에 Clash 상태부터 해결해야 합니다. 코어가 연결을 만들지 못하는 상태에서는 환경 변수를 정확히 입력해도 Claude Code의 인증 요청이 성공하지 않습니다.

구독 추가와 로컬 프록시 포트 설정

Clash Verge에서 구독을 추가할 때는 제공자가 안내한 구독 URL을 사용하고, 주소를 출처가 불분명한 변환 페이지에 입력하지 않는 것이 좋습니다. 구독 링크에는 노드와 설정 정보가 포함될 수 있으므로 다른 사람에게 공개하지 마세요. URL을 추가한 뒤에는 업데이트를 실행하고, 새 프로필의 YAML 구성이 정상적으로 파싱되는지 확인합니다.

1. Clash Verge를 열고 프로필 또는 구독 관리 화면으로 이동합니다.
2. 구독 URL을 추가한 뒤 업데이트를 실행합니다. 업데이트 실패가 표시되면 URL 만료, 네트워크 연결, 인증 토큰과 서버 응답을 확인합니다.
3. 새로 받아온 프로필을 활성화하고 mihomo 코어가 해당 프로필로 시작되는지 확인합니다.
4. 설정의 포트 항목에서 HTTP 포트 또는 mixed-port를 확인합니다. 예시는 7890이지만 실제 값은 설치 환경에 따라 다를 수 있습니다.
5. 가능하다면 로컬 수신 주소는 127.0.0.1로 유지합니다. 외부 네트워크에 프록시 포트를 공개하면 인증 없이 다른 장치가 사용할 위험이 있습니다.

Claude Code의 일반적인 HTTPS 요청에는 HTTP 프록시 형식의 주소를 사용할 수 있습니다. Clash의 mixed-port가 7890이라면 터미널에서 다음과 같이 설정합니다. 포트 번호는 반드시 Clash Verge 화면에 표시된 실제 값으로 바꾸세요.

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

HTTP_PROXY와 HTTPS_PROXY는 각각 HTTP와 HTTPS 요청에 적용됩니다. ALL_PROXY는 프로그램에 따라 SOCKS 또는 다른 프록시 형식을 기대할 수 있으므로, Clash의 포트 유형과 Claude Code가 사용하는 네트워크 라이브러리의 호환성을 확인해야 합니다. 처음에는 HTTP 및 HTTPS 변수만 설정해 동작을 확인하고, 필요한 경우에만 ALL_PROXY를 추가하는 방법이 안전합니다.

운영체제별 터미널에 프록시 적용하기

macOS와 Linux 셸

macOS 터미널이나 Linux의 Bash, Zsh에서는 export로 현재 셸에 환경 변수를 적용할 수 있습니다. 이 설정은 해당 터미널 창과 그 안에서 시작한 하위 프로세스에만 전달됩니다. 새 터미널을 열었는데 설정이 사라진다면 셸 초기화 파일에 추가하지 않았기 때문입니다.

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,::1

env | grep -i proxy

NO_PROXY는 로컬 주소를 프록시로 보내지 않기 위한 예외 목록입니다. 로컬 개발 서버, 패키지 저장소 미러, 사내 도메인을 직접 연결해야 하는 환경에서는 여기에 필요한 호스트를 추가할 수 있습니다. 다만 모든 도메인을 무조건 NO_PROXY에 넣으면 Claude Code 요청이 우회되어 프록시를 사용하지 않게 될 수 있으므로, 필요한 주소만 좁게 지정하세요.

Windows PowerShell

PowerShell에서는 $env: 형식으로 현재 세션에 값을 지정합니다. 아래 명령은 새 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"

Get-ChildItem Env: | Where-Object Name -Match "_PROXY"

Windows의 시스템 프록시 스위치를 켜는 것과 PowerShell 환경 변수를 설정하는 것은 서로 다른 작업입니다. 브라우저가 정상적으로 연결되더라도 터미널에서 Get-ChildItem Env: 결과가 비어 있으면 Claude Code 프로세스가 프록시 정보를 받지 못할 수 있습니다. 반대로 환경 변수가 설정되어 있어도 Clash 코어가 중지되어 있으면 요청은 로컬 포트에서 거부됩니다.

Git Bash와 WSL

Git Bash는 Windows 프로세스와 비슷하게 동작하는 부분이 있지만 별도의 셸 환경을 가지므로 직접 변수를 지정하는 편이 확실합니다. WSL은 더 주의해야 합니다. WSL 내부의 127.0.0.1이 Windows 호스트의 루프백 주소와 항상 같은 방식으로 연결되는 것은 아니며, WSL 네트워크 모드와 Windows 버전에 따라 접근 방식이 달라질 수 있습니다.

WSL에서 연결되지 않는다면 먼저 Windows의 일반 PowerShell에서 동일한 포트가 작동하는지 확인한 뒤 WSL에서 로컬 주소를 테스트하세요. 필요하면 Windows 호스트의 실제 가상 네트워크 주소를 사용해야 할 수 있지만, Clash의 수신 주소가 루프백 전용이면 외부 인터페이스에서 접근할 수 없습니다. 이 경우 방화벽과 수신 주소를 함부로 개방하기보다 WSL 네트워크 구성과 보안 영향을 먼저 검토해야 합니다.

직접 연결 테스트와 Claude Code 실행 순서

환경 변수를 입력한 뒤 바로 복잡한 프로젝트 작업을 시작하지 말고, 작은 요청부터 단계적으로 테스트하세요. 먼저 로컬 포트가 열려 있는지, 그다음 외부 HTTPS 연결이 프록시를 통해 전달되는지, 마지막으로 Claude Code 인증을 확인하면 문제의 범위를 빠르게 좁힐 수 있습니다.

1. Clash 로그를 엽니다. 터미널 테스트를 실행할 때 새로운 연결 기록이 나타날 수 있도록 로그 화면을 준비합니다.
2. 환경 변수를 확인합니다. macOS·Linux에서는 env | grep -i proxy, PowerShell에서는 환경 변수 조회 명령으로 현재 셸의 값을 확인합니다.
3. HTTPS 요청을 테스트합니다. curl을 사용할 수 있다면 다음과 같이 실행하고 Clash 로그에 연결이 기록되는지 봅니다.

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

응답 코드가 항상 성공이어야 하는 것은 아닙니다. 중요한 것은 DNS 또는 TLS 연결이 즉시 끊기는지, 로컬 포트 연결 거부가 발생하는지, Clash 로그에 요청이 남는지입니다. API 주소의 응답이 인증 헤더 부족으로 오류를 반환하더라도 네트워크 경로 자체는 통과했을 수 있습니다.

4. Claude Code를 실행합니다. 같은 터미널 세션에서 명령을 실행해야 환경 변수가 전달됩니다.
5. 로그인 또는 인증을 진행합니다. 브라우저가 열리는 방식이라면 브라우저 인증을 완료한 뒤 원래 터미널로 돌아옵니다.
6. 간단한 읽기 작업으로 확인합니다. 프로젝트 전체를 변경하는 요청보다 현재 디렉터리의 파일 구조를 설명하게 하여 연결과 권한을 구분합니다.
7. 작업이 끝난 뒤 프록시를 해제할지 결정합니다. 해당 셸에서만 프록시가 필요하다면 세션을 종료하거나 아래 명령으로 변수를 제거합니다.

unset HTTP_PROXY HTTPS_PROXY ALL_PROXY NO_PROXY

Windows PowerShell에서는 다음과 같이 현재 세션의 변수를 제거할 수 있습니다.

Remove-Item Env:HTTP_PROXY, Env:HTTPS_PROXY, Env:ALL_PROXY, Env:NO_PROXY -ErrorAction SilentlyContinue

테스트 중 Clash 로그에 전혀 기록이 없다면 Claude Code가 다른 프록시 설정을 사용하거나, 환경 변수가 하위 프로세스에 전달되지 않았거나, WSL·컨테이너·원격 서버에서 실행되고 있을 가능성이 있습니다. 로그에는 기록이 있지만 연결이 실패한다면 규칙, DNS, 노드 프로토콜과 TLS 협상을 차례로 확인하세요.

로그인 실패와 시간 초과 문제 해결하기

로그인 실패는 하나의 원인으로만 발생하지 않습니다. 브라우저 인증은 성공했지만 터미널이 콜백을 받지 못하는 경우, 프록시 노드가 인증 서비스에 접근하지 못하는 경우, 시스템 시간이 틀린 경우, 기존 인증 정보가 충돌하는 경우가 서로 다른 증상으로 나타날 수 있습니다. 오류 문구만 보고 구독을 다시 추가하기보다 요청이 Clash 로그에 도달했는지부터 확인하세요.

시간 초과가 반복될 때

시간 초과가 발생하면 먼저 자동 선택 그룹을 일시적으로 사용하지 말고 안정적인 노드를 수동으로 선택해 비교하세요. 로그인 중 노드가 바뀌면 인증 서버가 다른 IP나 지역에서 접속한 것으로 판단할 수 있고, 브라우저 인증과 터미널 요청의 출구가 달라져 세션이 무효화될 수 있습니다. 이것이 항상 인증 실패의 원인은 아니지만, 진단 단계에서는 변수를 줄이는 데 도움이 됩니다.

또한 DNS 모드, TUN 모드, 시스템 프록시를 한꺼번에 변경하지 마세요. Claude Code가 터미널 환경 변수로 HTTP 프록시를 사용하고 있다면 먼저 해당 경로를 안정화한 뒤 필요할 때만 TUN을 검토합니다. TUN은 더 많은 애플리케이션 트래픽을 처리할 수 있지만, 터미널 프록시 문제를 해결하기 위한 필수 조건은 아니며 DNS와 라우팅 문제를 추가할 수도 있습니다.

인증 정보와 보안 점검

API 키나 인증 토큰을 셸 명령에 직접 붙여 넣거나 셸 기록과 화면 공유에 노출하지 마세요. 프로젝트 디렉터리에 비밀 값을 평문으로 저장하는 것도 피해야 합니다. 인증이 계속 실패한다면 먼저 프록시 연결을 확인한 다음, Claude Code의 공식 인증 절차와 현재 계정 상태를 확인하세요. 프록시가 통신을 전달한다고 해서 계정 권한이나 서비스 이용 가능 지역 문제가 해결되는 것은 아닙니다.

개발 작업에서 안정적으로 사용하는 방법

Claude Code를 장시간 사용할 계획이라면 먼저 일상용 프로필과 개발용 프로필을 구분하는 방법을 고려할 수 있습니다. 개발용 프로필에서는 인증과 코드 저장소 접속에 적합한 노드를 선택하고, 필요하지 않은 자동 속도 측정이나 잦은 노드 전환을 줄입니다. 자동 그룹은 편리하지만 측정 대상과 실제 서비스의 경로가 다를 수 있으므로, 로그인·결제·원격 개발처럼 출구 IP 안정성이 중요한 작업에서는 수동 선택 그룹이 더 예측 가능할 수 있습니다.

프로젝트별로 프록시를 적용해야 한다면 셸에서만 환경 변수를 설정하거나 짧은 실행 스크립트를 사용하세요. 전역 시스템 프록시를 항상 켜 두면 패키지 관리자, 로컬 개발 서버, 사내 네트워크까지 의도치 않게 프록시를 거칠 수 있습니다. 반대로 프록시 변수를 셸 초기화 파일에 영구 저장하면 공용 컴퓨터나 원격 서버에서 설정이 무심코 재사용될 수 있으므로, 저장 위치와 권한을 확인해야 합니다.

• 작업 시작 전 Clash Verge의 활성 프로필과 코어 상태를 확인합니다.
• 현재 터미널의 프록시 변수가 올바른 포트와 형식을 가리키는지 확인합니다.
• 로그인과 장시간 작업에는 안정적인 노드를 우선 사용하고, 필요하면 노드 자동 전환을 잠시 줄입니다.
• WSL, Docker, SSH 환경에서는 실행 위치와 127.0.0.1의 의미가 달라질 수 있음을 고려합니다.
• 문제 재현 시 코어 로그, 터미널 오류, 실행 환경과 사용한 포트 번호를 함께 기록합니다.
• 인증 토큰, API 키, 구독 URL을 터미널 기록과 공개 저장소에 남기지 않습니다.

정리하면 Clash Verge는 Claude Code 자체를 설정하는 프로그램이 아니라, Claude Code가 사용할 수 있는 로컬 프록시 경로를 제공하는 클라이언트입니다. 구독을 활성화하고 코어를 실행한 뒤 실제 HTTP 포트를 확인하고, 같은 터미널 세션에 프록시 환경 변수를 적용해야 합니다. 이후 curl과 Clash 로그로 네트워크 경로를 검증하면 로그인 실패와 시간 초과를 훨씬 체계적으로 분리할 수 있습니다.