이 글이 맞는 증상
Claude Code를 터미널에서 실행했을 때 로그인 화면이나 요청이 오래 멈추거나, ETIMEDOUT·ECONNRESET·TLS 연결 오류가 반복된다면 프록시 경로부터 확인해 볼 수 있습니다. 웹 브라우저에서는 Claude 웹 페이지가 열리는데 터미널에서만 문제가 생긴다면, 브라우저와 셸이 서로 다른 네트워크 설정을 사용하고 있을 가능성이 큽니다. 브라우저는 운영체제의 시스템 프록시를 따르더라도, 터미널 프로그램은 별도의 환경 변수나 자체 네트워크 설정이 없으면 직접 연결을 시도할 수 있습니다.
이 가이드는 Clash Verge에서 구독 프로필을 활성화하고, 연결 모드를 확인한 뒤, Claude Code가 실행되는 터미널에 프록시 환경 변수를 적용하는 순서를 다룹니다. 화면의 메뉴 이름은 Clash Verge 버전과 운영체제에 따라 조금 다를 수 있습니다. 구독 제공자나 특정 노드에 의존하지 않고, 실제 연결 기록을 확인하면서 원인을 좁히는 방식으로 설명합니다. 프록시 설정은 네트워크 경로를 바꾸는 방법이지, Claude 서비스의 이용 가능 지역이나 계정·요금제 제한을 우회하거나 해결하는 방법은 아닙니다.
네트워크 오류와 계정·요금제 오류 구분하기
먼저 오류가 발생한 시점과 표시된 응답을 확인합니다. 요청이 서버 응답을 받기 전에 멈추거나 연결이 재설정된다면 DNS, 프록시 포트, 라우팅, TLS 연결을 살펴볼 이유가 있습니다. 반면 HTTP 상태 코드와 함께 인증 실패, 권한 부족, 사용량 제한 같은 내용이 명확히 표시된다면 프록시를 바꾸기 전에 계정 로그인 상태와 서비스 정책을 점검해야 합니다. 네트워크 경로가 정상이어도 계정 자격 증명이나 사용 한도 문제는 그대로 남을 수 있습니다.
비교할 때는 웹 브라우저가 열린다는 사실만으로 터미널 연결도 정상이라고 판단하지 마세요. 브라우저의 시스템 프록시 설정과 셸의 HTTPS_PROXY 값은 별개일 수 있습니다. 반대로 Claude Code만 실패한다고 해서 곧바로 Clash Verge 문제라고 단정해서도 안 됩니다. 오류 메시지, 실패 시각, 현재 활성화된 Clash 프로필과 프록시 그룹을 함께 기록하면 원인을 더 빠르게 구분할 수 있습니다.
- 연결 전 타임아웃: 터미널이 프록시를 거치지 않거나, 지정한 로컬 포트에 연결하지 못하는 경우를 확인합니다.
- TLS 오류나 연결 재설정: 노드 상태, DNS 응답, 중복 프록시 설정, 네트워크 전환 시점을 확인합니다.
- 명시적인 인증·한도 오류: 로그인 계정, 자격 증명, 조직 정책과 서비스 이용 상태를 별도로 확인합니다.
문제가 반복될 때는 여러 설정을 한꺼번에 바꾸기보다 한 항목씩 수정하고, 같은 요청을 다시 실행하는 편이 좋습니다. 그래야 어떤 변경이 결과에 영향을 주었는지 알 수 있습니다.
1단계: Clash Verge 구독과 로컬 프록시 포트 확인
Clash Verge를 열고 사용할 구독 프로필이 목록에 있는지, 해당 프로필이 현재 선택되어 있는지 확인합니다. 구독 업데이트 직후라면 프로필이 정상적으로 불러와졌는지와 코어가 실행 중인지도 살펴보세요. 구독 형식이 맞지 않거나 설정 검증에 실패하면 앱 창은 열려 있어도 프록시 서비스가 요청을 처리하지 못할 수 있습니다. 오류가 표시된다면 먼저 프로필 업데이트 상태와 코어 로그를 확인하고, 제공자가 안내한 구독 주소를 다시 대조합니다.
그다음 설정 화면에서 HTTP 또는 혼합 포트 번호를 확인합니다. 혼합 포트는 일반적으로 HTTP 프록시와 SOCKS 연결을 함께 받을 수 있지만, 앱 버전과 설정에 따라 다를 수 있으므로 실제로 표시되는 포트를 사용해야 합니다. 예를 들어 포트가 7890이라면 환경 변수에 쓰는 주소는 대개 http://127.0.0.1:7890 형태입니다. 이 값은 예시일 뿐이며, Clash Verge 화면에 표시된 실제 포트가 우선입니다.
포트를 확인했다면 Clash Verge의 연결 화면에서 요청이 기록되는지 살펴봅니다. Claude Code를 실행한 시각에 관련 연결이 전혀 나타나지 않는다면, 요청이 Clash Verge로 전달되지 않았을 가능성이 있습니다. 연결이 보이지만 DIRECT, 거부 또는 실패로 표시된다면 해당 연결이 선택한 규칙과 프록시 그룹을 따라가는지 확인하세요.
2단계: 모드를 선택하고 Anthropic 연결 경로 확인
처음 문제를 좁힐 때는 모드를 하나씩 시험합니다. 글로벌 모드는 모든 연결을 선택된 프록시 그룹으로 보내므로, 터미널 요청이 프록시를 통과하는지 확인하기 쉽습니다. 다만 개발 도구, 로컬 네트워크, 패키지 다운로드를 포함한 다른 트래픽까지 같은 경로를 사용할 수 있어 장시간의 기본 설정으로는 불편할 수 있습니다. 연결 확인이 끝나면 규칙 모드로 돌아가 필요한 도메인만 적절한 그룹을 사용하도록 관리하는 편이 일반적입니다.
규칙 모드에서는 Claude Code가 접속한 호스트가 어떤 정책을 타는지 연결 기록에서 확인합니다. 흔히 볼 수 있는 Anthropic API 호스트로 api.anthropic.com이 있지만, 실제 접속 대상은 Claude Code 버전이나 환경 설정, 네트워크 구성에 따라 달라질 수 있습니다. 따라서 예시 호스트를 무조건 넓은 와일드카드 규칙으로 추가하기보다, 실패 직후 로그에 나온 실제 호스트와 정책 결과를 먼저 확인하세요. 구독의 규칙이 해당 연결을 직접 연결로 보내거나 거부한다면, 제공되는 규칙 편집 기능에서 그 호스트에 맞는 프록시 그룹을 지정합니다.
노드를 바꿀 때는 짧은 연결 테스트만 보고 안정성을 판단하지 않는 것이 좋습니다. Claude Code는 요청을 보내고 응답을 기다리는 동안 연결을 유지할 수 있으므로, 테스트 중 지연이 크게 변하거나 연결이 반복해서 끊기는지도 함께 살펴야 합니다. 노드 선택은 속도뿐 아니라 지속적인 연결 안정성, 사용 가능한 지역, 구독 제공자의 안내를 고려해 결정하세요.
3단계: 터미널에 프록시 환경 변수 적용
셸에서 실행되는 프로그램은 시스템 프록시 설정을 자동으로 사용하지 않을 수 있습니다. 이 경우 Claude Code를 시작하는 터미널 세션에 HTTP_PROXY와 HTTPS_PROXY를 지정하면, 이를 지원하는 네트워크 라이브러리가 요청을 Clash Verge의 로컬 프록시로 전달할 수 있습니다. 다음은 macOS·Linux에서 현재 터미널 세션에 값을 임시로 설정하는 예입니다. 포트는 본인의 Clash Verge 설정에 맞게 바꿉니다.
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"
환경 변수 이름은 일부 프로그램에서 대문자와 소문자를 다르게 처리할 수 있으므로, 문제가 계속되면 해당 Claude Code 버전과 런타임에서 안내하는 이름을 확인합니다. SOCKS 프록시만 지정된 포트를 이용하려면 URL 형식과 지원 여부를 별도로 확인해야 합니다. HTTP 프록시용 포트에 임의로 socks5:// 주소를 넣으면 연결에 실패할 수 있습니다.
환경 변수가 적용됐는지는 Claude Code를 실행하기 전에 터미널에서 확인합니다. 사용하는 셸과 운영체제에 따라 확인 명령이 다르며, macOS·Linux의 일반적인 셸에서는 echo "$HTTPS_PROXY"로 현재 값을 볼 수 있습니다. 출력된 포트가 Clash Verge 화면의 값과 일치해야 합니다. 변수를 설정한 뒤에도 이미 실행 중인 IDE나 터미널 탭은 이전 환경을 계속 사용할 수 있으므로, 새 터미널 세션을 열어 다시 시험하세요.
NO_PROXY에는 localhost나 내부 개발 서비스처럼 프록시를 거치지 않아야 하는 주소만 신중하게 추가합니다. 너무 넓은 도메인이나 와일드카드를 넣으면 Claude 관련 호스트가 예외 처리되어 프록시를 우회할 수 있습니다. 반대로 내부 서비스까지 프록시를 거치도록 하면 로컬 개발 서버 연결이 깨질 수 있습니다. 변수를 셸 프로필에 영구 저장하기 전에는 현재 세션에서 정상 동작하는지 먼저 확인하고, 필요할 때 설정을 쉽게 되돌릴 수 있도록 변경 내용을 기록해 두세요.
연결을 검증하고 실패 원인을 좁히기
설정을 적용한 뒤에는 동일한 터미널에서 Claude Code를 다시 실행하고, 같은 시각의 Clash Verge 연결 기록을 살펴봅니다. 기록에 예상한 호스트가 있고 선택한 프록시 그룹을 통과한다면 환경 변수와 Clash Verge 사이의 연결은 적어도 요청 경로에 반영된 것입니다. 반대로 연결 기록이 없다면 변수 이름이나 포트, 터미널 세션을 확인합니다. 기록에 호스트는 있지만 DIRECT로 나간다면 규칙 모드와 규칙 순서를 검토합니다. 연결이 프록시 그룹으로 들어갔는데 실패한다면 다른 안정적인 노드로 한 번 바꾸어 비교하고, 코어 로그에 나온 오류도 함께 확인합니다.
| 관찰한 결과 | 우선 확인할 항목 | 다음 조치 |
|---|---|---|
| Clash 연결 기록이 없음 | 환경 변수, 포트, 실행 중인 터미널 | 변수 값을 확인하고 새 셸에서 다시 실행 |
| 호스트가 DIRECT로 표시됨 | 활성 모드, 규칙 순서, 실제 호스트 | 해당 호스트가 의도한 프록시 그룹을 타도록 조정 |
| 프록시 그룹 연결이 실패함 | 노드 상태, DNS, 코어 로그 | 다른 노드와 비교하고 실패 시각을 기록 |
| 서버 응답에 인증·한도 오류가 표시됨 | 로그인 상태, 계정 권한, 서비스 정책 | 네트워크 설정과 별개로 계정 상태 확인 |
IDE 통합 터미널에서만 실패한다면 IDE를 완전히 종료한 다음, 환경 변수가 설정된 상태로 다시 실행해 보세요. IDE가 시작될 때 전달받은 환경을 자식 프로세스에 넘기는 방식이라, IDE를 켜 둔 채 셸 설정만 바꾸면 새 값이 전달되지 않을 수 있습니다. Docker나 원격 개발 환경에서 Claude Code를 실행하는 경우에는 호스트 컴퓨터의 환경 변수가 컨테이너나 원격 셸로 자동 전달된다고 가정하지 말고, 실제 프로세스가 실행되는 환경에서 프록시 주소에 접근할 수 있는지 따로 확인해야 합니다.
또한 설정을 공유하거나 로그를 저장하기 전에 API 키, 인증 토큰, 구독 URL, 사용자 정보가 포함되지 않았는지 살펴보세요. 터미널 명령 기록과 디버그 로그에 자격 증명이 남을 수 있으므로 공개 저장소나 지원 요청에 그대로 올리지 않는 편이 안전합니다. 문제를 재현하는 데 필요한 시간대, 오류 유형, 호스트와 연결 결과만 남기고 민감한 값은 가린 뒤 공유하세요.
터미널 도구마다 프록시 변수를 읽는 방식이 달라 수동 설정이 번거로울 수 있고, 일부 앱은 시스템 프록시만 따르거나 자체 네트워크 설정을 따로 두기도 합니다. Clash Verge는 규칙 모드와 연결 기록을 함께 활용해 Claude Code 요청의 경로를 확인하고, 다른 트래픽은 기존 정책에 맞춰 분리할 수 있다는 장점이 있습니다. 브라우저와 터미널의 연결 경로를 구분해 관리하려는 경우라면, 사용 중인 운영체제에 맞는 Clash 클라이언트와 설정을 확인해 보세요.