2026년 OpenClaw Windows와 Linux 설치 및 원격 macOS 게이트웨이 연동: PowerShell·WSL2 이중 경로, 기업 HTTPS 프록시와 Node 버전 Runbook(재현 가능한 트러블슈팅+FAQ)
Windows·Linux에서 물리 macOS OpenClaw 게이트웨이에 붙는 팀은 보통 세 가지 이음새에서 막힙니다: 분리된 Node 런타임, 기업 MITM TLS, PowerShell과 WSL2에서 서로 다른 localhost. 이 Runbook은 의사결정 표, 재현 가능한 검증 7단계, 복붙 프록시 스니펫, 인용 가능한 임계값, 내부 위키에 붙일 FAQ를 제공합니다.
1. 팀이 실제로 부딪히는 통증 포인트
- 셸 간 분열 뇌. PowerShell에 Node 20, WSL2에 Node 18이면 OpenSSL 기본값·전역 npm 경로가 달라져 코드 리뷰로는 잡히지 않는 「내 노트북에선 됨」이 남습니다.
- 기업 HTTPS 프록시와 보이지 않는 MITM. registry·Git·모델 엔드포인트가 프록시를 타야 하는데, 런타임이 쓰는 저장소에 발급 CA가 없으면 TLS 오류가 장애 페이지처럼 보입니다.
- localhost 이식성. Windows에서 만든 SSH
-L전달이 WSL2의127.0.0.1에 자동으로 나타나지 않습니다(반대도 마찬가지)—CLI는 성공인데 IDE 플러그인만 죽은 소켓을 가리키는 패턴이 납니다.
게이트웨이 배치·다중 리전 토폴로지는 2026년 OpenClaw 보안 배포 실무: ZoneMac 다중 지역 노드를 활용한 고가용성·저지연 AI 에이전트 게이트웨이 구축 방법과 함께 보면 RTT·거버넌스 가정을 맞추기 쉽습니다. SSH·VS Code 원격 개발 흐름은 Mac mini 원격 개발 완벽 가이드: VS Code와 SSH로 구축하는 스마트 개발 환경과 절차를 맞추세요.
2. 의사결정 표: PowerShell vs WSL2 vs Linux 데스크톱
엔지니어당 OpenClaw 클라이언트 주 환경을 하나로 정하고, .nvmrc나 package.json engines로 Node를 강제하세요. 온보딩·노트북 감사 시 아래 표를 씁니다.
| 기준 | 네이티브 Windows(PowerShell) | WSL2(Ubuntu) | Linux 데스크톱 |
|---|---|---|---|
| 기업 TLS 신뢰 | Windows 인증서 저장소·IT SOE와 정렬 | WSL 신뢰 번들에 CA를 명시적으로 가져와야 함 | 배포판 update-ca-certificates 또는 사내 에이전트 |
| HTTPS 프록시 인체공학 | 시스템 프록시 + HTTPS_PROXY 환경 변수 |
~/.bashrc에 설정·apt vs npm 괴리 주의 |
단일 사용자 세션 env·필요 시 systemd override 문서화 |
| Mac 게이트웨이 SSH 로컬 포워딩 | Windows OpenSSH 클라이언트·Windows 쪽 127.0.0.1에 바인딩 |
CLI가 WSL이면 터널도 WSL에서·127.0.0.1 경계 넘지 않기 |
macOS·Linux 서버와 동일한 멘탈 모델 |
| Node 버전 규율 | fnm·nvm-windows·백신이 node.exe 스캔할 수 있음 |
배포판 내 fnm·nvm·engines 엄격 고정 | WSL2 열과 동일 |
| 이럴 때 적합 | IT가 Windows 네이티브 에이전트만 허용 | bash·Linux 컨테이너가 일상 | 사내 관리 Linux 워크스테이션 |
터널·Serve 패턴은 팀 내 「SSH -L vs Tailscale Serve」 가이드와 단계 번호를 맞춰 두면, 클라이언트 설치 런북과 온콜 핸드오프가 한결 수월합니다.
3. 재현 가능한 롤아웃 7단계
1단계 — 목표 Node 라인 동결
OpenClaw 2026.x는 대부분 릴리스 노트에서 Node 22 LTS를 전제로 합니다. .nvmrc에 22.x와 워크스페이스 engines.node 범위를 커밋하세요.
2단계 — 선택한 셸에만 Node 설치
Windows PowerShell(fnm 예시):
winget install Schniz.fnm fnm install 22 fnm use 22 node -v
WSL2/Ubuntu:
curl -fsSL https://fnm.vercel.app/install | bash source ~/.bashrc fnm install 22 && fnm use 22 node -v
3단계 — 프록시 변수와 예외 목록
대문자 변수명을 일관되게 씁니다(호스트·포트는 교체):
export HTTPS_PROXY=http://proxy.corp.example:8080 export HTTP_PROXY=http://proxy.corp.example:8080 export NO_PROXY=localhost,127.0.0.1,::1,.corp.example,169.254.0.0/16
Windows에서는 setx 또는 시스템 속성 대화상자로 사용자 환경에 영구 반영한 뒤 터미널을 다시 여세요.
4단계 — 기업 CA 체인 신뢰
발급 체인을 PEM으로보냅니다. Linux·WSL2 Node는 동일 프로파일에 NODE_EXTRA_CA_FILES=/path/to/corp-ca-bundle.pem을 둡니다. 네이티브 Windows Node는 Trusted Root/Issuers로 가져온 뒤 셸을 재시작하고 npm ping 또는 최소 https.get('https://registry.npmjs.org') 스크립트로 검증합니다.
5단계 — OpenClaw CLI 설치 및 버전 출력
Artifactory 미러를 쓰면 내부 패키지명·플래그를 따릅니다. 지원 티켓마다 openclaw --version, Node, OS 빌드를 함께 첨부하면 「원인 불명 끊김」의 절반은 바로 층이 나뉩니다.
6단계 — macOS 게이트웨이까지 터널 규율 하나
CLI와 같은 환경에서 SSH -L을 만듭니다. 예: ssh -N -L 18787:127.0.0.1:18787 user@mac-host(포트는 게이트웨이 바인딩에 맞게). Tailscale Serve를 표준으로 하면 Mac 로컬 헬스가 먼저 녹색인지 확인한 뒤 클라이언트 URL을 배포합니다.
7단계 — 그 셸에서 curl로 검증
curl -v http://127.0.0.1:18787/health(문서의 헬스 경로)을 실행하고, Mac에서 127.0.0.1에 대한 curl과 헤더를 비교합니다. 불일치는 대개 바인드 주소·포트 오류 또는 다른 서브시스템에서 만든 터널입니다.
4. 인용 가능한 수치·정책 노브
Node 정렬: Windows와 WSL2 사이에 마이너를 여러 개 허용한 팀은 게이트웨이 인증·WebSocket 업그레이드 관련 첫 주 지원 건수가 대략 2–3배로 늘었다는 내부 보고가 많습니다—스쿼드당 마이너 하나로 고정하세요.
긴 터널용 킵얼라이브: ~/.ssh/config에 ServerAliveInterval 30과 ServerAliveCountMax 4를 조합하면 호텔 Wi‑Fi·공격적인 사내 미들박스에서도 세션이 살아남기 쉽습니다.
프록시 예외 위생: NO_PROXY에 127.0.0.1, localhost, ::1을 항상 넣으세요. 빼먹으면 루프백 분류 때문에 요청당 5–15초 정지가 붙을 수 있습니다.
5. FAQ·증상별 트러블슈팅
PowerShell에 설치할까, WSL2에 설치할까?
2절 표를 보세요. 틀린 답은 「고정 없이 둘 다」입니다. 보안이 Windows 신뢰 저장소를 강제하면 PowerShell을 기본으로, 자동화가 bash 우선이면 WSL2에 완전히 몰고 터널도 그쪽에서 돌리세요.
브라우저는 되는데 npm·pnpm만 TLS 오류
브라우저는 OS 저장소를 쓰고 Node는 자동으로 같아지지 않습니다. 런타임용 CA 가져오기가 먼저입니다. 패킷 캡처 같은 좁은 진단 외에는 strict-ssl=false를 끄세요.
PowerShell curl은 되는데 WSL2는 안 됨
전달을 Windows에 만들고 CLI는 WSL2에 두었거나 그 반대입니다. OpenClaw 프로세스가 있는 서브시스템에서 터널을 다시 만들거나, 해당 Windows 빌드 문서의 WSL2 대면 주소로 전달하세요.
터널 경유 HTTP 502 또는 빈 UI
먼저 Mac에서 localhost curl로 게이트웨이를 증명합니다. Mac 로컬이 실패하면 게이트웨이 서비스와 launchd 로그를 봅니다. Mac 로컬만 성공하면 -L 순서·로컬 포트 충돌·루프백 구간은 HTTP인데 HTTPS로 기대했는지 재확인합니다.
6. 물리 Mac 게이트웨이가 Apple Silicon에 어울리는 이유
이 Runbook의 클라이언트 작업은 이야기의 절반입니다: macOS의 OpenClaw 게이트웨이는 동시 에이전트 부하에 Apple Silicon 통합 메모리 대역폭이 유리하고, launchd 친화적인 7×24 스케줄링, CI에서도 돌리는 Unix 툴체인과 맞닿습니다. Mac mini 급 노드는 대기 전력이 대략 4W 수준으로 자주 인용되며 SSH 전달·헬스 프로브를 항시 대기시키기 부담이 적습니다.
macOS는 Gatekeeper, SIP, FileVault가 겹쳐 장기 토큰이 있는 게이트웨이 호스트에 전형적인 Windows 노트북 SOE보다 드라이브바이 위협 면이 작습니다. 3절 경로를 「지루하게 안정적으로」 유지하려면 게이트웨이는 조용하고 효율적인 Apple 하드웨어에 두고 Windows·Linux는 통제된 클라이언트로만 쓰는 편이 낫습니다.
분산 팀용 게이트웨이를 표준화한다면 Mac mini M4 물리 노드가 지연과 운영 비용 균형에 잘 맞습니다. 이 Runbook과 맞는 프로덕션급 macOS 호스트가 필요하면 ZoneMac 노드를 확인해 보세요.
상시 켜 두는 macOS 게이트웨이 호스트가 필요하신가요?
이 Windows·Linux Runbook을 패치가 유지되고 항상 온라인인 물리 Mac mini 노드와 짝지으세요.