브라우저로 docs.openclaw.ai는 보이는데 OpenClaw CLI만 게이트웨이에 붙지 않습니다.

브라우저는 시스템 프록시를 따르지만 Node 기반 CLI는 DIRECT로 나가는 경우가 많습니다. TUN을 켜거나 터미널에 HTTPS_PROXY를 주입한 뒤 Connections에서 openclaw·node 프로세스가 동일 출구를 통과하는지 확인하세요.

npm install은 되는데 특정 스코프나 tarball만 실패합니다.

메타데이터와 실제 tarball CDN이 서로 다른 규칙에 걸리면 일부 패키지에서만 ECONNRESET이 납니다. verbose 로그로 tarball URL을 확인해 CDN 호스트를 레지스트리와 같은 정책 그룹에 묶으세요.

OpenClash를 쓰는 집에서 PC Clash도 켜면 더 불안정해집니다.

이중 NAT·이중 TUN이 겹치면 MTU·라우팅 충돌이 납니다. 한 단만 TUN을 담당하고 다른 쪽은 HTTP 프록시 모드로 정리하거나, PC는 라우터 DNS·DHCP만 따르도록 출구를 하나로 고정하세요.

OpenClaw·CLI·타임아웃? Clash 안정화

어떤 호스트가 동시에 터지나요

설치 직후 가장 먼저 나오는 불만은 문서·가이드 페이지를 열지 못한다는 것입니다. 검색 키워드에 docs.openclaw.ai가 붙는 이유도 여기 있습니다. 브라우저에서만 문서 열림이 깨져 보이면 캐시·광고 차단부터 의심하지만, OpenClaw CLI가 가져오는 같은 도메인의 JSON·링크 검증이 따로 타임아웃한다면 패턴이 갈립니다. 둘째 축은 모델·추론 게이트웨이 또는 제어 평면이라 부르기 쉬운 장시간 TCP·TLS 스트림입니다. 문서에서는 “게이트웨이 handshake”처럼 한 줄 로그만 보이더라도, 실체는 DNS·좁아진 출구 중 하나가 느린 경우가 많습니다. 셋째는 npm과 사내 레지스트리 미러처럼 패키지 메타데이터·tarball CDN이 섞이는 축입니다. 넷째는 GitHub의 api.github.com, 오브젝트 스토리지, 릴리스 자산 URL처럼 API와 대용량 바이너리를 동시에 다루는 축입니다. 이 네 축을 머릿속에서 나눈 뒤에야 분류 규칙을 써도 덜 흔들립니다.

한 줄 요약

“한 번에 다 막힌다”가 아니라 문서는 되는데 npm만, 혹은 게이트웨이만 같은 식이면 대부분 호스트 단위 출구 분리 문제입니다. 추측한 도메인 리스트를 복붙하지 말고 Connections 로그를 단일 출처로 삼으세요.

시스템 프록시만으로는 왜 부족한가요

macOS·Windows에서 “시스템 프록시 사용”을 켜도 터미널에서 돌아가는 Node 프로세스는 환경에 따라 DIRECT로 국내 회선·사내망에 그대로 붙습니다. Safari나 Chrome은 정상인데 OpenClaw CLI만 지연되거나 인증서 검증 관련 에러 문자열이 뜬다면 전형적인 케이스입니다. 회사 디바이스에서 SSL 검사 미들웨어를 쓸 때는 브라우저에 신뢰 저장소만 주입되어 있고, CLI 런타임은 회사 프록시를 모르거나 다른 CA 체인을 보는 경우도 있습니다.

분리된 프로세스 트리: 에디터·터미널·백그라운드 데몬이 각자 프록시 정책을 읽습니다.
동시 다발 요청: 문서 프리패치와 npm install 병렬이 겹치면 한 노드의 큐가 막히기 쉽습니다.
환경 변수 누락: HTTPS_PROXY를 쉘에는 넣었는데 CI 파이프라인이나 GUI가 띄운 자식에는 비어 있는 식입니다.

그래서 2026년 개발자 프록시 검색 패턴에서는 “브라우저 확장 하나”보다 TUN 모드 또는 전역 규칙으로 CLI까지 덮기가 자주 따라붙습니다. Clash Verge Rev를 쓰는 경우 자동 스타트업·시스템 프록시 토글·TUN 권한이 한 화면에 모여 있다는 점이 실무에서는 편합니다. 다만 TUN은 가내 라우터의 다른 VPN·멀티 WAN과 충돌할 수 있으니 뒤 절차에서 분리 원칙을 같이 적용합니다.

1단계: 트래픽을 ‘문서·게이트웨이·npm·GitHub’로 나누기

규칙을 쓰기 전에 실제로 맞는 호스트를 모읍니다. 첫째 그룹은 문서·온보딩·설정 페이지에 해당하는 호스트입니다. 검색 결과에 많이 노출되는 docs.openclaw.ai 문자열 주변처럼, 제품 업데이트 시 서브도메인이 추가될 수 있으므로 릴리스 노트 확인과 로그 교차 검증을 권장합니다. 둘째는 OpenClaw가 붙는 게이트웨이 또는 제어 채널로 추정되는 API·스트림 엔드포인트입니다. 문서 표기 이름과 실제 SNI 문자열은 다를 수 있습니다. 셋째는 npm 기본 레지스트리·스코프 전용 레지스트리 URL·실제 tarball이 들어 있는 CDN 도메인입니다. 넷째는 GitHub 본관·GraphQL·오브젝트 스토리지·패키지·릴리스 자산처럼 같은 ‘GitHub 작업’ 안에서도 패턴이 다른 하위 호스트 묶음입니다.

이후 각 묶음에 정책 그룹 이름을 하나씩 배정합니다. 예를 들면 DOCS-WEB, AI-GW, PKG-CDN, GITHUB처럼 운영자가 기억하기 쉬운 태그를 쓰고, 그룹 내부 노드는 서로 다른 품질 기준을 둡니다. 장시간 스트림과 짧지만 많은 패키지 요청을 한 그룹에 억지로 넣으면 자동 테스트 그룹이 공격적으로 돌며 세션이 깨지고 “문서 접속 타임아웃”처럼만 보입니다.

2단계: Connections 로그로 실제 문자열 채우기

Clash·Mihomo 대시보드의 Connections에서 프로세스 열과 목적지를 추적합니다. OpenClaw CLI 바이너리 이름, Node 기반 플러그인 래퍼, npm, git 자식까지 한 작업 줄에서 동시에 뜨면 서로 다른 호스트로 갈 가능성을 염두에 둡니다. Windows에서는 WSL 안의 패키지 설치와 호스트 바깥 패키지 설치 경로가 갈립니다만, WSL2 네트워킹 가이드를 같이 읽으면 이중 스택 점검이 수월합니다.

예시 카테고리(환경마다 다르니 교차 확인 필요)

문서와 정적 자산이 놓인 문서 호스트 패턴(.ai 루트·서브 포함).
모델·게이트웨이 호스트(제품 문서 또는 릴리스에 따름).
registry.npmjs.org와 tarball CDN 서브도메인.
api.github.com, GitHub 패키지·오브젝트 호스트 문자열 일체.

아래 블록은 스켈레톤 예시입니다. 실제 이름은 각자 구성의 proxy-group에 맞춰 바꾸고 행 순서와 도메인은 로그 근거로 채워야 합니다.

# Skeleton rules — align group names with your profile; verify hostnames via logs
rules:
  - DOMAIN-SUFFIX,registry.npmjs.org,PKG-CDN
  - DOMAIN-SUFFIX,npmjs.org,PKG-CDN
  - DOMAIN-SUFFIX,docs.openclaw.ai,DOCS-WEB
  - DOMAIN-SUFFIX,github.com,GITHUB
  - DOMAIN-SUFFIX,githubusercontent.com,GITHUB
  - DOMAIN-KEYWORD,example-gateway.invalid,AI-GW
  - MATCH,DIRECT

분류 규칙은 위에서 아래로 첫 매칭이 승자입니다. 거대 RULE-SET을 붙였다면 내부에 이미 GITHUB나 OpenAI류 패턴이 있는지부터 읽어야 로컬 오버라이드가 덮이는 위치인지 알 수 있습니다. DOMAIN-KEYWORD,git처럼 지나치게 넓은 행은 예기치 않은 트래픽까지 끌고 와 느린 출구 하나에 몰림을 만들므로 가능하면 DOMAIN-SUFFIX와 구체 문자열 위주가 안전합니다.

3단계: 게이트웨이 스트림과 fat download 노드 분리

게이트웨이 레이턴시는 순간 순위가 높아도 장시간 대화에서는 지터와 세션 교체 빈도가 체감에 더 크게 들어옵니다. 반대로 npm 클래스는 많은 바이트를 짧게 쏟아내고 간헐적으로 큰 파일을 받습니다. url-test가 짧은 주기로 회전하면 스트림만 끊기고 패키지는 살아 있거나 반대 패턴도 나옵니다. 그래서 모델·게이트웨이 스트림에는 네트워크가 덜 들쭉날쭉한 노드를 장시간 고정하고, npm·CDN에는 처리량 우선 또는 재시도에 강한 노드를 따로 둔 뒤, GitHub API는 레이트 리밋 때문에 출구 IP가 자주 바뀌면 곤란하니 그룹을 또 나누는 운영이 많습니다.

구간	노드에 바라는 성질	자주 생기는 실수
문서 HTTPS	TTFB와 TLS 완료가 빠르고 캐시 친화	FAT 패키지용 느린 노드만 남김
OpenClaw 게이트웨이	플랫한 RTT와 안정적인 세션	패키지 테스트와 같은 그룹 공유
npm 레지스트리	다운로드 폭발·재시도에 강함	tarball 도메인 누락으로 부분 성공
GitHub 복합	API와 오브젝트가 같은 정책으로 나감	직접만 나가도록 남긴 패턴

4단계: DNS·fake-ip와 ‘인증서 이상해 보임’ 줄이기

TLS 핸드셰이크 타임아웃 메시지만 보면 노드 불량으로 결론 내기 쉬운데, 실제 원인은 DNS와 IPv6 선택인 경우도 많습니다. Clash 계열에서 fake-ip를 쓸 때 일부 스택은 이름과 인증서 산 출처가 불일치해 보였다가 끊기는 패턴으로 보입니다. DNS·fake-ip 가이드 순서처럼 한 번에 변수 하나만 고정해서 재현을 줄이세요. 회사 또는 학교에서는 제로 트러스트 에이전트가 시스템 DNS를 덮어쓰므로,OpenClaw CLI 프로세스가 어떤 리졸버를 읽는지가 문서 접속 장애의 숨은 변인이 됩니다.

AAAA 우선 문제: IPv6 회선만 막히는 경우 CLI만 멈춘 것처럼 보입니다.
스플릿 호라이즌 VPN: 문서 호스트만 VPN으로 라우팅된다면 패키지는 다른 회선이라 인증 플로가 갈립니다.
중간 검사 장비: 브라우저에 깔린 사용자 정의 신뢰 앵커 없이 CLI가 도메인 검증 실패 문자열을 냅니다.

주의

예시 호스트 문자열과 그룹 이름은 이해를 돕기 위한 목적입니다. OpenClaw 제품 업데이트 후 실제 문자열은 달라질 수 있으니 반드시 연결 로그로 확정하세요.

5단계: TUN·HTTP_PROXY·터미널 동선 확정

브라우저와 CLI를 동일 출구에 올리는 실무 패턴은 대략 두 갈래입니다. 첫째, 데스크톱 앱에서 TUN 모드를 켜 전 OS 트래픽 중 필요한 레이어만 Clash 매트릭스로 들이미는 방법입니다. Clash Verge Rev는 권한·스타트 순서까지 GUI로 노출되어 시행착오가 적은 편입니다. 둘째, 특정 세션만 HTTPS_PROXY·ALL_PROXY로 국한하는 방법입니다. Git은 http.proxy를 노드가 따르지만 Node 패키지는 환경 변수를 무시하고 기업 프록시만 별도 변수를 읽기도 해서,같은 셸에서 문서 크롤링과 패키지 설치 로그가 서로 다른 경로인지 대조해야 합니다. 패턴 깊이 있는 설명은 터미널·git 프록시 가이드와 맞먹습니다.

컨테이너 안에서 CLI를 실행한다면 빌더 이미지에 프록시가 비어 있는지까지 내려가야 간헐 실패만 남지 않습니다. CI에서는 시크릿으로 주입되는 프록시 URL과 회사 허용 egress 리스트 불일치로 일부 패키지만 403 또는 긴 대기 후 타임아웃이 나오기도 합니다.

6단계: OpenClash·가내 라우터와 함께 쓸 때

가내 라우터에 OpenClash를 깔아 전 세대 장치까지 우회하면 편하지만 PC에서 또 Clash TUN을 켜면 이중 터널링, MTU 감소·루프·DNS 이중 처리가 발생할 수 있습니다. 실무에서는 “어느 한 지점만 TUN”으로 고정합니다. 예를 들어 라우터가 패밀리 DNS와 아이패드까지 커버한다면 노트북은 HTTP 프록시 모드 또는 PAC만 받고 라우팅 우선순위를 정렬합니다. 반대로 PC가 개발 규칙을 세밀히 쓰고 라우터는 ISP 기본이라면 라우터 쪽 과도 필터링을 줄입니다. 회사에서는 정책상 라우터를 못 고치므로 PC 전용 패턴만 다룹니다.

증상별로 의심할 순서

브라우저 문서는 되고 CLI 패치 체크만 실패합니다

문서 페이지가 정적 HTML만 가져오는 반면 업데이터가 다른 서브패스 또는 JSON을 받는 분기가 숨었을 때가 있습니다. 해당 분기 문자열만 국내 회선 DIRECT로 남은 경우 패턴입니다.

문서 접속 타임아웃과 게이트웨이 지연이 교대합니다

DNS 교착 상태, 자동 failover 주기 과도함, NAT 세션 초과가 서로 교대 증상을 만듭니다. Connections에서 패킷이 어느 그룹에 붙었다 떼어졌는지 타임라인으로 보면 원인 분리가 쉬워집니다.

글로벌 패키지는 되는데 스코프 패키지만 끊깁니다

스코프가 가리키는 레지스트리와 tarball 호스트 분리 때문에 자주 발생합니다.

자주 묻는 질문

Clash만 말하면 되나요 Mihomo 명도 같이 봐야 하나요?

커맨드와 YAML은 계열 이름이 바뀌어도 Mihomo 기반 클라이언트가 많습니다. 기능적으로는 같은 축이라 UI만 다르다고 보아도 되고,Clash Verge Rev는 이런 구성 검색 의도와 잘 묶입니다.

CLI에서 인증서 경고 문자열과 게이트웨이 지연이 같이 옵니다

미들보스 검사 또는 사내 브레이킹 포인트 때문일 때가 많습니다. 브라우저가 이미 회사 신뢰 앵커를 쓰도록 되어 있는지, Node CA 번들에는 없는지 비교해야 합니다. 동시에 OpenClaw CLI 게이트웨이 호스트 문자열 자체가 잘못된 프록시 행으로 가는 문제도 교차 검증하세요.

npm은 되고 Git clone·릴리스만 느립니다

GitHub API와 객체 스토리지가 다른 정책 그룹이면 패턴적으로 보입니다.

실무 체크리스트

OpenClaw·문서·패키지·git 자식별 Connections 문자열 저장.
문서 호스트 패턴, 게이트웨이, 레지스트리·CDN, GitHub 패턴 각각 프록시 그룹 결정.
DNS 모드와 IPv6 상태를 하나로 고정해 재현 테스트.
스트림 노드와 fat download 노드 분리 또는 자동 전환 완만화.
TUN 또는 HTTPS_PROXY 적용 후 CLI와 브라우저가 같은 경로인지 검증.
가내 라우터 OpenClash와 PC 세트앱 간 이중 우회 회피.

정리와 제품 관점에서의 선택

일부 초경량 프록시 또는 브라우저 특화 우회 확장만으로는 문서 접속 속도 같은 좁은 지표는 맞춰도,OpenClaw CLI가 동시에 쓰는 게이트웨이·패키지·GitHub 레이어를 한 줄로 설계하기 어렵습니다. DNS와 TLS가 얽힐 때는 간헐 오류처럼만 보여 재현이 힘든데 이때 Clash 계열 분류 규칙·DNS·정책 그룹이 한 번에 깔리는 장점이 큽니다.Mihomo 사용자라도 동작 축은 같고 노드 선택만 업무 패턴과 맞추면 검색량이 늘고 있는 ‘2026 CLI 에이전트’ 스택 불만을 줄이기 쉽습니다.

비슷한 주제가 필요하면 이미 정리된 OpenCode CLI·npm·GitHub 라우팅, Codex 라우팅, OpenClash 패밀리 프록시 글과 같이 두고 읽히는 편입니다.

개발 트래픽을 한 번 정리하고 싶다면 Clash를 무료로 내려받아 앞 단계 순서 그대로 실험해 보실 수 있습니다

OpenClaw CLI와 게이트웨이·문서·npm이 자주 타임아웃될 때 2026년 Clash 분류로 안정화하기