Claude Code 연결 오류 해결, Clash Verge로 CLI 프록시 설정하기

Claude Code 연결 오류가 프록시 문제인지 확인하기

터미널에서 Claude Code를 실행했을 때 로그인 화면이 열리지 않거나, 인증은 끝났는데 첫 요청에서 멈추거나, 응답이 오기 전에 시간 초과가 발생한다면 먼저 터미널 프로세스의 네트워크 경로를 확인해 보세요. 브라우저에서 Claude 웹사이트가 열리는 것만으로는 CLI 연결까지 정상이라고 판단하기 어렵습니다. 브라우저는 운영체제의 시스템 프록시를 사용하는 반면, Claude Code는 실행된 셸이나 런타임이 전달받은 환경 변수에 따라 직접 연결할 수 있기 때문입니다.

자주 보이는 증상은 ETIMEDOUT, ECONNRESET, TLS 핸드셰이크 오류, 인증 토큰 교환 실패, 요청을 보낸 뒤 응답이 오지 않는 현상입니다. 반대로 서버에서 HTTP 상태 코드와 명확한 오류 메시지를 받았다면 네트워크가 아니라 계정 권한, 사용 한도, API 인증 또는 조직 정책 문제일 수도 있습니다. 오류 문구와 발생 시점을 기록하고, 동일한 명령을 다른 네트워크나 새 터미널에서 실행했을 때 결과가 달라지는지 비교하면 원인을 좁히기 쉽습니다.

이 가이드는 Clash Verge 또는 Mihomo 코어를 사용하는 호환 클라이언트를 기준으로 합니다. 메뉴 이름과 기본 포트는 버전에 따라 다를 수 있으므로 특정 값이 모든 설치에서 동일하다고 가정하지 않습니다. 핵심은 Clash Verge가 실제로 열어 둔 로컬 포트를 확인하고, Claude Code를 실행하는 바로 그 터미널에 프록시 변수를 설정한 뒤, 연결 로그에서 요청이 의도한 정책 그룹을 통과하는지 확인하는 것입니다.

Clash Verge의 로컬 프록시 포트와 프로필 확인

먼저 Clash Verge를 열어 사용할 프로필이 활성 상태인지 확인합니다. 프로필 업데이트 직후라면 구독이 정상적으로 파싱되었는지, 코어가 실행 중인지, 프록시 그룹에 선택 가능한 노드가 있는지도 살펴보세요. 노드가 표시되더라도 실제 연결이 가능한 것은 아니므로, 평소 사용하던 안정적인 노드를 선택하고 연결 기록으로 시험하는 편이 좋습니다.

다음으로 설정 화면에서 Mixed Port 또는 혼합 포트의 번호를 찾습니다. 혼합 포트는 일반적으로 HTTP 프록시와 SOCKS 프록시 요청을 함께 받지만, 실제 동작은 현재 코어와 설정에 달려 있습니다. 포트 번호를 확인하지 않은 채 예시에서 흔히 보이는 7890을 복사하면, 다른 포트를 쓰는 환경에서는 연결 거부가 발생합니다. 클라이언트가 시스템 프록시만 설정하고 혼합 포트를 열지 않은 상태라면, 환경 변수에 넣을 수 있는 로컬 HTTP 프록시 주소가 따로 있는지도 확인해야 합니다.

Clash Verge의 연결 로그를 열어 둔 뒤 Claude Code를 실행하면 어떤 도메인이 어떤 규칙과 프록시 그룹에 매칭되는지 볼 수 있습니다. Claude API 호출에서 흔히 확인할 호스트는 api.anthropic.com이지만, 로그인이나 제품 기능에 따라 추가 호스트가 나타날 수 있습니다. 도메인 목록을 추측해 넓게 허용하기보다 실패한 요청 직후 로그에 표시된 실제 호스트를 기준으로 판단하세요. 도메인이 DIRECT로 나가는지, 의도한 프록시 그룹을 타는지, 아니면 REJECT되는지에 따라 조치가 달라집니다.

Claude 요청을 규칙으로 분기하고 노드를 선택하기

글로벌 모드는 빠른 진단에 유용하지만 모든 터미널 트래픽이 같은 노드를 통과하게 만듭니다. 패키지 다운로드나 내부 개발 서버까지 해외 경로로 보내면 속도 저하와 불필요한 연결 문제가 생길 수 있으므로, 원인을 확인한 뒤에는 규칙 모드로 돌아가 필요한 호스트만 분기하는 방식을 고려하세요. 구독 프로필이 제공하는 규칙 그룹과 규칙 형식은 서로 다를 수 있으니, 아래 예시는 YAML을 직접 관리하는 경우에만 참고하고 실제 그룹 이름을 자신의 프로필에 맞게 바꿔야 합니다.

rules:
  - DOMAIN,api.anthropic.com,AI
  - MATCH,DIRECT

위 예시의 AI는 실제로 존재하는 프록시 그룹 이름으로 바꿔야 합니다. 이미 구독 규칙이 api.anthropic.com을 더 앞선 규칙에서 처리하고 있다면, 새 규칙을 뒤에 추가해도 실행되지 않을 수 있습니다. Clash 계열 규칙은 위에서 아래로 먼저 일치하는 항목을 적용하는 구성이 일반적이므로, 사용자 규칙 영역이나 규칙 프로바이더의 우선순위를 확인하고 수정 전 원본 프로필을 백업하세요. 구독을 갱신할 때 직접 편집한 부분이 덮어써질 수 있다면, 클라이언트가 지원하는 오버라이드 또는 패치 기능을 이용하는 편이 안전합니다.

노드 선택은 한 번의 짧은 지연 시간 측정만으로 결정하지 마세요. Claude Code는 인증 요청뿐 아니라 응답이 길게 이어지는 스트리밍 연결도 사용할 수 있어, 처음 연결은 빠르지만 장시간 요청에서 끊기는 노드가 있을 수 있습니다. 같은 요청을 두세 개의 안정적인 후보에서 각각 시험하고, 응답 시작 시간과 중간 끊김 여부, Clash Verge 로그의 연결 상태를 함께 비교합니다. 자동 선택 그룹이 노드를 바꾸는 구성이라면 시험하는 동안 수동으로 한 노드를 고정해 결과가 서로 다른 출구 경로 때문에 흔들리지 않게 합니다.

• 연결이 거부됨: 혼합 포트 번호, Clash 코어 상태, 로컬 방화벽을 확인합니다.
• 요청이 직접 연결됨: 규칙 매칭과 터미널의 프록시 변수 설정을 각각 확인합니다.
• 간헐적 시간 초과: 다른 노드를 고정해 스트리밍 요청을 비교하고, 자동 노드 전환과 DNS 설정도 점검합니다.
• 인증 오류만 발생함: 네트워크 우회 설정을 반복하기보다 로그인 상태, 토큰 만료, 계정 접근 권한을 확인합니다.

Claude Code를 실행하는 터미널에 프록시 변수 설정

Clash Verge의 포트를 확인했다면 Claude Code가 실행되는 셸에 프록시 주소를 전달합니다. 혼합 포트가 HTTP 프록시 요청을 받는 구성에서는 아래처럼 로컬 주소를 사용할 수 있습니다. 숫자 7890은 예시이므로 실제 포트로 바꾸세요. HTTPS 요청도 프록시를 통해 터널링하도록 HTTPS_PROXY에 HTTP 프록시 URL을 지정하는 경우가 흔합니다. 클라이언트 설정에서 SOCKS만 활성화되어 있다면 해당 프로토콜과 포트에 맞춰야 합니다.

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 NO_PROXY="localhost,127.0.0.1,::1"

위 명령은 macOS와 Linux의 Bash·Zsh 계열 셸에서 현재 터미널 세션에 적용됩니다. 명령을 실행한 같은 창에서 Claude Code를 시작해야 하며, 새 터미널을 열면 값이 사라지는 것이 정상입니다. 매번 사용할 개발 환경에 적용하고 싶다면 셸 프로필에 변수를 추가할 수 있지만, 처음부터 전역으로 설정하기보다는 현재 세션에서 시험하는 편이 문제를 되돌리기 쉽습니다. 특히 다른 프로젝트나 사내 네트워크에는 프록시를 적용하지 않아야 한다면 프로젝트별 환경 변수 관리 기능을 이용하고 저장소에 개인 설정을 커밋하지 마세요.

Windows PowerShell에서는 현재 창에 다음과 같이 설정할 수 있습니다. PowerShell을 관리자 권한으로 실행할 필요는 없으며, 적용 후 같은 창에서 연결 테스트와 Claude Code 실행을 진행합니다.

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

NO_PROXY에는 프록시를 거치지 않아야 하는 로컬 주소나 사내 호스트만 넣습니다. 여기에 넓은 도메인 패턴을 추가하면 Claude 요청까지 예외 처리될 수 있습니다. 프록시 주소에 사용자 이름과 비밀번호를 넣어야 하는 환경이라면 명령 기록, 셸 프로필, 화면 공유, 로그에 인증 정보가 남을 수 있으므로 주의하세요. 비밀 값을 공유 저장소에 기록하지 말고, 필요하면 운영체제의 비밀 저장소나 팀에서 승인한 비밀 관리 방식을 사용합니다.

연결을 검증하고 실패 지점을 분리하기

환경 변수를 입력한 뒤 바로 Claude Code에서 여러 작업을 반복하기보다, 먼저 프록시 포트와 API 호스트를 별도로 확인합니다. macOS나 Linux에서는 curl을 이용해 프록시 경유 요청을 시험할 수 있습니다. 아래 요청은 연결 경로와 HTTP 응답이 오는지 확인하는 용도이며, 인증 없는 요청은 정상적인 API 작업 결과를 반환하지 않을 수 있습니다. 이때 401 또는 404 같은 응답이 도착한다면 적어도 DNS·TCP·TLS 연결이 성립했을 가능성이 높고, 시간 초과와 연결 거부는 다른 층의 문제입니다.

curl -I --proxy "$HTTPS_PROXY" https://api.anthropic.com

Windows PowerShell에서는 curl이 별칭으로 동작하는 환경이 있으므로, 필요하면 curl.exe를 명시하고 현재 변수 값을 확인하세요. 시험 결과만으로 계정 인증이나 Claude Code 내부 설정까지 검증되는 것은 아닙니다. 연결이 성립하면 같은 터미널에서 Claude Code를 실행하고, 시작 시각과 실패 시각을 적어 Clash Verge 연결 로그와 대조합니다. 로그에서 해당 요청이 올바른 그룹으로 전달되고 응답이 돌아오는지 확인하면 CLI 환경 변수 문제와 규칙 문제를 분리할 수 있습니다.

브라우저 로그인은 되지만 CLI 인증만 실패한다면, 로그인 흐름의 브라우저와 토큰 교환을 수행하는 CLI 프로세스가 서로 다른 프록시 설정을 사용할 수 있습니다. IDE 통합 터미널도 마찬가지입니다. IDE를 프록시 변수 설정 전에 실행했다면 새 값을 상속하지 않을 수 있으므로, IDE를 완전히 종료한 뒤 다시 열어 동일한 터미널에서 시험하세요. WSL, Docker, 원격 SSH 세션에서 Claude Code를 실행한다면 127.0.0.1은 Windows 또는 호스트 컴퓨터가 아니라 해당 환경 자신을 가리킬 수 있습니다. 이 경우 호스트의 Clash 포트가 실행 환경에서 접근 가능한지 확인하고, 방화벽을 무작정 개방하기보다 허용 범위를 최소화해야 합니다.

오류가 계속되면 한 번에 하나씩만 바꾸세요. 먼저 터미널 변수 값을 출력해 오타와 오래된 포트를 확인하고, 다음으로 Clash Verge 로그에서 실제 목적지와 매칭 규칙을 확인합니다. 그 뒤 노드를 바꾸고 다시 시험한 다음, 마지막으로 계정 권한과 서비스 상태를 점검합니다. 이 순서를 따르면 프록시, DNS, 인증, 서비스 한도를 동시에 바꿔 원인을 놓치는 일을 줄일 수 있습니다. 환경 변수를 변경한 뒤에도 효과가 없다면 Claude Code 프로세스를 완전히 종료하고 새 셸에서 다시 시작해 기존 프로세스가 이전 변수를 계속 사용하는 상황을 배제하세요.

자주 묻는 질문

시스템 프록시를 켜면 Claude Code도 자동으로 프록시를 사용하나요?

항상 그렇지는 않습니다. 브라우저나 일부 데스크톱 앱은 운영체제 프록시를 따르지만, CLI 프로그램은 별도의 환경 변수를 요구할 수 있습니다. Clash Verge의 시스템 프록시가 켜져 있어도 Claude Code를 실행하는 셸에서 HTTPS_PROXY가 비어 있으면 터미널 요청은 직접 연결될 수 있습니다. 연결 로그에 요청이 나타나는지 확인해 실제 경로를 판단하세요.

환경 변수에 어떤 포트 번호를 넣어야 하나요?

Clash Verge 설정에서 현재 활성화된 혼합 포트 또는 HTTP 프록시 포트를 확인해 사용합니다. 예시의 7890은 흔히 볼 수 있는 값일 뿐 고정 규격이 아닙니다. 포트를 잘못 지정하면 연결 거부가 발생하거나, 다른 로컬 서비스로 요청이 전달될 수 있으므로 설정 화면의 실제 값을 확인하세요.

처음부터 글로벌 모드로 설정해도 괜찮나요?

진단을 위해 잠시 사용할 수는 있지만, 모든 네트워크 요청이 같은 프록시 노드를 통과하게 됩니다. 원인이 프록시 경로인지 확인한 뒤에는 필요한 API 도메인만 규칙으로 분기하는 편이 일반적으로 관리하기 쉽습니다. 특히 사내 시스템, 로컬 개발 서버, 패키지 저장소가 있는 환경에서는 글로벌 모드가 예상하지 못한 접속 문제를 만들 수 있습니다.

프록시를 설정했는데 인증 오류가 계속되면 무엇을 확인해야 하나요?

프록시 연결과 계정 인증은 별개의 단계입니다. 먼저 Clash Verge 로그에 API 요청이 도착하고 응답이 반환되는지 확인한 다음, Claude Code의 로그인 상태, 계정 또는 조직 접근 권한, 토큰 만료 여부를 점검하세요. 네트워크 연결이 정상인데 401·403 등 명시적인 인증 응답이 계속되면 노드를 반복해서 바꾸기보다 계정 설정과 서비스 정책을 확인하는 것이 적절합니다.

일부 CLI 도구는 프록시 변수를 읽는 방식이 셸과 런타임마다 달라 설정을 찾기 어렵고, 시스템 프록시만 제공하는 앱은 터미널 요청이 실제로 어디로 나가는지 확인하기도 쉽지 않습니다. Clash Verge는 로컬 포트를 지정해 CLI 트래픽을 전달하고, 도메인별 규칙과 연결 로그로 Claude 요청의 경로를 확인할 수 있어 이런 문제를 단계적으로 분리하기 좋습니다. 기기별 설치 파일과 클라이언트 정보를 확인하려면 다운로드 페이지를 이용하세요.

지금 Clash를 무료로 다운로드하고 자유로운 인터넷 경험을 →