2026 OPENCLAW
UPDATE_
WROTE_
WRONG_
NODE.

OpenClaw v2026.5.20 전후 장애 중 「가짜 업그레이드」나 「채널 인증 고장」으로 오진되기 쉬운 유형의 실체는 LaunchAgent에 고정된 Node 경로와 대화형 셸의 which node 불일치입니다. openclaw update follow-up이 PATH 상의 다른 Node로 post-install·doctor·재시작을 실행하면 plist 서비스 정의만 바뀌고, 다음 gateway restart에서 launchd가 즉시 종료합니다. 5.20 공식 수정(PR #84043)은 Gateway를 위탁하는 service Node를 업데이트 체인 전체에 사용하고, gateway status --json에 runningVersion을 노출해 CLI/Gateway 프로토콜 skew를 식별합니다. 본문은 증상 매트릭스·의사결정표·6단계 Runbook·3중 게이트·사례·FAQ를 제공하며, 사이트 내 가짜 업그레이드·gateway status, LaunchAgent token 만료, invalid config·doctor와 역할을 나누어 원격 Apple Silicon Gateway에서 7×24 대조 검증과 롤백을 돕습니다.

1. 통증 분해: 버전 번호가 아니라 Node 바이너리 드리프트

1）다중 Node 공존은 일상: Homebrew /opt/homebrew/opt/node/bin/node, nvm 기본 22.x, fnm 글로벌 20.x가 한 Mac에 공존. openclaw gateway install은 당시 node 절대 경로를 ai.openclaw.gateway plist에 기록. 2）PATH 전환이 드리프트 유발: 터미널에서 nvm use 25 후 openclaw update하면 구 로직은 새 PATH의 node로 follow-up 실행——패키지 root는 그대로인데 plist만 다른 prefix의 openclaw를 가리킴. 3）「가짜 업그레이드」와 구분: 가짜 업그레이드는 CLI 5.20·Gateway 5.12 버전 차이; 본문은 engines.node 미달·바이너리 불일치로 기동 직후 크래시·WS 핸드셰이크 실패. 4）프로토콜 skew: 5.20은 CLI가 Gateway보다 마이너 1개 새 버전일 때 restart health check 유지; Node 드리프트로 Gateway가 안 뜨면 unauthorized·RPC 타임아웃이 먼저. 5）레거시 updater LaunchAgent: Issue #82167의 ai.openclaw.update.* 재기동·Gateway SIGTERM; 5.20+ update가 best-effort disable——Runbook에 launchctl 목록 확인 필수.

2. 의사결정표: Node 정렬 vs 패키지 롤백

현장 신호	1차 조치	금지
openclaw --version과 plist node major 불일치	PATH 고정 → service Node로 update 재실행 또는 gateway install --force	plist 백업 없이 ProgramArguments 수동 편집
gateway status --json에 runningVersion 없음	gateway restart --wait 후 launchd 종료 코드 확인	~/.openclaw 전체 삭제
업데이트 후 Telegram만 간헐 단절	Node 드리프트 제거 후 채널 계층	5.2 HTTP 타임아웃과 혼합 수리
노트북 OK·원격 Mac 전면 장애	대조 노드에서 plist node와 npm root -g 비교	로컬 nvm 경로를 원격에 복사
프로덕션 변경 감사 필요	대조기에서 6단계 + 30분 프로브	금요일 야간 피크·롤백 창 없이 업데이트

3. 6단계 Runbook

Step 1 「삼원 증거」 고정

기록: openclaw --version, which node·node -v, plist ProgramArguments 앞 두 항(node 경로 + openclaw 진입점). openclaw gateway status --json의 runningVersion(5.20+) 저장.

Step 2 engines.node 임계값 확인

글로벌 openclaw package.json의 engines.node 확인. service Node major가 부족하면 Node 먼저 업그레이드——doctor 통과해도 Gateway 기동 실패 방지.

Step 3 위탁 Gateway Node 정렬(5.20 권장)

2026.5.20 적용 후 openclaw update: 공식은 LaunchAgent baked node를 follow-up에 우선. 이미 드리프트면 openclaw gateway install --force로 의도한 node 재고정, npm root -g와 plist 일치 확인.

Step 4 레거시 updater LaunchAgent 정리

launchctl list | grep openclaw: ai.openclaw.update.* 재시작 루프면 5.20+에서 update가 disable; 구버전은 launchctl bootout gui/$UID/ai.openclaw.update.*(진행 중 작업 확인 후). Issue #82167 「업데이트 성공 후 3분마다 SIGTERM」 회피.

Step 5 Gateway 순서 재시작·JSON 프로브

openclaw gateway restart --force --wait 후 openclaw gateway status --json 3회 연속. runningVersion이 목표와 일치·RPC 임계 내. 원격 Mac은 launchctl kick -k gui/$UID/ai.openclaw.gateway 후 반복.

Step 6 원격 7×24 대조·롤백 창

대조 노드는 nvm 미전환 깨끗한 PATH로 Step 1–5 재현. 프로덕션 실패 시 버전 고정·plist/npm prefix diff 보존; 30분 channels.probe 전 녹색일 때 closure.

4. 3중 자가 검사 게이트

1차 Node 게이트: plist node 존재·node -v가 engines.node 충족. 2차 버전 게이트: gateway status --json runningVersion과 openclaw --version 허용 skew 내(5.20 헬스체크). 3차 채널 게이트: openclaw channels status --probe 적색 없음·30분 내 「재시작 직후 즉시 종료」 없음.

5. 심층 사례: 「update 성공, 다음 날 Gateway 전 채널 오프라인」

팀은 《가짜 업그레이드》로 버전 문자열 확인, CLI·status 모두 5.20으로 채널 token 장애 오판. plist와 which node diff로 Node 드리프트 특정. MACGPU 대조기에서 단일 Homebrew Node로 Gateway 재설치 후, 프로덕션 Studio는 plist 앞 두 항 교체·gateway install --force만으로 30분 내 복구. 변경표: nvm 포함 대화형 셸에서 원격 launchd update 금지; 업데이트 창은 service 계정 또는 env -i 최소 PATH로 통일.

6. 업계 관점: Agent Gateway 「런타임 고정」과 Mac 위탁

2026 Node 분열(nvm/fnm/Volta/Homebrew)로 「글로벌 CLI」와 「daemon 고정 런타임」이 이중 진실. OpenClaw 5.20이 managed service Node를 업데이트 체인에 넣은 것은 Agent 운영이 「설치만 되면 OK」에서 고정·diff·롤백 가능 단계로 이동한 표시. 엔터프라이즈는 업데이트 티켓에 plist node 경로, engines.node 검증, gateway status JSON을 요구——버전 스크린샷만으로는 부족.

Windows/Linux에도 다중 Node는 있으나 macOS launchd의 절대 경로 의미론이 더 엄격——한 번 드리프트하면 전 채널 중단. Apple Silicon 원격 Mac은 전용 메모리·Metal·7×24 그래픽/Agent 혼합 부하로 골드 대조 환경으로 쓰임: PATH 깨끗, 디스크 스냅샷, 로그 티켓 재생. MACGPU 원격 Mac에서 로컬 nvm과 격리된 노드로 5.20 업데이트·Node 정렬·롤백을 먼저 완료한 뒤 프로덕션에 적용하세요.

7. 인용 가능 수치 임계값

① plist node와 which node 불일치: 업데이트 성공 선언 금지. ② engines.node Node ≥22(설치 패키지 기준): service Node 미달 시 런타임 교체 선행. ③ 업데이트 후 30분 launchd 비0 종료 3회 초과: 기본 롤백·plist diff 보존. ④ gateway status --json 3회 runningVersion 실패: Unhealthy. ⑤ 원격·로컬 npm 글로벌 prefix 다름: plist 조각 크로스 머신 붙여넣기 금지.

8. FAQ

Q: 가짜 업그레이드와 차이? A: 가짜 업그레이드는 버전 문자열; 본문은 Node 바이너리·plist 경로. Q: 5.20 필수? A: 5.20부터 공식 수정; 이전은 gateway install --force로 수동 정렬. Q: Docker? A: 컨테이너는 보통 단일 Node; 볼륨·이미지 tag 주의. Q: plist 수동 편집? A: 가능하나 백업 필수; 권장 gateway install --force. Q: MACGPU 노드 역할? A: 대조 검증·PATH 격리·롤백 창——변경 승인 대체 아님.