튜토리얼 2026년 10월 18일

Claude Code 연결 오류, Clash로 터미널 프록시 설정하는 방법

Claude Code가 터미널에서 연결되지 않을 때 Clash 설정을 확인해 보세요. 프록시 모드와 환경 변수 지정부터 연결 경로 점검, 흔한 오류 해결까지 초보자도 따라 할 수 있게 안내합니다.

공항 선택 Clash 구독 보안 가이드

Claude Code가 터미널에서 연결되지 않는 이유

브라우저에서는 Claude에 접속되는데 터미널에서 Claude Code만 연결되지 않는다면, 먼저 계정이나 모델 설정을 바꾸기보다 터미널 프로세스가 어떤 네트워크 경로를 사용하는지 확인하는 편이 좋습니다. 브라우저는 운영체제의 시스템 프록시나 브라우저 자체 설정을 따를 수 있지만, Claude Code와 그 하위 프로세스는 셸 환경 변수, Node.js 네트워크 동작, 또는 시스템 라우팅에 따라 별도의 경로로 연결될 수 있습니다. 따라서 Clash에서 브라우저 트래픽이 프록시를 타더라도 CLI 요청은 직접 연결을 시도하는 상황이 생깁니다.

특히 오류가 요청 시간 초과, 연결 재설정, TLS 연결 실패처럼 나타난다면 인증 정보를 반복해서 입력하기 전에 네트워크 경로를 분리해 점검하세요. 반대로 API 인증 오류나 권한 오류가 명확히 표시된다면 프록시 연결은 이미 성립했을 수 있으므로, 이때는 키·로그인 상태·조직 정책을 따로 확인해야 합니다. 이 글은 특정 지역이나 네트워크 제한을 우회하는 방법이 아니라, 사용자가 이용할 권한이 있는 연결에서 Clash와 터미널의 프록시 설정을 일관되게 맞추는 절차를 설명합니다.

Clash의 프록시 모드와 로컬 포트 확인

먼저 Clash Verge, Clash Verge Rev 또는 Mihomo 기반 클라이언트에서 코어가 실행 중인지 확인합니다. 프로필이 선택되어 있더라도 코어가 중지되어 있거나 프록시 포트가 바뀌었다면 터미널은 연결할 수 없습니다. 설정 화면에서 혼합 포트(Mixed Port) 또는 HTTP·SOCKS 포트 번호를 확인하고, 예시로 흔히 쓰이는 7890을 실제 설정값으로 착각하지 않도록 주의하세요. 포트는 프로필이나 앱 설정에 따라 달라질 수 있습니다.

혼합 포트가 활성화되어 있다면 HTTP와 SOCKS 요청을 한 포트에서 받을 수 있어 환경 변수 설정이 간단해집니다. 단, 앱마다 혼합 포트를 제공하는 방식과 기본값이 다를 수 있으므로 Clash 화면에 표시된 주소와 포트를 기준으로 해야 합니다. 아래 예시에서 포트가 다르면 실제 값으로 바꾸고, 연결 테스트를 할 때는 Clash의 연결 로그도 함께 열어 두세요.

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

Claude Code를 실행하는 같은 터미널 세션에 프록시 변수를 설정해야 합니다. 새 터미널 창을 열거나 IDE에서 별도의 통합 터미널을 사용하면 기존 셸의 변수가 전달되지 않을 수 있습니다. 먼저 현재 사용 중인 셸을 확인한 다음, 해당 세션에서만 변수를 지정해 연결 여부를 시험하세요. 아래 주소와 포트는 예시이며, Clash가 실제로 수신 중인 로컬 포트로 교체합니다.

macOS·Linux·일반 Unix 셸

터미널에서 다음과 같이 설정한 뒤 같은 창에서 Claude Code를 실행합니다. HTTP_PROXY와 HTTPS_PROXY는 일반적인 HTTP 클라이언트가 참조하는 변수이며, 소문자 이름도 함께 지정하면 일부 도구와 라이브러리에서 인식될 가능성을 높일 수 있습니다.

export HTTP_PROXY="http://127.0.0.1:7890"
export HTTPS_PROXY="http://127.0.0.1:7890"
export http_proxy="$HTTP_PROXY"
export https_proxy="$HTTPS_PROXY"

claude

위 설정은 현재 터미널 세션에만 적용됩니다. 터미널을 닫으면 사라지므로, 일회성 진단에 적합합니다. 매번 적용하고 싶다면 사용하는 셸의 시작 파일에 설정할 수 있지만, 회사 장비나 공유 계정에서는 전역 적용 전에 정책을 확인하세요. 프록시를 쓰지 않아야 하는 호스트가 있다면 NO_PROXY에 해당 주소를 지정할 수 있습니다. 단, 지나치게 넓은 와일드카드나 도메인 예외는 필요한 요청까지 프록시에서 제외할 수 있으므로 범위를 좁혀야 합니다.

Windows PowerShell

PowerShell에서는 환경 변수 문법이 다릅니다. 아래 설정 역시 현재 PowerShell 프로세스와 그 하위 프로세스에 적용되므로, 그 창에서 Claude Code를 실행하고 결과를 확인합니다.

$env:HTTP_PROXY = "http://127.0.0.1:7890"
$env:HTTPS_PROXY = "http://127.0.0.1:7890"
$env:http_proxy = $env:HTTP_PROXY
$env:https_proxy = $env:HTTPS_PROXY

claude

Windows 터미널 안에서도 PowerShell, 명령 프롬프트, Git Bash는 환경 변수 설정 방식이 서로 다릅니다. 한 셸에서 설정한 변수가 다른 셸 창에 자동으로 복사되는 것은 아닙니다. IDE 통합 터미널을 사용하는 경우에는 IDE를 완전히 종료한 뒤 다시 실행해야 변수를 새로 읽는 환경도 있으므로, 우선 별도의 새 터미널에서 같은 명령을 시험해 차이를 비교하세요.

연결 경로를 단계별로 검증하기

변수를 설정했는데도 실패한다면 노드를 무작정 바꾸기보다 프록시 수신 → 규칙 매칭 → 터미널 적용 → 서비스 응답 순서로 확인합니다. 진단 중에는 한 번에 하나의 설정만 바꾸고, 변경 전후에 오류 메시지와 시각을 기록해야 원인을 좁힐 수 있습니다.

  1. 포트가 열려 있는지 확인합니다. Clash 코어가 실행 중인지, 표시된 혼합 포트가 설정한 주소·포트와 일치하는지 확인합니다. 앱에서 포트를 변경했다면 기존 터미널 변수도 함께 바꿔야 합니다.
  2. 변수가 현재 셸에 들어왔는지 확인합니다. macOS·Linux에서는 env | grep -i proxy, PowerShell에서는 Get-ChildItem Env:*proxy*를 실행해 값이 보이는지 확인합니다. 자격 증명이나 비밀 토큰이 출력된다면 로그를 공유하기 전에 반드시 가립니다.
  3. 같은 터미널에서 HTTPS 요청을 시험합니다. curl -v https://api.anthropic.com/처럼 요청하면 DNS, 프록시 연결, TLS 협상 단계의 단서를 얻을 수 있습니다. 인증이 필요한 API 호출이 아닌 단순 확인 요청은 정상적인 응답이나 서비스 오류를 반환할 수 있으므로, 응답 코드만으로 연결 성공 여부를 단정하지 말고 출력의 연결 단계를 살펴보세요.
  4. Clash 연결 로그를 같은 시각에 확인합니다. Claude Code 실행 시 관련 연결이 로그에 나타나는지, 어떤 규칙에 매칭되었는지, 최종 선택된 프록시 그룹이 의도와 같은지 봅니다. 로그에 요청 자체가 없다면 환경 변수가 적용되지 않았거나 해당 프로세스가 다른 네트워크 경로를 쓸 가능성이 있습니다.
  5. 브라우저 결과와 비교합니다. 브라우저만 성공하고 CLI 요청이 로그에 없거나 DIRECT로 나가면, 시스템 프록시와 셸 프록시가 서로 다른 상태일 수 있습니다. 이 경우 CLI 환경 변수를 명시하는 방식으로 먼저 검증하고, 전역 네트워크 설정은 마지막에 검토합니다.

curl은 성공하지만 Claude Code만 실패한다면, 앱의 로그인 상태, 설치된 버전, 실행 셸, 조직 정책을 확인합니다. 반대로 curl도 프록시 연결 단계에서 멈추면 Claude Code 자체보다 포트, 규칙, 선택된 노드 또는 네트워크 방화벽을 먼저 살펴볼 수 있습니다. 테스트용 URL의 응답 내용은 서비스 상태와 인증 요구에 따라 달라지므로, 응답이 비어 있거나 인증 오류가 나온다는 이유만으로 프록시가 실패했다고 판단하지 않는 것이 중요합니다.

규칙 미매칭과 TUN 모드 판단

규칙 모드를 쓰는 경우 Claude Code의 요청이 어떤 규칙에 걸리는지 확인하세요. 서비스의 엔드포인트는 계정 구성, 리전, 제품 업데이트에 따라 달라질 수 있으므로, 특정 도메인 목록을 그대로 복사하기보다 Clash 로그에 실제 표시된 호스트를 기준으로 좁혀 가는 편이 안전합니다. 필요한 호스트만 명시적으로 라우팅하고, 해당 규칙이 넓은 외부 RULE-SET이나 일반 규칙보다 위에 있는지 확인합니다. 규칙은 위에서부터 평가되므로, 너무 넓은 키워드 규칙을 먼저 추가하면 관련 없는 트래픽까지 같은 그룹으로 보낼 수 있습니다.

환경 변수를 지원하지 않는 하위 프로그램이 있거나 여러 CLI를 같은 경로로 보내야 한다면 TUN 모드를 검토할 수 있습니다. TUN은 운영체제의 네트워크 경로에서 트래픽을 처리하므로 프록시 설정을 모르는 프로그램에도 도움이 될 수 있습니다. 다만 다른 VPN, 보안 에이전트, 가상 네트워크 어댑터와 충돌하거나 DNS 동작을 바꿀 수 있습니다. 먼저 셸 변수와 규칙 모드로 단일 CLI만 시험하고, 그래도 앱별 경로가 일관되지 않을 때에만 TUN을 테스트하세요. 문제가 전체 네트워크로 번지면 TUN을 끄고 이전 상태로 되돌린 뒤 원인을 분리하는 것이 좋습니다.

전역 모드는 규칙 문제인지 출구 문제인지 짧게 비교할 때 사용할 수 있지만, 정상 운영 설정으로 간주하지 않는 편이 낫습니다. 전역 모드에서만 연결된다면 규칙 미매칭 가능성을 확인하고, 두 모드 모두 실패한다면 로컬 포트와 노드 연결 상태를 확인합니다. 반대로 규칙 모드에서 로그상 올바른 그룹을 선택했는데 연결이 끊긴다면 DNS, TLS 인증서 검사, 네트워크 정책처럼 프록시 라우팅 이후의 계층을 점검해야 합니다.

Claude Code 터미널 연결 오류와 해결 방법

문제 해결 중에는 노드, 규칙 모드, TUN, 환경 변수를 한꺼번에 바꾸지 마세요. 변경이 여러 개 겹치면 어떤 항목이 효과가 있었는지 알기 어렵고, 이후 문제가 재발해도 재현하기 힘듭니다. 먼저 로컬 포트와 변수 적용 여부를 확인하고, 다음으로 로그의 매칭 규칙과 최종 아웃바운드를 봅니다. 마지막으로 인증 및 계정 오류를 네트워크 오류와 분리하면 불필요한 재설정과 자격 증명 재발급을 줄일 수 있습니다.

자주 묻는 질문

시스템 프록시를 켰는데 왜 Claude Code는 연결되지 않나요?

시스템 프록시 설정은 브라우저처럼 해당 설정을 읽는 앱에는 적용되지만, 모든 터미널 프로그램이 이를 따르는 것은 아닙니다. Claude Code를 실행하는 셸에 HTTP_PROXY와 HTTPS_PROXY를 지정하고, 같은 터미널에서 실행했는지 확인하세요.

HTTP 포트와 SOCKS 포트 중 어느 것을 써야 하나요?

Clash가 제공하는 혼합 포트는 HTTP와 SOCKS 연결을 함께 받을 수 있어 일반적인 셸 환경 변수 설정에 편리합니다. 혼합 포트가 없다면 클라이언트가 지원하는 프록시 형식에 맞춰 해당 포트를 사용해야 합니다. 화면에 표시된 프로토콜과 포트 정보를 확인하고 임의로 번호를 추측하지 마세요.

전역 모드에서만 연결되면 전역 모드를 계속 써도 되나요?

전역 모드에서만 연결된다면 규칙 모드에서 요청이 다른 그룹이나 DIRECT로 빠지는지 확인할 단서입니다. 전체 트래픽을 우회하면 관계없는 서비스의 지연이 늘거나 사내 네트워크에 영향을 줄 수 있습니다. 로그에서 실제 요청 호스트와 매칭 규칙을 확인한 다음 필요한 규칙만 조정하는 것을 권합니다.

환경 변수를 설정해도 안 되면 바로 TUN을 켜야 하나요?

바로 켜기보다 먼저 변수가 현재 셸에 적용됐는지, 로컬 포트가 열려 있는지, Clash 로그에 요청이 나타나는지 확인하세요. 프록시 변수를 읽지 않는 프로그램이 확인되거나 여러 CLI의 경로를 운영체제 수준에서 통일해야 할 때 TUN을 검토할 수 있습니다. 다른 VPN이나 보안 도구와의 충돌 가능성도 함께 고려해야 합니다.

일부 단순 프록시 앱은 브라우저 설정만 바꾸거나 한 가지 연결 방식만 제공해 CLI와 하위 프로세스의 경로를 확인하기 어려울 수 있습니다. 반면 Clash는 규칙 모드, 그룹 선택, 연결 로그를 통해 요청이 어떤 호스트에서 들어와 어느 출구로 나갔는지 단계별로 살펴볼 수 있고, 환경 변수나 TUN과 조합해 Claude Code 같은 터미널 도구의 경로도 조정할 수 있습니다. 터미널마다 별도 설정을 반복하는 대신 사용 환경에 맞는 Clash 클라이언트를 확인하고 싶다면 아래 다운로드 페이지에서 시작할 수 있습니다.

Clash 다운로드 보기 →

Claude Code 연결을 점검할 준비가 되셨나요?

사용 중인 플랫폼에 맞는 Clash 클라이언트를 선택하고, 터미널 프록시 설정을 차근차근 확인해 보세요.