Claude Code 중국 사용법｜Clash Verge 터미널 연결 설정

Claude Code와 터미널 프록시의 기본 구조

Claude Code는 명령줄 환경에서 파일을 읽고, 코드를 작성하거나 수정하고, 프로젝트 구조를 분석하는 작업을 돕는 AI 도구입니다. 그래픽 브라우저처럼 화면에서 프록시를 자동으로 선택하는 프로그램이 아니므로, 터미널에서 실행할 때는 운영체제 또는 셸에 프록시 주소를 직접 알려줘야 합니다. Clash Verge를 켜는 것만으로 모든 명령줄 프로그램이 자동으로 프록시를 사용하는 것은 아니라는 점이 첫 번째 핵심입니다.

Clash Verge의 시스템 프록시 기능은 Windows나 macOS의 네트워크 설정에 HTTP 프록시 정보를 등록합니다. 이 설정을 따르는 브라우저와 애플리케이션은 별도의 입력 없이 프록시를 사용할 수 있지만, 터미널 명령과 개발 도구는 환경 변수만 읽거나 자체 네트워크 설정을 사용하는 경우가 많습니다. 따라서 Claude Code를 터미널에서 사용하려면 Clash Verge에서 실제로 열려 있는 포트를 확인한 뒤 HTTP_PROXY, HTTPS_PROXY 또는 ALL_PROXY를 설정하는 방식이 가장 재현성이 높습니다.

프록시 연결은 대체로 다음 순서로 이루어집니다. 먼저 Clash Verge가 구독 설정과 프록시 노드를 불러오고, 정책 그룹에서 사용할 노드를 선택합니다. 이어서 로컬 프록시 포트가 열려 있는지 확인하고, 터미널 프로세스에 해당 포트 주소를 전달합니다. Claude Code가 네트워크 요청을 시작하면 요청은 로컬 Clash 포트로 들어가고, Clash의 규칙에 따라 직접 연결되거나 선택된 프록시 노드를 통해 전달됩니다.

Clash Verge에서 포트와 작동 모드 확인하기

Clash Verge를 실행한 뒤 먼저 Profiles 또는 구성 화면에서 사용할 설정을 선택합니다. 구독을 추가했지만 구성을 활성화하지 않았다면 노드와 정책 그룹이 보여도 실제 요청은 예상한 경로로 전달되지 않을 수 있습니다. 활성 구성에서 프록시 그룹을 열고 연결할 노드를 선택한 다음, 대시보드에서 현재 연결 상태와 로그를 확인하세요.

로컬 포트 확인

Clash Verge의 Settings 또는 일반 설정 화면에서 HTTP, SOCKS, Mixed 포트 항목을 찾습니다. 버전과 구성에 따라 표시 이름이나 기본값이 다를 수 있으므로, 특정 숫자를 무조건 입력하지 말고 현재 화면에 표시된 값을 사용해야 합니다. 예를 들어 Mixed 포트가 127.0.0.1:7897로 표시된다면 HTTP와 SOCKS5 요청을 한 포트에서 처리할 수 있지만, 사용 중인 버전에서 실제로 Mixed 포트가 활성화되어 있어야 합니다.

시스템 프록시와 TUN 중 선택하기

Claude Code만 터미널에서 프록시로 연결하려는 경우에는 우선 시스템 프록시와 환경 변수 조합을 권장합니다. 적용 범위가 명확하고, 문제가 생겼을 때 어떤 프로세스가 프록시를 사용하는지 추적하기 쉽기 때문입니다. 반면 패키지 관리자, Git, 런타임, 확장 도구처럼 환경 변수를 무시하는 프로그램이 함께 통신해야 한다면 TUN 모드가 더 편리할 수 있습니다.

TUN은 가상 네트워크 인터페이스와 라우팅을 이용해 프로세스의 트래픽을 넓은 범위에서 Clash로 넘깁니다. 그러나 TUN을 켜면 DNS, IPv6, 로컬 네트워크, 다른 VPN 프로그램과의 충돌이 발생할 수 있습니다. 처음부터 TUN과 여러 VPN을 동시에 켜기보다는, 시스템 프록시와 셸 환경 변수로 먼저 연결을 검증한 뒤 필요한 경우에만 TUN을 추가하세요.

터미널에 프록시 환경 변수 설정하기

다음 단계는 운영체제와 셸에 상관없이 적용할 수 있는 기본 절차입니다. 여기서 127.0.0.1은 현재 컴퓨터를 뜻하고, 7897은 설명을 위한 예시 포트입니다. 반드시 Clash Verge 화면에서 확인한 포트로 바꿔 입력하세요. 로컬 포트에 사용자 이름이나 비밀번호가 필요하지 않다면 주소는 보통 http://127.0.0.1:포트 형태로 작성합니다.

1. Clash Verge에서 활성 구성과 사용할 노드를 선택하고, 대시보드의 연결 로그에 오류가 없는지 확인합니다.
2. Settings에서 HTTP 또는 Mixed 포트를 확인합니다. 포트가 비활성화되어 있거나 다른 프로그램이 이미 사용 중이면 먼저 Clash Verge 설정을 수정합니다.
3. 운영체제의 시스템 프록시를 켭니다. 이 단계는 브라우저와 시스템 설정을 따르는 프로그램의 동작을 확인하는 데 유용하지만, 터미널 환경 변수 설정을 대신하지는 않습니다.
4. 현재 사용하는 터미널 셸에 프록시 환경 변수를 임시로 설정합니다. 임시 설정은 해당 터미널 창에서 실행한 명령에만 적용되므로, 실험할 때 안전합니다.
5. curl 또는 패키지 관리 명령으로 연결을 테스트하고, 동시에 Clash Verge 로그에 해당 요청이 표시되는지 확인합니다.
6. 연결이 검증된 뒤에만 셸 프로필 파일에 영구 설정을 추가합니다. 포트를 바꾸거나 공용 컴퓨터를 사용할 때는 기존 값을 먼저 제거해야 합니다.

Windows PowerShell 설정

PowerShell에서는 다음처럼 현재 창에만 변수를 설정할 수 있습니다. HTTPS_PROXY에도 https://가 아니라 HTTP 프록시 주소를 넣는 이유는 대부분의 로컬 Clash HTTP 프록시가 HTTPS 목적지에 CONNECT 방식으로 터널을 만들기 때문입니다.

$env:HTTP_PROXY="http://127.0.0.1:7897"
$env:HTTPS_PROXY="http://127.0.0.1:7897"
$env:ALL_PROXY="socks5://127.0.0.1:7897"
$env:NO_PROXY="localhost,127.0.0.1,::1"

세 변수 중 무엇을 사용할지는 프로그램마다 다릅니다. HTTP와 HTTPS 요청을 주로 처리하는 도구는 앞의 두 변수를 읽는 경우가 많고, SOCKS5를 지원하는 도구는 ALL_PROXY를 사용할 수 있습니다. 모든 변수를 무조건 설정하면 프로그램 간 우선순위가 달라질 수 있으므로, 문제가 발생하면 ALL_PROXY를 잠시 지우고 HTTP_PROXY와 HTTPS_PROXY만으로 다시 테스트하세요.

PowerShell에서 현재 값은 $env:HTTPS_PROXY로 확인할 수 있습니다. 설정을 제거하려면 다음 명령을 실행합니다.

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

macOS와 Linux 설정

zsh, bash 등 대부분의 Unix 계열 셸에서는 export를 사용합니다. 아래 예시에서 포트는 실제 Clash Verge 포트로 바꾸세요.

export HTTP_PROXY="http://127.0.0.1:7897"
export HTTPS_PROXY="http://127.0.0.1:7897"
export ALL_PROXY="socks5://127.0.0.1:7897"
export NO_PROXY="localhost,127.0.0.1,::1"

현재 셸에서만 적용하려면 위 명령을 직접 입력하면 됩니다. 새 터미널을 열 때마다 자동으로 적용하려면 사용하는 셸에 맞춰 ~/.zshrc 또는 ~/.bashrc에 필요한 줄을 추가한 후 source ~/.zshrc 또는 source ~/.bashrc를 실행합니다. 다만 모든 개발 작업에 프록시가 필요한 것은 아니므로, 전역 영구 설정보다는 프로젝트별 실행 스크립트나 별도 셸 함수를 사용하는 편이 관리하기 쉽습니다.

Linux에서 서비스나 IDE가 별도의 프로세스로 실행되는 경우에는 사용자의 셸 프로필을 읽지 않을 수 있습니다. 터미널에서 Claude Code가 정상인데 IDE 내장 터미널에서 실패한다면, 두 환경의 env | grep -i proxy 결과와 실행 경로를 비교하세요. GUI 앱은 셸 프로필을 자동으로 읽지 않는 경우가 많으므로, 해당 앱의 자체 프록시 설정이나 TUN 모드를 검토해야 합니다.

Claude Code 실행 전 연결 테스트

환경 변수를 설정한 뒤 바로 복잡한 프로젝트에서 Claude Code를 실행하지 말고, 먼저 작은 네트워크 요청으로 경로를 확인하세요. 아래 명령은 특정 서비스의 정상 응답을 보장하는 검사가 아니라, 현재 셸이 프록시 변수를 가지고 있는지와 Clash 로그에 요청이 나타나는지를 확인하기 위한 예시입니다.

echo $HTTPS_PROXY
curl -I https://example.com

Windows PowerShell에서는 다음처럼 확인할 수 있습니다.

$env:HTTPS_PROXY
curl.exe -I https://example.com

요청을 실행한 직후 Clash Verge의 Logs 화면을 확인하세요. 요청이 보이고 선택한 정책 그룹 또는 노드로 전달되었다면 터미널에서 Clash까지의 경로는 성립한 것입니다. 로그에 아무 기록도 없으면 환경 변수 이름, 포트, 셸 적용 범위를 먼저 확인해야 합니다. 로그에는 기록이 있지만 연결이 실패하면 선택한 노드의 상태, 규칙에 따른 DIRECT 또는 PROXY 판정, 원격 서버의 응답을 차례로 점검합니다.

이제 프로젝트 폴더로 이동해 Claude Code를 실행합니다. 설치 방식과 실행 명령은 사용 중인 배포 문서에 맞춰야 하며, 여기서는 중요한 원칙만 기억하면 됩니다. 반드시 프록시 변수를 설정한 같은 터미널에서 실행하고, 새 터미널이나 IDE 버튼으로 다시 시작할 때는 해당 프로세스에도 같은 변수가 전달되는지 확인하세요.

자주 발생하는 오류와 해결 순서

connection refused 또는 포트 연결 실패

이 오류는 터미널이 지정한 주소에서 프록시 서비스를 찾지 못할 때 나타납니다. Clash Verge가 종료되었거나, HTTP 포트 대신 SOCKS 포트를 잘못 입력했거나, 포트가 설정 변경으로 바뀐 경우가 흔한 원인입니다. 대시보드에서 Clash가 실행 중인지 확인하고, 설정 화면의 포트를 다시 복사한 뒤 환경 변수를 재설정하세요. Windows에서는 다른 프로그램이 포트를 점유했는지도 확인할 수 있고, macOS와 Linux에서는 lsof -i :포트 같은 명령으로 리슨 상태를 확인할 수 있습니다.

프록시를 설정했지만 계속 시간 초과

환경 변수의 주소가 올바른데도 시간 초과가 발생하면 선택된 노드가 불안정하거나, Clash 규칙이 해당 도메인을 DIRECT로 처리하고 있을 수 있습니다. 로그에서 실제 정책을 확인하고 다른 노드로 바꿔 보세요. 구독 노드 자체가 만료된 경우에는 프록시 변수보다 먼저 구성 업데이트와 노드 상태를 확인해야 합니다. 또한 회사나 학교 네트워크가 로컬 프록시 포트를 차단하는 상황은 드물지만, 다른 네트워크에서 같은 테스트를 해 보면 원인을 분리할 수 있습니다.

인증, TLS, 인증서 관련 오류

인증 실패 메시지가 나온다면 프록시 포트와 계정 인증 정보를 혼동하지 않아야 합니다. Clash의 로컬 포트는 보통 별도의 Claude 계정 비밀번호를 요구하지 않지만, 프록시 서버나 구독 서비스에 인증이 필요한 구성이라면 제공된 형식에 맞춰야 합니다. 시스템 시간이 크게 어긋나면 HTTPS 인증서 검증이 실패할 수 있으므로 날짜와 시간 자동 설정을 켜고 다시 시도하세요. 셸 기록에 토큰이나 민감한 URL이 남았다면 기록을 정리하고 필요한 자격 증명을 재발급하는 것이 안전합니다.

대문자와 소문자 환경 변수 차이

일부 런타임과 패키지 도구는 대문자 변수만 읽고, 일부 도구는 소문자 변수의 우선순위를 높게 둡니다. 대문자 설정이 무시되는 것처럼 보이면 다음처럼 소문자 변수도 임시로 추가해 비교할 수 있습니다.

export http_proxy="http://127.0.0.1:7897"
export https_proxy="http://127.0.0.1:7897"
export no_proxy="localhost,127.0.0.1,::1"

대문자와 소문자에 서로 다른 포트를 넣으면 결과를 해석하기 어려워집니다. 테스트가 끝나면 한 가지 형식만 남기고, NO_PROXY에는 로컬 주소와 사내 개발 서버처럼 직접 연결해야 하는 대상만 추가하세요. 너무 넓은 도메인을 NO_PROXY에 넣으면 프록시를 우회해 연결 문제가 다시 나타날 수 있습니다.

매일 안정적으로 사용하는 운영 방법

처음 연결에 성공한 뒤에는 영구 설정을 무작정 넓히기보다 사용 범위를 정하는 것이 좋습니다. Claude Code와 관련 도구만 프록시를 사용해야 한다면 별도의 셸 스크립트로 실행 환경을 묶을 수 있습니다. 스크립트에는 실제 인증 정보나 구독 링크를 넣지 말고, 로컬 프록시 주소와 포트만 기록하세요. 포트가 변경되면 스크립트 한 곳만 수정하면 됩니다.

프로젝트별로 직접 연결이 필요한 사내 Git 서버나 로컬 API가 있다면 NO_PROXY를 활용합니다. 반대로 모든 트래픽을 TUN으로 처리하는 경우에는 환경 변수와 TUN의 역할이 겹칠 수 있으므로, 어느 경로가 실제로 적용되는지 로그로 확인해야 합니다. TUN을 끄고 환경 변수만 검사하거나, 환경 변수를 해제하고 TUN만 검사하는 식으로 한 번에 하나의 변수를 바꾸면 원인 분석이 쉬워집니다.

Clash Verge 구성 업데이트 후에는 정책 그룹 이름이나 포트가 바뀌지 않았는지 확인하세요. 노드가 바뀌어도 로컬 포트는 그대로일 수 있지만, 설정을 새로 가져오면서 시스템 프록시가 꺼지거나 TUN 권한이 초기화되는 경우가 있습니다. 운영체제 업데이트 이후에는 방화벽 권한, VPN 권한, 네트워크 서비스 권한도 다시 확인해야 합니다.

정리하면 가장 안정적인 순서는 활성 구성 선택, 노드 선택, 로컬 포트 확인, 시스템 프록시 설정, 셸 환경 변수 설정, 간단한 요청 테스트, Clash 로그 대조, Claude Code 실행입니다. 이 순서를 지키면 인증 문제와 프록시 문제를 섞지 않고 단계별로 해결할 수 있습니다.

다음 단계: 클라이언트와 기본 설정 점검

Clash Verge를 아직 설치하지 않았거나 플랫폼별 설정 화면을 더 확인해야 한다면 다운로드 센터에서 사용 중인 운영체제에 맞는 클라이언트를 선택하세요. 설치 후에는 구성을 활성화하고 시스템 프록시 또는 TUN을 한 가지 방식부터 검증하는 것이 좋습니다.

다운로드 센터 설정 튜토리얼