GitHub Copilot CLI 의존성 설치가 반복적으로 타임아웃될 때: Clash TUN·분류 규칙·DNS로 npm·GitHub API·터미널 에이전트를 한 축에 맞추기 (2026)

증상 — 설치 명령은 알겠는데 터미널만 오래 멈출 때

공식 문서의 npm install -g @github/copilot나 npx 경로는 정상 회선에서는 곧바로 통과합니다. 그러나 제한된 환경에서는 registry.npmjs.org에서 패키지 메타를 읽다가 실제 tarball이 놓인 CDN 호스트로 넘어가는 단계에서만 시간이 늘어나거나, ETIMEDOUT·ECONNRESET 문자열이 뜬 뒤 바로 종료됩니다. 또 Copilot Agent가 모델 호출뿐 아니라 저장소 메타·워크플로 상태를 GitHub REST로 가져오는 흐름이 섞이면 api.github.com만 간헐적으로 막혀 전체가 실패한 것처럼 보이기도 합니다. 브라우저로 시작한 OAuth는 성공했는데 CLI 재시도에서만 401이 나는 경우도 토큰 교환·리다이렉트 URL이 다른 FQDN으로 갈라져 규칙 트리에서 아래쪽 DIRECT로 새는 패턴과 잘 맞습니다.

HTTP/3(QUIC) 우선 때문에 UDP가 규칙 밖으로 새면 다운로드 구간만 느려진 것처럼 체감됩니다. TUN이 꺼져 있거나 UDP가 프록시 그룹을 타지 않으면 패키지 크기가 커질수록 타임아웃 확률이 올라갑니다. 기본 절차는 Clash Verge Rev TUN 가이드를 기준으로 하고, 스택 선택은 gvisor·system 비교 글에서 OS·보안 제품과의 충돌이 적은 쪽을 고르세요.

왜 터미널 문제에는 TUN이 먼저 떠오르나

Node·npm은 macOS Keychain·Windows WPAD·Linux 셸 프로파일마다 시스템 프록시를 읽는 방식이 달라 “브라우저만 프록시를 탄다”는 착시가 자주 생깁니다. 매 세션 HTTP_PROXY를 수동으로 넣는 것도 가능하지만, IDE 통합 터미널·CI 에이전트·백그라운드 작업이 서로 다른 환경을 읽으면 재현이 깨집니다. TUN은 커널이 가상 인터페이스로 패킷을 넘겨 애플리케이션이 프록시를 “알아야 할” 부담을 줄이고, 긴 TLS 연쇄·대용량 tarball에 유리합니다. 조직 정책으로 가상 어댑터 설치가 막혀 있다면 허용 범위 안에서만 적용하세요.

이 글이 다루는 범위

Copilot 구독 등급·요금·모델 이름·에이전트 기능 스위치는 공식 릴리스 노트를 따릅니다. 여기서는 외부 네트워크 표면만 다룹니다. 어떤 FQDN이 로그에 찍히는지, 규칙 트리에서 어디가 첫 매칭인지, 코어 DNS와 브라우저 DoH가 같은 이름을 서로 다른 IP로 풀지 않는지에 집중합니다. 엔드포인트는 시점에 따라 바뀔 수 있으니 아래 YAML·명령은 패턴 예시이고 실제 문자열은 본인 로그를 기준으로 바꿉니다.

1로그·curl로 레지스트리·GitHub 호스트 관측

실패한 줄에 나온 호스트를 그대로 모읍니다. npm은 registry.npmjs.org와 tarball CDN 하위 호스트가 갈라지고, 사내 registry 미러를 쓰면 공식 문서 예시와 FQDN이 완전히 다릅니다. Copilot Agent·CLI 인증 흐름에서는 github.com·api.github.com·간헐적 collector·upload 계열 호스트가 추가로 보일 수 있습니다. 터미널에서 오류가 난 직후 Clash 연결 패널을 열어 첫 매칭 규칙 이름과 타임스탬프를 맞춰 보세요. 아래는 TLS 핸드셰이크만 빠르게 확인하는 예시입니다.

# Example — replace hosts; increase -m if your path is slow
curl -v -m 25 https://registry.npmjs.org/
curl -v -m 25 https://api.github.com/
curl -v -m 25 https://github.com/

단계마다 응답 시간을 메모해 두면 이후에 DNS만 손댔는지 규칙만 손댔는지 분리하기 쉽습니다. 연결 리셋 로그 읽기는 연결 리셋 글을 참고하세요.

2TUN 켜기와 예외 범위

클라이언트 UI에서 TUN을 켠 뒤 사내 VPN·제로 트러스트 에이전트와 기본 라우트가 이중으로 잡히지 않는지 확인합니다. 사내 전용 npm 미러·내부 Git 엔드포인트는 fake-ip-filter·직통 규칙으로 먼저 고정하고 루프백·LAN 대역은 위쪽에 둡니다. Windows에서 처음 환경을 잡을 때는 Windows Clash 설치 튜토리얼을 먼저 밟은 뒤 TUN을 켜면 변수가 줄어듭니다.

3분류 규칭 초안 — npm·GitHub API 묶음

실제 프로파일에는 이미 거대 RULE-SET·GEOIP 블록이 있으므로 사용자 전용 조각을 Mixin으로 덧붙이는 방식이 안전합니다. 핵심은 관측한 호스트 전부를 같은 정책 그룹으로 보내 설치·에이전트 세션이 첫 프레임부터 출구를 바꾸지 않게 하는 것입니다.

# Illustration — replace PROXY_DEV; keep order above catch-all GEOIP/MATCH
rules:
  - DOMAIN-SUFFIX,registry.npmjs.org,PROXY_DEV
  - DOMAIN-SUFFIX,npmjs.org,PROXY_DEV
  - DOMAIN-SUFFIX,github.com,PROXY_DEV
  - DOMAIN-SUFFIX,githubusercontent.com,PROXY_DEV
  - DOMAIN-SUFFIX,githubassets.com,PROXY_DEV
  - DOMAIN-SUFFIX,github.io,PROXY_DEV
  - DOMAIN-SUFFIX,api.github.com,PROXY_DEV
  # Add exact hosts from your logs (OAuth, CDN, enterprise host)
  - MATCH,DIRECT

npm 환경 변수와 TUN의 관계

npm config set proxy·HTTPS_PROXY만으로도 동작하는 경우가 있지만, Copilot CLI는 설치 단계 이후에도 여러 하위 프로세스가 동시에 붙을 수 있어 환경 변수 누락이 반복되기 쉽습니다. TUN이 켜진 상태에서는 변수를 비운 채 동일 경로가 나가는지 먼저 비교해 보세요. 반대로 회사 정책상 특정 호스트는 반드시 직통이어야 한다면 변수 기반 분리가 필요할 수 있습니다. 일반적인 Git·npm 혼합 시나리오는 WSL2·Git·npm 연계 글과 함께 보는 편이 빠릅니다.

4DNS·FakeIP·스니퍼 정합성

브라우저 Secure DNS와 코어 DNS가 동시에 켜져 있으면 이름만 같아도 연결 패널 표기가 달라져 규칙이 헛도는 것처럼 보입니다. fake-ip-filter 범위와 스니퍼를 함께 맞추고 변경은 한 번에 한 축만 움직이세요. 세부는 DNS 유출 방지 가이드와 HTTPS 스니퍼 글을 참고합니다.

5정책 그룹 고정과 설치·에이전트 재시도

대용량 설치 중 url-test가 공격적으로 노드를 바꾸면 세션이 끊긴 것처럼 보입니다. 디버깅 동안에는 selector로 단일 노드를 고정한 뒤 npm install -g @github/copilot와 Copilot Agent 작업을 다시 실행하세요. 자동 장애조치 패턴은 url-test·fallback 글을 따릅니다. 안정성이 확인되면 자동 그룹을 되살립니다.

WSL2·원격 개발 환경

Windows에서 Docker·WSL 안의 Node까지 같은 경로로 맞추려면 호스트 게이트웨이·포워딩이 추가로 필요합니다. 호스트 OS의 TUN만으로 게스트 브리지가 자동 연결되지는 않습니다. 절차는 WSL2·Git·npm 연계 글을 우선 적용하세요.

설치·에이전트 안정성 간이 체크리스트

1. 오류 줄·연결 로그에 등장한 모든 호스트 이름을 목록화했는가.
2. 그 목록이 규칙 트리 어디에서 첫 매칭되는지 시간축이 일치하는가.
3. TUN ON/OFF에 따라 증상이 근본적으로 바뀌는가, 앱 레벨 프록시 잔여 설정은 없는가.
4. 브라우저 DoH·OS DNS·코어 DNS가 서로 덮어쓰지 않는가.
5. 한 번에 한 가지 설정만 바꿨는가.

자주 묻는 질문

npm 레지스트리 프록시만 넣으면 되지 않나요

메타데이터와 tarball·GitHub API·인증 리다이렉트가 서로 다른 호스트로 갈라지면 부분 최적화가 됩니다. @github/copilot 설치와 Agent 실행은 여러 패밀리를 동시에 쓰는 경우가 많아 한 줄 규칙만으로는 부족할 때가 잦습니다.

GitHub Enterprise를 쓰는 조직

호스트 이름이 전부 온프레미스로 바뀌므로 관측 목록을 팀 표준에 맞춰 갱신하세요. 내부 CA를 쓰면 TLS 검증 실패가 프록시 문제와 별도로 생기니 증상을 분리해 기록합니다.

정책·약관 준수

조직 네트워크 규정과 클라우드 데이터 처리 지침을 지키세요. 토큰·샘플 응답은 공개 채널에 올리지 말고 공식 문서의 엔드포인트 변경을 수시로 확인합니다.

맺음말

GitHub Copilot CLI와 Copilot Agent는 터미널에서 짧게 재시도만 반복돼도 “환경이 망가졌다”는 인상을 주기 쉽습니다. 브라우저와 달리 npm 런타임은 시스템 프록시 인식이 들쭉날쭉하므로 TUN으로 트래픽을 한 파이프에 올린 뒤, 관측 기반으로 레지스트리·GitHub API 묶음을 분류 규칙에 고정하고 DNS·FakeIP를 같은 축에서 맞추는 세트가 가장 재현성이 높습니다. 이미 다른 CLI 글에서 익힌 패턴을 그대로 이식하되 호스트 목록만 최신 로그로 갱신하면 이후에도 같은 방식으로 확장할 수 있습니다.

한편 범용 프록시 유틸리티는 여전히 긴 설정 파일을 손으로 맞추거나 터미널마다 환경 변수를 중복 정의해야 해 실수 여지가 큽니다. Clash 계열은 GUI에서 프로파일과 규칙 트리를 바로 열어보고 Meta 코어의 DNS·TUN·프로세스 분기까지 한 제품군에서 실험할 수 있어 에이전트 CLI를 자주 갱신하는 개발자에게 시간을 아껴 줍니다. 아직 쓰지 않았다면 Clash 클라이언트를 무료로 받아 본문 순서대로 전역 설치와 Agent 작업을 다시 실행해 보고, 동일 명령이 안정적으로 끝까지 도달하는지 직접 비교해 보시길 권합니다.