증상: Claude Code가 터미널에서만 도구·API를 동시에 못 붙일 때
VS Code·Cursor·JetBrains 같은 IDE 확장이 아니라 터미널에서 직접 Claude Code(claude CLI)를 켜 두었을 때 흔한 불만은 한 가지입니다. 추론 요청은 걸리는데 npm 설치가 중간에 멈추거나, 반대로 패키지는 받아지는데 Anthropic API 호출만 길게 ETIMEDOUT·read ECONNRESET에 가깝게 끊긴다는 식의 교차 실패입니다. 사용자는 「회선 전체가 망가졌다」고 느끼기 쉽지만, 실제로는 Clash 규칙상 api.anthropic.com과 registry.npmjs.org, 그리고 tarball이나 GitHub 릴리스가 머무는 서로 다른 SNI가 각각 다른 정책 그룹·노드·직결 경로로 나가고 있을 가능성이 큽니다.
또 하나의 착시는 「느린 SSH 프록시 한 줄이 전부를 막는다」는 설명입니다. 단일 병목도 있지만, 2026년 현재 에이전트형 CLI는 짧은 턴이 아니라 긴 스트리밍 응답과 병렬 HTTP 요청을 섞습니다. 그 사이에 npm registry 메타데이터와 실제 tarball 호스트, GitHub CDN(objects.githubusercontent.com·codeload.github.com 등)까지 끼면, 한 노드의 패킷 손실이 API와 무관한 다운로드에만 먼저 드러나기도 합니다. 본문은 규제 우회를 조장하지 않으며, 기업망에서는 IT 정책·키 관리 규정을 먼저 확인해야 합니다.
한 프로필에 몰지 말고 세 축으로 나누는 이유
만약 모든 HTTPS를 하나의 ♻️ Auto 그룹에만 넣어 두면, 노드 교체 시 API·레지스트리·CDN이 동시에 따라 바뀝니다. A 노드는 Anthropic 핸드셰이크는 빠르지만 미국 서부에서 npm tarball만 느린 경우, B 노드는 그 반대인 경우가 흔해서, 운영자가 원인을 단정하기 어렵습니다. 반대로 GEOIP,XX,DIRECT나 넓은 domestic rule-set이 위에 깔리면, 일부 CDN은 직결이 더 나쁜 경로로만 나가기도 합니다.
그래서 AI-ANTHROPIC·NPM-REGISTRY·GITHUB-CDN(이름은 자유)처럼 역할별 select/url-test 그룹을 만들고, 각 그룹에 맞는 노드 후보만 넣는 방식이 디버깅에 유리합니다. 웹 전용 Claude 안정화는 Claude 웹·브라우저 축 글에서 다루고, 순수 Node 패키지만 다룬 경우는 npm·pnpm 레지스트리 분리 글과 비교해 읽으면 중복 없이 이해가 빠릅니다. 터미널 OpenAI Codex와의 공통점은 Codex CLI 가이드에 가깝습니다.
도메인 묶음 설계(출발점)
실제 세션에서 관측되는 호스트는 버전 업으로 늘 수 있으므로, 아래는 출발 목록이며 Clash 연결 로그와 curl -v의 SNI로 반드시 교차 확인해야 합니다.
- AI-ANTHROPIC: 문서화된 REST·스트리밍 엔드포인트가 붙는
api.anthropic.com, 계정·문서·웹 자산이 섞일 수 있는anthropic.com·claude.ai일부 경로, (환경에 따라) 텔레메트리·기능 플래그 관련 별도 호스트. - NPM-REGISTRY: 메타데이터의 중심인
registry.npmjs.org, 팀이 쓰는 사설 registry 미러, 중국권 미러를 쓴다면 해당 접미사 전체. - NPM-TARBALL / CDN: 패키지 tarball이 리다이렉트되는
registry.npmjs.com계열, 또는 응답 헤더에 나오는*.npmjs.com·*.npmjs.net패턴(실측값 우선). - GITHUB-CDN:
github.com, 릴리스 자산objects.githubusercontent.com, 아카이브·raw 다운로드codeload.github.com, 필요 시githubusercontent.com계열.
Clash에서는 가능하면 DOMAIN-SUFFIX로 상위 접미사를 잡고, 오탐이 커지는 DOMAIN-KEYWORD는 테스트 프로필에서만 씁니다. Rule provider를 쓴다면 Rule Providers·rule-set 문서와 병합 후 최종 줄 순서를 대시보드에서 한 번 더 확인하세요.
# Example skeleton — verify live hostnames in your client logs
proxy-groups:
- name: AI-ANTHROPIC
type: select
proxies:
- 🇯🇵 Low-latency
- ♻️ Auto
- DIRECT
- name: NPM-REGISTRY
type: select
proxies:
- 🌐 Global stable
- DIRECT
- name: GITHUB-CDN
type: select
proxies:
- 🌐 Global stable
- DIRECT
rules:
- DOMAIN-SUFFIX,anthropic.com,AI-ANTHROPIC
- DOMAIN-SUFFIX,claude.ai,AI-ANTHROPIC
- DOMAIN-SUFFIX,npmjs.org,NPM-REGISTRY
- DOMAIN-SUFFIX,npmjs.com,NPM-REGISTRY
- DOMAIN-SUFFIX,github.com,GITHUB-CDN
- DOMAIN-SUFFIX,githubusercontent.com,GITHUB-CDN
위 예시보다 위쪽에 더 넓은 DIRECT 규칙이 있으면 Anthropic 전용 줄은 실행되지 않습니다. 반대로 FINAL 한 줄로 모든 것을 한 그룹에 몰아넣었는지도 함께 봅니다.
DNS·fake-ip가 터미널과 브라우저를 갈라 놓는 경우
fake-ip를 쓰는 프로필에서는 OS·셸 리졸버와 코어 내부가 서로 다른 A/AAAA를 들고 있으면, 브라우저는 정상인데 터미널만 이상한 「반쪽 경로」가 됩니다. Claude Code가 자식 프로세스로 npm·git을 부를 때 각각 다른 환경 변수를 물려받으면 증상이 더 복잡해집니다. redir-host vs fake-ip를 바꿔 재현되는지, fake-ip-filter에 공용 레지스트리 호스트를 넣을 필요가 있는지 점검하세요.
공용 DNS가 지역별로 다른 CDN 엣지를 돌려 주면, 규칙은 맞는데 RTT만 유난히 큰 경우도 있습니다. TUN과 systemd-resolved·Windows 네트워크 스택이 겹친다면 TUN 모드 가이드와 macOS 터미널 프록시 환경 변수 글을 같이 읽으면 셸·코어·OS 세 층을 동시에 맞추기 쉽습니다.
터미널·하위 프로세스의 HTTPS_PROXY 정렬
Node·npm 일부 버전은 HTTPS_PROXY를 따르지만, 다른 도구는 무시하고 직접 소켓을 엽니다. Claude Code가 번들한 런타임이 혼합되어 있으면 「mixed 포트에는 잡히는데 레지스트리는 DIRECT로 새는」 패턴이 나올 수 있습니다. 동일 호스트를 curl -x http://127.0.0.1:포트과 프록시 없이 비교하고, Clash 연결 로그에서 어떤 인터페이스로 나갔는지 확인하세요.
회사망에서 고정 egress IP가 허용 목록과 묶여 있다면, 문서에 적힌 base URL과 실제 SNI·인증서 이름이 어긋나지 않는지도 함께 봐야 합니다. TLS 경고가 반복되면 순수 지연과 인증 문제를 먼저 가릅니다. 연결은 되는데 화면만 멈춘다는 보고는 로그·DNS·규칙 자가 점검 글과 맞물립니다.
규칙 우선순위·직결 오매칭을 rule hit로 잡기
문제가 재현되는 순간 연결 한 건만 골라 대시보드의 rule hit 이름을 적어 두세요. 예상했던 AI-ANTHROPIC 대신 오래된 국내 직결 rule-set이 먼저 매칭되면, API만 유독 느리거나 끊깁니다. 반대로 GitHub이 DIRECT로 떨어져 기업 방화벽에 걸리는 경우도 있습니다.
대응은 단순합니다. 검증된 Anthropic·npm·GitHub 접미사 규칙을 충돌 블록보다 위로 올리되, 범위를 불필요하게 키우지 않습니다. 여러 rule-provider를 병합했다면 머릿속 순서와 실제 순서가 다를 수 있으니, 클라이언트가 보여 주는 최종 테이블을 기준으로 삼으세요.
QUIC·HTTP/3와 긴 스트리밍 응답
UDP 기반 HTTP/3가 프록시 체인에서 제한되면 TCP 폴백 전까지 빈 화면처럼 느껴질 수 있습니다. 브라우저와 달리 터미널 HTTP 클라이언트는 HTTP/2 고정인 경우가 많아 증상 차이가 납니다. 그래도 일부 라이브러리는 QUIC을 시도하므로, 실험적으로 끄고 비교해 볼 가치가 있습니다. 세부는 QUIC·HTTP/3 규칙 글을 참고합니다.
긴 토큰 스트리밍은 유휴 타이머·중간 프록시의 idle timeout에 걸리기 쉬우므로, API만 끊길 때는 노드 품질과 함께 세션 길이 정책도 의심합니다.
체크리스트(짧게 메모하기 좋게)
- 실패한 요청의 Host·경로·상태 코드를 터미널 로그에 남긴다.
- 같은 시각 Clash에서 rule hit·정책 그룹 이름을 스크린샷 또는 텍스트로 남긴다.
- Anthropic·npm·GitHub 각각에 대해 의도한 proxy-group이 맞는지 노드를 바꿔 A/B 한다.
- DNS 모드·nameserver·fake-ip-filter를 바꿔 재현 여부를 본다.
HTTPS_PROXY·셸 프로필·IDE 통합 터미널이 서로 다른 값을 주지 않는지 확인한다.- TUN·시스템 프록시·다른 VPN이 동시에 개입하지 않는지 확인한다.
이 순서를 지키면 「CLI가 불안정하다」는 보고를 호스트별 규칙 오매칭이나 환경 변수 누락 같은 구체 가설으로 바꿀 수 있습니다.
정리
Claude Code가 터미널에서만 Anthropic API와 npm registry·GitHub CDN을 한 번에 문제 삼을 때, 첫 번째 질문은 「노드가 나빠서?」가 아니라 도메인 축마다 어떤 정책 그룹이 걸렸는가여야 합니다. 세 축을 나누고 rule hit로 직결 오매칭을 걸러 내면, 한 줄 회선이 전체 체인을 죽이는 착시를 빠르게 걷어 낼 수 있습니다.
장기적으로는 원격 rule-set으로 호스트 목록을 갱신하고, 로컬 YAML에는 충돌이 적은 최소 규칙만 남기세요. Mihomo 기반 클라이언트는 코어·TUN·DNS가 세트로 개선되는 경우가 많아, 노드만 바꾸기보다 클라이언트 세대를 맞추는 것이 운영 비용을 줄입니다. 다른 AI CLI와 달리 Anthropic과 패키지 생태계가 한 프로세스 안에 붙는 점만 기억해 두면, 이후 튜닝이 훨씬 단순해집니다.
브라우저 전용 분기와 공존하는 프로필을 쓴다면, 실험용 프로필을 분리해 두는 것도 체감 품질을 지키는 실용적인 타협입니다. 비슷한 설계를 이미 쓰고 있다면 Codex·npm 단독 글의 체크리스트를 한 장으로 합쳐 팀 위키에 두어 재사용하세요.