Claude Code 접속 오류, 어디서부터 확인할까
Claude Code를 설치한 뒤 로그인 페이지가 열리지 않거나, 인증을 마친 후에도 요청이 시간 초과되는 경우에는 계정 상태와 네트워크 경로를 나누어 확인해야 합니다. 특히 브라우저에서는 Claude에 접속할 수 있는데 터미널에서 실행한 Claude Code만 실패한다면, 터미널 프로세스가 시스템 프록시를 사용하지 않거나 셸에 오래된 프록시 환경 변수가 남아 있을 수 있습니다. 반대로 로그인과 요청이 모두 거부되고 응답에 계정·인증 관련 안내가 표시된다면, 프록시만 바꾸어 해결할 수 있는 문제라고 단정해서는 안 됩니다.
이 안내는 Clash Verge에서 구독 프로필과 프록시 모드를 확인하고, 터미널의 HTTP_PROXY·HTTPS_PROXY 설정을 점검하는 기본 순서를 설명합니다. Clash Verge의 버전과 운영체제에 따라 메뉴 이름이나 화면 배치는 달라질 수 있으므로, 아래의 용어는 기능을 찾기 위한 기준으로 활용하세요. 구독 제공자나 특정 노드에 의존하지 않으며, 실제 Claude Code 요청이 어떤 경로로 나가는지는 Clash Verge 연결 기록과 명령 실행 결과를 함께 확인하는 방식으로 판단합니다.
먼저 오류 메시지와 발생 시점을 기록해 두세요. 로그인 창을 열기 전 실패하는지, 브라우저 인증 후 터미널로 돌아오는 단계에서 멈추는지, 아니면 요청 전송 후 응답을 기다리다 시간 초과되는지에 따라 점검할 지점이 달라집니다. 설정을 한꺼번에 여러 개 바꾸면 무엇이 효과가 있었는지 알기 어려우므로, 한 항목씩 바꾸고 같은 동작을 다시 시험하는 편이 좋습니다.
1단계: Clash Verge의 프로필과 프록시 포트 확인
Clash Verge를 열고 사용할 프로필이 선택되어 있으며 정상적으로 불러와졌는지 확인합니다. 구독을 방금 추가했거나 갱신했다면 프로필이 최신 상태인지, 코어가 실행 중인지도 살펴보세요. 구독 주소를 입력했는데 노드 목록이 비어 있거나 프로필 업데이트가 실패했다면, 터미널 설정을 바꾸기 전에 제공자가 안내한 구독 주소와 갱신 상태부터 점검해야 합니다. 구독 주소에는 계정 권한 정보가 포함될 수 있으므로 다른 사람에게 전달하거나 공개된 화면에 그대로 노출하지 마세요.
다음으로 Clash Verge의 설정에서 혼합 포트(mixed-port) 또는 HTTP 프록시 포트 번호를 확인합니다. 혼합 포트는 HTTP와 SOCKS 방식의 연결을 함께 받는 포트로 설정된 경우가 많지만, 실제 동작 여부와 번호는 앱의 현재 설정을 기준으로 판단해야 합니다. 일반적인 기본값이라고 알려진 숫자를 그대로 복사하지 말고, 화면에 표시된 값을 확인하세요. 포트를 확인했다면 터미널에 설정할 주소는 보통 http://127.0.0.1:포트번호 형태가 됩니다. 이 주소는 같은 컴퓨터 안에서 실행되는 Clash Verge를 가리킵니다.
Clash Verge에서 연결 모드를 확인할 때는 우선 규칙 모드를 기준으로 점검하는 것이 실용적입니다. 규칙 모드는 요청 호스트에 따라 직접 연결 또는 프록시 그룹을 선택하므로, 필요한 트래픽만 프록시로 보낼 수 있습니다. 다만 현재 규칙이 Claude Code의 요청에 적용되는지는 연결 기록으로 확인해야 합니다. 처음 원인을 좁히는 짧은 시험에서는 글로벌 모드를 잠시 사용해 차이를 비교할 수도 있지만, 모든 트래픽이 프록시를 통과할 수 있으므로 테스트 뒤에는 원래 모드로 되돌리고 불필요하게 계속 사용하지 않는 편이 좋습니다.
2단계: 규칙 모드와 TUN 모드를 구분하기
Clash Verge의 시스템 프록시 설정은 운영체제의 프록시를 따르는 앱에 영향을 줄 수 있지만, 모든 터미널 도구가 이를 자동으로 사용하는 것은 아닙니다. 따라서 브라우저 로그인은 되는데 Claude Code 요청만 실패한다면 시스템 프록시가 켜져 있다는 사실만으로 터미널도 같은 경로를 탄다고 볼 수 없습니다. 이 경우 터미널 환경 변수 설정을 확인하는 것이 우선입니다.
TUN 모드는 지원되는 환경에서 네트워크 트래픽을 가상 인터페이스를 통해 처리하는 방식입니다. 앱이 일반적인 시스템 프록시 설정을 읽지 않더라도 트래픽이 Clash Verge로 들어올 수 있어, 환경 변수 설정이 적용되지 않는 프로그램을 점검할 때 비교 방법으로 도움이 됩니다. 다만 TUN 모드는 권한이나 운영체제별 네트워크 설정이 필요할 수 있고, 이미 다른 VPN·방화벽·네트워크 필터가 동작 중이면 경로가 복잡해질 수 있습니다. 원인을 파악하지 않은 채 시스템 프록시, TUN, 별도 VPN을 동시에 켜면 이중 프록시나 연결 충돌이 생길 수 있으므로 한 번에 하나씩 시험하세요.
연결 기록을 볼 때는 실패한 시각과 호스트 또는 앱 이름을 함께 확인합니다. Claude Code를 실행한 시점에 관련 요청이 나타나고, 선택한 프록시 그룹을 통과하는지 확인하세요. 호스트 이름이나 요청 경로가 버전과 사용 방식에 따라 달라질 수 있으므로, 인터넷에서 본 규칙을 무조건 복사하기보다 자신의 연결 기록에서 확인되는 정보를 우선합니다. 규칙을 직접 편집해야 한다면 기존 구독 프로필을 덮어쓰기 전에 앱이 제공하는 규칙 오버라이드 방식이 있는지 확인하고, 변경 전 설정을 복구할 수 있도록 기록해 두세요.
3단계: 터미널 환경 변수와 실행 환경 확인
터미널에서 실행되는 프로그램은 HTTP_PROXY와 HTTPS_PROXY 같은 환경 변수를 읽어 프록시를 사용하는 경우가 있습니다. 앱에서 시스템 프록시를 켰더라도 Claude Code가 실행된 셸에 해당 값이 전달되지 않았다면 요청은 직접 연결을 시도할 수 있습니다. 앞 단계에서 확인한 Clash Verge 포트 번호를 사용해 환경 변수를 설정한 뒤, 새 터미널에서 Claude Code를 다시 실행해 보세요. 포트가 다르거나 Clash Verge가 실행되지 않은 상태라면 로컬 프록시 주소에 연결할 수 없습니다.
- macOS·Linux: 현재 터미널 세션에 프록시 변수를 설정하고, 같은 세션에서 Claude Code를 실행합니다.
- Windows PowerShell: 현재 PowerShell 세션의 환경 변수로 지정한 뒤 같은 창에서 실행합니다.
- 공통: HTTP와 HTTPS에 서로 다른 주소를 넣기보다, Clash Verge에서 확인한 로컬 포트가 두 변수에 일관되게 적용되었는지 점검합니다.
예를 들어 셸에서 HTTPS_PROXY를 지정한 뒤 별도의 IDE를 열어 통합 터미널에서 실행하면, IDE가 시작될 때 전달받은 환경 변수가 달라 새 설정을 읽지 못할 수 있습니다. 이 경우 IDE를 완전히 종료했다가 다시 열거나, IDE가 실행하는 터미널의 환경 설정을 확인하세요. 반대로 기존 셸에 설정된 값을 바꿨는데 같은 셸에서 계속 이전 결과가 나온다면, 해당 세션에 변수가 어떻게 적용되어 있는지 출력해 비교해야 합니다.
ALL_PROXY를 읽는 도구도 있지만 런타임마다 지원 범위가 다르므로, Claude Code가 사용하는 실행 방식에서 어떤 변수를 읽는지 확인하지 않은 채 여러 변수를 무작정 추가하지 마세요. NO_PROXY에 넓은 와일드카드나 관련 도메인이 포함되어 있으면 프록시를 우회할 수 있습니다. 기존에 내부 서비스나 로컬 주소를 직접 연결하도록 설정한 경우에는 이를 모두 지우기보다, 어떤 예외가 필요한지 확인하고 Claude 관련 요청이 우회 대상에 들어 있지 않은지 살펴보세요. 프록시 주소에 사용자 이름이나 비밀번호를 추가해야 하는 환경이라면 셸 기록과 프로세스 목록에 민감 정보가 남을 수 있으므로 조직의 보안 지침을 따르세요.
4단계: 연결을 재현하고 원인을 좁히기
환경 변수를 적용한 새 터미널에서 Claude Code를 실행하고 로그인 또는 간단한 요청을 재현합니다. 같은 시각에 Clash Verge 연결 기록을 새로 고쳐 관련 연결이 생성되었는지 확인하세요. 연결 자체가 나타나지 않으면 Claude Code가 실행된 프로세스에 변수가 전달되었는지, 다른 터미널이나 컨테이너에서 실행 중이지 않은지 살펴봅니다. 연결이 나타나지만 직접 연결로 분류되면 규칙 모드의 매칭 결과와 프록시 모드 설정을 확인합니다. 프록시 그룹에 들어갔는데도 실패한다면 노드 변경 전후의 결과를 비교하고, 특정 노드만 반복해서 끊기는지 확인하세요.
Docker 컨테이너, 원격 개발 환경, WSL, SSH 세션 또는 CI 작업에서 Claude Code를 실행한다면 127.0.0.1이 가리키는 위치를 특히 주의해야 합니다. 컨테이너 안의 127.0.0.1은 대개 컨테이너 자신을 뜻하며, 호스트에서 실행 중인 Clash Verge를 자동으로 가리키지 않습니다. 원격 서버의 셸 역시 로컬 컴퓨터의 Clash Verge와 같은 네트워크 공간을 공유하지 않습니다. 이때는 해당 환경에서 사용할 수 있는 프록시 주소와 네트워크 정책을 별도로 확인해야 하며, 로컬 포트를 무작정 외부에 열어 두는 방식은 보안상 피해야 합니다.
오류가 계속되면 메시지를 종류별로 나눠 보세요. 연결 시간 초과나 TLS 연결 실패는 경로·DNS·노드 상태를 점검할 단서가 될 수 있습니다. 인증 거부나 권한 부족 응답은 로그인 계정, 토큰 만료, 조직 정책 등 별도의 원인일 수 있습니다. 사용량 한도나 결제 관련 안내도 프록시 연결 문제와 다릅니다. 오류 문구를 복사해 공유할 때는 토큰, 이메일 주소, 구독 URL, API 키와 같은 비밀 정보를 먼저 제거하세요. 연결 기록과 터미널 로그를 같은 시각 기준으로 비교하면 네트워크 단계에서 멈춘 것인지, 서버 응답을 받은 뒤 거부된 것인지 구분하는 데 도움이 됩니다.
설정을 바꾼 뒤에는 성공 여부뿐 아니라 되돌릴 방법도 확인합니다. 테스트로 글로벌 모드나 TUN을 켰다면 원래 모드로 복구하고, 임시 환경 변수는 현재 터미널을 닫거나 값을 해제해 제거할 수 있습니다. 셸 프로필에 변수를 영구 저장했다면 사용하지 않는 포트나 오래된 주소가 남지 않았는지 다시 확인하세요. 구독 갱신 후 포트나 규칙이 달라질 수도 있으므로, 문제가 재발했을 때는 이전 메모와 현재 앱 설정을 비교하면 반복 점검을 줄일 수 있습니다.
자주 묻는 질문
브라우저에서는 되는데 Claude Code만 실패하는 이유는 무엇인가요?
브라우저는 운영체제 시스템 프록시를 사용하지만 터미널 프로그램은 별도의 환경 변수를 요구하는 경우가 있습니다. Claude Code를 실행한 셸에서 HTTPS_PROXY가 설정되어 있는지, Clash Verge의 로컬 포트와 일치하는지 확인하세요. IDE 통합 터미널이나 컨테이너에서 실행했다면 해당 실행 환경이 변수를 전달받았는지도 살펴봐야 합니다.
글로벌 모드로 바꾸면 항상 해결되나요?
글로벌 모드는 원인을 비교하는 짧은 테스트로 활용할 수 있지만, 모든 트래픽이 같은 프록시 경로를 사용할 수 있어 지속적인 해결책이라고 단정할 수 없습니다. 테스트 중 연결 기록이 어떻게 바뀌는지 확인한 뒤 규칙 모드로 돌아가 필요한 요청이 적절한 그룹을 타도록 점검하세요.
Clash Verge 연결 기록에 Claude Code 요청이 보이지 않으면 어떻게 하나요?
Claude Code를 실행한 터미널에서 프록시 변수가 실제로 적용되었는지 확인하고, 설정한 포트가 현재 Clash Verge에서 열려 있는지 살펴보세요. 컨테이너·원격 셸에서 실행했다면 로컬 주소가 Clash Verge를 가리키지 않을 수 있습니다. 먼저 실행 위치와 네트워크 경계를 확인한 뒤 해당 환경에 맞는 프록시 연결 방법을 선택하세요.
프록시 설정으로 계정이나 지역 관련 오류도 해결할 수 있나요?
프록시는 네트워크 연결 경로를 바꾸는 기능이지, 계정 권한이나 이용 가능 지역, 사용량 한도를 변경하는 기능은 아닙니다. 서버가 인증·계정·결제 관련 오류를 반환한다면 해당 안내를 확인하고, 공식 지원 경로와 서비스 정책을 따르세요.
일부 프록시 도구는 시스템 전체 설정과 터미널별 환경을 한눈에 확인하기 어렵거나, 앱마다 프록시 적용 방식이 달라 원인을 찾는 데 시간이 걸릴 수 있습니다. Clash Verge는 프로필과 연결 모드를 관리하고 연결 기록을 살펴볼 수 있어, Claude Code 요청이 어떤 경로를 탔는지 단계적으로 확인하는 데 유용합니다. 운영체제 프록시만으로 해결되지 않을 때도 터미널 환경 변수와 로그를 함께 점검할 수 있으므로, 현재 설정을 직접 비교하며 문제를 좁히려는 사용자에게 실용적인 선택입니다.