2026-04-16 헤드리스 임대 클라우드 Mac에서 OpenClaw 게이트웨이 업그레이드와 롤백
임대한 Apple Silicon Mac이 SSH만 말할 때 OpenClaw 업그레이드는 순수 운영입니다. Finder 클릭 경로도 “앱만 다시 시작”도 없습니다. 이 2026-04-16 플레이북은 인그레스 동결, npm 전에 중지 순서, ~/.openclaw의 체크섬 백업, 맹목적 @latest가 아닌 버전 고정, openclaw doctor 검증, 글로벌 설치 후 가끔 필요한 게이트웨이 이중 재시작, 빌드가 틀어졌을 때 3분 이내 tarball 롤백을 다룹니다. 환경 변수·비밀(2026-04-15), 헬스 프로브, nginx 인그레스로 연결해 HK / JP / KR / SG / US 전역에서 스택을 일치시킵니다.
헤드리스 게이트웨이 특유의 위험
- 뜨거운 글로벌 npm — Node가 핸들을 잡은 채 파일을 바꾸면 부분 설치와 “유령” 버전이 생깁니다.
- launchd 겹침 — 먼저 unload하지 않으면 사용자 LaunchAgent가 업그레이드 중에 게이트웨이를 다시 띄웁니다.
- 설정 드리프트 — 새 마이너에서 키 이름이 바뀔 수 있습니다. 비밀을 제외한
openclaw.jsonGit 추적보내기를 유지하세요. - Webhook 스탬피드 — 준비 검사 없이 nginx를 열면 상대가 공격적으로 재시도합니다. 헬스 글의 프로브를 사용하세요.
먼저 공개 트래픽을 동결
nginx 리버스 프록시를 쓰는 호스트에서는 업스트림을 점검 모드로 돌리거나 작업 중 503과 Retry-After: 90을 반환합니다. 내부 카나리는 127.0.0.1:18789에 닿아야 하며, 외부를 다시 열기 전에 검증할 수 있습니다.
백업 표: npm을 건드리기 전에 tar할 것
| 경로 / 아티팩트 | 포함? | 메모 |
|---|---|---|
~/.openclaw(또는 $OPENCLAW_STATE_DIR) |
항상 | 먼저 게이트웨이 중지; shasum -a 256으로 gzip 무결성 확인 |
| 글로벌 npm prefix 트리 | 선택 | npm prefix -g와 npm ls -g --depth=0 텍스트를 diff용으로 저장 |
| launchd plist | 항상 | ~/Library/LaunchAgents에서 같은 tarball 폴더로 복사 |
TS=$(date +%Y%m%d-%H%M)
tar -czf "/Volumes/backups/openclaw-state-$TS.tgz" -C "$HOME" .openclaw
shasum -a 256 "/Volumes/backups/openclaw-state-$TS.tgz" > "/Volumes/backups/openclaw-state-$TS.tgz.sha256"
설치·고정: semver를 DB 마이그레이션처럼
프로덕션 게이트웨이는 인프라 저장소에 명시적 semver(예 1.24.3)를 추적합니다. CI는 조금 더 빠르게 움직여도 되지만, 싱가포르에서 파트너를 마주하는 Mac이 새벽 2시에 깨지는 플러그인 API로 놀라게 해서는 안 됩니다. 서비스 중지 후:
npm install -g openclaw@1.24.3
openclaw gateway status로 보고된 빌드와 openclaw --version을 비교하세요. 불일치는 전환 중입니다.
검증·재시작·두 번 바운스가 필요할 때
openclaw doctor를 실행하고 stdout을 로그 십퍼로 보냅니다. plist에 따라 launchctl bootstrap/kickstart로 시작합니다. 로그에 오래된 모듈 경로나 이상한 require 스택이 보이면 한 번 더 깨끗이 중지/시작하세요—온콜이 플래핑으로 오해하지 않도록 문서화합니다. nginx 점검을 끄기 전 헬스 프로브 합성 검사를 다시 실행합니다.
롤백: 상태를 되돌리고 기도하지 말 것
- 게이트웨이와 nginx 업스트림을 다시 중지.
- 필요 시 깨진 글로벌 설치 제거:
npm rm -g openclaw후 이전 semver 재설치. - tarball 풀기:
tar -xzf openclaw-state-....tgz -C "$HOME"(소유권 확인). - plist가 바뀌었으면 복원; 필요 시
launchctl bootout/bootstrap. - doctor와 내부 curl 검증 후에만 공개 인그레스에서 200 반환.
관련 런북·비밀 규율
업그레이드는 비밀 순환과 같은 파일을 만집니다. launchd 환경 가이드와 조율해 .env와 plist 키를 맞추세요. 블루/그린으로 두 번째 게이트웨이 사용자를 추가하면 해당 글처럼 OPENCLAW_STATE_DIR 경로를 분리합니다. 연속 실패 후 용량은 지친 한 대에 끝없이 패치하기보다 요금에서 witness 노드를 추가하세요.
FAQ: 클라우드 Mac 게이트웨이 업그레이드
| 질문 | 답변 |
|---|---|
| npm 대신 pnpm? | 지원—동일한 중지/백업/고정/시작 규율을 따르고 runbook에 스토어 경로 기록. |
| 매주 자동 업그레이드? | 카나리 + 자동 doctor + 프로브 게이트가 있을 때만. 담당자 없이 프로덕션 자동 업그레이드 금지. |
| 인시던트는 어디에? | 기존 브리지 사용; 구조화 로그 필드와 상관. |
한 줄: OpenClaw 업그레이드를 DB 페일오버처럼—트래픽 동결, 상태 백업, 버전 고정, 두 번 검증, 운영하는 모든 리전에서 롤백을 리허설해 근육 기억으로.
