Claude Code가 터미널에서 프록시를 필요로 하는 이유

Claude Code는 브라우저에서만 사용하는 채팅 서비스가 아니라, 터미널에서 현재 프로젝트의 파일을 읽고 명령을 실행하며 모델 API와 지속적으로 통신하는 개발 도구입니다. 로그인할 때는 인증 페이지와 계정 세션을 확인하고, 실제 작업을 시작하면 프롬프트·파일 문맥·도구 실행 결과를 여러 차례 주고받습니다. 따라서 브라우저에서 claude.ai가 열린다고 해서 터미널의 Claude Code 연결까지 자동으로 정상이라고 볼 수는 없습니다.

특히 회사망, 학교망, 해외 서버와의 지연이 큰 회선에서는 로그인 창은 열리지만 인증 완료 후 터미널로 돌아오지 않거나, 첫 번째 명령에서 connection timeout·fetch failed·socket hang up 같은 오류가 발생할 수 있습니다. 응답이 길어지는 작업에서는 연결이 끊기지 않고도 스트리밍이 중간에 멈추는 경우가 있습니다. 이때는 단순히 노드를 바꾸기보다 Claude Code 프로세스가 실제로 Clash Verge의 프록시를 사용하고 있는지, 필요한 도메인이 같은 정책 그룹을 타는지부터 확인해야 합니다.

터미널 앱은 브라우저와 다른 네트워크 경로를 사용할 수 있습니다. 브라우저는 시스템 프록시나 TUN 모드의 영향을 받지만, 셸에서 실행한 CLI는 HTTP_PROXY·HTTPS_PROXY·ALL_PROXY 환경 변수만 참고하거나 자체적인 인증 흐름을 사용할 수 있습니다. 반대로 Clash Verge의 시스템 프록시가 켜져 있어도 현재 터미널 세션이 예전 환경 변수를 기억하고 있으면 새 설정이 적용되지 않습니다. 이 차이를 이해하면 «Clash는 켜져 있는데 Claude Code만 실패한다»는 상황을 훨씬 빠르게 좁힐 수 있습니다.

먼저 기억할 원칙 프로필을 가져오는 단계, Clash Verge에서 프록시를 실행하는 단계, Claude Code 터미널에 프록시를 전달하는 단계는 서로 다릅니다. 세 단계가 모두 완료되어야 로그인과 API 스트리밍이 안정적으로 이어집니다.

Clash Verge에 프로필 가져오기

Clash Verge를 처음 설치했다면 먼저 사용할 구독 URL 또는 로컬 YAML 프로필을 준비합니다. 구독 URL은 서비스 제공자가 발급한 주소이며, 보통 계정 페이지에서 복사할 수 있습니다. 이 주소에는 인증 토큰이 포함되는 경우가 많으므로 공개 저장소, 이슈 게시판, 화면 공유에 그대로 노출하지 마세요. 링크가 유출되면 다른 사람이 사용량을 소비하거나 계정의 노드를 이용할 수 있습니다.

Clash Verge를 열고 프로필 또는 Profiles 화면으로 이동한 다음, 구독 URL 입력란에 주소를 붙여 넣습니다. 이름은 나중에 알아보기 쉽도록 예를 들어 Claude-Work 또는 2026-07-main처럼 정합니다. 가져오기가 완료되면 프로필 카드에 노드 수와 마지막 업데이트 시간이 표시됩니다. 카드가 생성되었는데 노드가 0개라면 URL 만료, 인증 오류, 제공자의 응답 형식 문제를 먼저 의심해야 하며, 이 상태에서 규칙만 수정해도 연결은 복구되지 않습니다.

프로필을 선택한 뒤 실제로 사용할 노드를 하나 정합니다. 처음부터 자동 선택 그룹만 믿으면 지연 측정 주소는 빠르지만 Claude API와의 장기 스트리밍에는 불안정한 노드가 선택될 수 있습니다. 우선 수동으로 비교적 안정적인 노드를 골라 로그인과 짧은 명령을 시험하고, 이후 url-test나 fallback 그룹으로 자동화를 추가하는 순서가 안전합니다. 노드 이름이 한글이나 특수문자를 포함해도 대부분 문제가 없지만, YAML을 직접 편집할 때는 따옴표와 들여쓰기를 보존해야 합니다.

구독 업데이트와 설정 덮어쓰기 제공자가 다시 내려준 YAML로 프로필을 갱신하면 직접 추가한 규칙이나 그룹이 사라질 수 있습니다. 사용자 오버라이드 기능을 지원하는 버전이라면 오버라이드에 분기 규칙을 두고, 그렇지 않다면 원본을 별도로 백업한 뒤 변경 내용을 기록해 두세요.

시스템 프록시와 터미널 환경 변수 설정

Clash Verge에서 프로필과 노드를 선택한 뒤에는 프록시 실행 스위치를 켭니다. 일반적인 데스크톱 환경에서는 System Proxy를 활성화하면 브라우저와 시스템 프록시를 따르는 애플리케이션이 Clash Verge로 연결됩니다. 이 방식은 설정이 간단하지만 모든 CLI가 시스템 프록시를 자동으로 따르는 것은 아닙니다. Claude Code를 실행하는 터미널에서 별도로 환경 변수를 지정하면 애플리케이션이 프록시를 무시하는 문제를 줄일 수 있습니다.

Clash Verge의 포트 화면에서 HTTP 또는 mixed 포트를 확인합니다. 예시로 mixed 포트가 7897이라면 macOS·Linux의 셸에서는 다음처럼 현재 세션에 적용할 수 있습니다. 실제 포트는 반드시 자신의 Clash Verge 화면에 표시된 값으로 바꾸세요.

export HTTP_PROXY=http://127.0.0.1:7897
export HTTPS_PROXY=http://127.0.0.1:7897
export ALL_PROXY=socks5://127.0.0.1:7897
claude

Windows PowerShell에서는 같은 목적의 명령이 다음과 같이 달라집니다. PowerShell 창을 새로 열었을 때마다 적용해야 하는 방식과, 프로필 파일에 넣어 영구 적용하는 방식은 구분해야 합니다. 공유 컴퓨터나 회사 장비에서는 영구 환경 변수에 토큰과 프록시 정보를 남기지 않는 편이 좋습니다.

$env:HTTP_PROXY="http://127.0.0.1:7897"
$env:HTTPS_PROXY="http://127.0.0.1:7897"
$env:ALL_PROXY="socks5://127.0.0.1:7897"
claude

환경 변수를 설정한 뒤에는 새 프로세스로 Claude Code를 실행해야 합니다. 이미 실행 중인 셸이나 백그라운드 프로세스는 이전 값을 유지할 수 있기 때문입니다. 또한 프록시 주소에 http://와 socks5://를 혼동하지 않아야 합니다. mixed 포트는 두 프로토콜을 모두 받을 수 있는 경우가 많지만, 제공하는 포트 종류는 클라이언트와 코어 설정에 따라 달라질 수 있습니다. 연결이 안 되면 포트가 열려 있는지, 해당 포트가 다른 프로그램에 점유되지 않았는지, 로컬 방화벽이 127.0.0.1 연결을 차단하지 않는지 점검합니다.

환경	우선 적용할 방법	확인할 문제
macOS·Linux 터미널	환경 변수와 System Proxy를 함께 확인	셸 설정 파일의 오래된 포트, 잘못된 프로토콜
Windows PowerShell	`$env:` 변수 설정 후 새 프로세스 실행	CMD와 PowerShell 문법 혼용, 포트 오타
VS Code 내장 터미널	VS Code 재시작 후 외부 터미널과 비교	IDE가 별도 환경 변수 또는 프록시 설정을 사용
Docker·원격 SSH	컨테이너·원격 호스트에서 별도 프록시 지정	`127.0.0.1`이 로컬 PC가 아닌 실행 환경을 가리킴

Claude Code 트래픽을 규칙으로 안정화하기

전역 프록시만 켜는 것보다 Claude 관련 도메인을 명시적인 정책 그룹에 연결하면 원인 추적이 쉬워집니다. 다만 특정 도메인 목록을 영원히 고정된 공식 목록처럼 생각해서는 안 됩니다. 인증 호스트, API 호스트, 업데이트 서버, 텔레메트리 경로는 클라이언트 버전과 운영 정책에 따라 바뀔 수 있습니다. 따라서 처음에는 연결 로그를 열어 Claude Code 실행 시 실제로 요청되는 호스트를 확인하고, 그 결과를 기준으로 규칙을 보완하세요.

일반적으로는 DOMAIN-SUFFIX로 서비스의 안정적인 상위 도메인을 묶고, 인증이나 결제처럼 직접 연결이 필요한 호스트는 별도 정책으로 나눕니다. 예시의 그룹 이름은 자신의 프로필에 이미 존재하는 그룹으로 바꿔야 합니다.

rules:
  - DOMAIN-SUFFIX,anthropic.com,Claude-Work
  - DOMAIN-SUFFIX,claude.ai,Claude-Work
  - DOMAIN-SUFFIX,console.anthropic.com,Claude-Work
  - MATCH,Final

위 규칙을 그대로 복사하는 것보다 중요한 것은 규칙 순서입니다. 앞쪽에 있는 광범위한 DIRECT 규칙이나 광고 차단 규칙이 먼저 적중하면 뒤의 Claude 규칙은 실행되지 않습니다. 반대로 지나치게 넓은 접미사를 사용하면 관련 없는 트래픽까지 같은 노드로 보내 개인정보와 속도 측면에서 불필요한 부담이 생깁니다. 필요한 호스트만 좁게 시작하고, 연결 로그에서 미적중 목적지가 확인될 때 한 줄씩 추가하는 방식이 좋습니다.

Clash Verge의 연결 또는 로그 화면에서는 목적지 호스트, 포트, 선택된策略 그룹, 최종 노드를 확인할 수 있습니다. Claude Code에서 짧은 질문을 보낸 뒤 해당 연결이 Claude-Work에 적중했는지 확인하세요. 인증은 성공했지만 응답 스트리밍만 끊긴다면 같은 호스트의 연결이 여러 개 열리는지, 노드가 장시간 연결을 유지하는지, DNS 결과가 지역별로 달라지는지 살펴봅니다. 403이나 401처럼 즉시 반환되는 오류는 프록시 규칙보다 계정 권한, 구독 상태, 서비스 정책을 먼저 확인해야 합니다.

테스트 순서 먼저 브라우저에서 계정 페이지를 확인하고, 다음으로 터미널의 짧은 Claude Code 명령을 실행한 뒤, 마지막으로 여러 파일을 읽는 긴 작업을 시험하세요. 단계별로 연결 로그를 비교하면 노드 문제와 환경 변수 문제를 구분하기 쉽습니다.

로그인 실패와 스트리밍 중단을 진단하는 방법

로그인 페이지가 아예 열리지 않으면 Clash Verge의 실행 상태, 선택된 프로필, 로컬 포트부터 확인합니다. 페이지는 열리지만 인증 완료 후 CLI가 멈추면 브라우저와 터미널이 서로 다른 프록시 출구를 사용하는지 봅니다. 브라우저는 프록시를 타고 터미널은 DIRECT로 나가면 세션 교환이나 콜백 단계에서 실패할 수 있습니다. 반대로 터미널은 프록시를 타지만 인증 도메인만 DIRECT라면 로그인 버튼 이후에만 오류가 발생합니다.

command not found는 네트워크 문제가 아니라 Claude Code 설치 경로와 셸의 PATH 문제입니다. fetch failed와 TLS 오류는 프록시 주소·DNS·노드 인증서를 함께 확인하고, ETIMEDOUT은 연결 로그의 목적지와 지연 시간을 비교합니다. 긴 응답이 중간에 멈추는 경우에는 노드를 바꿔 단순 비교하되, 매번 규칙 전체를 다시 작성하지 말고 동일한 프로필에서 테스트해야 결과가 의미 있습니다.

기본 터미널 프록시 도구만 사용하는 방식은 빠르게 시작할 수 있지만, 앱마다 환경 변수를 따로 관리해야 하고 어떤 호스트가 DIRECT로 빠졌는지 한눈에 보기 어렵습니다. 일부 GUI 클라이언트는 시스템 프록시 토글은 편리하지만 규칙 편집과 연결 로그가 제한적이어서 장시간 API 스트리밍 문제를 조사할 때 답답할 수 있습니다. Clash Verge는 프로필 가져오기, 정책 그룹 선택, 규칙 확인, 연결 로그를 한 화면 흐름으로 이어갈 수 있고, 필요하면 터미널 환경 변수와 TUN 모드를 용도에 맞게 조합할 수 있다는 점이 차별점입니다.

다만 Clash Verge도 모든 문제를 자동으로 해결하지는 않습니다. 구독 서버가 만료되었거나 Anthropic 계정에 권한이 없거나, 원격 SSH 환경에서 127.0.0.1을 잘못 지정하면 어떤 클라이언트를 사용해도 실패합니다. 이 글의 설정을 적용한 뒤에도 오류가 남는다면 프로필 유효성, 실제 실행 위치, 연결 로그의 matched rule을 순서대로 확인하세요. 필요한 트래픽만 안정적인 그룹으로 보내는 구조가 잡혔다면 이제 Claude Code를 매번 수동으로 재설정하지 않고도 편안하게 사용할 수 있으므로, 자신의 운영체제에 맞는 Clash 클라이언트를 준비해 다운로드 단계로 넘어가면 됩니다.

→ Clash 무료 다운로드, Claude Code와 터미널 환경에 맞는 클라이언트를 설치하고 안정적인 프록시 연결을 시작해 보세요.