📖 튜토리얼 ⏱ 약 20분 분량

Claude Code CLI가 계속 타임아웃? 2026 Anthropic CLI·도메인 분류와 Clash DNS로 터미널 실측 나누기

Claude 웹이나 IDE 플러그인은 되는데, 명령줄의 Claude Code CLI(또는 Anthropic 계열 CLI)만 API에 붙다 끊기거나 핸드셰이크가 길게 남는 증상은 2026년에도 자주 검색됩니다. 원인은 「노드 하나가 전부 나쁘다」보다 api.anthropic.com류 호스트가 규칙에서 빠졌거나, DNS가 브라우저와 터미널에서 서로 다른 경로로 풀리는 경우가 많습니다. 이 글은 Claude 웹·챗 전용 글과 검색 의도를 나누고, 개발용 CLI 관점에서 Clash·Mihomo 분류와 fake-ip·DoH·TUN을 한 세트로 점검하는 한국어 순서입니다. 같은 패턴의 Gemini CLI 실측은 Gemini CLI·Clash DNS 글과 짝을 맞추면 터미널 레이어망이 거의 같다는 걸 빨리 확인할 수 있습니다.

① 웹·IDE와 Claude Code CLI가 Clash 규칙에서 왜 갈라지는가

브라우저 세션은 탭 하나만 봐도 수십 개 호스트가 동시에 붙습니다. Claude 관련 제품도 웹·앱·에디터 각각이 claude.ai, console.anthropic.com, CDN·계정 줄을 번갈아 부릅니다. 반면 Claude Code CLI처럼 터미널에서 도는 바이너리는 상대적으로 REST·스트리밍 API 중심으로 api.anthropic.com 계열 비중이 큽니다. 첫 블록이 막히면 뒤 단계까지 안 가서 사용자 입장에서는 「전부 타임아웃」처럼 보일 수 있습니다.

  • API 본류: 모델 호출·스트림이 api.anthropic.com으로 모이는 패턴이 흔합니다. 빌드나 기능 플래그 때문에 statsig.anthropic.com 같은 보조 호스트가 따라오기도 합니다.
  • 계정·콘솔: 키 발급·쿼터 확인을 브라우저와 같이 쓰는 흐름이라면 console.anthropic.com·anthropic.com 하위 몇 줄이 같은 세션에 섞입니다.
  • 터미널만의 함정: macOS·Windows·Linux 모두 시스템 프록시를 터미널 셸·Go/Rust CLI가 무시하는 사례가 흔합니다. Rule 모드만 켠 상태와 TUN·mixed-port를 연 상태에서 증상이 갈리는지 비교하는 게 첫 낫입니다.

이 차이를 알면 “Clash 분명 켜 뒀는데 왜 Claude Code만 안 되지” 하는 체감이 설명됩니다. 에디터 통합 프록시는 따로 타는데 순수 터미널은 DIRECT로 새어 같은 ISP 경로에서 지연만 길어지는 그림도 자주 나옵니다.

② 규칙 후보: Anthropic API 중심의 최소 세트

호스트 이름은 서비스 업데이트로 늘거나 바뀔 수 있으므로 아래 목록은 「규칙 후보」이며, 반드시 실패 직후 Clash 로그로 교차 검증해야 합니다. 웹 전용 패턴만 있고 API 줄이 빠져 있으면 브라우저는 잘 되고 CLI만 막히는 재현이 그대로 남습니다.

  • API 1차: DOMAIN-SUFFIX,api.anthropic.com,PROXY처럼 가장 좁게 시작합니다.
  • 확장: 로그에 반복되는 다른 *.anthropic.com가 보이면 그때 DOMAIN-SUFFIX,anthropic.com,PROXY까지 넓힙니다. 다만 anthropic.com 전체를 무조건 우회에 넣으면 문서·브랜드 사이트까지 같은 출구로 가므로 업무 패턴과 충돌할 수 있습니다.
  • 보조·텔레메트리: 일부 빌드는 statsig류 호스트가 간헐적으로 붙습니다. 로그 증거가 있을 때만 줄을 추가합니다.
  • OAuth와 섞이지 않는 경우: Anthropic 쪽 CLI는 종종 API 키만으로 끝나지만, 조직 SSO·브라우저 연계가 섞이면 accounts.google.com 같은 외연 호스트가 동시에 필요할 수도 있습니다. 그때는 Gemini CLI 글의 OAuth 세트와 교차해 보세요.
팁: 실패 세션 안에서만 로그를 자르세요. 성공 직후의 긴 로그에 섞이면 「어느 요청이 마지막으로 터졌는지」가 흐려집니다. 시간 스탬프를 기준으로 한 블록만 저장하는 습관이 재현 속도를 올립니다.

③ 복붙용 YAML 개념 스케치: Claude Code CLI 우선

아래 블록은 문법 예시입니다. PROXY 자리에는 본인 프로필의 프록시 그룹 이름을 넣어야 하며, 국내로 반드시 DIRECT해야 하는 동일 서픽스가 있다면 그 줄을 더 위에서 예외 처리합니다. 규칙 순서 문법이 낯설다면 사용자 정의 규칙 튜토리얼을 먼저 맞추는 걸 권합니다.

# rules excerpt — Claude Code / Anthropic API oriented; rename PROXY
rules:
  - DOMAIN-SUFFIX,api.anthropic.com,PROXY
  - DOMAIN-SUFFIX,console.anthropic.com,PROXY
  - DOMAIN-SUFFIX,claude.ai,PROXY
  # widen only when logs show other *.anthropic.com repeatedly
  - DOMAIN-SUFFIX,anthropic.com,PROXY
  - MATCH,DIRECT

맨 아래를 MATCH,DIRECT로 두는 패턴은 국내 업무·사내 호스트를 프록시에서 빼려 할 때 흔합니다. 반대로 증거 없이 전 구간을 PROXY에 얹으면 테스트는 빨라질 수 있지만 대역과 지연 면에서 비용이 큽니다. 최소 세트에서 막히는 호스트가 로그에 찍힐 때마다 한 줄씩 더하는 접근이 누적 가독성에 유리합니다. 그룹 설계가 복잡하면 프록시 그룹 가이드와 짝을 맞추세요.

④ DNS 레이어: fake-ip, DoH, 터미널 리졸버 불일치

Claude Code CLI 증상 중 일부는 패킷이 안 나가서가 아니라 이름이 잘못 풀리거나 OS와 코어가 보는 결과가 다른 경우입니다. fake-ip 프로필에서 브라우저 DoH·다른 VPN이 동시에 개입하면 간헐적 타임아웃 패턴이 납니다. 디버깅 때는 경로를 하나로 줄여 비교하세요. TUN 안에서 조회가 어디로 새는지는 TUN 모드·DNS 심화 체크리스트와 맞물립니다.

리눅스는 systemd-resolved, macOS는 스텁 리졸버를 경유하는 경우가 많아 dig api.anthropic.com @8.8.8.8 한 줄만 보고 「DNS 맞네」로 끝내기 어렵습니다. 터미널 셸이 실제로 어떤 /etc/resolv.conf·SC 설정을 보는지, Clash 로그의 DOMAIN 줄과 같은 타임스탬프로 교차해야 합니다. IPv6 AAAA 우선인데 실제 경로는 IPv4 노드에서만 안정하는 환경도 있어, 한동안 IPv6를 맞추거나 끊은 뒤 비교하는 게 진단에 도움이 됩니다.

주의: 회사 장비에서는 PAC·방화벽·HTTPS 검사 때문에 CLI만 막히는 경우가 있습니다. 이는 개인 Clash 규칙만으로 해결하는 문제가 아닐 수 있으며, IT 허용 범위를 먼저 확인해야 합니다.

⑤ Rule과 Global으로 원인 빠르게 가르기

잠깐 Global(또는 실질적 전체 출구 선택)을 켠 뒤 동일 명령을 다시 실행해 보고, 증상이 사라지면 규칙 누락·GEOIP 순서 역전·잘못된 DIRECT 우선 쪽을 의심합니다. Global에서도 시간 초과만 반복되면 노드 품질·패킷 드랍·TLS 차단·상단 방화벽 줄을 따라가야 합니다.

Windows에서 WSL2 안의 CLI는 호스트 Clash 포트만 보거나 라우팅 테이블이 달라 분리되는 경우가 있습니다. 터미널이 WSL에 있으면 WSL2·Clash 글 순서를 같이 놓고 보세요. 즉 터미널 타임아웃은 DNS 한 줄만 만지는 것보다 레이어망을 순서대로 벗기는 편이 빠르게 결론을 줍니다.

⑥ 단계별 실측 순서: 코딩 에이전트 CLI 워크플로에 붙이기

  1. 프로필 백업 후 동일 테스트 명령을 메모합니다.
  2. 실패 직후 Clash 로그에서 해당 세션의 RULE 대상 호스트를 모두 적습니다.
  3. 로그에 없던 이름을 DOMAIN-SUFFIX로 추가하고, api.anthropic.com은 상단 쪽에 둡니다.
  4. fake-ip 해제 또는 DoH 단일화 테스트로 이름 해석 경로 차이를 비교합니다.
  5. 시스템 프록시 대 TUN·mixed-port를 바꿔 같은 명령이 일관되는지 봅니다.
  6. 여전히 막히면 회사 정책·IPv6·상단 보안 스택까지 범위를 넓힙니다.

처음에는 플래그 도움말만 길게 읽기보다, 위 루프(로그 증거 → 규칙 한 줄 → 재현)를 돌며 체계를 잡는 방식이 빠릅니다. 개념 정리는 Clash 입문 튜토리얼에서 Rule·모드만 잡힌 뒤 이 글을 읽으면 훨씬 수월합니다.

⑦ 자주 묻는 형태와 오해 줄이기

한 팀 안에서도 「에디터 플러그인은 되는데 팀원 CLI만 안 된다」는 보고가 섞입니다. 이는 종종 규칙이 아니라 프록시 환경 변수(HTTPS_PROXY 등) 미설정이나, 에디터가 내부적으로 프록시를 타는데 순수 셸은 DIRECT로 나가는 케이스입니다. 반대로 환경 변수만 맞춰 두고 DNS는 여전히 ISP 쪽이라 이름만 간헐적으로 틀어지는 경우도 있습니다. 한 세션에서는 변수 하나 또는 규칙 한 줄만 바꿔 결과를 확인하는 습관이 디버깅 비용을 줄입니다.

또 다른 패턴은 첫 TLS 핸드셰이크는 되는데 이후 스트림에서만 끊긴다고 말하는 경우입니다. 이때는 노드가 긴 세션을 싫어하거나 중간 박스가 있을 수 있으니, 동일 프로필로 Global 대비·다른 노드 그룹 교차가 필요합니다. 문제를 「항상 재설치」로만 해결하려 하면 재현 속도는 오히려 느려집니다.

⑧ 지역 규약·약관 준수

Anthropic 제품은 지역·조직 정책·과금 조건이 업데이트될 수 있습니다. 이 글은 합법적 범위에서의 연결 신뢰성·네트워크 분류 표현을 다룹니다. 개인이라도 토큰·데이터 처리 약관은 공식 안내를 따르고, 회사 장비에서는 IT 허용 범위가 우선입니다.

⑨ 도구 관점 정리와 Clash 쪽 선택지

한 줄로 전 구간을 터널링하는 방식은 초기 설정은 단순하지만, 에디터·브라우저·패키지 매니저·CLI까지 모두 같은 경로로 몰면 스플릿이 어렵고 업무 네트워크와 충돌할 때 되돌리기도 느립니다. Clash·Mihomo 계열은 도메인 단위 분류로 Claude Code CLI 테스트용 프로필과 일상 프로필을 바꿔 끼우기 쉬워, 증거 기반으로 규칙 한 줄만 조정해 재시도하기 좋습니다. 반면 규칙 편집 UI가 빈약하거나 프로필 공유가 불편한 일부 도구는 같은 증상이 반복될 때 원인 분리가 더 느릴 수 있습니다. 터미널 코딩 에이전트처럼 호출이 잦은 워크플로에서는 이름 해석·매칭 로그를 남긴 뒤 조정하는 방식이 재설치 루프보다 학습 비용이 낮습니다.

→ Clash를 받아 위 후보 라인부터 프로필에 반영하며 Claude Code CLI 흐름을 다시 잡아 보세요.