Windows에서 Docker Desktop과 WSL2로 OpenClaw를 실행할 때 설치 마법사가 멈추거나, 토큰 URL이 뜨지만 도달하지 않거나, 컨테이너는 running인데 호스트 CLI가 프로브에 실패하거나, 업그레이드 후 바이너리와 컨테이너 버전이 어긋나는 증상을 다룹니다. 사내 티켓에 붙일 수 있는 점검표이며, Windows·macOS·Linux 설치 총람, Compose 페어링(1006/1008), GHCR 이미지와 Control UI, Gateway doctor 분류, 그리고 SSH 로컬 포워딩으로 원격 Gateway와 macOS 네이티브 경로와 역할을 나눕니다. 공식 Gateway 문제 해결은 OpenClaw Gateway Troubleshooting을 참고하세요.
docker compose up이 공존해 이중 Gateway나 문서에 나온 루프백 포트 경합(openclaw gateway status로 확인).openclaw --version과 컨테이너 CLI 불일치로 doctor 경고가 모델 장애로 읽힘.개념 투어가 아니라 Windows와 Docker에 대한 실행 가능한 분류입니다. macOS, Linux systemd, Tailscale Runbook과 같은 검증 사다리를 쓰지만 호스트 책임은 다릅니다.
이미 무응답·모델 오류 Runbook을 보고 있다면, 본문을 모델·채널 층에 들어가기 전 선행 조건으로 취급하세요.
현업에서는 WSL 배포판 버전과 Docker Desktop 채널이 엇갈리면서 동일한 compose 파일이라도 내부 DNS만 바뀌는 경우가 잦습니다. 이때 OpenClaw를 재설치하기 전에 wsl --shutdown 후 재기동, 사내 VPN이 vEthernet에 미치는 영향을 먼저 배제하면 불필요한 재작업을 줄일 수 있습니다.
토큰과 gateway.auth의 단일 출처를 Runbook에 박아 두지 않은 채 여러 사람이 만지면 ‘내 노트북에서는 된다’는 상태가 굳어집니다. 변경 관리 측면에서 docker ps와 openclaw gateway status의 마스킹된 로그를 티켓에 첨부하고 Compose 페어링 글의 표와 대조하는 절차를 권장합니다.
오프라인·준오프라인 환경에서는 GHCR과 Docker Hub 경로가 프록시와 미러로 이중화되어 digest 검증이 빠지면 pull이 ‘무작위로’ 실패하는 것처럼 보입니다. 이 경우 GHCR Runbook의 데이터 플레인 절과 맞춰 내부 레지스트리 메타데이터 캐시 TTL까지 기록하세요.
| 증상 묶음 | 첫 점검(5분 이내) | 다음 조치 |
|---|---|---|
| 마법사 멈춤·URL 미표시 | Docker Desktop 상태, WSL 활성화, 여유 디스크 약 20GB 초과(예시 임계, 팀 기준으로 조정) | 문서화된 compose로 Gateway를 올리고 docker logs 확인. 스크립트와 수동 이중 기동 금지 |
| 컨테이너 running인데 호스트 CLI 불통 | 포트 충돌, 컨테이너 네트워크에만 보이는 잘못된 바인딩 | openclaw gateway status / openclaw status 실행 후 Compose 페어링 문서와 TOKEN·네임스페이스 대조 |
| 업그레이드 직후 퇴보 | 호스트 CLI와 이미지 태그 정렬, 충돌 구성이 남은 오래된 볼륨 | 버전 맞춘 뒤 openclaw doctor. 백업 체크포인트를 남기고 문서에 따른 Gateway 강제 재구성 |
커뮤니티 경험(벤더 보장 아님): 멈춘 마법사를 끊고 docker compose up -d로 전환하는 사례가 있습니다. 미문서 플래그나 pending JSON을 건드렸다면 최신 공식 문서로 되돌리고, 프로덕션에서는 미공개 스위치에 의존하지 마세요.
wsl --version, OpenClaw CLI --version, 이미지 digest를 티켓에 붙입니다.openclaw status → openclaw gateway status → openclaw doctor → openclaw channels status --probe(설치 채널 문서의 정확한 명령을 따름).3단계와 4단계 사이에 막히면 프롬프트를 만지기 전에 마스킹된 컨테이너 환경 변수 일부와 docker port 매핑을 출력하세요. 많은 ‘무응답’은 전송 계층 미준비에서 비롯됩니다.
SSH로 원격 Gateway 포워딩을 쓰면 노트북에는 전달 포트로의 TCP와 단일 TOKEN 출처만 필요합니다. 공인 인터넷에 인증 없이 Gateway 포트를 노출하지 마세요.
당번 교대 시에도 같은 순서로 분류하려면 각 단계에 ‘기대 출력 예’와 ‘불일치 시 되돌아갈 단계’를 Markdown으로 남기는 것이 좋습니다. doctor 메시지는 버전별로 문구가 바뀌므로 스크린샷보다 텍스트 로그를 권장합니다.
wsl --status docker version openclaw --version openclaw gateway status openclaw doctor
doctor를 비우거나 명시적 면제를 등록하고, Gateway에 의존하는 파이프라인 변경은 머지하지 않습니다.절전 정책, 패치 화요일, Docker Desktop 업그레이드가 가용성을 예측하기 어려운 조각으로 자릅니다. ‘내 머신에서 됨’ Gateway 공유는 동형 이미지·고정 리스너·감사 로그를 어렵게 만듭니다.
그 지름길과 비교할 때, 예측 가능한 Apple Silicon 호스트, 안정된 리전 이그레스, 문서화된 SSH나 tailnet 토폴로지로 7×24 Gateway를 올리고 Windows Docker는 개발 샌드박스로 두려면 MACCOME 클라우드 Mac mini가 보통 더 안전한 프로덕션 평면입니다. 여섯 리전 전용 노드, 유연한 임대, 독점 디스크와 프로세스 공간이며 다른 OpenClaw·원격 Mac Runbook과 논지가 맞습니다.
인사 이동이나 장비 교체 시 노트북 종속 Gateway는 키와 로컬 상태 이전 비용이 커집니다. 전용 원격 Mac으로 옮기면 기동 절차와 모니터링을 인프라 쪽으로 모으기 쉬워 온보딩 재현성이 좋아집니다.
인수인계에는 이미지 태그, compose 스니펫 개정, 프록시 정책, 명령 출력 샘플이 필요합니다. 다른 Windows 머신에서 재현되지 않으면 Runbook은 미완입니다.
네이티브 macOS Runbook과 대조하면 사다리는 같고 호스트 의무는 다릅니다. launch 의미를 섞지 마세요.
마지막 5분 체크: Docker 단일 진실 준비됨? Gateway 단일 트랙? doctor 클린? 셋 다 yes일 때만 모델·채널 분류 문서를 엽니다.
FAQ
토큰 URL이 나왔는데 브라우저가 열리지 않습니다. Gateway가 죽었나요?
엔진과 컨테이너 준비를 기다린 뒤 재시도하고, 프록시와 포트 충돌을 확인하세요. 안정적인 전용 호스트는 Mac mini 대여 요금과 Mac mini 대여 요금 페이지에서 옵션을 확인할 수 있습니다.
docker compose와 공식 마법사를 영구 병행해도 되나요?
분류 기간에만 잠시 병행하세요. 단일 소스로 수렴해 이중 Gateway와 토큰 드리프트를 피하고, 같은 변경 티켓에서 Compose 페어링·doctor 문서를 갱신하세요.