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을 실제 설정값으로 착각하지 않도록 주의하세요. 포트는 프로필이나 앱 설정에 따라 달라질 수 있습니다.
- 규칙 모드: 설정한 규칙에 따라 Claude Code 관련 요청이 프록시 그룹 또는 DIRECT로 전달됩니다. 일상적인 사용에는 이 모드가 적합합니다.
- 전역 모드: 모든 트래픽을 선택한 프록시 경로로 보내는 진단용 선택지입니다. 짧은 비교 테스트에는 유용하지만, 패키지 저장소나 사내 서비스까지 우회시킬 수 있어 계속 켜 둘 필요는 없습니다.
- 시스템 프록시: 브라우저 등 시스템 설정을 따르는 앱에 영향을 주지만, 모든 셸 프로그램이나 CLI가 이를 자동으로 사용하는 것은 아닙니다.
혼합 포트가 활성화되어 있다면 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를 완전히 종료한 뒤 다시 실행해야 변수를 새로 읽는 환경도 있으므로, 우선 별도의 새 터미널에서 같은 명령을 시험해 차이를 비교하세요.
연결 경로를 단계별로 검증하기
변수를 설정했는데도 실패한다면 노드를 무작정 바꾸기보다 프록시 수신 → 규칙 매칭 → 터미널 적용 → 서비스 응답 순서로 확인합니다. 진단 중에는 한 번에 하나의 설정만 바꾸고, 변경 전후에 오류 메시지와 시각을 기록해야 원인을 좁힐 수 있습니다.
- 포트가 열려 있는지 확인합니다. Clash 코어가 실행 중인지, 표시된 혼합 포트가 설정한 주소·포트와 일치하는지 확인합니다. 앱에서 포트를 변경했다면 기존 터미널 변수도 함께 바꿔야 합니다.
- 변수가 현재 셸에 들어왔는지 확인합니다. macOS·Linux에서는
env | grep -i proxy, PowerShell에서는Get-ChildItem Env:*proxy*를 실행해 값이 보이는지 확인합니다. 자격 증명이나 비밀 토큰이 출력된다면 로그를 공유하기 전에 반드시 가립니다. - 같은 터미널에서 HTTPS 요청을 시험합니다.
curl -v https://api.anthropic.com/처럼 요청하면 DNS, 프록시 연결, TLS 협상 단계의 단서를 얻을 수 있습니다. 인증이 필요한 API 호출이 아닌 단순 확인 요청은 정상적인 응답이나 서비스 오류를 반환할 수 있으므로, 응답 코드만으로 연결 성공 여부를 단정하지 말고 출력의 연결 단계를 살펴보세요. - Clash 연결 로그를 같은 시각에 확인합니다. Claude Code 실행 시 관련 연결이 로그에 나타나는지, 어떤 규칙에 매칭되었는지, 최종 선택된 프록시 그룹이 의도와 같은지 봅니다. 로그에 요청 자체가 없다면 환경 변수가 적용되지 않았거나 해당 프로세스가 다른 네트워크 경로를 쓸 가능성이 있습니다.
- 브라우저 결과와 비교합니다. 브라우저만 성공하고 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 터미널 연결 오류와 해결 방법
- 브라우저는 되지만 Claude Code는 시간 초과됩니다. 브라우저가 사용하는 시스템 프록시와 CLI가 사용하는 셸 환경 변수는 별개일 수 있습니다. Claude Code를 실행한 바로 그 터미널에서 변수를 확인하고, Clash 로그에 요청이 나타나는지부터 비교합니다.
- 연결이 거부되거나 로컬 프록시에 접속할 수 없습니다. 변수에 적은 포트가 실제 혼합 포트인지 확인하고, Clash 코어가 실행 중인지 봅니다. 포트 번호를 변경한 뒤에는 터미널 변수와 Clash 설정이 서로 일치하는지도 다시 확인해야 합니다.
- TLS 또는 인증서 오류가 표시됩니다. 시스템 시각, 네트워크의 TLS 검사 정책, Clash의 연결 로그를 확인합니다. 인증서 검증을 끄거나 임의의 CA를 신뢰하도록 설정하면 보안 위험이 커질 수 있으므로, 인증서 검증 비활성화는 해결책으로 사용하지 마세요. 회사 네트워크라면 승인된 인증서와 보안 설정을 관리자에게 문의합니다.
- 프록시 요청은 보이는데 인증 오류가 납니다. 이 경우 네트워크 연결은 성립했을 수 있습니다. Claude Code의 로그인 상태와 사용 권한, API 자격 증명, 조직에서 허용한 인증 방식을 별도로 확인합니다. 비밀 키를 셸 명령이나 공개 로그에 남기지 마세요.
- 셸에서는 되지만 IDE 터미널에서는 실패합니다. IDE가 실행될 때 환경 변수를 전달받지 못했거나, 별도 셸 프로필을 읽을 수 있습니다. IDE를 재시작하거나 IDE의 터미널 셸과 환경 설정을 확인한 뒤, 동일한 변수와 테스트 명령을 다시 실행합니다.
문제 해결 중에는 노드, 규칙 모드, 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 클라이언트를 확인하고 싶다면 아래 다운로드 페이지에서 시작할 수 있습니다.