Claude Code 터미널에서 반복되는 타임아웃과 ‘노드만 나쁘다’ 착시

2026년에는 에디터 안에서 바로 돌리는 터미널 CLI 계열 코딩 에이전트가 주류로 자리 잡았고, 그중 Claude Code는 리포지토리 단위 컨텍스트와 프롬프트 루프를 묶어 쓰기 쉬워 선택되는 경우가 많습니다. 사용자는 브라우저에서 동일 공급자 문서를 빠르게 읽은 뒤 같은 회선에서 CLI만 재현해 보곤 하는데, 웹은 멀쩡한데 CLI만 분 단위로 멈추거나 스트리밍 중간에 API 타임아웃 메시지가 남는 패턴이 반복되면 무의식중에 업스트림 노드부터 갈아탑니다.

그러나 실제 현장에서는 「전 노드 불량」보다 Anthropic API 엔드포인트 줄과 구성·관측용 CDN 또는 서드파티 호스트, 그리고 브라우저 기반 OAuth 교환 줄이 서로 다른 Clash 정책 이름으로 찍히는 경우가 흔합니다. 예를 들어 api.anthropic.com만 프록시 그룹으로 보내고 정작 토큰 교환이나 기능 플래그 번들이 붙은 다른 접미는 DIRECT에 남아 있으면, TLS는 통과한 것처럼 보이다 애플리케이션 레이어에서만 길게 대기하는 증상이 남습니다. 한국·일본·미국 간 회선을 오가는 개발자일수록 레이턴시 편차가 커져 같은 YAML이라도 체감이 극단적으로 달라지기도 합니다.

그래서 첫 디버깅 화면부터 속도 테스트 숫자가 아니라 Clash 라이브 연결 로그를 펼치라고 말합니다. 공통 틀은 연결 로그·TLS 타임아웃과 규칙 매칭 모범을 옆에 두면 분기 속도가 빨라집니다. 같은 증상이라도 IDE 내장 터미널과 외부 터미널 앱은 환경 변수 상속이 달라 재현 경로가 갈라지므로, 한 번 관측했다고 끝내지 말고 세션 종류별로 로그를 한 줄씩 비교하는 편이 안전합니다.

ℹ 첫 단추는 라이브 연결: 실패 직후 필터에 anthropic, claude, claude-code, 관측된 서브도메인 문자열을 넣어 보세요. 한 줄이라도 정책 문자열이 다르면, 노드를 바꾸기 전에 도메인 분류 한두 줄이 답인 경우가 많습니다.

실제로 두드리는 이름 공간: Anthropic API·claude·CDN·OAuth

아래 목록은 출발점용 체크리스트입니다. 릴리스·조직 SSO·기능 플래그에 따라 하위 호스트는 바뀔 수 있으므로, 팀은 실제 로그 문자열과 날짜를 YAML 주석에 남기는 습관을 들이는 편이 안전합니다. 웹 중심 이름 공간을 이미 Claude·Anthropic 웹·API 분류 글로 정리했다면 이번에는 터미널 프로세스 기준으로 한 번 더 훑습니다.

브라우저 중심 시나리오와 달리 터미널은 HTTP_PROXY 계열 변수·셸 프로파일·IDE 통합 터미널의 상속 차이까지 겹칩니다. 그래서 «같은 노드인데 왜 브라우저만 된다»는 말이 자주 나옵니다.

CLAUDE_CODE_CLI 정책 그룹과 웹용 규칙의 차이

한 덩어리로 묶는 설계

운영 난이도 대비 효과가 좋은 형태는 CLAUDE_CODE_CLI 그룹을 하나 두고, 라이브에서 관측한 Anthropic·claude 관련 접미와 해당 세션에서 실제로 열린 CDN 줄을 우선 같은 정책으로 보내는 것입니다. 이때 DOMAIN-SUFFIX,.com처럼 지나치게 넓은 줄을 붙이면 업무 트래픽까지 한 노드에 몰려 역효과가 나므로 주의합니다.

API와 CDN을 쪼개는 설계

CLAUDE_CODE_API와 CLAUDE_CODE_CDN처럼 나누면 원인 추적에는 유리하지만, 서로 다른 레이턴시 등급의 노드를 붙이면 스트리밍·장시간 세션에서 경로가 교차하며 새로운 끊김이 생길 수 있습니다. 분리한다면 같은 리전 또는 같은 채널 집합을 운영 문서로 고정하는 편이 안전합니다. 규칙 순서가 복잡해지면 GeoIP·우선순위 글과 diff를 함께 봅니다.

macOS에서 시스템 확장·레거시 프록시 잔상이 겹치면 증상만 보고는 한참 헤맬 수 있습니다. 같은 시기에 고생 중이면 macOS TUN·프록시 충돌 문서를 병렬로 열어두세요.

팀에서 Codex CLI·Gemini CLI·OpenCode CLI를 병행한다면 프로필 안에서 섹션 주석으로 공급자별 블록을 시각적으로 나누는 것이 중요합니다. 그렇지 않으면 RULE-SET 자동 갱신 때 덮어쓰기 사고가 납니다.

OAuth 브라우저 탭은 되는데 터미널만 비는 경우

브라우저에서 성공 배너를 봤다고 CLI까지 끝난 것은 아닙니다. 마지막 교환 패킷이 여전히 차단되거나 다른 출구로 나가면 터미널은 조용히 재시도 루프에 들어갑니다. 회사망에서는 HTTPS 인터셉트 없이도 정책 라벨만으로 특정 접미가 느려지거나 HTML 응답이 바뀌는 일이 있어, 사람 눈에는 단순 터미널 CLI 버그처럼 보입니다.

따라서 OAuth 관련 호스트도 Anthropic API 블록과 같은 지연 프로필 아래 두거나, 최소한 라이브 로그에서 정책 문자열을 맞춘 뒤에야 로그인을 다시 시도하는 순서를 지키는 편이 낫습니다. 수동으로 HTTPS_PROXY를 넣었다면 자식 프로세스가 변수를 물려받지 못하는 빌드도 있으므로, 재현 순서를 로그 스크린샷 수준으로 남기면 이후 분석이 빨라집니다.

예시 YAML 조각과 운영 시 수정 포인트

아래는 교육용 예시입니다. 프로덕션에 그대로 복사하지 마세요. 실제 수동 줄은 라이브 연결 문자열과 공식 문서의 호스트 목록을 따라가고, RULE-SET이 수동 DOMAIN을 가리지 않는지 패치 노트처럼 확인합니다. 관측되지 않은 서드파티 접미는 주석으로 비워 두었다가 로그가 채워지면 붙입니다.

Illustrative YAML fragment

rules:
  - DOMAIN-SUFFIX,anthropic.com,CLAUDE_CODE_CLI
  - DOMAIN-SUFFIX,claude.ai,CLAUDE_CODE_CLI
  # Add CDN or telemetry suffixes observed in live logs:
  # - DOMAIN-SUFFIX,example-cdn.net,CLAUDE_CODE_CLI
  - GEOIP,KR,DIRECT
  - MATCH,DIRECT

GEOIP 줄과 최종 MATCH는 조직·회선에 맞게 조정합니다. 구독 품질·갱신 URL 자체가 병목이 되는 경우는 구독 유지 가이드와 함께 봅니다.

TUN, Meta DNS, 터미널 환경 변수

터미널이 운영체제의 시스템 프록시 레이어를 건너뛰면 TUN으로 로컬 소켓 패스 전체를 한 라우팅 스택 아래 둘 때가 많습니다. 그다음은 DNS입니다. 외부 DoH가 빠르게 응답해 보여도 규칙 적중 순서만 틀어지면 같은 엔드포인트라도 다른 IP로 붙고 줄이 또 갈립니다. 가능하면 단말 안의 권위 경로를 한 갈래로 정리합니다.

Meta DNS에서는 fallback과 fake-ip 필터 순서가 중요합니다. 구체 패턴은 nameserver·fallback·fake-ip 문서를 적용한 뒤, 터미널 앱을 완전히 종료했다가 다시 열어 상속을 초기화합니다.

Clash를 종료했는데도 시스템 프록시 잔상이 남으면 CLI 문제와 비슷한 착시가 납니다. 종료 후 네트워크 복구 절차를 함께 확인하세요.

검증 순서와 체크포인트

아래 순서를 플레이북처럼 고정하면 다른 앱과의 교차 영향을 줄이면서 빠르게 좁힐 수 있습니다.

  1. 설치·업데이트 단계부터 연결 로그를 켭니다. 패키지 레이어에서 막히면 사용자 공간 규칙 이전에 별도 카테고리가 필요합니다.
  2. 실패 직후 라이브 목록에서 Anthropic API·CDN·OAuth 줄의 정책명을 나란히 비교합니다. 하나라도 다르면 DOMAIN 줄을 보강하고 RULE-SET 상단 순서를 점검합니다.
  3. OAuth 브라우저 탭이 조직 차단 페이지로 바뀌지 않았는지 확인한 뒤 CLI를 재시작합니다.
  4. RULE-SET을 자동 갱신한 직후에만 깨졌다면 차단 카테고리가 새로운 접미를 삼켰는지 외부 diff로 확인합니다.
  5. 노드 교체로 패턴이 그대로면 순수 회선 문제인지 TLS 경고인지 TLS 로그부터 다시 읽습니다.
  6. GUI 편집은 부담스럽지만 터미널 디버깅은 가볍다고 느낀다면, 사용 중인 클라이언트가 라이브 뷰를 제대로 내주는지 클라이언트 선택 문서와 대조합니다.

자주 묻는 질문

웹 Claude 규칙을 그대로 썼는데 CLI만 계속 타임아웃입니다.

웹 세션과 CLI 세션은 호스트 집합이 완전히 같지 않은 경우가 많습니다. 특히 번들·관측·업데이트 축이 추가되면 브라우저 규칙만으로는 부족합니다. 라이브 로그에서 CLI 프로세스가 연 호스트를 한 줄씩 채워 넣으세요.

RULE-SET에 이미 Anthropic이 포함된다고 적혀 있는데 수동 DOMAIN이 필요할까요?

주석과 실제 패널 줄은 다를 수 있습니다. GeoIP나 광범위한 차단 규칙에 밀려 다른 정책으로 찍히면 한 줄이라도 어긋납니다. 라이브 문자열이 다르면 수동 DOMAIN을 보강하는 편이 안전합니다.

HTTP/2나 스트리밍 경고가 로그에 반복됩니다. 무시해도 되나요?

중간 프록시가 협상만 방해하면 업로드·다운로드 비대칭 구간에서만 지연이 커질 수 있습니다. 반복되면 노드나 스니핑 관련 옵션을 검토하되, 조직 정책으로 금지된 설정은 건드리지 마세요.

준수와 한계

⚠ 준수 알림: 현지 법령, 서비스 약관, 고용·학내 정책을 따르세요. 본 글은 합법망에서의 라우팅 위생을 다루는 기술 자료이며, 통제 회피를 돕는 내용은 포함하지 않습니다.

Zero Trust 장비에서는 사용자가 규칙을 아무리 정교하게 써도 인증 교환 단계에서 아예 거절되는 경우가 많습니다. 이때는 IT 승인 없이 우회를 시도하기보다, 정책상 불가능한 케이스로 분류하고 공식 경로를 밟는 편이 안전합니다.

맺음말

Claude Code의 API 타임아웃은 단일 장애라기보다 Anthropic API·제품 호스트·CDN·OAuth 줄이 서로 다른 출구를 타거나 DNS와 TCP 경로만 엇나가며 생기는 경우가 적지 않습니다. Clash에서 이를 줄이려면 이름 공간마다 명시적인 도메인 분류와 짧은 주기의 규칙 세트 점검 루틴이 필요하고, 웹용 목록과 터미널용 목록을 문서적으로 분리해 두는 편이 혼선을 줄입니다.

원클릭형 상용 VPN 일부는 애플리케이션별 호스트를 세밀하게 보여 주는 라이브 뷰가 부족해 증상이 길어지면 시간만 소모되는 경우가 있습니다. 반면 한 패널에서 RULE 순서·TUN·연결 로그를 함께 다룰 수 있는 Clash Meta 계열은 터미널 도구와 맞물릴 때 디버깅 루프를 짧게 만드는 데 유리합니다. Clash V.CORE는 멀티 공급자·멀티 스트림 시나리오를 전제로 프로필과 UI 신호를 정리해 두었기 때문에 Claude Code처럼 조용히 멈추는 CLI와도 확인 단계가 덜 헷갈립니다.

→ Clash를 무료로 다운로드해서 이번에 정리한 Anthropic·CDN·OAuth 줄을 라이브 연결 숫자로 다시 교차 검증해 보세요.