공식 install.sh 또는 install.ps1 직후 터미널에 Gateway를 찾을 수 없음, 기본 포트 미 LISTEN, Control UI 미동작이 나오면 대개 「설치 실패」가 아니라 2026년 흔한 반설치 상태입니다. CLI는 있으나 Gateway 데몬과 onboard 마무리가 닫히지 않았습니다. OpenClaw를 프로덕션으로 올리는 개발자에게 10분 검수, 6단계 Runbook, 대조표, checklist를 제공합니다. 전 플랫폼 설치 트러블슈팅, Node 24 프로덕션 베이스라인과 함께 읽으세요.
2026년 3월 전후 upstream에서 보고가 몰렸습니다. 새 환경에서 스크립트가 기존 Gateway만 갱신하고 최초 daemon install을 실행하지 않아 겉으로는 성공이나 Gateway가 없습니다. 수정 빌드 후에도 구형 머신에 반설치 흔적이 남을 수 있습니다. 아래 2개 이상이면 호스트 재설치 대신 본문 복구 경로를 따르세요.
openclaw-gateway 또는 동등 명령 없음:which openclaw는 있으나 Gateway 바이너리가 PATH 예상 위치에 없습니다.
기본 포트(예 18789) LISTEN 없음:openclaw gateway status가 미실행·반복 종료이고 openclaw logs가 비거나 매우 짧습니다.
Control UI / Dashboard 무응답:브라우저로 로컬 관리 UI 접속 시 타임아웃. 인증 실패와 달리 프로세스 미기동인 경우가 많습니다.
onboard --install-daemon에서 오류 또는 스킵:v2026.3.x 일부 빌드에서 systemd 검사 실패로 「설정만·서비스 없음」 틈이 남습니다.
업그레이드 후 악화:구 npm 전역 업그레이드 후 PATH에 openclaw 두 개, doctor split brain—먼저 업그레이드 분기 복구, 이후 본문으로 Gateway 검수.
채널 probe만 실패·Gateway는 running:반설치 최위험 단계는 지났습니다. 인증 트러블슈팅으로 이동해 설정을 잘못 삭제하지 마세요.
| 확인 항목 | 정상(프로덕션 가능) | 반설치(본문) | 가짜 성공(오판 쉬움) |
|---|---|---|---|
openclaw gateway status | Runtime: running；프로브 ok | not running / 명령 누락 | running이나 포트 미 LISTEN(오래된 PID) |
openclaw doctor | 블로킹 없음·설정 validate 통과 | daemon 미설치 또는 PATH 이상 | warning만 방치 |
channels status --probe | Connectivity probe: ok | 채널 미설정(Gateway만 단계 허용) | probe 실패를 「망가짐」으로 오인 |
| Node 런타임 | Node 24（또는 공식 최소 22.14+） | 시스템 Node와 nvm 혼용으로 service 사용자가 못 읽음 | 대화형 shell node -v는 맞지만 systemd 유닛은 구버전 |
「스크립트 마지막 줄 성공」은 Gateway 상주를 뜻하지 않습니다. 프로덕션 검수는 status, doctor, 포트 LISTEN 세 가지로 확정하세요.
순서가 중요합니다. Gateway 기동·상주 후 onboard로 모델·채널 보완. 프로세스 없이 openclaw.json만 바꾸지 마세요.
현장 고정:openclaw --version, which -a openclaw, 설치 방식(curl/npm/git) 기록. Node와 설정 동시 변경 금지.
공식 진단 단계:openclaw status → openclaw gateway status → openclaw logs --follow(별도 터미널)→ openclaw doctor。
Gateway 기동:openclaw gateway start；daemon 미설치면 openclaw onboard --install-daemon(마법사로 Token·최소 설정).
「CLI 있음·Gateway 없음」 복구:Node 24 확인 후 npm install -g openclaw --force. 컨테이너는 Docker/Podman, systemd 강행 금지.
버전 전략:v2026.3.2 daemon 회귀면 단기 v2026.3.1 고정 또는 PR #48649 빌드, 변경서에 롤백점.
프로덕션 검수:openclaw channels status --probe, loopback/Token, 재시작 후 재검. macOS는 원격 Mac launchd, Linux는 Ubuntu systemd.
# 10분 검수(2026 권장 순서) openclaw status openclaw gateway status openclaw doctor openclaw gateway start openclaw onboard --install-daemon # daemon 미설치 시 openclaw channels status --probe
안내:공식 설치 스크립트는 Node 24 권장. 먼저 CVE-2026-25253·Node 24 베이스라인 후 복구. 패치 미정렬 시 Gateway 공개 금지.
주의:반설치 단계에서 Gateway를 공인터넷에 직접 노출하지 마세요. 기본 127.0.0.1, 원격은 Tailscale·터널. 사이트 Gateway 보안 문서 참고.
onboard --install-daemon은 「Gateway를 재시작 가능 서비스로」— 하나라도 빠지면 반설치.doctor·gateway status 정기 프로브 기록. GitHub #48272는 「설치 로그 성공」이 프로세스급 검수를 대체 못 함을 보여줍니다.Gateway를 슬립 노트북·공유 개발기에 두면 OS 업데이트 후 반설치로 돌아가기 쉽습니다. 전용·상시 온라인 macOS 노드가 Agent 게이트웨이 호스트에 적합합니다. VPS처럼 SSH·검수 스크립트가 필요하면 NodeMini Mac Mini 클라우드 렌탈이 유력합니다. 사양은 대여 가격, 연결은 고객센터.