Claude Code 중국 사용에서 먼저 이해할 연결 구조

Claude Code는 브라우저에서만 사용하는 채팅 서비스가 아니라, 터미널 프로세스가 인증 서버와 모델 API에 직접 연결하는 AI 코딩 도구입니다. 따라서 웹 브라우저에서 Claude 페이지가 열리는 것만으로는 터미널 로그인이나 코드 생성 요청까지 정상이라고 판단하기 어렵습니다. 브라우저는 시스템 프록시를 자동으로 상속할 수 있지만, 터미널은 셸 환경 변수, 운영체제의 시스템 프록시, 실행 중인 Clash 코어 중 어느 경로를 사용할지 서로 다르게 동작할 수 있습니다.

중국 네트워크에서 Claude Code를 사용할 때는 대체로 세 가지 연결을 따로 생각해야 합니다. 첫 번째는 계정 로그인과 인증 토큰 발급이고, 두 번째는 Claude Code가 명령을 처리하는 모델 API 통신이며, 세 번째는 업데이트 확인이나 패키지 다운로드처럼 부가적으로 발생하는 HTTPS 요청입니다. 로그인 화면은 열리는데 터미널에서 인증이 끝나지 않거나, 인증은 성공했지만 프롬프트를 보낼 때 타임아웃이 발생한다면 이 세 흐름 중 하나만 다른 경로를 타고 있을 가능성이 큽니다.

Clash는 모든 트래픽을 무조건 같은 노드로 보내는 도구가 아니라, 요청의 도메인과 규칙에 따라 DIRECT 또는 프록시 정책 그룹을 선택하는 라우터입니다. 그러므로 “Clash를 켰다”는 사실보다 시스템 프록시가 실제로 활성화되었는지, Claude Code가 그 포트를 사용하는지, 관련 연결이 로그에서 어떤 정책으로 매칭되는지가 더 중요합니다. 회사나 학교 네트워크에서는 별도의 프록시 사용 제한이 있을 수 있으므로, 반드시 허용된 계정과 네트워크에서 합법적인 범위로 테스트해야 합니다.

ℹ 핵심 원칙: 브라우저 로그인 성공과 Claude Code API 성공은 별개의 테스트입니다. 로그인 직후 모델 요청을 실행하고, 같은 시간대의 Clash 연결 로그에서 인증·API·업데이트 요청이 모두 의도한 정책 그룹을 사용하는지 확인하세요.

중국 사용자를 위한 Clash 클라이언트와 준비 항목

Windows에서는 Clash Verge Rev 또는 Mihomo 코어를 포함한 유지 관리형 클라이언트를 선택하는 편이 좋습니다. macOS에서는 ClashX 계열이나 Clash Verge 계열을 사용할 수 있고, Android에서는 시스템 VPN 권한을 제공하는 Clash 클라이언트가 필요합니다. 화면의 메뉴 이름은 클라이언트마다 다르지만, 이 글에서 확인할 핵심 항목은 동일합니다. 즉, 활성 프로필, 실행 중인 코어, 혼합 포트, 시스템 프록시, 현재 선택된 정책 그룹입니다.

시작하기 전에 프록시 제공자가 발급한 구독 URL과 계정 정보를 준비합니다. 구독 주소에는 개인 식별 정보나 사용량 인증 값이 포함될 수 있으므로 공개 채팅이나 화면 녹화에 그대로 노출하지 마세요. 이미 다른 VPN, WireGuard, 회사용 보안 터널, 예전 Clash 포크가 실행 중이라면 첫 설정 동안에는 하나만 남기는 것이 좋습니다. 여러 프로그램이 동시에 같은 포트나 가상 네트워크 인터페이스를 사용하면 연결은 살아 있지만 실제 경로가 예상과 달라질 수 있습니다.

Claude Code를 중국에서 사용하는 목적이 단순한 문서 조회인지, 실제 프로젝트 파일을 읽고 코드를 수정하는 에이전트 작업인지도 구분해야 합니다. 후자는 한 번의 요청이 오래 유지되고 응답 스트리밍이 이어질 수 있으므로 순간적인 핑보다 장시간 연결 안정성과 노드의 지속성이 중요합니다. 속도가 가장 빠른 노드보다 일정한 지연과 안정적인 TLS 연결을 제공하는 노드가 실제 코딩 세션에는 더 적합할 때가 많습니다.

구독 가져오기, 노드 선택, 시스템 프록시 적용

Clash 클라이언트의 Profiles, 프로필, 또는 Remote 메뉴에서 새 구성을 추가하고 제공자의 구독 URL을 붙여 넣습니다. 클라이언트에 따라 “가져오기”, “추가”, “업데이트”라는 표현이 다를 수 있지만, 완료 후 프로필 크기와 노드 목록이 표시되는지가 중요한 성공 신호입니다. 목록이 비어 있다면 바로 노드를 바꾸기보다 URL 앞뒤의 공백, HTTPS 인증서, 구독 만료, DNS 응답, HTTP 상태 코드를 차례로 확인하세요.

프로필을 활성화한 뒤 Proxies 또는 정책 그룹 화면으로 이동합니다. 처음에는 자동 선택 그룹보다 직접 고르는 select 그룹에서 안정적인 노드 하나를 선택하는 것이 문제를 좁히기 쉽습니다. “자동”, “규칙에 따름”, “Proxy”처럼 표시되는 그룹은 내부에 여러 노드와 다른 정책이 연결되어 있을 수 있습니다. Claude Code 첫 로그인에서는 노드 자동 교체로 인해 인증 세션의 출구가 바뀌지 않도록 하나의 노드를 고정하고, 정상 작동을 확인한 뒤 자동 선택을 시험하는 순서가 안전합니다.

다음으로 Clash의 System Proxy 또는 시스템 프록시를 켭니다. 이 설정은 브라우저와 일부 데스크톱 프로그램에 영향을 주지만 모든 터미널 프로그램이 자동으로 따르는 것은 아닙니다. 셸에서 사용하는 프록시 변수가 별도로 설정되어 있다면 이전 VPN이나 회사 프록시의 값이 남아 있지 않은지 확인해야 합니다. Windows PowerShell, macOS Terminal, Linux 셸, IDE 통합 터미널은 시작 시점에 서로 다른 환경을 읽을 수 있으므로, 설정을 바꾼 뒤에는 터미널을 완전히 닫고 새로 열어 테스트하세요.

터미널 환경 변수와 mixed-port 확인

Claude Code가 시스템 프록시를 상속하지 않는 환경이라면 HTTP 계열과 HTTPS 계열 요청이 사용할 프록시 주소를 셸에 명시해야 할 수 있습니다. 여기서 실제 포트는 사용 중인 Clash 설정에 맞춰야 하며, 예시의 7890을 무조건 복사하면 안 됩니다. mixed-port가 7897이나 다른 값으로 설정되어 있다면 그 번호를 사용합니다. SOCKS만 열려 있는 포트와 HTTP 요청을 받는 포트를 혼동하면 로그인 페이지는 열려도 API 요청이 실패할 수 있습니다. 

export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
export ALL_PROXY=http://127.0.0.1:7890

위 변수는 현재 셸 세션에만 적용되는 예시입니다. 영구 저장을 원한다면 사용하는 셸의 프로필 파일에 넣되, 회사 네트워크나 다른 프로젝트의 패키지 설치에 예기치 않은 영향을 줄 수 있으므로 먼저 일회성으로 테스트하세요. 사용하지 않을 때는 변수를 제거하거나 새 셸에서 실행하는 편이 좋습니다. 또한 일부 Node 기반 CLI는 대문자 변수만 읽거나, 소문자 변수만 우선하는 경우가 있으므로 연결 로그와 프로세스 문서를 함께 확인해야 합니다.

Claude Code 로그인과 실제 API 요청 테스트

모든 설정을 마친 뒤 새 터미널을 열고 Claude Code의 공식 로그인 명령을 실행합니다. 명령어는 설치된 버전과 배포 방식에 따라 달라질 수 있으므로, 임의의 블로그 명령보다 공식 문서나 프로그램의 도움말에 표시되는 명령을 기준으로 사용하세요. 브라우저 인증 창이 열리면 계정 로그인이 끝날 때까지 창을 닫지 말고, 터미널에 성공 메시지나 인증 완료 안내가 돌아오는지 확인합니다. 브라우저가 열렸다는 사실만으로는 로컬 콜백이나 토큰 교환이 완료되었다고 볼 수 없습니다.

로그인 직후에는 작은 프로젝트에서 짧은 요청을 먼저 보냅니다. 예를 들어 현재 폴더의 파일 목록을 설명하게 하거나, 테스트 파일의 간단한 함수 동작을 요약하게 하면 모델 연결과 로컬 파일 권한을 함께 확인할 수 있습니다. 처음부터 대규모 저장소 분석이나 긴 코드 생성을 요청하면 API 문제가 아니라 파일 검색 시간, 셸 권한, 토큰 한도, 로컬 CPU 사용량이 섞여 원인을 파악하기 어려워집니다.

  1. 인증 테스트: 로그인 명령을 실행하고 브라우저 인증 뒤 터미널 세션이 정상적으로 돌아오는지 확인합니다.
  2. 짧은 API 테스트: 작은 프로젝트에서 한두 문장으로 답할 수 있는 요청을 보냅니다.
  3. 스트리밍 테스트: 짧은 코드 설명을 요청해 응답이 중간에 끊기지 않는지 확인합니다.
  4. 도구 호출 테스트: 파일 읽기나 테스트 실행처럼 로컬 권한이 필요한 작업을 한 번만 수행합니다.
  5. 장시간 테스트: 정상 확인 뒤에만 여러 파일을 분석하고, 연결 로그에서 재시도와 정책 변경을 관찰합니다.

실패 직후 Clash의 Connections 또는 Logs 화면을 열어 anthropic, claude, 인증 관련 호스트, 업데이트 호스트를 검색합니다. 로그에 도메인이 보이지 않는다면 CLI가 프록시를 전혀 사용하지 않거나, 요청이 다른 로컬 네트워크 계층에서 실패했을 수 있습니다. 도메인은 보이지만 정책이 DIRECT라면 규칙 또는 환경 변수 문제이고, 프록시 정책으로 표시되지만 연결이 오래 멈춘다면 선택한 노드, TLS 지연, 서버 측 제한을 순서대로 비교합니다.

⚠ 주의: 토큰, API 키, 구독 URL, 전체 연결 로그에는 계정 정보가 포함될 수 있습니다. 오류를 공유할 때는 인증 헤더와 개인 도메인을 가리고, 무작정 API 키를 설정 파일에 저장하지 마세요.

타임아웃과 연결 끊김을 단계별로 고치는 방법

로그인 화면 자체가 열리지 않으면 먼저 브라우저와 터미널을 분리해서 검사합니다. 브라우저의 시크릿 창에서 로그인 주소가 열리는지 확인하고, 동시에 Clash 로그에 같은 요청이 기록되는지 봅니다. 브라우저만 성공하면 터미널의 프록시 상속을 의심하고, 둘 다 실패하면 활성 노드와 규칙 그룹, DNS, 제공자 상태를 점검합니다. 브라우저와 터미널이 서로 다른 노드를 선택하도록 두면 테스트 결과가 계속 흔들리므로 처음에는 같은 출구를 고정하세요.

API 요청이 시작되지만 중간에 끊기는 경우에는 노드의 순간 속도보다 스트리밍 연결 유지 능력을 확인해야 합니다. 자동 URL 테스트 그룹이 짧은 프로브 결과만 보고 노드를 바꾸면, 진행 중인 Claude Code 세션의 출구가 바뀌거나 새 연결이 다른 지역으로 이동할 수 있습니다. 장시간 작업에서는 안정적인 노드를 수동 선택하고, 노드가 불안정할 때 세션을 종료한 뒤 다른 노드로 바꾸는 방식이 예측 가능합니다.

규칙을 추가할 때는 처음부터 넓은 도메인 접미를 무리하게 프록시로 보내지 않는 것이 좋습니다. 실제 로그에서 확인한 필요한 호스트를 좁게 기록하고, 일반적인 중국 내 업무 사이트나 사내 주소가 함께 프록시로 들어가지 않는지 확인합니다. 규칙 순서에서 더 넓은 DOMAIN-SUFFIX가 위에 있으면 아래의 특정 규칙이 실행되지 않을 수 있으므로, 수정 후에는 연결 로그의 최종 정책을 반드시 확인하세요. 설정 파일을 직접 편집한다면 구독 갱신으로 로컬 변경이 덮어써지지 않는지도 함께 관리해야 합니다.

Claude Code 연결을 안정화하는 목적이라면 단순히 노드 수를 늘리는 것보다 “로그인·API·스트리밍을 같은 의도로 라우팅하고, 터미널 환경 변수와 Clash 시스템 프록시의 충돌을 제거하는 것”이 효과적입니다. 다른 일부 프록시 앱은 구독 가져오기와 시스템 프록시 전환은 간단하지만, 정책 그룹의 실제 매칭 로그나 Mihomo 규칙을 세밀하게 확인하기 어렵고 장시간 세션의 원인 분석도 제한적일 수 있습니다. Clash V.CORE는 프로필과 노드 선택, mixed-port, 연결 로그, 규칙 기반 라우팅을 한 흐름에서 점검할 수 있어 중국에서 Claude Code를 사용하는 개발자가 로그인 실패와 API 타임아웃을 분리해 진단하기 좋습니다. 위 절차를 반복해서 사용할 계획이라면 공식 다운로드 페이지에서 Clash V.CORE를 받아 자신의 운영체제에 맞는 클라이언트와 코어로 구성해 보세요.