Claude Code에서 나타나는 연결 오류부터 구분하기

Claude Code를 실행할 때 로그인 화면은 열리지만 모델 응답이 시작되지 않거나, 작업 도중 연결이 끊기고, ETIMEDOUT·ECONNRESET·TLS 관련 오류가 반복된다면 먼저 인증 문제와 네트워크 경로 문제를 나눠 보세요. 브라우저에서 Claude 페이지가 열린다는 사실만으로 터미널에서 실행되는 Claude Code까지 같은 프록시를 사용한다고 볼 수는 없습니다. 브라우저는 운영체제의 시스템 프록시 설정을 따를 수 있지만, 터미널 프로그램은 별도의 환경 변수나 런타임 설정을 사용하기도 합니다.

오류가 HTTP 응답 코드와 함께 나타나는지도 중요한 단서입니다. 401이나 403처럼 서버 응답이 분명하면 로그인 상태, 계정 권한, 이용 가능 지역 또는 조직 정책을 확인해야 합니다. 반면 응답 코드가 나오기 전에 요청 시간이 초과되거나 소켓이 닫힌다면 DNS 조회, 프록시 연결, 노드 상태, TLS 연결 경로를 먼저 살펴보는 편이 효율적입니다. 429처럼 요청 제한을 알리는 응답은 네트워크가 연결된 뒤 서버가 반환한 결과이므로, 이때는 프록시만 바꾸기보다 요청량과 계정 상태도 함께 점검해야 합니다.

이 안내는 Clash Verge Rev와 Mihomo 계열 클라이언트를 기준으로 설명하지만, 핵심 원리는 다른 Clash 호환 클라이언트에도 적용할 수 있습니다. 메뉴 이름이나 로그 화면은 버전마다 다를 수 있으므로 특정 버튼 위치보다 실제 연결 호스트, 선택된 규칙, 사용된 프록시 그룹을 확인하는 데 초점을 맞추세요. 구독 URL이나 API 키가 들어 있는 화면을 공유할 때는 민감한 값을 반드시 가려야 합니다.

Clash 연결 표시와 터미널 연결은 따로 확인하기

먼저 Clash에서 프로필이 활성화되어 있는지, 코어가 정상 실행 중인지, 선택한 노드가 실제로 사용할 수 있는지 확인합니다. 연결 상태 표시가 켜져 있어도 Claude Code 요청이 그 노드를 통과한다는 뜻은 아닙니다. 시스템 프록시만 켜진 상태에서 터미널이 해당 설정을 읽지 않거나, Claude Code를 실행한 환경에 프록시 변수가 전달되지 않으면 브라우저는 정상인데 CLI만 직접 연결을 시도할 수 있습니다.

Clash의 연결 로그 또는 관련 기록을 열어 둔 뒤 Claude Code에서 짧은 요청을 한 번 실행해 보세요. 실행 시각과 로그 시각을 맞춰 보면 요청이 기록되는지, 어떤 호스트로 향하는지, 어느 규칙에 걸렸는지, 최종적으로 어떤 그룹이나 노드가 선택되었는지 파악할 수 있습니다. 실제 요청 호스트는 Claude Code 버전, 로그인 방식, 사용 기능에 따라 달라질 수 있으므로 알려진 도메인 목록을 무조건 복사하기보다 자신의 로그에서 확인한 호스트를 기준으로 판단하세요.

  • 관련 연결 기록이 전혀 없음: CLI가 Clash의 로컬 포트를 사용하지 않거나, TUN이 해당 프로세스의 트래픽을 가져오지 못했을 수 있습니다.
  • 호스트는 보이지만 DIRECT로 선택됨: 규칙 순서, 규칙 공급자 갱신 상태, 도메인 매칭 범위를 확인합니다.
  • 프록시 그룹을 선택했지만 실패함: 현재 노드의 연결 품질, 인증 상태, DNS 응답과 장시간 연결 안정성을 점검합니다.
  • 로그에는 성공처럼 보이지만 CLI에서 끊김: 호출이 이어지는 스트리밍 연결, 런타임의 프록시 처리 방식, 추가 호스트 연결을 함께 살펴봅니다.

이 단계에서는 모든 트래픽을 곧바로 글로벌 프록시로 바꾸기보다, 로그에 나타난 결과를 먼저 기록하는 것이 좋습니다. 처음 상태와 설정 변경 후 상태를 비교할 수 있어야 어떤 조치가 효과가 있었는지 판단하기 쉽습니다. 노드 이름이나 구독 제공자의 설명만 보고 원인을 단정하지 말고, 실제로 선택된 규칙과 연결 결과를 근거로 좁혀 가세요.

터미널의 HTTPS_PROXY와 실행 환경 점검하기

Claude Code를 터미널에서 실행한다면 현재 셸이 어떤 프록시 변수를 전달하는지 확인합니다. 일반적인 HTTP 클라이언트는 HTTPS_PROXY, HTTP_PROXY, 때로는 ALL_PROXY를 참고할 수 있으며, 예외 목록인 NO_PROXY가 지정되어 있으면 일부 호스트가 프록시를 건너뛸 수 있습니다. 각 프로그램이 모든 변수 이름과 형식을 똑같이 지원하는 것은 아니므로, 변수를 설정했다는 사실만으로 적용을 확정하지 말고 Clash 연결 로그에서 실제로 요청이 나타나는지 확인하세요.

Clash의 mixed port가 예를 들어 7890이라면, HTTP 프록시 주소는 보통 http://127.0.0.1:7890처럼 로컬 주소와 포트를 조합합니다. 다만 본인의 클라이언트에서 mixed port가 실제로 어떤 값인지 먼저 확인해야 합니다. 포트가 바뀌었는데 셸 프로필에 이전 값이 남아 있으면 연결을 시도해도 거부되거나 시간 초과가 날 수 있습니다. SOCKS 전용 포트를 HTTP 프록시 주소로 잘못 지정한 경우도 마찬가지로 확인이 필요합니다.

새 터미널 창을 열어 변수를 설정한 뒤 Claude Code를 실행하고, 해당 창에서만 성공하는지 비교해 보세요. macOS·Linux 계열 셸에서는 임시 테스트에 export를 사용할 수 있고, Windows PowerShell에서는 현재 세션에 환경 변수를 설정하는 문법이 다릅니다. 테스트가 끝난 뒤에는 자격 증명이나 내부 주소가 포함되지 않았는지 확인하고, 공유 컴퓨터나 공개 저장소에 프록시 설정을 평문으로 남기지 마세요.

IDE 통합 터미널도 별도로 확인해야 합니다. VS Code, Cursor, JetBrains 같은 앱을 프록시 변수를 설정하기 전에 열어 두었다면, IDE가 이미 시작될 때 받은 환경이 터미널에 전달될 수 있습니다. 셸에서 직접 실행하면 되는데 IDE 안에서만 실패한다면 IDE를 완전히 종료한 뒤 다시 실행하거나, IDE 터미널에서 변수가 보이는지 확인합니다. 반대로 터미널에서는 되지만 GUI에서 시작한 도구에서는 안 되는 경우도 있으므로, 어느 실행 경로에서 문제가 재현되는지 기록해 두세요.

규칙 매칭과 노드 상태를 순서대로 검증하기

로그에 Claude Code 관련 연결이 나타났다면 도메인 규칙과 최종 정책을 확인합니다. 특정 호스트가 DIRECT로 빠진다면 규칙 순서상 더 넓은 직접 연결 규칙이 먼저 적용되는지, 규칙 공급자가 최신 상태인지 살펴보세요. 반대로 너무 넓은 도메인 패턴을 추가하면 관련 없는 서비스까지 같은 그룹으로 보내 다른 문제가 생길 수 있습니다. 실패한 요청에서 확인한 호스트를 기준으로 필요한 범위만 다루고, 실제 규칙 문법은 사용 중인 코어와 프로필 형식에 맞춰야 합니다.

규칙이 의도한 프록시 그룹을 선택하더라도 해당 그룹의 현재 노드가 불안정하면 연결이 끊길 수 있습니다. 같은 노드로 짧은 요청은 성공하지만 긴 응답이나 스트리밍 작업에서만 중단된다면, 순간적인 지연뿐 아니라 패킷 손실, 업스트림 혼잡, 연결 유지 시간도 고려해야 합니다. 한 번의 테스트 결과에 의존하지 말고 짧은 요청과 실제 작업을 각각 여러 차례 실행해 재현되는지 비교하세요. 노드를 바꿔 테스트할 때는 규칙과 환경 변수는 그대로 두어야 노드 차이를 분리할 수 있습니다.

DNS도 함께 확인할 항목입니다. Clash가 처리하는 DNS 응답과 터미널 프로세스가 실제로 사용하는 경로가 어긋나면, 도메인 규칙은 맞아도 연결이 예상한 노드로 이어지지 않을 수 있습니다. DNS 설정을 여러 곳에서 동시에 바꾸기보다는 현재 활성 프로필, 시스템 DNS, TUN 또는 로컬 DNS 리스너가 어떻게 구성되어 있는지 확인하고 한 번에 하나씩 조정하세요. 사내 VPN이나 보안 에이전트를 함께 사용한다면 이들이 로컬 포트 접근이나 라우팅을 가로채는지도 살펴봐야 합니다.

팁: 테스트를 시작하기 전에 오류가 난 시각, Claude Code 실행 방식, 선택한 노드, Clash 로그의 호스트와 규칙 결과를 간단히 적어 두세요. 설정을 한꺼번에 바꾸지 않으면 DIRECT 분기, 환경 변수 누락, 노드 불안정 가운데 원인을 더 빠르게 구분할 수 있습니다.

TUN 모드는 마지막 분리 테스트로 사용하기

환경 변수를 지정하기 어려운 실행 경로이거나, CLI가 로컬 프록시 설정을 읽는지 불분명하다면 TUN 모드를 제한적인 진단 방법으로 시험할 수 있습니다. TUN은 운영체제의 가상 네트워크 인터페이스를 통해 프로세스의 트래픽을 처리하므로, 일반적인 시스템 프록시를 사용하지 않는 앱의 연결 경로를 확인하는 데 도움이 될 수 있습니다. 다만 TUN을 켜면 Claude Code만이 아니라 다른 앱의 네트워크 경로와 DNS 동작에도 영향을 줄 수 있으므로, 문제 해결을 위해 무조건 항상 켜 두는 설정으로 간주해서는 안 됩니다.

테스트 전에는 Clash 프로필이 정상적으로 검증되고 있는지 확인하고, 운영체제가 요청하는 네트워크 확장 또는 관리자 권한 승인을 정확히 읽은 뒤 진행하세요. TUN을 활성화한 다음 같은 터미널에서 같은 요청을 실행하고, 로그에서 해당 연결이 포착되는지와 어떤 규칙에 매칭되는지 확인합니다. TUN을 켰을 때만 성공한다면 터미널 환경 변수나 앱의 프록시 지원 여부가 핵심 단서일 수 있습니다. 반대로 결과가 달라지지 않으면 노드·규칙·DNS 등 다른 원인을 계속 분리해야 합니다.

테스트가 끝나면 TUN을 끄고 원래 동작을 다시 확인합니다. TUN과 HTTPS_PROXY를 동시에 적용하면 같은 트래픽이 겹쳐 처리되거나 예외 설정과 충돌할 수 있습니다. 특히 NO_PROXY에 로컬 주소나 개발용 서비스가 들어 있는 환경에서는 변경 전후의 차이를 주의 깊게 살펴보세요. 한 가지 방식이 확실히 효과를 보였다면 그 방식을 유지하고, 필요하지 않은 중복 경로는 정리하는 편이 문제를 재발 없이 관리하기 쉽습니다.

자주 묻는 질문

브라우저에서는 되는데 Claude Code만 실패하는 이유는 무엇인가요?

브라우저와 터미널 앱이 같은 프록시 설정을 사용하지 않을 수 있습니다. 브라우저가 시스템 프록시를 따르는 동안 Claude Code를 실행한 셸에는 HTTPS_PROXY가 없거나, IDE가 오래된 환경 변수를 물려받았을 수 있습니다. 먼저 Clash 로그에 CLI 요청이 나타나는지 확인하고, 셸과 IDE 터미널을 각각 비교하세요.

글로벌 모드로 바꾸면 연결 오류가 해결되나요?

글로벌 모드에서 성공한다면 규칙 매칭이나 규칙 순서가 원인일 가능성을 좁힐 수 있습니다. 하지만 모든 트래픽이 같은 노드를 통과하면서 다른 서비스가 느려지거나 실패할 수 있으므로, 이를 곧바로 최종 해결책으로 삼기보다 어떤 호스트가 기존 규칙에서 빠졌는지 확인한 뒤 필요한 규칙만 조정하는 것이 좋습니다.

TUN 모드를 계속 켜 두어야 하나요?

반드시 그렇지는 않습니다. TUN은 시스템 프록시를 따르지 않는 앱의 트래픽을 확인하는 데 유용하지만, 운영체제의 라우팅과 DNS에 더 넓게 영향을 줍니다. TUN을 켠 상태에서만 문제가 해결되는지 먼저 테스트하고, 결과와 사용 환경에 맞춰 유지 여부를 결정하세요.

401이나 429 오류도 노드 문제인가요?

항상 그렇지는 않습니다. 401은 인증 정보나 로그인 상태, 429는 요청 제한과 관련될 수 있으며, 두 경우 모두 서버까지 연결된 뒤 응답을 받은 상황일 수 있습니다. 오류 코드와 응답 내용을 먼저 확인하고, 응답 자체에 도달하지 못하는 타임아웃과 구분해 대응하세요.

일부 프록시 클라이언트는 시스템 프록시 설정을 간편하게 제공하지만, 터미널 변수와 프로세스별 경로를 확인하기 어렵거나 규칙 결과를 세밀하게 추적하기 힘든 경우가 있습니다. Clash 계열 도구는 연결 로그로 호스트와 규칙을 확인하고, 필요한 경우 환경 변수 방식과 TUN 방식을 분리해 시험할 수 있어 Claude Code의 연결 원인을 단계적으로 좁히는 데 도움이 됩니다. 한 번의 설정 변경보다 재현 조건과 로그를 비교하며 안정적인 경로를 찾고 싶다면 Clash 클라이언트와 자신의 운영체제에 맞는 구성을 확인해 보세요.

Clash 다운로드 →