2026년 OpenClaw v2026.5.20 Mac VPS 업그레이드 검수: managed Gateway Node, 프로토콜 편차와 Policy/Doctor 한 페이지 Runbook(의사결정표·FAQ)
OpenClaw는 2026-05-21에 v2026.5.20을 공개했으며, 다중 Node 환경에서 openclaw update가 Gateway를 잘못된 바이너리로 조용히 바꾸는 문제와 CLI/Gateway 프로토콜 버전 편차로 재시작 헬스체크가 무력화되는 프로덕션급 결함을 수정했습니다. Mac VPS에서 launchd로 Gateway를 7×24 운영 중인데 「올리면 안 뜸·채널만 녹색·Cron이 성공을 실패로 표시」가 걱정된다면, 본문이 실행 가능한 결론을 제시합니다. 네 가지 번호 붙은 통증, 승급 시점 의사결정표, 사전 스냅샷, 7단계 Runbook, 5.20 전용 검수표, 오류 대조, 인용 가능한 세 판정, FAQ, 게이트웨이 장애·다채널·5월 클린 베이스라인 내부 링크를 포함합니다.
목차
1. 통증 분해: 다중 Node, 프로토콜 편차, 설정 표류
Mac 클라우드에서 OpenClaw 장애는 「모델 미납」만이 아닙니다. Gateway 프로세스는 살아 있고 18789도 LISTEN인데 CLI와 Gateway가 다른 Node에서 돌거나 프로토콜 버전이 한 단계 어긋나면, 업그레이드 직후 gateway restart 헬스체크가 타임아웃하고 채널이 무작위로 끊기며 Cron이 성공 작업을 실패로 찍습니다. 5.20은 이 클래스를 「재현 가능한 검수 항목」으로 내리는 패치입니다.
- 다중 Node 조용한 표류: Homebrew Node, nvm, 설치 스크립트 번들 Node가 공존하면 구버전
openclaw update는 패키지 루트가 같아도 follow-up 명령을 다른 Node로 바꾸고 managed Gateway 서비스만 옛 경로를 가리킬 수 있었습니다. - CLI/Gateway 프로토콜 편차: CLI는 5.20, Gateway는 5.18이면 재시작 헬스체크가 오판하고 팀은 플러그인 재설치 등 잘못된 층을 파게 됩니다.
- doctor 신규 경고 무시: 5.20부터
openclaw.json평문 API Key, 샌드박스에 숨은 MCP 도구, 무효thinkingFormat을 경고합니다. diff 없이--fix하면 필요한 provider 필드까지 지울 위험이 있습니다. - Exec 승인 경로 변경: Skill은
cat SKILL.md호환 경로를 허용하지 않고 read 도구가 필수입니다. 셸 cat 자동화는 「도구 거부」 가짜 장애가 됩니다.
온콜에서는 먼저 「프로세스 녹색인가」「18789 열렸는가」를 확인한 뒤 Node 경로와 running version 일치로 넘어가세요. 모델 Provider를 먼저 의심하는 순서는 5월 밀집 릴리스 기간에 시간 낭비로 이어지기 쉽습니다. v2026.5.20은 update·restart·doctor·Cron을 한 변경서에 묶어 검증할 수 있게 설계된 릴리스이므로, 「게이트웨이만 재설치」 같은 단일 조치로는 재발을 막기 어렵습니다.
2. 의사결정표: 언제 5.20으로 올릴까
| 전략 | 적용 장면 | 리스크 | 권장 |
|---|---|---|---|
| 즉시 업그레이드 | update 후 Gateway 기동 불가, 다중 Node, Cron 종태 정확성 중요 | 10–20분 유지보수 창 필요 | 본 Runbook을 저트래픽 시간대에 실행 |
| 다음 패치 대기 | 데스크톱 시험만, 7×24 채널 없음 | 구버전 update/프로토콜 문제 지속 | 프로덕션 Mac VPS에는 비권장 |
| 신규 노드 클린 설치 | 설정 감사 불가, 플러그인 난립 | 페어링 재스캔·마이그레이션 비용 | 사이트밀집 릴리스 클린 베이스라인 정렬 후 트래픽 전환 |
Staging과 프로덕션 Node 관리 방침이 다른 팀은 staging에서 7단계를 통과한 뒤 변경서에 managed Node 경로를 명시하세요. Docker만 staging, npm+launchd가 프로덕션인 구성도 흔하며, 본문 검수 항목은 npm 계열 Mac VPS를 주 대상으로 합니다. 유지보수 창 10–20분 안에 managed Node·gateway status 버전·Policy/doctor·Cron 종태까지 닫을 수 있으면 5.20 승급은 성공으로 기록하세요.
3. 업그레이드 전 스냅샷
바이너리를 건드리기 전 아래 출력을 변경서 텍스트로 저장하세요. 롤백 diff는 여기서 시작합니다.
openclaw --version openclaw gateway status --json | tee /tmp/gw-before.json lsof -nP -iTCP:18789 -sTCP:LISTEN which node; node -v type -a node 2>/dev/null || true cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak.$(date +%Y%m%d) launchctl print gui/$(id -u)/ai.openclaw.gateway 2>/dev/null | head -80
ProgramArguments의 Node 절대 경로와 gateway status --json의 running Gateway version(5.20부터 더 신뢰)을 중점 기록합니다. 게이트웨이 장애 Runbook 기준과 다르면 5.20 전에 기준부터 복구하세요.
4. 7단계 Runbook
단계 1: 목표 버전 고정 후 update
openclaw update --tag v2026.5.20 # npm 글로벌 환경 예: # npm i -g openclaw@2026.5.20
명령 종료 시 재시작 헬스체크 통과를 기다립니다. 실패하면 플러그인 전체 재설치로 도망치지 말고 2단계에서 Node를 확인하세요.
단계 2: managed Gateway Node 표류 여부
openclaw --version which node node -v openclaw gateway status --json | jq '.server,.version,.runningVersion'
5.20 수정 요지는 openclaw update 이후 follow-up이 managed Gateway 서비스와 동일 Node를 쓰는 것입니다. 「CLI는 Homebrew Node, launchd는 /usr/local 다른 세트」 상태를 해소하세요. 두 경로 node -v 메이저는 일치해야 합니다.
단계 3: Gateway 재시작과 18789 확인
openclaw gateway restart sleep 3 lsof -nP -iTCP:18789 -sTCP:LISTEN openclaw gateway status --deep
--deep 프로브 실패 시 게이트웨이 Runbook대로 gateway.auth, loopback, Token을 확인하고 모델 Provider는 미루세요.
단계 4: openclaw doctor(Policy 플러그인 포함)
openclaw doctor openclaw doctor --fix # 삭제·변경 필드 diff 확인 후만
5.20 번들 Policy 플러그인은 채널 컴플라이언스와 workspace 복구 힌트를 냅니다. 「평문 API Key」 경고는 doctor를 끄지 말고 환경 변수 또는 SecretRef로 이전하세요. MCP 샌드박스로 숨겨진 도구 경고가 보이면 Skill 권한과 Policy 설정을 함께 검토하고, 무작정 --fix로 필드를 지우지 마세요.
단계 5: 주 채널 스모크
프로덕션 Telegram / Feishu / Slack 등에서 단발 송수신합니다. 병행 채널은 다채널 검수 Runbook의 단일 채널 단계를 따르고 한 번에 변수를 늘리지 마세요.
단계 6: Cron 시험
openclaw cron list # 저위험 예약 작업 1건 실행, 종태 success이며 tool warning으로 덮이지 않는지 확인
5.20은 성공 Cron이 꼬리 tool 경고로 실패 처리되던 문제와 main-session·cron wake lane 상호 블록을 수정합니다. 업그레이드 후 로그와 UI 종태가 일치해야 합니다.
5. v2026.5.20 전용 검수표
| 검수 항목 | 합격 기준 | 실패 시 1차 확인 |
|---|---|---|
| 프로토콜 편차 헬스체크 | update 후 restart 1회 성공 | CLI·Gateway 모두 5.20인지 |
| managed Node 일치 | launchd·CLI node 경로/intent 일치 | launchctl print vs which node |
| gateway status 버전 필드 | JSON에 running Gateway version | 구 plist가 제거된 prefix 가리킴 |
| Policy / 평문 키 | doctor에 차단급 secret 경고 없음 | 키 이전 후 gateway restart |
| Exec / Skill | read 도구로 Skill 실행 가능 | shell cat SKILL.md 자동화 제거 |
6. 오류 대조와 롤백
| 현상 | 흔한 근본 원인 | 조치 |
|---|---|---|
| update 후 Gateway 기동 불가 | Node 경로 표류 | managed Node 정렬; 필요 시 gateway install --force(게이트웨이 Runbook) |
| doctor --fix 후 모델 전멸 | provider 필드 오삭제 | openclaw.json.bak 복원, thinkingFormat 수동 정리 |
| 채널 online인데 무응답 | 페어링/윈도(업그레이드 무관) | 채널 장애 문서; Gateway 버전 일치 먼저 증명 |
| Cron 여전히 실패 | 작업 자체 exec 거부 | cron show + JSONL; Skill read 경로 확인 |
롤백: json 백업 복원, 이전 tag 고정 후 gateway restart. 설정 감사 불가면 5월 클린 베이스라인대로 신규 노드 재구축이 더 빠를 수 있습니다. 롤백 후에도 managed Node 경로와 gateway status를 다시 스냅샷에 남겨 두면 다음 승급 시 비교가 쉽습니다.
7. 세 가지 인용 가능 판정
- Node 일치성: 동일 유지보수 창에서 managed launchd Node와
openclaw update가 보고하는 Node 메이저가 일치. 불일치면 5.20 수정이 실효 없음. - 버전 가시성:
gateway status --json에서 running Gateway version = 2026.5.20(동등 문자열) 읽히고openclaw --version과 정렬. - Cron 종태: 성공 예약 작업이 꼬리 tool 경고로 최종 결과를 덮지 않음. Gateway 녹등만이 아니라 시험 1건 delivered 플래그를 근거로.
8. FAQ
질문: Docker와 npm 경로 차이? 컨테이너 내부는 이미지 단일 Node가 기준. 호스트 Mac VPS npm+launchd일수록 Node 고정이 중요. Docker는 이미지 tag와 볼륨 설정 백업을 맞추세요.
질문: 5.18/5.19 건너뛰고 5.20? 가능. 반드시 스냅샷 후 staging 7단계 통과 뒤 프로덕션.
질문: 최초 5단계와 관계? 5단계는 「제로에서 기동」, 본문은 「기존 7×24 인스턴스를 5.20으로 안전 승급」. 신규는 5.20부터 설치 후 다채널 검수로.
9. 결론
v2026.5.20의 가치는 기능 목록보다 Mac VPS에서 잦은 「올리면 게이트웨이 죽음」 사고를 Node·프로토콜 계약으로 수렴시키는 데 있습니다. 노트북·WSL2는 단기 시험용이나 수면·NAT·다중 Node 혼재로 update 표류 재현이 어렵습니다. Linux VPS도 Gateway는 돌지만 launchd·Apple 스택 문서 누적 이점은 Mac 클라우드 쪽에 치우칩니다. OpenClaw를 7×24 프로덕션 입구로 쓴다면 유지보수 창에서 7단계를 끝내 managed Node·doctor·Cron 종태를 변경 템플릿에 적는 편이 매번 풀 재설치보다 시간을 아낍니다. 안정 디스크, 감사 가능 launchd, SSH Runbook을 원하는 팀에는 VPSMAC Apple Silicon Mac 클라우드로 18789·설정 백업·업그레이드 검수를 한 운영면에 올리는 선택이 엣지 단말·과도 컨테이너 실험 스택보다 5월 밀집 릴리스 기간에 통제하기 쉽습니다——사이트 게이트웨이 장애·다채널·클린 베이스라인 가이드가 가정하는 환경과 일치합니다.