OpenHands 의존성·Docker 설치가 반복 타임아웃될 때: Clash TUN·분류·DNS로 GitHub·Docker Hub·npm·모델 API를 한 축에 맞추기 (2026)

먼저 다섯 층으로 나누기: GitHub·Docker·npm·모델 API·런타임 CDN

터미널·Docker 로그에는 모두 “다운로드 중”으로 보이지만 실패 지점은 다섯 갈래입니다. 첫째 GitHub—github.com·api.github.com·raw.githubusercontent.com·objects.githubusercontent.com 등 저장소·API·LFS·Actions 아티팩트. 둘째 컨테이너 레지스트리—registry-1.docker.io·auth.docker.io·production.cloudflare.docker.com, 이미지가 ghcr.io에 있으면 해당 FQDN까지. 셋째 npm registry와 tarball CDN—UI·에이전트 런타임의 npm ci·pnpm 구간. 넷째 추론 모델 API—api.anthropic.com·api.openai.com·generativelanguage.googleapis.com 등 OpenHands 설정의 제공자별 호스트. 다섯째 샌드박스·브라우저 자동화가 쓰는 추가 HTTPS·WebSocket—문서에 없는 하위 도메인이 로그에만 나타나는 경우가 많습니다. 한 층만 고치면 나머지에서 다시 “OpenHands 전체가 망가졌다”는 인상을 받기 쉽습니다.

docker compose pull·make build·첫 Agent 세션 직후 Clash Connections에서 완전한 호스트명·첫 매칭 규칙·최종 정책 그룹을 적어 두세요. 연결이 없으면 트래픽이 Meta 코어에 안 들어오거나 다른 VPN·ZTNA가 가로챈 것입니다. DIRECT로만 보이면서 RTT가 튀면 해당 클러스터를 넓은 국내 직연결 위에 올려야 합니다.

브라우저·git은 되는데 Docker pull·컨테이너 npm만 실패하는 이유

데스크톱 브라우저와 git clone은 PAC·시스템 HTTPS 프록시를 잘 따르지만, dockerd·rootless Docker·compose가 띄운 컨테이너·백그라운드 Node는 HTTPS_PROXY가 비어 있거나 자식만 직연결·회사 MITM 인증서 미신뢰로 TLS가 먼저 깨지고 구두로는 “타임아웃”이라 부르기도 합니다. HTTP/3·QUIC은 TCP 프록시만 있는 환경을 우회합니다. Mixed Port는 환경 변수를 존중하는 셸에는 유효하지만 OpenHands 스택이 동시에 여는 프로세스·컨테이너에는 불안정합니다. TUN은 라우팅 계층에서 패킷을 보이게 해 작성한 분류 규칙과 실제 출구를 맞춥니다.

macOS·Windows의 Docker Desktop은 VM 안에서 pull이 일어나 호스트 TUN과 경로가 어긋날 수 있습니다. 증상이 pull에만 국한되면 VM·WSL 쪽 라우팅을 WSL2·Git·npm 연계와 함께 점검하세요. Linux 네이티브 dockerd는 호스트 TUN과 동일 스택을 공유하는 경우가 많아 규칙만 맞추면 개선되는 비율이 높습니다.

이 글이 다루는 범위

OpenHands 버전·모델명·요금·기능 스위치는 공식 저장소 릴리스를 따릅니다. 여기서는 외부 네트워크 표면만 다룹니다. 아래 YAML·curl은 패턴 예시이며 실제 문자열은 본인 Connections 기준으로 바꿉니다. ghcr.io·사내 미러·프라이빗 레지스트리 FQDN은 시점·조직마다 다르니 정적 목록만 외우지 마세요.

1로그로 다섯 층의 호스트 관측

GitHub: github.com, api.github.com, 릴리스·서브모듈·토큰 검증에 쓰이는 OAuth·CDN 하위 도메인. Docker: registry-1.docker.io, auth.docker.io, compose에 적힌 image: 레지스트리 호스트. npm: registry.npmjs.org, *.npmjs.org·사내 Nexus. 모델 API: 설정 파일·환경 변수의 제공자별 API 호스트와 302 체인. 런타임: 샌드박스·Playwright 등 verbose 로그의 URL. 호스트 터미널 오류·docker compose 출력·컨테이너 exec curl 직후 연결 패널 타임스탬프를 맞춥니다.

# Example — replace hosts; increase -m on slow paths
curl -v -m 25 https://api.github.com/
curl -v -m 25 https://registry-1.docker.io/v2/
curl -v -m 25 https://registry.npmjs.org/
curl -v -m 25 https://api.anthropic.com/
curl -v -m 25 https://api.openai.com/

2TUN 켜기와 dockerd·터미널 동시 확인

Meta 계열 클라이언트에서 TUN·규칙 모드를 켠 뒤 드라이버·Helper 권한을 마칩니다. Clash Verge Rev TUN 가이드를 먼저 통과하고, 스택은 gvisor·system 비교를 참고하세요. 같은 세션에서 docker compose pull과 호스트 npm·첫 Agent 작업을 연 뒤 Connections에 dockerd·node·python 등 프로세스가 보이는지 확인합니다. 사내 VPN·ZTNA와 기본 라우트가 겹치면 예외·fake-ip-filter로 내부 미러·프라이빗 레지스트리를 먼저 고정하세요.

3분류 규칙 초안 — GITHUB·DOCKER·PKG·AI_API 묶음

거대 RULE-SET·GEOIP 위에 Mixin으로 사용자 조각을 덧붙이는 편이 안전합니다. 관측 호스트를 같은 정책 그룹(예: GITHUB_PROXY·DOCKER_PROXY·PKG_PROXY·AI_API)에 넣어 클론·이미지 pull·npm 설치·추론이 첫 프레임부터 출구를 바꾸지 않게 합니다.

# Illustration — replace group names; order above catch-all GEOIP/MATCH
rules:
  - DOMAIN-SUFFIX,github.com,GITHUB_PROXY
  - DOMAIN-SUFFIX,githubusercontent.com,GITHUB_PROXY
  - DOMAIN-SUFFIX,docker.io,DOCKER_PROXY
  - DOMAIN-SUFFIX,docker.com,DOCKER_PROXY
  - DOMAIN-SUFFIX,ghcr.io,DOCKER_PROXY
  - DOMAIN-SUFFIX,registry.npmjs.org,PKG_PROXY
  - DOMAIN-SUFFIX,npmjs.org,PKG_PROXY
  - DOMAIN-SUFFIX,anthropic.com,AI_API
  - DOMAIN-SUFFIX,openai.com,AI_API
  - DOMAIN-SUFFIX,googleapis.com,AI_API
  - MATCH,DIRECT

Docker·npm 프록시와 TUN

호스트 /etc/docker/daemon.json의 proxies·compose environment의 HTTP_PROXY·npm config get proxy를 확인합니다. TUN ON 상태에서 이중 프록시가 TLS를 깨는지 비교하세요. 컨테이너만 실패하면 docker compose exec 안에서 동일 curl 프로브를 돌리고, 호스트와 컨테이너가 다른 DNS를 쓰는지 봅니다. 기업은 승인된 Harbor·Nexus·직통 정책을 우선합니다.

4다중 제공자 모델 API — 장시간 스트리밍과 노드 고정

OpenHands는 작업 중 Claude·OpenAI·Google 등 제공자를 바꿀 수 있어 짧은 REST와 긴 스트리밍·도구 호출이 섞입니다. url-test가 세션 중 노드를 바꾸면 끊긴 것처럼 보이므로 디버깅 중에는 selector로 AI_API 그룹을 고정하세요. Claude Code CLI·Codex CLI·Gemini CLI·Symphony·Linear·Codex API 글과 같은 패턴이며 호스트 목록만 OpenHands 세션 로그로 갱신하면 됩니다.

5DNS·FakeIP·스니퍼

규칙에 DOMAIN을 썼는데 DNS 모듈이 다른 경로로 풀면 “DIRECT인데 이상하다”는 착시가 납니다. DNS 유출 방지·fake-ip-filter·nameserver-policy로 GitHub·Docker·모델 API 이름을 규칙과 일치시키고 변경은 한 축씩만 하세요. 브라우저 DoH가 코어 DNS를 덮지 않게 합니다.

검증 — 전체 빌드 대신 가벼운 프로브

매번 docker compose up --build로 부딪치지 말고: (1) api.github.com·registry-1.docker.io curl -Iv, (2) 호스트·컨테이너 각각 registry.npmjs.org, (3) 설정된 제공자 API 헬스 경로. TUN ON 후에도 안정적 직연결 타임아웃이면 MTU·인증서·회선 쪽을 의심합니다. 첫 Agent가 샌드박스에서 외부 URL을 열면 로그에 새 FQDN이 찍히므로 규칙을 한 줄씩 보강하세요.

OpenHands 배포 간이 체크리스트

1. 다섯 층(GitHub·Docker·npm·모델 API·런타임) 중 어느 단계에서 멈췄는지 로그로 구분했는가.
2. 호스트·컨테이너·브라우저가 각각 다른 출구를 쓰지 않는가.
3. 관측 FQDN이 규칙 트리 어디서 첫 매칭되는가.
4. TUN ON/OFF로 pull·npm·API 증상이 근본적으로 바뀌는가.
5. 한 번에 한 설정만 변경했는가.

자주 묻는 질문

compose pull만 실패하고 git clone은 되는 경우

DOCKER_PROXY에 없는 인증·CDN 하위 도메인이거나 Docker Desktop VM이 호스트 TUN 밖에 있을 수 있습니다. pull 시각의 Connections 전체 FQDN을 규칙에 추가하세요.

컨테이너 안 npm만 실패

compose 네트워크·프록시 환경·내부 DNS를 점검하고, 필요 시 컨테이너에 호스트와 동일한 프록시 정책을 넣거나 TUN 중심으로 호스트 라우팅을 통일하세요.

정책·약관

조직 네트워크·클라우드 데이터 처리 지침을 지키고 API 키·작업 로그를 공개 채널에 올리지 마세요.

맺음말

OpenHands·OpenDevin 계열 배포는 GitHub·Docker Hub·npm·다중 모델 API가 동시에 열립니다. 브라우저만 프록시를 타면 반쯤 성공 상태가 반복되므로 TUN으로 dockerd·터미널·컨테이너를 한 파이프에 올리고, 로그 기반 분류 규칙과 DNS를 같은 축에서 맞추는 것이 재현성이 가장 높습니다. Cline·Copilot CLI 글에서 익힌 순서를 그대로 쓰되 호스트 목록만 OpenHands·compose 세션 로그로 갱신하세요.

범용 프록시 도구는 터미널·Docker·컨테이너마다 환경 변수를 복사해야 해 한쪽만 고치면 다른 쪽이 다시 타임아웃됩니다. Clash Meta 클라이언트는 구독·규칙·Connections를 한 화면에서 보며 다섯 층을 동시에 대조할 수 있습니다. 아직 쓰지 않았다면 Clash 클라이언트를 무료로 받아 본문 순서대로 TUN·규칙·DNS를 맞춘 뒤 compose pull·npm 설치·첫 Agent 추론이 같은 출구로 안정하는지 비교해 보세요.