01. 세 가지 고통: Node 드리프트, 18789, 셸 분열

1) Node 22 미만: OpenClaw는 Node.js 22+를 요구합니다. WSL과 PowerShell이 서로 다른 바이너리를 가리키면 doctor 결과가 엇갈립니다.

2) 포트 18789: 이전 게이트웨이나 다른 에이전트가 점유했는데 WSL localhost 전달 때문에 보이지 않을 수 있습니다.

3) 설정 이중화: SSH 키와 환경 변수가 /home과 C:\Users에 갈라집니다. 명령 오류 FAQ를 참고하세요.

VPN·프록시·백신 변경 후 doctor를 다시 돌리고, 마스킹한 성공 로그를 기준선으로 보관하세요.

기업망에서는 TLS 검사 프록시가 npm/Git을 가로막고, 실시간 백신이 대용량 압축 해제를 느리게 하며, GPO가 특정 인터페이스 리슨을 막을 수 있습니다. OpenClaw 결함이 아니라도 공수를 먹습니다. 게이트웨이를 127.0.0.1에만 둘지 0.0.0.0으로 의도적으로 열지 문서화하고 설치 가이드의 보안 원칙과 맞추세요.

openclaw doctor는 이륙 전 체크리스트로 취급하고 Hyper-V/vSwitch 업데이트, 루트 인증서 교체, 사내 VPN 전환 때마다 다시 실행합니다. 마스킹된 성공 출력의 차이는 분기 후에도 단서가 됩니다.

온보딩 자료에서는 경고와 기동을 막는 블로커를 구분해 겉보기 경고에 시간을 쓰지 않게 하세요.

도메인 계정·로밍 프로필에서는 로그인 전후로 홈 경로가 달라져 doctor에 간헐 권한 오류가 날 수 있습니다—바이너리 손상이 아닙니다.

02. 비교표: WSL2·네이티브·클라우드 Mac 리허설

관점	WSL2	네이티브	클라우드 Mac
Linux 프로덕션 정합	높음	다소 낮음	macOS 워크플로에 적합
18789 분석	Linux+Windows 이중	단일 OS	WSL만큼 복잡하지 않음
설정·경로 가시성	Windows 드라이브와 분리되기 쉬움	단일 OS로 단순	테넌트별 리셋 용이
Apple 생태계 적합	게이트웨이 중심에 적합	게이트웨이 중심에 적합	키체인·Xcode 맥락에 유리
비용	CAPEX 낮음, 인지 부담 높음	Node만 맞으면 가장 빠름	비용 시험

Apple 전용 검증이 잦다면 일 대여 함정을 먼저 읽고 짧은 macOS 창을 캘린더에 올리세요.

「클라우드 Mac」 열은 Windows를 부정하는 것이 아니라 데스크톱 세션·브라우저 인증서·확장 자동화 같은 검증 축을 더하는 것입니다. 릴리스 캘린더에 리허설을 박고 급한 「누군가 Mac 빌려줘」 운영을 줄이세요.

여러 제품 라인에는 팀별 주 플랫폼 라벨을 붙여 OS 신앙 논쟁을 줄입니다.

백엔드 위주 조직은 Linux 파드와의 정합을 이유로 WSL2를 기본으로 두기 쉽고, 모바일·디자인 조직은 인증서·MDM·단말 실험실 때문에 macOS 열이 불가피한 경우가 많습니다. 서비스 카탈로그에 그 전제를 박아 두면 아키텍처 리뷰가 짧아지고 Mac 일 대여가 갑자기 폭증하는 일을 줄일 수 있습니다.

관측 가능성 측면에서는 게이트웨이 bind 주소, 부모·자식 프로세스 관계, WSL·Windows 혼합 기동 시도 여부를 메트릭으로 남기면 사후 원인 근사가 빨라집니다. 포스트잇보다 마스킹된 doctor 출력을 주간으로 아카이브하는 편이 감사·지원에 유리합니다.

03. 전제: Node 22+, 경로, 툴체인

패키지 설치 전 실제 사용 셸에서 Node.js 22+를 충족하세요. CI 컨테이너만 최신이면 의미가 없습니다. npm/pnpm를 맞추고 모델 API 외향 트래픽은 검증된 VPN 경로와 동일하게. split-tunnel에서는 doctor 성공 후 런타임 호출만 실패하는 패턴이 흔합니다.

WSL2는 커널 업데이트, systemd는 배포판 권장을 따르고, 네이티브 Windows는 VC++ 재배포 패키지와 긴 경로 정책을 확인하세요. OpenClaw 설정은 선택한 런타임의 home 트리로 단일화하고 암묵적 symlink는 피합니다.

HDD에서는 첫 압축 해제가 조용히 길어져 게이트웨이가 죽은 것처럼 보입니다. SSD/메모리를 런북에 명시하고 사내 TLS는 먼저 curl이나 openssl s_client로 분리합니다.

대상 셸에서 Node ≥22를 확인하고 npm/pnpm 정책을 통일합니다. 정본은 설치 가이드입니다.

node -v
which node

04. 게이트웨이까지 다섯 단계

활성 셸에서 Node 22+ 확인—v20 이하면 런타임부터 갱신.
WSL2 또는 네이티브 결정: Ubuntu WSL은 localhost 전달을 이해한 뒤, 네이티브는 PowerShell 전제를 맞추고 비교 목적 이중 기동은 금지.
가이드대로 CLI 설치—패키지 매니저 혼용 금지.
openclaw doctor 실행 후 의존성·권한 수정. 미스터리는 명령 오류 FAQ와 대조.
18789 해제 또는 변경 후 게이트웨이 기동, 루프백과 필요 시 LAN 프로브. 포트 변경은 클라이언트·프록시·FW를 같은 티켓에서 갱신.

openclaw doctor
ss -lntp | grep 18789 || true
netstat -ano | findstr 18789

같은 토큰으로 WSL과 Windows에 게이트웨이를 동시에 띄우지 마세요. 로그 잠금이 네트워크 오류처럼 보입니다. 런북에 안티패턴으로 명문화하세요.

성공 후 Node 전체 버전 문자열·bind 주소·PID·마스킹된 설정 발췌를 증거 패키지로 보관하세요.

Blue/Green에서는 node_modules 크기를 기록하고 느린 디스크에서 압축 해제 중 무반응처럼 보이는 점을 공유하세요.

05. 지표와 doctor 오해

지표 1: 첫 doctor 실패의 약 38–52%가 Node 22 미만 또는 PATH 충돌.
지표 2: 18789 티켓은 체크리스트 없이 45–90분, 있으면 대개 15분 이내.
지표 3: 실행 면을 하나로 통일하면 환경 불일치 에스컬이 약 25–35% 감소 경향.

오해: doctor 통과＝WAN 도달은 아님—루프백만일 수 있습니다. WSL과 Windows의 Node는 자동 공유되지 않습니다. 포트 변경은 클라이언트와 문서를 동시에—명령 오류 FAQ 참고.

doctor 통과가 외부 도달·클라이언트 설정까지 보장하지는 않습니다. 요금, 원격 가이드.

운영 지표로 doctor 재실행 횟수·첫 헬스 체크 성공까지 시간·18789 계열 티켓 비율을 추적하면 위 세 지표를 보강합니다.

온콜 런북에는 「doctor 녹색인데 클라이언트만 실패」 분기를 넣고, VPN 프로파일·프록시 예외·로컬 방화벽을 같은 체크리스트에 묶으세요. 증상만으로는 OpenClaw와 네트워크 팀 사이에서 공 넘기기가 반복됩니다.

이미지 재설치나 랩톱 교체 후에는 이전 증거 패키지와 새 doctor 출력을 diff하는 것이 표준 절차여야 합니다. 그렇지 않으면 「예전엔 됐는데」라는 비공식 기억만 남습니다.

06. Windows 한계와 macOS 일 대여

게이트웨이와 대부분의 브라우저 자동화는 Windows로 충분하지만 키체인 서명·일부 Safari 맥락은 macOS가 생산에 가깝습니다. 짧은 일 대여 네이티브 macOS로 리허설하고 SSH·VNC FAQ로 대역폭을 계획하세요.

일상은 Windows 5단계와 Node 22+를 유지하고, 스프린트마다 Mac 열이 계속 이기면 비용 시험으로 설명을 맞추세요.

마일스톤 마무리 세 질문: 재부팅 후에도 doctor가 녹색인가? 포트 기술이 실제 리스너와 일치하는가? 동일 토큰의 WSL/Windows 이중 게이트웨이는 없는가?

재무 대화에서는 Windows 게이트웨이를 기존 하드 위 Opex, 짧은 macOS 일 대여를 Apple 리스크의 캘린더형 capex 대체로 포지셔닝하면 OS 종교 논쟁을 줄일 수 있습니다.

릴리스 직전에만 Mac을 빌리는 패턴은 비용 변동을 키웁니다. 스프린트 초반에 짧은 리허설 슬롯을 고정하면 대역폭·일정·비용을 예측하기 쉽고, SSH·VNC FAQ의 대역폭 가정과도 맞추기 좋습니다.

Windows로 충분한 구간과 macOS가 필요한 구간을 RACI에 명시하면, 엔지니어링과 재무가 같은 언어로 트레이드오프를 논의할 수 있습니다.

2026 OpenClaw on Windows:
WSL2 vs 네이티브 PowerShell—게이트웨이 `18789`, `openclaw doctor`, Node.js 22+

목차