브라우저는 되는데 Claude Code만 연결되지 않는 이유
Claude Code는 브라우저 탭이 아니라 셸에서 실행되는 코딩 도구입니다. 따라서 브라우저에서 Claude 웹 화면이 잘 열려도 터미널에서 실행한 Claude Code가 같은 프록시를 사용한다고 단정할 수 없습니다. 브라우저는 운영체제의 시스템 프록시 설정을 따르는 반면, CLI 프로세스는 실행 당시의 셸 환경 변수와 부모 프로세스 설정을 상속하는 경우가 많습니다. Clash에서 시스템 프록시를 켰더라도 터미널에 프록시 주소가 전달되지 않으면 API 요청이 다른 경로로 나갈 수 있습니다.
증상도 단계별로 다릅니다. 로그인 페이지를 열지 못하면 인증 흐름이나 브라우저 호출을, 로그인은 됐지만 대화가 시작되지 않으면 API 연결과 셸 프록시를, 코드 변경이나 도구 실행 중 멈추면 장시간 연결과 연결 유지 동작을 살펴봐야 합니다. 패키지 설치를 거쳤다면 레지스트리나 다운로드 호스트가 별도로 실패했을 수도 있습니다. 모든 현상을 한꺼번에 “노드가 느리다”로 판단하지 말고, 어떤 명령과 단계에서 문제가 생겼는지 먼저 기록하세요.
이 글은 승인된 네트워크 환경에서 Clash와 셸 프록시 설정을 점검하는 절차를 설명합니다. 조직의 보안 정책이나 서비스 이용 조건을 우회하는 방법은 다루지 않습니다. 먼저 사용하는 Clash 클라이언트와 코어가 정상 실행 중인지 확인하고, 그다음 터미널이 실제로 어느 로컬 포트를 바라보는지 확인하면 불필요한 설정 변경을 줄일 수 있습니다.
Clash 프로필과 로컬 포트 확인
Claude Code를 실행하기 전에 Clash에서 프로필을 불러오고 코어가 실행 중인지 확인합니다. 구독을 추가했더라도 프로필이 활성화되지 않았거나 코어가 오류로 멈춰 있으면 로컬 프록시 포트가 연결을 받지 못할 수 있습니다. 클라이언트의 대시보드나 설정 화면에서 HTTP 또는 mixed 포트 번호를 확인하고, 상태 표시가 실행 중인지 살펴보세요. 기본값으로 알려진 포트 번호를 그대로 가정하기보다 현재 설정 화면에 표시된 값을 사용하는 것이 안전합니다.
터미널에서 사용할 주소는 대개 로컬 장치의 HTTP 프록시 주소입니다. 예를 들어 Clash의 mixed 포트가 7890으로 설정되어 있다면 HTTP 프록시 URL은 http://127.0.0.1:7890처럼 구성할 수 있습니다. 사용 중인 포트가 다르면 숫자를 바꾸세요. mixed 포트는 일반적으로 HTTP 요청과 HTTPS용 CONNECT 터널을 함께 처리하므로, CLI용 프록시 주소를 정할 때 편리합니다. 단, 각 클라이언트의 포트 종류와 지원 방식은 설정에 따라 다를 수 있으므로 화면에 표시된 설명을 우선합니다.
Clash가 규칙 모드라면 연결 로그에서 목적지와 적용된 정책을 함께 확인합니다. 로그에 Claude Code가 사용한 호스트가 보이는데 의도하지 않은 정책으로 분류된다면 그 연결만 조사하고, 관측하지 않은 도메인을 넓게 추가하는 방식은 피하세요. 서비스의 호스트 이름과 인증 흐름은 업데이트에 따라 달라질 수 있습니다. 도메인 규칙을 복사해 붙이는 것보다 실제 로그에 나타난 호스트와 기존 규칙 순서를 확인하는 편이 재현성도 높고 다른 트래픽에 미치는 영향도 작습니다.
셸 환경 변수로 터미널에 프록시 전달
Clash의 시스템 프록시 설정과 셸의 환경 변수는 서로 다른 설정 층입니다. Claude Code를 실행할 셸에서 프록시 변수를 지정하면 그 셸에서 시작한 프로그램이 값을 상속할 수 있습니다. macOS·Linux의 zsh 또는 bash에서는 아래처럼 현재 터미널 세션에 임시 적용해 먼저 시험할 수 있습니다. 포트 번호는 실제 Clash 설정에 맞추세요.
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"
export NO_PROXY="localhost,127.0.0.1,::1"
export no_proxy="$NO_PROXY"
대소문자 환경 변수를 함께 지정하는 이유는 프로그램과 라이브러리마다 읽는 변수 이름의 관례가 다를 수 있기 때문입니다. NO_PROXY에는 로컬호스트를 넣어 로그인 과정의 로컬 콜백이나 로컬 서비스 연결이 불필요하게 프록시를 거치지 않도록 합니다. 처음부터 셸 시작 파일에 영구 저장하지 말고, 현재 창에서만 적용해 결과를 확인하세요. 설정이 잘못되면 새 터미널에도 영향을 주지 않고 쉽게 되돌릴 수 있습니다.
Windows PowerShell에서는 현재 창에 다음과 같이 지정할 수 있습니다. 명령 프롬프트를 사용하는 경우와 PowerShell을 사용하는 경우의 환경 변수 설정 문법은 다르므로, 현재 사용하는 셸에 맞는 명령을 실행해야 합니다.
$env:HTTP_PROXY = "http://127.0.0.1:7890"
$env:HTTPS_PROXY = "http://127.0.0.1:7890"
$env:NO_PROXY = "localhost,127.0.0.1,::1"변수를 설정한 뒤에는 같은 터미널 창에서 Claude Code를 실행합니다. 데스크톱 앱이나 IDE를 먼저 열어 둔 다음 내부 터미널을 사용하는 경우, 그 앱이 시작될 때 환경 변수를 상속하지 않았을 수 있습니다. 셸에서 직접 실행했을 때는 되지만 IDE 통합 터미널에서만 안 된다면 IDE를 완전히 종료한 뒤 변수를 지정한 환경에서 다시 시작하거나, IDE가 제공하는 터미널 환경 설정을 확인하세요. 명령을 실행하는 터미널과 변수를 입력한 터미널이 같은 세션인지도 점검합니다.
Claude Code 실행 전 연결을 검증하는 순서
먼저 셸이 프록시 변수를 실제로 가지고 있는지 확인합니다. macOS·Linux에서는 env 또는 셸의 출력 명령으로 HTTP_PROXY와 HTTPS_PROXY 값을 살펴보고, PowerShell에서는 $env:HTTPS_PROXY를 출력할 수 있습니다. 값이 비어 있거나 포트가 Clash 설정과 다르면 애플리케이션을 재설치하기 전에 환경 변수부터 바로잡으세요. 변수에 인증 정보를 넣어야 하는 네트워크라면 터미널 기록, 스크립트, 공유 로그에 비밀 값이 남지 않도록 별도로 주의해야 합니다.
그다음 Clash 연결 로그를 열어 둔 상태에서 안전한 기본 연결 테스트를 진행합니다. 테스트 결과가 성공하더라도 그것만으로 Claude Code의 모든 API와 인증 요청이 정상이라는 뜻은 아닙니다. 반대로 테스트 요청이 Clash 로그에 나타나지 않으면 지정한 주소·포트가 잘못되었거나 터미널의 프록시 설정이 적용되지 않았을 수 있습니다. 연결이 로그에 표시되면 목적지 호스트, 사용된 정책, 연결 결과를 함께 메모하고 Claude Code에서 실패한 시점의 기록과 비교합니다.
진단을 재현할 때는 한 번에 변수 하나만 바꾸세요. 예를 들어 먼저 Clash의 로컬 포트와 코어 상태를 확인하고, 다음에 셸 환경 변수를 적용한 뒤, 마지막으로 같은 명령을 다시 실행합니다. 노드와 라우팅 규칙, 셸 설정을 동시에 바꾸면 어느 조치가 문제를 해결했는지 알기 어렵습니다. 기록에는 실행한 시간, 사용한 프로필, 셸 종류, 오류가 시작된 명령을 남기되 구독 URL이나 API 키, 인증 토큰은 포함하지 마세요.
자주 발생하는 연결 오류와 원인 좁히기
아래 표는 흔한 증상을 다음 점검 항목과 연결한 것입니다. 오류 문구는 Claude Code 버전과 네트워크 계층에 따라 달라질 수 있으므로, 문구 하나만으로 원인을 확정하지 말고 Clash 로그와 함께 판단하세요.
| 증상 | 우선 확인할 항목 | 다음 조치 |
|---|---|---|
| 요청이 시간 초과되거나 연결이 거부됨 | Clash 코어 상태, 로컬 포트 번호, 셸 변수의 주소 | 현재 설정에 표시된 포트로 변수를 수정하고 새 연결 로그를 확인 |
| 로그인은 되지만 대화 요청이 실패함 | API 요청의 로그 유무와 적용된 라우팅 정책 | 실제 로그의 목적지와 규칙 순서를 비교하고 해당 연결만 재검증 |
| 브라우저 인증은 열리지만 CLI로 돌아오지 않음 | 브라우저와 터미널의 프록시 경로, 로컬 콜백 처리 | 로그인 절차를 다시 진행하고 로컬호스트가 우회 목록에 있는지 확인 |
| 터미널에서는 되지만 IDE에서는 실패함 | IDE 실행 시점의 환경 변수 상속 여부 | IDE를 다시 실행하거나 통합 터미널의 환경 설정을 점검 |
| 프로필 갱신 뒤 갑자기 동작이 달라짐 | 활성 프로필, 정책 그룹, 최신 연결 로그 | 갱신 전후 설정 차이를 비교하고 필요한 규칙만 복구 |
연결이 잠깐 성공했다가 긴 응답 중 끊긴다면 단순한 속도 테스트만 반복하지 말고, 실패한 세션이 로그에 어떤 결과로 남는지 확인하세요. 무선 네트워크 변화, 절전, 다른 VPN이나 터널의 동시 실행, 보안 소프트웨어의 연결 검사도 장시간 요청에 영향을 줄 수 있습니다. 테스트할 때는 가능한 한 한 개의 프록시 경로만 활성화하고, 다른 터널을 잠시 중지해 원인을 분리합니다. 회사 장비라면 이러한 변경이 허용되는지 먼저 관리자에게 확인해야 합니다.
오류 해결 후에는 임시 설정을 정리합니다. 셸 변수만으로 테스트했다면 새 터미널을 열어 적용 범위를 확인하고, 영구 설정을 추가했다면 이후 필요하지 않을 때 제거하는 방법도 기록해 둡니다. 규칙을 수정했다면 원래 프로필을 백업하고 변경한 줄과 확인한 로그를 함께 남기세요. 이렇게 하면 구독 갱신이나 코어 업데이트 후 문제가 다시 나타나도 이전 상태와 비교해 빠르게 원인을 좁힐 수 있습니다.
재현 가능한 Claude Code 작업 환경 만들기
안정적인 사용의 핵심은 특정 노드 하나를 무작정 바꾸는 것이 아니라, 프로필·로컬 포트·셸 환경 변수·실제 라우팅 결과를 일관되게 확인하는 것입니다. 프로필이 바뀌면 로컬 포트와 정책 그룹을 다시 살피고, Claude Code를 실행하는 셸이 그 값을 상속하는지도 점검하세요. 여러 개발자가 같은 구성을 사용한다면 비밀 정보를 제외한 체크리스트와 오류 재현 절차를 공유하는 편이 좋습니다. 사용자별 API 인증 정보나 구독 주소를 공용 설정 파일에 넣지 않는 것도 기본 보안 수칙입니다.
GUI에서 시스템 프록시만 켜는 방식은 브라우저에는 충분해도 터미널 도구까지 자동으로 설정된다는 보장은 없습니다. 반대로 셸 환경 변수만 지정하면 다른 앱에는 적용되지 않을 수 있습니다. 두 방식의 차이를 이해하고, 연결 로그로 요청이 어느 정책을 탔는지 확인하면 Claude Code의 로그인 실패와 API 타임아웃을 더 정확히 분리할 수 있습니다. 일부 클라이언트는 메뉴 이름이나 기본 포트가 다르고, 오래된 빌드는 현재 코어 기능을 지원하지 않을 수 있으므로 화면과 버전에 맞춰 설정을 검토하세요.
수동으로 여러 파일을 고치거나 운영체제별 프록시 설정을 따로 추적하는 방식은 클라이언트 업데이트 때 설정 위치가 달라져 유지 관리가 번거로울 수 있습니다. Clash V.CORE는 프로필과 프록시 상태를 한곳에서 확인하며 이 글의 점검 절차를 이어가기 좋은 선택지입니다. 사용 중인 환경에 맞는 클라이언트를 비교해 보고 싶다면 다운로드 페이지에서 확인해 보세요.