which openclaw부터 첫 메시지까지 7단계, 클라우드 Mac 특유 PATH·로그 함정, M4 시험과 M4 Pro 상주 선정을 정리합니다. 공식 install-daemon, 18789 이중 경로, launchd token, 진단 사다리, 헤드리스 SSH와 함께 읽으시기 바랍니다.
2026 Setup Wizard Retry: 변경 티켓에 붙일 네 가지 근본 원인
Setup Wizard는 macOS 앱이 전역 openclaw CLI와 launchd Gateway 프로세스 기동 완료를 폴링합니다. 클라우드 Mac에서는 설치 로그만 녹색이고 마법사만 빨간 Retry가 가장 흔하며, 팀은 API 키와 모델명을 바꾸며 시간을 씁니다. 실제로는 마법사가 호출하는 명령이 대화형 셸과 다른 PATH를 쓰거나, launchctl kickstart가 이미 exit 1인 plist를 못 살리거나, 다른 사용자·구 install이 18789를 잡거나, plist에 PATH·OPENCLAW_STATE_DIR가 없는 네 경우로 수렴합니다.
CLI·데몬 버전 정렬을 건너뛰면 마법사는 대기 화면만 보여 주고 바이너리 불일치로 즉시 죽은 자식 프로세스를 계속 봅니다. 18789 부착이면 ready로 오인하면서 다른 인스턴스에 붙기도 합니다. 1차 분기는 항상 Retry 버튼이 아니라 SSH 7단계 체크리스트입니다.
PATH에 CLI 없음: install은 ~/.npm-global 등에 성공했지만 login 셸과 launchd EnvironmentVariables가 미동기화됩니다. 마법사는 command not found를 타임아웃으로 보입니다.
failed 상태에서 Retry: launchctl print에서 LastExitStatus가 0이 아닌데 UI만 대기합니다. doctor로 plist를 먼저 고칩니다.
18789 점유: 구 Gateway, CI 스크립트, 이중 install 중 하나입니다. lsof -nP -iTCP:18789로 소유자를 확정합니다.
launchd 환경 변수 누락: SSH에서는 echo $PATH가 맞아도 plist는 /usr/bin:/bin만 가질 수 있습니다. ProgramArguments 절대 경로화 또는 plist에 PATH를 명시합니다.
Screen Sharing과 SSH 혼용: 마법사는 GUI 키체인을 요구하고 복구는 SSH로 하면 토큰 상태가 어긋납니다. token 전문으로 분기합니다.
인수 티켓에는 Retry 횟수 대신 7단계 각 명령 출력, doctor 종료 코드, 18789 LISTEN 행, 첫 handshake 타임스탬프를 남깁니다. 버튼을 몇 번 눌렀는지 같은 무의미한 지표에서 벗어납니다.
온콜이 마법사 스크린샷만 받는 워크플로는 2026년에도 실패합니다. 스크린샷은 Retry 문구만 보여 주고 launchd LastExitStatus나 /tmp/openclaw의 스택은 숨깁니다. 티켓 템플릿에 7단계 붙여넣기 칸을 만들면 원인 분류가 PATH·포트·토큰·리소스 네 갈래로 빨라지고, 불필요한 모델 교체 롤백을 줄일 수 있습니다.
마법사 필수 vs CLI 완결: 클라우드 Mac 이원 매트릭스
2026 공식 경로는 macOS 앱이 경험·최초 페어링, Gateway 실체는 전역 CLI입니다. KVMNODE에서는 Screen Sharing을 짧게 열고 나머지는 SSH Runbook으로 고정하는 팀이 많습니다. 아래 표는 설계 Wiki에 그대로 붙일 수 있습니다.
| 경로 | 적합한 경우 | 마법사 Retry와의 관계 |
|---|---|---|
| CLI + doctor + install-daemon | 헤드리스 운영, 프로비저닝 직후, CI 전용 사용자 | 마법사 없이 7단계로 Ready 정의 가능 |
| macOS 앱 Setup Wizard | 최초 채널 QR, GUI 토큰, 비개발 인수 | 뒤에서 CLI 미준비면 Retry만 증가 |
| 하이브리드(권장) | SSH 7단계 통과 후 Screen Sharing으로 한 번 확인 | Retry는 UI 버그가 아니라 미통과 신호 |
마법사 Retry는 다시 기다리라는 뜻이 아니라 launchd 진실이 아직 맞지 않다는 알림입니다.
헤드리스 SSH로 Node 22와 PREFIX를 먼저 고정하고 install-daemon으로 plist 단일 출처를 만든 뒤 앱을 열면 Retry 루프가 거의 사라집니다. 반대로 앱만 먼저 열면 설치 성공 착각으로 시간을 씁니다.
명령 블록: PATH·18789·launchd 로그를 한 화면에
7단계 전반은 이 블록으로 빠르게 가져갑니다. 로그는 /tmp/openclaw를 우선하고 진단 사다리 L1/L2에 매핑합니다. TZ는 노드 로컬로 통일해 육 리전 장애에서도 시각 비교가 틀어지지 않게 합니다.
node -v which openclaw openclaw --version openclaw gateway status openclaw doctor launchctl print gui/$(id -u)/ai.openclaw.gateway 2>/dev/null | head -40 lsof -nP -iTCP:18789 -sTCP:LISTEN tail -n 80 /tmp/openclaw/openclaw-gateway.log 2>/dev/null
팁: doctor가 PATH 수정을 제안하면 대화형 ~/.zprofile뿐 아니라 LaunchAgent EnvironmentVariables 또는 ProgramArguments 절대 경로도 같은 유지보수 창에 반영합니다. 한쪽만 고치면 Retry가 재발합니다.
gateway status JSON이 healthy여도 마법사가 실패하면 앱 샌드박스가 다른 사용자 소켓을 못 보는 패턴이 있습니다. 전용 클라우드 Mac에서는 OpenClaw와 CI를 같은 로그인에 올리지 않는 편이 18789·키체인 경계가 분명합니다. 공유가 필요하면 동일 풀 격리 라벨 규약을 먼저 적용합니다.
7단계 따라하기: Gateway did not become ready를 티켓으로 닫기
Node 22·CLI 존재 확인: node -v, which openclaw, openclaw --version을 티켓에 붙입니다. 22 미만이면 install.sh 또는 조직 mirror로 먼저 맞춥니다.
대화 PATH와 launchd PATH 차이 기록: echo $PATH와 plist EnvironmentVariables를 나란히 적습니다. 차이가 있으면 절대 경로화를 선택합니다.
doctor 비대화 실행: 제안 마이그레이션을 적용하고 종료 코드·전체 stdout을 저장합니다. 실패 시 마법사를 닫고 token 전문으로 분기합니다.
gateway stop과 18789 해제: openclaw gateway stop 후 lsof로 LISTEN 소멸을 확인합니다. 남는 PID는 구 install 잔재입니다.
install-daemon 또는 kickstart: 공식 plist 경로에 맞춰 재설치하고 launchctl print에서 LastExitStatus 0을 확인합니다.
gateway status와 로그 시각 정합: status uptime과 /tmp/openclaw 최신 행이 같은 기동 이벤트를 가리키는지 봅니다.
마법사 또는 CLI 첫 메시지: Screen Sharing으로 마법사를 한 번 통과하거나 CLI probe를 실행합니다. 성공 ID를 인수 티켓에 기록합니다.
7단계가 같은 노드에서 재현되면 Retry 버튼은 더 이상 쓰지 않습니다. 리전만 옮길 때도 절차는 같고 데이터면만 바꾸는 것이 2026 모범 사례입니다. 가까운 리전 M4에서 7단계가 통과하면 기종 변경은 불필요하고, 통과하지 못하는데 memory pressure와 병렬 xcodebuild가 겹치면 M4 Pro 또는 풀 분리를 검토합니다.
클라우드 Mac 함정으로 bastion SSH ForceCommand가 PATH를 자르는 경우, macOS 초기 설정 미완으로 Screen Sharing이 안 열리는 경우, 육 리전에서 로그가 로컬 디스크만 남는 경우가 있습니다. 표면 증상은 같으므로 7단계 출력을 티켓·아티팩트 저장소에 항상 첨부하는 운영이 효과적입니다.
인용 가능 데이터와 M4 시험 대 M4 Pro 상주: 마법사 밖에서 닫는 조건
마법사 대기는 흔히 60~120초 폴링이지만 launchd가 3초 만에 죽으면 Retry는 무한처럼 보입니다. 아래는 티켓 기술 데이터란에 그대로 쓸 값입니다.
기본 Gateway 포트: 18789(TCP LISTEN). 이중 install 시 부착 vs 신규 기동을 gateway status로 명시합니다.
Node 하한: 2026 공식 경로는 22 계열. 20 계열이면 doctor 경고 후 마법사 ready 실패가 잦습니다.
헬스 프로브 간격: 운영에서는 60초 cron과 gateway status를 병행해 Retry보다 먼저 알립니다. cron 프로브 참고.
| 프로필 | 가까운 리전 M4 시험 | 먼 리전 M4 Pro 상주 |
|---|---|---|
| 첫 마법사+단일 Gateway | 충분 | 과한 경우 많음 |
| 마법사+야간 CI+channels 프로브 | 16GB 주의 | 권장 |
| Retry가 PATH만 문제로 7단계 재현 | 기종 변경 불필 | 기종 변경 불필 |
메모: 개인 Mac을 유일한 Gateway 호스트로 두면 수면·PATH 드리프트로 Retry가 재발합니다. 7×24 launchd 진실이 필요하면 전용 클라우드 노드가 맞습니다.
노트북 상주의 약점은 예측 불가 수면, 사용자 전환 키체인 불일치, npm 전역 우발 덮어쓰기입니다. 마법사는 이를 Gateway 미준비로 뭉뜹니다. 감사 가능한 Setup 완료와 Agent 상주를 계약에 쓰려면 KVMNODE Mac mini 클라우드 대여가 실무 표준입니다. 육 리전에서 시험 후 M4 Pro로 승격해도 동일 Runbook으로 재현합니다.
프로비저닝 직후 30분 유지보수 창에 7단계를 넣으면 Retry 루프를 고객 데모 전에 끊을 수 있습니다. 창이 끝난 뒤에는 cron 프로브만으로 Gateway를 감시하고, 마법사 UI는 다시 열지 않는 것이 운영 비용을 가장 줄입니다. 주문은 주문, 절차는 고객 센터, SKU는 가격에서 확인하시기 바랍니다.