증상 묶음 — Q CLI 이행 직후에만 npm·SSO·플러그인이 동시에 흔들릴 때
문서에 적힌 그대로 npm install·npx 한 줄을 실행했는데 진행 표시줄이 끝없이 도는 상황은 레지스트리 품질 문제라기보다 경로 분기로 설명되는 경우가 많습니다. 표면 증상으로는 패키지 인덱스 JSON은 받았으나 실제 바이너리가 올라 있는 CDN 호스트에서만 시간 초과가 나는 경우, 또는 브라우저로 여는 AWS SSO 단계까지는 성공했는데 터미널의 토큰 교환·로컬 콜백 서버가 타 노드·다른 DNS 응답을 타 TLS 핸드셰이크 끝에서 떨어지는 경우가 대표적입니다. Kiro CLI나 플러그인이 추가로 받는 스크립트·번들 URL이 조직 방화벽 밖의 다른 도메인을 동시에 두드리면 로그에는 한 줄 요약만 남고 원인 추적이 어렵습니다.
이때 먼저 할 일은 버전 핀을 바꾸는 것이 아니라 실패 시각 기준으로 FQDN 목록을 모으는 것입니다. npm verbose, IDE 통합 터미널 출력, 브라우저 개발자 도구, Clash 연결 패널을 같은 분 단위로 맞추면 첫 번째로 매칭된 규칙 줄과 실제 출구 노드가 한 화면에 놓입니다. HTTP/3·QUIC가 선호되면 UDP가 GEOIP 아래로 새어 다운로드만 간헐적으로 실패하는 패턴도 보이므로 TUN 스택 선택은 TUN 가이드와 gvisor·system 비교를 함께 보는 편이 낫습니다.
왜 Kiro CLI·npm 조합은 TUN을 기본 전제에 두는가
Node.js 기반 도구는 운영체제마다 시스템 프록시를 읽는 방식이 들쑥날쑥하고, macOS 키체인·Windows WPAD·IDE가 띄운 셀은 서로 다른 env를 물려받습니다. 사용자가 Mixed 포트에만 의존하면 브라우저는 프록시를 타도 패키지 패치는 반쯤 DIRECT인 착각이 생깁니다. Clash TUN은 커널이 가상 NIC로 트래픽을 받아 규칙 트리를 공유하므로 애플리케이션이 프록시를 “알 필요”가 줄어듭니다. AWS SSO는 OIDC 루프에서 oidc.aws.amazon.com·signin.aws.amazon.com류와 STS·퍼블리셔 CDN이 연쇄로 열리므로, 브라우저만 다른 DNS 축을 쓰고 터미널만 코어 FakeIP를 쓰면 문자열은 같아 보여도 패킷 패밀이 갈라집니다.
회사 노트북에서는 제로 트러스트 에이전트나 사내 VPN이 TUN과 라우팅을 겹칠 수 있어, 드라이버 충돌 시점을 로그에 적어 보안팀과 공유할 수 있게 준비해야 합니다. 본문은 허가된 장비에서만 적용한다는 전제를 둡니다.
글의 범위
Kiro CLI의 공식 명령 표·과금·모델 선택 UI는 AWS 문서가 우선입니다. 여기서 다루는 것은 네트워크 레이어에서의 재현 절차뿐이며, IAM 정책·SCP·세부 포트 허용은 각 조직 규정을 따릅니다. 예시 도메인 문자열은 시점에 따라 바뀔 수 있으니 로그 기반 목록으로 치환해 사용해야 합니다.
1호스트 목록: npm·AWS OIDC·STS·CDN을 한 번에 적기
설치·업데이트 명령을 다시 돌리기 전에 실패 줄에 찍힌 이름을 빠짐없이 옮깁니다. npm은 registry.npmjs.org 외에 tarball이 놓인 버킷·jsdelivr·unpkg 계열, 팀 미러 문자열까지 한 흐름에 등장할 수 있습니다. AWS SSO 관련 후보로는 OIDC·로그인 포털 호스트, 리전별 sts·콘솔 API, 플러그인 마켓이 부르는 CloudFront 같은 이름이 붙습니다. 문자열마다 Clash 로그에서 첫 매칭 규칙과 정책 그룹을 적어 두면 이후 수정이 한 변수씩 줄어듭니다.
# Example — hosts and timeouts vary; widen -m on stalls
curl -v -m 25 https://registry.npmjs.org/
curl -v -m 25 https://oidc.aws.amazon.com/
curl -v -m 25 https://sts.ap-northeast-2.amazonaws.com/연속 두 번 실행하면 DNS 캐시 의존과 url-test 노드 교체에 따른 지연 변동을 분리할 수 있습니다. RST·리셋 패턴은 연결 리셋 로그 글의 표현을 참고하세요.
2TUN 켜기와 예외 라우팅
클라이언트에서 TUN을 활성화한 뒤 사내 허브·프린터·인트라넷 대역은 규칙 최상단에 DIRECT나 전용 노드로 명시합니다. Windows는 초기 설치 흐름을 윈도우 설치 글과 맞춰 두면 방화벽·서비스 모드 변수가 줄어듭니다. Apple Silicon Mac은 서명·헬퍼 이슈를 Apple Silicon 설치 글과 함께 점검하면 TUN 재시도가 수월합니다.
3분류 초안: AWS·npm 패밀리를 같은 정책 그룹으로
거대 RULE-SET을 직접 고치기 부담스러우면 mixin으로 사용자 조각만 덧붙입니다. 관측한 접미사를 GEOIP·MATCH보다 위에 두고, 한 번에 하나의 selector 노드에 고정해 세션 중 출구가 바뀌지 않게 합니다.
# Illustration — replace PROXY_AWS; keep above catch-all RULE-SET
rules:
- DOMAIN-SUFFIX,amazonaws.com,PROXY_AWS
- DOMAIN-SUFFIX,aws.amazon.com,PROXY_AWS
- DOMAIN-SUFFIX,npmjs.org,PROXY_AWS
- DOMAIN-KEYWORD,cloudfront,PROXY_AWS
- MATCH,DIRECT참고: 리전·엔드포인트 이름은 계정 설정에 따라 다릅니다. 위 예시는 패턴용이며 실제 문자열은 로그에서 복사해 상단에 두세요.
nameserver-policy로 OIDC·콘솔 DNS 축 맞추기
fake-ip 모드에서 OIDC 호스트만 이상한 resolver로 가면 브라우저와 코어가 서로 다른 응답을 캐시합니다. nameserver-policy로 특정 접미사에 신뢰 DoH·ISP DNS를 지정하는 절차는 nameserver-policy 가이드를 따르는 것이 안전합니다. 이때 브라우저 Secure DNS와 동시에 켜두면 또 다른 축이 생기므로 디버깅 동안에는 한쪽을 잠시 끄고 변수를 나누세요.
fake-ip-filter와 스니퍼 교차 오류 피하기
LAN·직통 호스트가 FakeIP에 잡히면 SSO 루프가 이상하게 보입니다. fake-ip-filter 글과 HTTPS 스니퍼 글을 순서대로 적용해 동일한 도메인 문자열을 스니퍼·규칙·resolver가 공유하는지 확인합니다.
4검증: aws sso login 후 npm·CLI 재실행
aws sso login 또는 조직이 안내하는 동등한 인증 흐름을 먼저 통과시킨 뒤, 동일 터미널에서 npm install·Kiro 관련 업데이트 명령을 다시 실행합니다. 문제 격리 구간에는 url-test 자동 전환을 잠시 끄고 fallback 가이드의 권장 순서로만 되돌립니다. 패널 로그에서 첫 줄 매칭·노드 이름·지연이 npm 단계와 OIDC 단계에서 동일한지 비교하면 “한쪽만” 고장 난 것이 실제로는 DNS 불일치인지 빠르게 갈립니다.
WSL2·컨테이너·원격 개발 박스
호스트 OS의 TUN 결과가 게스트에 자동 전파되지 않습니다. Windows에서 WSL2를 쓰면 Mixed 포트 전달·게이트웨이 별도 정의가 필요하므로 WSL2·Git·npm 연계 글과 조합해야 합니다. Dev Container 안이라면 컨테이너 DNS와 호스트 Clash DNS가 또 다른 축이 될 수 있어 동일한 “한 번에 한 변수” 원칙을 유지하세요.
편집기 확장·레지스트리만 프록시할 때의 함정
일부 팀은 npm 프록시 환경 변수만 설정하고 끝내려 하지만 postinstall 스크립트·네이티브 모듈 프리빌드 URL은 같은 변수를 따르지 않습니다. 반대로 사내 정책상 특정 AWS 호스트는 반드시 DIRECT여야 할 수도 있습니다. 이때는 문자열별 예외를 규칙 상단에 명시하고 문서화해 재현성을 높입니다. 범용 AI 편집기 트래픽 패턴은 Cursor·GitHub·npm 분류 글과 비교하면 중복 점검을 줄일 수 있습니다.
자가 진단 체크리스트
- 실패 시각 기준으로 npm·OIDC·STS·CDN FQDN 전체를 목록화했는가.
- 각 FQDN의 첫 규칙 매칭과 정책 그룹·노드 이름을 로그에 적었는가.
- TUN on/off에 따라 증상이 바뀌는가 바뀌지 않으면 인증서·사내 CA 쪽을 분리 검토했는가.
- 브라우저 DoH와 코어 DNS를 동시에 바꾸지 않았는가.
- aws 인증 단계와 npm 단계 테스트를 분리해 같은 타임라인으로 재현했는가.
FAQ
Amazon Q 브랜드 명령과 Kiro 패키지 이름이 헷갈립니다.
릴리스 시점마다 패키지 스코프·바이너리 이름이 바뀔 수 있습니다. 문서에 적힌 설치 문자열을 그대로 verbose 로그와 함께 보관하고, 레지스트리에서 실제 tarball URL이 어디로 향하는지만 추적하면 네트워크 층 디버깅에 충분합니다.
로그·토큰 공유 주의
SSO 세션 줄·임시 토큰은 티켓에 붙이기 전에 마스킹하고, 조직 정책이 금지하는 패킷 덤프는 수행하지 마세요.
준수: 프록시 우회는 보안 정책 범위 안에서만 적용하고, 고객 데이터·프로덕션 계정 테스트는 별도 가드레일을 따르세요.
맺음말
Kiro CLI로의 이행은 기능 소개와 별개로 네트워크 전제가 바뀌지 않으면 npm install timeout·AWS SSO 루프만 반복해 체감 신뢰를 떨어뜨리기 쉽습니다. 패킷을 TUN 아래에서 한 라우팅 축으로 모으고, 관측 기반 FQDN을 규칙 상단에 고정하며, nameserver-policy와 fake-ip-filter를 동시에 흔들지 않는 순서가 가장 설명 가능했습니다. DNS·규칙·노드 자동 전환을 각각 분리해 기록하면 재발 시 같은 스크립트로 복구할 수 있습니다.
범용 클라이언트는 YAML 직편집과 터미널 환경 변수를 반복해야 해 실수 여지가 큽니다. Clash 계열은 패널에서 DNS·TUN·프로파일을 바꾸며 실험하기 쉬워 CLI·npm·SSO가 겹치는 시나리오에 특히 잘 맞습니다. 아직 사용하지 않았다면 Clash 앱 무료 다운로드로 설치한 뒤 본문 순서를 그대로 따라가며 동일 테스트를 비교해 보세요.