터미널에서만 연결이 안 되는 패턴

2026년 현재 Claude Code는 개발자들이 터미널에서 직접 AI 코딩 작업을 수행할 수 있게 해주는 Anthropic 공식 CLI 도구입니다. 구독이 활성화되고 브라우저에서 claude.ai는 문제없이 열리는데, 터미널에서 claude 명령을 실행하면 아래와 같은 오류가 찍히는 경우가 있습니다.

• 요청이 한참 지나도 응답 없이 타임아웃
• Error: connect ECONNREFUSED 또는 ETIMEDOUT 메시지
• 첫 메시지 전송 시 세션이 끊기거나, 긴 응답 중간에 스트림이 중단
• claude --version 같은 로컬 명령은 잘 되는데 API 호출만 실패

이런 증상은 대부분 Clash가 켜져 있지만 Claude Code CLI가 붙는 호스트가 규칙 세트에 없거나, 잘못된 출구(DIRECT 또는 의도치 않은 노드)를 타고 있을 때 발생합니다. 단순히 "노드가 느려서"라고 단정하기보다 어느 호스트가 어느 규칙에 걸리는지부터 확인하는 것이 빠른 해결 경로입니다.

비슷하게 Cursor IDE가 멈추는 문제는 Cursor 분기 가이드에서 다루고 있고, 일반 AI 웹사이트 분기는 AI 웹 분기 가이드에 별도로 정리되어 있습니다. 이 글은 그것들과 겹치지 않게 Claude Code CLI + Anthropic API 전용 트래픽에 초점을 맞춥니다.

왜 브라우저 규칙만으로는 CLI가 안 풀릴까

브라우저에서 claude.ai를 여는 것과 터미널에서 claude 명령을 실행하는 것은 완전히 다른 호스트 묶음에 붙습니다. 웹 인터페이스는 주로 claude.ai와 그 하위 도메인을 통해 동작하지만, CLI 도구는 API를 직접 호출합니다.

• 웹 채팅: claude.ai, 정적 자산 CDN, 인증 세션 — 브라우저 시스템 프록시를 자연스럽게 따라가는 경우가 많습니다.
• CLI / SDK: api.anthropic.com에 직접 HTTPS 요청 — 환경변수나 코어 설정 없이는 시스템 프록시를 우회하거나 다른 경로로 나갑니다.

또 한 가지는 규칙 순서입니다. Clash의 rules는 위에서 아래로 평가되며 처음 매칭된 한 줄이 최종입니다. claude.ai가 포함된 AI 사이트 RULE-SET이 있어도, api.anthropic.com이 그 세트에 없으면 아래쪽 MATCH나 GEOIP,CN,DIRECT로 떨어지게 됩니다. 거기서 선택된 출구가 Anthropic 서버에 접근 불가한 경로면 CLI만 끊기는 증상이 납니다.

Claude Code가 연결하는 호스트 목록

Claude Code CLI와 Anthropic SDK가 실제로 붙는 호스트를 크게 세 축으로 나눌 수 있습니다. 정확한 목록은 CLI 버전과 기능 확장에 따라 달라질 수 있으므로, 아래 목록은 출발점으로 활용하고 실제 로그로 보완하는 방식을 권합니다.

① API 엔드포인트

Claude Code의 핵심 경로입니다. 모델 호출, 스트리밍 응답, 컨텍스트 전달이 모두 여기를 지납니다.

• api.anthropic.com — 메인 API 엔드포인트. 가장 중요하며, 이 호스트가 막히면 모든 CLI 기능이 동작하지 않습니다.
• anthropic.com — 인증·라이선스 검증·약관 관련 요청이 이쪽을 경유하는 경우가 있습니다.

② CDN 및 정적 자산

Claude Code가 자동 업데이트, 시스템 프롬프트 데이터, 릴리스 바이너리 등을 내려받을 때 사용하는 CDN 경로입니다. 이 트래픽이 느리거나 막히면 초기 실행이 지연되거나 업데이트가 실패합니다.

• storage.googleapis.com — 일부 빌드·릴리스 파이프라인에서 GCS를 경유합니다.
• registry.npmjs.org — npm 기반 설치·업데이트 경로. npm install -g @anthropic-ai/claude-code 실행 시 여기를 경유합니다.
• cdn.anthropic.com — 공식 CDN이 활성화되어 있는 경우 정적 에셋에 사용됩니다.

③ 텔레메트리 및 기능 플래그

오류 보고, 사용 통계, 기능 플래그 관리를 위한 호스트입니다. 이쪽이 막혀도 API 기능 자체는 유지되는 경우가 많지만, 특정 실험적 기능이 활성화되지 않거나 오류 메시지가 달라질 수 있습니다.

• statsig.anthropic.com — 기능 플래그(feature gate) 및 실험 관리.
• statsig.com — Statsig SaaS 엔드포인트. statsig.anthropic.com의 백엔드로 사용될 수 있습니다.
• sentry.io — 오류 트래킹. 이 도메인은 여러 개발자 도구가 공유하므로, 다른 앱 트래픽까지 일괄 처리하고 싶을 때 주의가 필요합니다.

전략 그룹 설계: PROXY_ANTHROPIC

실무에서는 proxy-groups에 Anthropic 전용 그룹을 하나 두고, 이름을 PROXY_ANTHROPIC처럼 고정해 두는 패턴이 관리하기 편합니다. 이 그룹의 출구 노드를 선택할 때 고려할 사항은 다음과 같습니다.

• 미국 서버: Anthropic API 서버가 주로 미국(US)에 있어, 미국 또는 북미 출구 노드가 레이턴시와 안정성 면에서 유리한 경우가 많습니다.
• 긴 세션 안정성: 스트리밍 응답은 수십 초 동안 연결을 유지해야 하므로, url-test로 자동 전환이 잦은 그룹보다 select로 안정적인 노드를 고정하는 편이 스트림 중단을 줄입니다.
• CDN 분리 고려: 필요에 따라 PROXY_ANTHROPIC_CDN을 별도로 두어 CDN·npm 트래픽은 더 높은 대역폭 노드로 보낼 수 있습니다. 다만 처음에는 하나로 시작해 문제가 계속 나타날 때 분리하는 것을 권합니다.

url-test를 쓴다면 측정 URL을 https://api.anthropic.com처럼 실제 연결 대상에 가까운 주소로 지정하면, 측정 결과가 실제 사용 레이턴시와 더 가깝게 됩니다.

규칙 예시와 순서

아래는 개념 예시입니다. 실제 프로필에서는 사용 중인 rule-provider 이름·경로와 전략 그룹 이름에 맞게 바꿔야 합니다. 핵심은 Anthropic 관련 줄이 넓은 GEOIP나 최종 MATCH보다 위에 있어야 한다는 점입니다.

# Conceptual excerpt — adapt names and providers to your profile
proxy-groups:
  - name: PROXY_ANTHROPIC
    type: select
    proxies:
      - NODE_US_1
      - NODE_US_2
      - PROXY_DEFAULT

rules:
  # Anthropic API — highest priority, must come first
  - DOMAIN-SUFFIX,api.anthropic.com,PROXY_ANTHROPIC
  - DOMAIN-SUFFIX,anthropic.com,PROXY_ANTHROPIC
  - DOMAIN-SUFFIX,claude.ai,PROXY_ANTHROPIC
  - DOMAIN-SUFFIX,cdn.anthropic.com,PROXY_ANTHROPIC

  # Feature flags & telemetry
  - DOMAIN-SUFFIX,statsig.anthropic.com,PROXY_ANTHROPIC
  - DOMAIN,statsig.com,PROXY_ANTHROPIC

  # npm registry (Claude Code install/update path)
  - DOMAIN-SUFFIX,registry.npmjs.org,PROXY_ANTHROPIC

  # Broad geo rules — come after all app-specific rules
  - GEOIP,CN,DIRECT
  - MATCH,PROXY_DEFAULT

위 목록은 교육용 스케치입니다. 실제로는 로그에서 확인된 호스트만 넣고 불필요한 줄을 최소화하는 것이 유지보수에 유리합니다. YAML 전체 구조·Fake-IP·rule-provider 활용법은 YAML 심층 가이드와 함께 보면 프로필 전체와 충돌이 적습니다.

RULE-SET을 활용하는 방법

직접 도메인 목록을 관리하는 대신, 커뮤니티에서 관리하는 RULE-SET을 쓰면 도메인 변경을 자동으로 따라갈 수 있습니다. 예를 들어 rule-providers에 Anthropic 전용 세트를 등록하고 RULE-SET,anthropic,PROXY_ANTHROPIC처럼 불러오는 방식입니다.

# Using community-maintained rule sets (conceptual example)
rule-providers:
  anthropic:
    type: http
    behavior: domain
    url: "https://example-ruleset-repo.com/anthropic.yaml"
    interval: 86400

rules:
  - RULE-SET,anthropic,PROXY_ANTHROPIC
  - GEOIP,CN,DIRECT
  - MATCH,PROXY_DEFAULT

단, 외부 세트를 쓸 때는 세트가 실제로 갱신되는지, 포함된 도메인이 의도에 맞는지 직접 확인하는 습관이 중요합니다. 세트에 없는 새 호스트가 추가되면 로컬 예외 줄을 위에 추가하는 방식으로 보완할 수 있습니다.

CLI 환경변수와 프록시 경로

CLI 도구가 시스템 프록시를 따르지 않고 직접 소켓을 여는 경우가 있습니다. 이 경우 Clash가 켜져 있어도 CLI 트래픽이 Clash 코어를 거치지 않고 직접 나가버립니다. 이를 해결하는 방법은 크게 두 가지입니다.

방법 1: 환경변수로 HTTP 프록시 지정

Node.js 기반 CLI 도구 대부분은 HTTPS_PROXY(또는 https_proxy) 환경변수를 존중합니다. 쉘 설정 파일(~/.zshrc, ~/.bashrc)에 아래 내용을 추가하면 claude 명령도 Clash 혼합 포트(mixed-port)를 경유하게 됩니다.

# Add to shell profile (~/.zshrc or ~/.bashrc)
# Replace 7890 with your Clash mixed-port value
export HTTPS_PROXY=http://127.0.0.1:7890
export HTTP_PROXY=http://127.0.0.1:7890
export NO_PROXY=localhost,127.0.0.1,::1

설정 후 새 터미널 탭을 열거나 source ~/.zshrc를 실행해 적용합니다. curl -v https://api.anthropic.com 으로 Clash를 통해 나가는지 확인할 수 있습니다. Windows 터미널 환경변수 설정은 Windows 혼합 포트 가이드에 자세히 나와 있습니다.

방법 2: TUN 모드로 모든 트래픽 포획

Clash의 TUN 모드는 환경변수 설정 없이도 시스템의 모든 TCP/UDP 트래픽을 코어로 끌어들입니다. CLI 도구뿐 아니라 환경변수를 무시하는 앱까지 포함되므로, 개발 환경에서 일관성을 원할 때 유용합니다. 다만 TUN 설정이 잘못되면 네트워크 전체가 끊길 수 있으니, Windows 사용자라면 TUN 점검 가이드를 먼저 확인하세요.

DNS 설정과 Fake-IP 주의사항

Clash의 enhanced-mode: fake-ip를 사용할 때 주의할 점이 있습니다. Fake-IP 모드에서는 DNS 쿼리에 가짜 IP를 반환해 규칙 매칭을 도모하는데, 일부 앱은 실제 IP를 확인하거나 DNS 응답을 캐시에 유지하면서 예외 동작을 보일 수 있습니다. Claude Code의 경우 대부분 도메인 기반으로 연결하므로 Fake-IP 환경에서도 잘 동작하는 편이지만, 연결이 이상하게 보인다면 fake-ip-filter에 Anthropic 도메인을 추가해 Fake-IP를 제외하는 것도 방법입니다.

# DNS fake-ip-filter example (add Anthropic domains if needed)
dns:
  enhanced-mode: fake-ip
  fake-ip-filter:
    - "*.anthropic.com"
    - "api.anthropic.com"
    - "claude.ai"

IPv6가 활성화된 환경에서는 AAAA 응답을 따라 트래픽이 IPv6 경로로만 나가며 규칙이 기대와 다르게 동작하는 사례도 있습니다. 재현이 어렵다면 일시적으로 IPv6를 비활성화해 변수를 분리해 보세요. DNS 설정 전반에 대한 심층 내용은 YAML 설정 가이드에서 다룹니다.

점검 순서 체크리스트

설정을 크게 뒤집기 전에 아래 순서를 권합니다.

1. 모드 확인: Clash가 rule 모드인지, 현재 프로필이 실제로 로드되어 있는지 확인합니다.
2. 연결 로그 확인: Clash 연결 로그에 api.anthropic.com이 찍히는지, 어느 규칙·그룹으로 처리됐는지 확인합니다. 로그에 없다면 CLI 트래픽이 Clash를 아예 우회하고 있는 것입니다.
3. 환경변수 확인: echo $HTTPS_PROXY로 환경변수가 올바른 포트를 가리키는지 확인합니다. Clash 혼합 포트와 일치해야 합니다.
4. 규칙 순서 확인: api.anthropic.com을 잡는 줄이 GEOIP,CN,DIRECT나 넓은 MATCH보다 위에 있는지 확인합니다.
5. PROXY_ANTHROPIC 그룹 확인: 지정된 노드가 실제로 Anthropic 서버에 접근 가능한 출구인지 확인합니다. 노드 자체의 헬스 체크가 통과해도 특정 서비스는 차단될 수 있습니다.
6. 스트리밍 끊김 여부 구분: 연결 자체가 안 되는 것인지, 긴 응답 중간에 끊기는 것인지 구분합니다. 후자라면 노드의 TCP keepalive·타임아웃 설정을 먼저 의심합니다.
7. DNS 캐시 초기화: 규칙 변경 후에는 clash api로 DNS 캐시를 플러시하거나 앱을 재시작해 이전 캐시 영향을 배제합니다.

이 순서대로 좁히면 대부분의 경우 2~4번 단계에서 원인을 찾을 수 있습니다.

다른 개발자 도구와의 공존

실제 개발 환경에서는 Claude Code 외에도 여러 CLI 도구가 동시에 동작합니다. 규칙 설계 시 아래와 같은 공존 사항을 고려하면 충돌이 줄어듭니다.

• npm / pip / cargo 등 패키지 매니저: registry.npmjs.org를 Claude Code와 공유하는 경우, 같은 그룹(PROXY_ANTHROPIC)에 묶거나 별도 PROXY_DEV 그룹으로 분리할 수 있습니다. npm 전용 프록시 설정은 Git·npm 혼합 포트 가이드를 참고하세요.
• Docker 레지스트리: claude 명령과 docker pull이 같은 터미널 세션에서 쓰인다면, Docker 레지스트리 전용 규칙도 함께 정리해 두는 편이 좋습니다. Docker 분기 가이드에 별도로 정리되어 있습니다.
• WSL2 환경: Linux 서브시스템에서 claude를 실행할 때는 Windows 호스트 게이트웨이 IP와 Clash 포트 설정이 추가로 필요합니다. WSL2에서 Windows Clash를 경유하는 방법은 WSL2 혼합 포트 가이드에서 다룹니다.

프로세스 이름 기반 규칙 (고급)

Clash·mihomo는 일부 플랫폼에서 PROCESS-NAME 규칙을 지원합니다. 예를 들어 node 프로세스에서 발생하는 트래픽을 도메인 무관하게 특정 그룹으로 보내는 방식입니다. Claude Code는 Node.js 런타임 위에서 동작하므로 이론상 적용이 가능하지만, 실제 환경에서는 다른 Node.js 앱 트래픽까지 함께 포획될 위험이 있어 도메인 기반 규칙을 우선 적용하고 프로세스 규칙은 보조로 활용하는 것을 권합니다.

# Process-name rule (advanced, macOS/Linux only in most builds)
# Use with caution — captures all 'node' process traffic
# - PROCESS-NAME,node,PROXY_ANTHROPIC

# Prefer domain-based rules first for precision
- DOMAIN-SUFFIX,api.anthropic.com,PROXY_ANTHROPIC

TUN 모드가 활성화된 경우에만 프로세스 규칙이 제대로 동작하는 구현도 있으니, 실제 동작을 로그로 확인한 뒤 사용하세요.

정리

Claude Code CLI가 타임아웃되거나 Anthropic API에 접속이 안 되는 문제는, "노드가 느려서"보다는 CLI 트래픽이 Clash를 경유하지 않거나, 경유하더라도 잘못된 규칙에 걸린 경우가 훨씬 많습니다. 핵심은 다음 세 가지입니다.

1. 환경변수(HTTPS_PROXY)로 CLI 트래픽이 Clash mixed-port를 실제로 지나도록 합니다.
2. 규칙에 api.anthropic.com을 명시하고, GEOIP·MATCH보다 위에 둡니다.
3. PROXY_ANTHROPIC 전략 그룹에 안정적인 미국 출구를 고정해 스트리밍 중단을 줄입니다.

Clash·mihomo의 YAML 한 장으로 이런 분기를 명시적으로 유지할 수 있고, 문제가 생겼을 때도 연결 로그 한 화면으로 원인 후보를 빠르게 좁힐 수 있습니다. Cursor IDE, Docker, WSL2 등 다른 개발자 도구의 분기와도 같은 프로필 안에서 충돌 없이 공존시킬 수 있는 것이 Clash 기반 환경의 장점입니다.

최신 코어 및 GUI 클라이언트와의 호환 빌드는 다운로드 페이지에서 확인할 수 있습니다. → Clash를 무료로 내려받아 PROXY_ANTHROPIC 그룹을 설정하고, 터미널에서 Claude Code가 끊김 없이 동작하는 환경을 바로 만들어 보세요.