Claude Code 연결 오류의 원인
Claude Code를 설치한 뒤 로그인이나 요청 단계에서 연결 오류가 발생하더라도, 원인이 반드시 계정이나 설치 파일에 있는 것은 아닙니다. 터미널에서 실행하는 CLI 도구는 브라우저와 프록시 설정을 공유하지 않을 수 있습니다. Clash가 켜져 있어도 터미널 프로세스가 프록시를 사용하지 않으면 Claude Code의 요청은 다른 경로로 나가거나 연결에 실패할 수 있습니다.
먼저 문제를 두 가지로 나누어 확인하세요. 브라우저에서도 서비스에 접속할 수 없다면 노드, 규칙, 네트워크 환경을 점검해야 합니다. 브라우저는 정상인데 Claude Code만 실패한다면, 터미널에 프록시 환경 변수가 전달되지 않았거나 Clash 규칙이 CLI의 요청을 다른 경로로 보내는 경우가 많습니다. 로그인 화면이 열리지만 인증이 끝나지 않는 문제는 브라우저와 터미널이 서로 다른 네트워크 경로를 사용하는 상황에서도 생길 수 있습니다.
이 가이드의 전제
Clash 클라이언트와 Mihomo 코어의 메뉴 이름은 버전에 따라 다를 수 있습니다. 아래에서는 로컬 HTTP 프록시 포트가 7890이라고 가정합니다. 실제 포트는 Clash의 설정 화면에서 확인해 해당 값으로 바꾸세요.
Clash Verge Rev 등 데스크톱 클라이언트에서 프로필을 가져와 노드를 선택하고 연결 상태를 확인한 뒤, 터미널에 프록시를 지정하는 순서로 진행하면 원인을 좁히기 쉽습니다. 구독 프로필에 문제가 있거나 노드가 만료된 경우에는 환경 변수만 설정해도 연결되지 않으므로, 먼저 일반 웹사이트의 프록시 연결이 정상인지 확인하는 것이 좋습니다.
1Clash 프로필과 프록시 포트 확인
Clash 클라이언트에서 사용할 프로필을 불러온 다음, 프로필을 활성화하고 프록시 노드를 선택하세요. 구독 주소는 제공업체가 발급한 주소를 사용해야 합니다. 출처를 확인할 수 없는 설정 파일이나 구독 링크를 가져오지 마세요. 프로필을 업데이트한 직후에는 설정이 적용되었는지, 노드 그룹에 선택 가능한 노드가 표시되는지 확인합니다.
- 프로필 활성화: Clash Verge 또는 Clash Verge Rev의 프로필 화면에서 구독을 추가하고, 해당 프로필을 현재 설정으로 선택합니다.
- 노드 선택: 프록시 화면에서 사용할 노드를 선택합니다. 자동 선택 그룹이 있다면 연결 상태와 지연 시간을 확인하고, 우선 하나의 노드를 직접 지정해 테스트하는 편이 원인 파악에 유리합니다.
- 포트 확인: 설정 화면에서 HTTP 또는 혼합 포트(Mixed Port)를 확인합니다. 아래 예시는
7890을 사용하지만, 실제 값이 다르면 명령어에 있는 포트도 함께 바꿔야 합니다. - 연결 확인: 클라이언트의 연결 로그나 트래픽 화면에서 테스트 요청이 표시되는지 살펴봅니다. 요청이 전혀 나타나지 않는다면 터미널이 해당 포트로 연결하지 못했을 가능성이 있습니다.
- HTTP 프록시: 터미널에서
http://127.0.0.1:7890형식으로 지정합니다. - SOCKS 프록시: Clash가 SOCKS 포트를 제공한다면 해당 포트를 확인하고
socks5h://127.0.0.1:포트처럼 지정할 수 있습니다.socks5h는 호스트 이름 조회도 프록시 쪽으로 전달하는 데 도움이 됩니다. - 혼합 포트: HTTP와 SOCKS 연결을 함께 받도록 구성된 포트입니다. 클라이언트 설정에서 지원 프로토콜을 확인하고, HTTP 방식으로 먼저 테스트하면 설정이 단순합니다.
포트와 주소를 혼동하지 마세요
일반적인 로컬 프록시 주소는 127.0.0.1 또는 localhost입니다. 예시 포트가 현재 Clash 설정과 다르면 연결되지 않습니다. 포트를 추측하지 말고 클라이언트 설정에서 확인하세요.
Clash의 규칙 모드에서는 연결 자체가 된다는 사실만으로 Claude Code 요청이 올바른 노드를 사용한다고 단정할 수 없습니다. 요청이 어떤 규칙에 일치했는지 연결 로그에서 살펴보세요. 정책 그룹 이름은 사용 중인 프로필마다 다르므로, 아래 YAML은 기존 규칙을 이해하기 위한 예시이며 그대로 덮어쓰는 완성 프로필이 아닙니다.
AI-Proxy는 예시 그룹 이름이므로 프로필에 실제로 존재하는 프록시 그룹명으로 바꾸세요. 더 구체적인 도메인 규칙은 일반적인 규칙보다 먼저 적용되어야 합니다. 이미 제공업체 프로필이 Claude 관련 규칙을 관리한다면 중복 규칙을 무작정 추가하지 말고, 현재 프로필의 규칙 순서와 그룹을 먼저 확인하세요.
2터미널에 프록시 환경 변수 설정
터미널에서 실행한 Claude Code가 시스템 프록시 설정을 자동으로 읽는다고 가정하지 마세요. CLI 프로세스가 시작될 때 HTTP_PROXY와 HTTPS_PROXY 같은 환경 변수를 읽는 방식으로 프록시를 지정할 수 있습니다. 아래 명령은 현재 터미널 창에서만 적용됩니다. Clash가 실행 중이고 포트가 7890인지 확인한 다음 운영체제에 맞는 명령을 사용하세요.
현재 셸 세션에 HTTP 프록시 주소를 지정하고, 같은 터미널에서 Claude Code를 실행합니다.
설정이 전달되었는지 확인하려면 echo "$HTTPS_PROXY"를 실행하세요. 출력이 비어 있거나 포트가 다르면 값을 수정해야 합니다. 프록시가 필요한 주소와 직접 연결할 주소를 분리하고 싶다면 로컬 주소를 예외로 지정할 수 있습니다.
매번 입력하기 번거롭다면 ~/.zshrc 또는 ~/.bashrc에 설정을 추가한 뒤 새 터미널을 여세요. 다만 프록시가 필요하지 않은 네트워크에서도 항상 적용되지 않도록, 셸 별칭이나 별도 실행 스크립트로 필요한 때만 활성화하는 방법이 더 안전합니다.
PowerShell에서는 환경 변수 이름 앞에 $env:를 붙입니다. 아래 설정은 현재 PowerShell 창에서 시작하는 프로세스에 적용됩니다.
환경 변수를 지정한 뒤 이미 실행 중이던 Claude Code를 그대로 두지 말고, 해당 프로세스를 종료한 다음 같은 PowerShell 창에서 다시 실행하세요. GUI 런처나 IDE의 내장 터미널은 별도의 환경을 사용할 수 있으므로, 우선 일반 PowerShell에서 테스트해 차이를 확인하는 것이 좋습니다.
변수명은 도구와 런타임에 따라 대소문자 처리 방식이 다를 수 있어 대문자와 소문자 이름을 함께 설정하는 예시를 제시했습니다. 프록시가 SOCKS 방식으로만 열려 있다면 주소의 프로토콜과 포트를 해당 포트에 맞게 바꿔야 합니다. HTTP 포트에 socks5h://를 지정하는 식으로 서로 다른 유형을 섞으면 연결에 실패할 수 있습니다.
먼저 현재 세션에서 시험하세요
셸 설정 파일에 영구 등록하기 전에 임시 환경 변수로 Claude Code가 연결되는지 확인하면, 잘못된 프록시 값이 다른 도구까지 영향을 주는 일을 줄일 수 있습니다.
3로그인 실패와 요청 시간 초과 점검
환경 변수를 설정했는데도 실패한다면 문제를 한꺼번에 바꾸기보다 단계별로 검사하세요. Clash가 요청을 받는지, 프록시를 통과한 네트워크 요청이 성공하는지, 마지막으로 Claude Code 자체에서 인증과 요청이 처리되는지 순서대로 확인하면 원인을 좁히기 쉽습니다.
- 프록시 포트 응답 확인: Clash가 실행 중인지 확인하고, 클라이언트 설정에 표시된 포트와 환경 변수 값이 같은지 대조합니다. 포트가 맞는데도 연결이 되지 않으면 다른 프로그램이 해당 포트를 점유했는지 또는 로컬 방화벽이 연결을 막는지 확인하세요.
- 외부 요청 테스트: macOS와 Linux에서는
curl로 프록시 경유 요청을 시험할 수 있습니다.
Windows PowerShell에서도 같은 curl 옵션을 시험할 수 있습니다. 이 검사는 프록시를 통해 호스트에 연결할 수 있는지 보는 용도이며, HTTP 응답 코드만으로 Claude Code의 로그인이나 API 인증이 성공했다고 판단할 수는 없습니다. 명령이 시간 초과되면 노드를 바꾸어 재검사하고, Clash 로그에서 연결 거부, DNS 오류, 규칙 적용 결과를 확인하세요.
- 로그인 콜백 점검: 인증 페이지가 열리지만 완료되지 않으면 기본 브라우저도 같은 네트워크 경로를 사용하는지 확인합니다. 브라우저가 다른 프록시를 사용하거나 로컬 콜백 주소가 프록시로 전달되면 인증이 돌아오지 않을 수 있습니다.
localhost와127.0.0.1을NO_PROXY에 포함하고, 인증을 다시 시도하세요. - 요청 시간 초과 점검: 한 노드에서만 실패하는지 확인하기 위해 안정적인 다른 노드로 바꾸어 시험합니다. 지연이 높거나 연결이 자주 끊기는 노드는 로그인은 되더라도 긴 요청 중 시간 초과를 일으킬 수 있습니다.
- 오래된 프로세스 종료: 환경 변수를 바꾼 뒤에는 기존 Claude Code 세션을 종료하고 새 터미널에서 다시 실행합니다. 터미널을 새로 열었는데도 값이 적용되지 않으면 셸 초기화 파일, IDE 터미널 설정, 실행 스크립트가 변수를 덮어쓰는지 확인하세요.
인증 정보와 로그 보호
오류를 해결하려고 API 키, 인증 토큰, 전체 환경 변수 출력 내용을 공개 채팅이나 이슈에 붙여 넣지 마세요. 로그를 공유해야 한다면 토큰과 계정 정보, 개인 경로를 먼저 가리세요. 서비스 제공자의 지역 지원과 이용 정책도 확인하고 준수해야 합니다.
진단 결과를 기록할 때는 운영체제, Clash 클라이언트와 코어 종류, 사용 포트, 선택한 노드, 오류가 발생한 단계만 정리해도 충분한 경우가 많습니다. 예를 들어 “브라우저는 접속되지만 PowerShell에서 curl이 시간 초과된다”와 같이 재현 가능한 증상을 적으면 원인 파악이 쉬워집니다. 반대로 여러 설정을 동시에 바꾸면 어떤 변경이 문제를 해결했는지 알기 어렵습니다.
마지막으로, Claude Code가 정상 작동한 뒤에도 항상 프록시를 강제로 사용해야 하는 것은 아닙니다. 네트워크 환경이 바뀌면 임시로 설정한 변수를 해제하거나 새 터미널을 열어 직접 연결 상태로 되돌릴 수 있습니다. 아래 페이지에서 사용하는 플랫폼에 맞는 Clash 클라이언트를 확인하세요.