Claude Code 접속 오류 해결, Clash로 터미널 프록시 설정하기

먼저 터미널 요청이 어디에서 막히는지 확인하기

브라우저에서는 인터넷이 되는데 Claude Code만 연결되지 않거나 요청 시간이 초과된다면, 브라우저가 사용하는 시스템 프록시와 터미널 프로그램의 프록시 설정이 다를 수 있습니다. Clash의 시스템 프록시를 켜도 모든 터미널 도구가 그 설정을 따르는 것은 아닙니다. 먼저 요청이 Clash의 로컬 포트에 들어오는지, 들어온 요청이 어떤 규칙과 아웃바운드를 선택하는지, 그 다음 원격 서비스까지 연결되는지를 나누어 점검하세요.

Clash 클라이언트에서 실제 수신 포트를 확인하세요. 아래 예시의 7890은 흔히 쓰이는 포트일 뿐이며, 사용하는 클라이언트의 설정에 표시된 혼합 포트 또는 HTTP 프록시 포트가 기준입니다. 혼합 포트는 일반적으로 HTTP와 SOCKS 프록시 연결을 모두 수신하지만, SOCKS 전용 포트를 HTTP 프록시 주소로 지정하면 연결이 실패할 수 있습니다.

Clash의 프로필이 활성화되어 있고, 프록시 그룹에 사용할 노드가 선택되어 있는지 확인합니다.
클라이언트 설정 또는 로그에서 로컬 프록시 포트와 코어 실행 상태를 확인합니다.
터미널에서 로컬 포트에 연결할 수 있는지 먼저 검사합니다. 포트 연결 자체가 실패하면 Claude Code 설정이나 원격 노드보다 Clash가 해당 주소에서 대기 중인지 확인해야 합니다.
요청을 다시 보낸 뒤 Clash의 연결 목록과 로그에서 대상 도메인, 매칭 규칙, 선택된 아웃바운드를 확인합니다.

nc -vz 127.0.0.1 7890

nc가 설치되지 않았거나 운영체제에서 지원하지 않으면 같은 포트를 사용하는 프록시 지정 요청으로 확인할 수 있습니다. 원격 사이트가 해당 요청을 허용하는지에 따라 응답 상태는 달라질 수 있으므로, 이 검사는 Claude Code API 인증이나 전체 기능이 정상이라는 보증이 아니라 로컬 프록시를 거쳐 HTTP 요청을 보낼 수 있는지 확인하는 용도입니다.

curl -I --proxy http://127.0.0.1:7890 --connect-timeout 10 --max-time 20 https://www.anthropic.com/

터미널 세션에 프록시 환경 변수 지정하기

명령줄 프로그램은 운영체제의 시스템 프록시 대신 HTTP_PROXY, HTTPS_PROXY 또는 ALL_PROXY 환경 변수를 읽을 수 있습니다. 우선 현재 터미널 세션에만 변수를 지정해 테스트하면 기존 시스템 설정을 바꾸지 않고 결과를 비교할 수 있습니다. 여기서는 Clash의 혼합 포트가 HTTP 프록시 연결을 받는다고 가정합니다. 실제 포트가 다르면 모든 예시에서 7890을 바꾸세요.

macOS와 Linux

zsh 또는 bash에서 Claude Code를 실행할 터미널에 다음 변수를 설정합니다. 도구에 따라 대문자 변수만 읽거나 소문자 변수만 읽는 경우가 있으므로 테스트할 때는 두 표기를 함께 지정할 수 있습니다.

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"

claude

HTTP_PROXY와 HTTPS_PROXY의 값에 http://를 쓰는 것은 로컬 프록시와 HTTP 방식으로 통신한다는 의미입니다. HTTPS 웹사이트 요청도 프록시에 HTTP CONNECT를 요청한 뒤 암호화된 연결을 만들 수 있습니다. 대상이 HTTPS라고 해서 프록시 주소 앞부분을 임의로 https://로 바꾸면 안 됩니다. 프록시 서버 자체가 TLS를 제공하는 경우에만 클라이언트가 요구하는 형식을 사용하세요.

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"

claude

변수를 설정한 뒤에도 연결되지 않으면 curl에 같은 프록시 주소를 직접 지정해 비교하세요. curl 요청은 성공하지만 Claude Code만 실패하면 환경 변수 상속, 프로그램 실행 환경 또는 서비스 측 응답을 살펴볼 수 있습니다. 둘 다 실패하면 Clash 로그에서 요청이 도착했는지 확인한 다음 포트, 노드, 규칙, DNS 순서로 범위를 좁히세요. 문제가 해결된 뒤 환경 변수를 제거하려면 macOS와 Linux에서는 unset HTTP_PROXY HTTPS_PROXY ALL_PROXY http_proxy https_proxy all_proxy, PowerShell에서는 Remove-Item Env:HTTP_PROXY, Env:HTTPS_PROXY, Env:ALL_PROXY를 실행합니다.

Clash 규칙과 노드에서 도메인별 경로 확인하기

환경 변수가 올바르고 요청이 Clash에 도착해도, 규칙 모드에서 대상 도메인이 DIRECT로 처리되거나 예상과 다른 프록시 그룹을 선택하면 결과가 달라질 수 있습니다. 클라이언트의 연결 기록에서 요청 대상, 매칭된 규칙, 최종 아웃바운드를 확인하세요. 전역 모드로 잠시 비교할 수는 있지만, 이는 트래픽 경로를 바꾸는 진단 방법입니다. 테스트가 끝나면 평소 사용하던 모드로 되돌리고, 가능하면 규칙 모드에서 대상 요청이 원하는 그룹을 통과하는지 확인하세요.

일부 설정에서는 필요한 도메인을 기존 규칙보다 앞에 추가해 특정 프록시 그룹으로 보낼 수 있습니다. 다음은 구조를 보여주는 예시이며, ClaudeProxy는 실제 설정에 존재하는 그룹 이름으로 바꿔야 합니다. 이 예시가 모든 서비스 요청에 필요한 호스트를 포함한다고 보장하지는 않습니다. 서비스의 공식 문서와 현재 연결 로그를 기준으로 필요한 도메인을 확인하고, 기존 규칙을 무작정 교체하지 마세요.

rules:
  - DOMAIN-SUFFIX,anthropic.com,ClaudeProxy
  - MATCH,기존최종규칙

규칙 파일에 추가할 때는 기존 rules 목록의 순서를 유지해야 합니다. 위와 같이 넓은 도메인 규칙을 추가하면 해당 도메인의 다른 요청에도 영향을 줄 수 있으므로, 정책이 허용되는 환경에서 필요한 범위만 적용하세요. 연결 기록에 요청이 없으면 아직 규칙 매칭 단계에 도달하지 않았을 수 있습니다. 반대로 요청은 보이지만 연결 오류가 기록되면 선택된 노드의 상태, 인증 정보, 원격 연결 오류를 살펴보세요.

관찰한 결과	먼저 확인할 항목	다음 단계
로컬 포트 검사 실패	Clash 실행 상태, 주소, 혼합 포트	실제 수신 포트 확인 후 다시 검사
curl 요청이 시간 초과됨	Clash 연결 기록, 노드, DNS 및 규칙	요청이 기록되었는지부터 구분
curl은 되지만 Claude Code는 실패	실행한 셸의 환경 변수와 프로그램 실행 방식	같은 터미널에서 변수를 확인하고 재실행
요청은 보이지만 연결 오류 발생	매칭 규칙, 아웃바운드, 원격 연결 및 인증	로그의 구체적인 오류 문구를 확인
인증 또는 이용 권한 오류	계정, 인증 상태, 서비스 응답	네트워크 문제와 계정 문제를 분리

DNS, NO_PROXY와 계정 상태까지 구분하기

DNS 오류와 프록시 연결 오류는 로그에 비슷한 시간 초과로 보일 수 있습니다. 도메인 해석이 로컬에서 이뤄지는지 프록시 쪽에서 이뤄지는지는 프록시 프로토콜, Clash의 DNS 설정, 규칙과 코어 동작에 따라 달라집니다. 연결 기록에 호스트가 표시되는지, 로그에 이름 해석 오류가 있는지, 다른 노드에서도 같은 오류가 반복되는지 살펴보세요. DNS 설정을 바꿀 때는 현재 값을 기록하고 한 번에 한 항목만 변경해야 원인을 되돌려 확인할 수 있습니다.

NO_PROXY 또는 no_proxy에 도메인이나 주소가 포함되어 있으면 해당 대상의 요청이 프록시를 우회할 수 있습니다. 설정되어 있다면 테스트 중에 값이 의도한 범위인지 확인하세요. 반대로 로컬 주소나 사내 서비스까지 무조건 프록시로 보내면 연결이 깨질 수 있으므로, 진단을 위해 기존 제외 목록을 삭제하기보다 대상 도메인과 일치하는 항목이 있는지 살펴보는 편이 안전합니다.

연결 기록에 요청이 없음: Claude Code가 실행된 터미널에 변수가 전달되었는지, 프록시 주소와 포트가 맞는지 확인합니다.
요청이 DIRECT로 표시됨: 규칙 순서와 NO_PROXY를 확인하고, 현재 활성 프로필이 예상한 설정인지 살펴봅니다.
요청이 노드에 도달한 뒤 실패함: 다른 사용 가능한 노드로 비교하고, 로그에 나타난 원격 연결 및 이름 해석 오류를 구분합니다.
네트워크 요청은 성공하지만 로그인이 거부됨: 인증 상태, 계정 설정, 서비스 응답과 이용 조건을 별도로 확인합니다.

Claude Code의 접속 가능 여부와 계정 또는 서비스 이용 자격은 같은 문제가 아닙니다. 지원 지역, 계정 유형, 서비스 정책은 달라질 수 있으므로 네트워크 우회만으로 이용 권한이 생긴다고 가정하지 마세요. 규칙을 공유하거나 로그를 전달할 때는 구독 주소, 인증 토큰, 개인 식별 정보와 요청 본문을 가리고 오류 문구와 관련된 도메인, 선택 규칙, 아웃바운드만 남기는 것이 안전합니다.