OpenClaw 게이트웨이 npm ci, package-lock.json, 재현 가능 설치, 임대 클라우드 Mac에서의 클린 리빌드 규율(2026-05-09)
2026년 커뮤니티 이슈 스트림은 같은 실패 모드를 반복합니다: 운영자가 게이트웨이가 파일 핸들을 쥔 채인데 npm install -g openclaw@latest를 실행해 이름만 바꾼 트리, 빠진 플러그인 런타임 의존성, 텔레그램 폴링을 굶기는 재시작 루프를 남깁니다. 홍콩, 일본, 한국, 싱가포르, 미국에서 자동화를 배포하는 MacLogin 테넌트는 게이트웨이를 다른 프로덕션 바이너리처럼 다뤄야 합니다: 락파일을 커밋하고, npm ci 의미로 설치하며, 먼저 launchd를 멈추고, 모듈 해석 캐시가 거짓말할 때 이중 재시작 완화를 리허설하세요. 이 2026년 5월 런북은 매트릭스, 중지 순서, 9단계 CI, 관측 가능성 점검, FAQ로 Apple Silicon 리스에서 OpenClaw를 예측 가능하게 유지합니다.
짝지어 읽기: 피어 의존성 드리프트와 클린 리빌드, doctor 진단, macOS 앱과 CLI 핸드오프. 허브: OpenClaw 주제 색인. 또한 도움말, 요금, VNC(GUI 검증).
OpenClaw가 CLI처럼 느껴져도 락파일이 중요한 이유
게이트웨이는 전송, 플러그인, 모델 어댑터의 전이 의존성을 묶습니다. 그래프를 고정하지 않으면 semver 범위가 같아도 레지스트리 게시 후 두 머신이 조용히 갈라집니다—재현 가능 CI가 없애려는 악몽입니다.
package-lock.json을 손으로 편집하지 마세요. 통제된 업그레이드와 코드 리뷰로 재생성합니다.npm ci 대 npm install(결정 매트릭스)
| 명령 | 게이트웨이에서 쓸 때 | 건너뛸 때 위험 |
|---|---|---|
npm ci | CI 이미지, 새 워크스페이스, 리빌드 파이프라인 | 결정적 설치, 락/패키지 불일치 시 즉시 실패 |
npm install | 락파일을 의도적으로 바꾸는 탐색적 업그레이드 | 재커밋 없으면 JP와 US 노드 드리프트 |
npm install --package-lock-only | 스크립트 없이 락만 갱신하는 PR 준비 | 전이 범프 검토는 여전히 필요 |
게이트웨이 버전과 함께 Node.js와 npm 고정
삼중항 (node -v, npm -v, openclaw --version)을 CMDB에 기록합니다. Volta, asdf, MacPorts 핀을 헤드리스 온보딩과 Node 기준 맞추기에 맞춰 CI와 임대 미니가 동일 엔진을 평가하도록 하세요.
NODE_OPTIONS와 플러그인 경로를 LaunchAgent 환경 패턴으로 내보내면 재시작 후에도 고정된 툴체인을 물려받습니다.npm 전역 경로를 건드리기 전 launchd 중지 순서
launchctl bootout gui/$UID/ai.openclaw.gateway(plist 라벨에 맞게 조정).pgrep -fl openclaw로 자식node가 남지 않았는지 확인.- 그다음에만 npm 변경 실행.
doctor가 부분 트리를 보고할 때 클린 리빌드 시퀀스
피어 드리프트 글의 정신을 따르세요: node_modules를 제거하고 npm ci로 재설치한 뒤 openclaw doctor를 다시 실행하고 표준 출력을 지원 번들에 담습니다. 전역 설치는 깨진 prefix 경로를 지운 뒤 깨끗이 재설치하는 커뮤니티 우회를 미러링합니다.
게이트웨이 업그레이드용 9단계 CI 런북
- 스냅샷: 현재 plist, 체크섬, 헬스 JSON.
- 브랜치: 시맨틱 버전 태그로 Git에 락 업데이트.
- 빌드:
npm ci를 쓰는 일회성 CI macOS 러너. - 테스트: doctor, 합성 웹훅, 모델 ping.
- 스테이징: 불변 버전으로 객체 스토리지에 아티팩트.
- 중지: launchd 정책에 따라 프로덕션 게이트웨이 중지.
- 설치: 스테이징한 아티팩트에서(떠도는 latest 아님).
- 부트스트랩: 헬스가 흔들리면 두 번(이중 재시작 완화).
- 게시: 릴리스 노트와 롤백 tarball 위치.
오래된 모듈 해석을 위한 이중 재시작 완화
헬스는 통과하지만 런타임이 여전히 오래된 해시를 참조하면 짧은 수면 직후 즉시 두 번째 launchctl kickstart -k를 예약하세요. 증상을 문서화해 TLS나 프록시 실패와 혼동하지 마세요.
교차 링크: 피어 드리프트 글과 이 락파일 글
피어 드리프트 가이드는 의존 그래프가 터지는 쪽에 초점을 둡니다. 이 글은 그래프를 고정하는 쪽입니다. 둘 다 쓰세요: 일상 빌드는 락, 긴급 리빌드는 상충 피어를 게시한 뒤 드리프트 글.
리전 간 게이트웨이 롤아웃을 위한 아티팩트 캐싱
홍콩과 미 서부 테넌트가 같은 시간에 올리면 공개 레지스트리에서 동일 tarball을 두 번 당겨 속도 제한과 지터를 초대합니다. 불변 아티팩트를 자사 객체 스토리지(S3 호환, Artifactory, GitHub Release 자산)에 승격하고 각 리스가 콘텐츠 주소 URL로 가져오게 하세요. 감사를 위해 package-lock.json의 git SHA와 함께 변경 티켓에 SHA256을 기록해 JP와 SG 노드가 동일 바이트를 실행했음을 증명합니다.
| 리전 | 권장 캐시 | 폴백 |
|---|---|---|
| HK / SG | APAC 버킷 레플리카 | 분당 설치 동시성 2로 제한 |
| JP / KR | 도쿄 인접 엣지 캐시 | 야간 창 설치 선호 |
| US | 미동부 주 + 서부 미러 | tarball 캐시 시 npm ci --prefer-offline |
npm ci 전에 서명·체크섬 검증은 선택이 아닙니다.FAQ
install.sh 흐름은 여전히 쓸 수 있나요? 스크립트 curl은 부트스트랩에만 두고 반복 작업은 커밋된 락으로 전환하세요.
에어갭 설치는? npm pack 출력으로 벤더 tarball을 만들고 npm ci --offline 전에 SHA256을 검증하세요.
격리 게이트웨이는 어디서 빌리나요? 시끄러운 업그레이드를 분리하려면 JP 대 US 풀을 요금으로 비교하세요.
Dependabot이 OpenClaw 범프를 자동 머지해도 되나요? doctor, 웹훅 에코, 플러그인 그래프를 돌리는 게이트 CI가 있을 때만—아니면 주간 인간 검토가 이깁니다.
OpenClaw 허브, 도움말, 리전 용량
락파일 정책을 OpenClaw 허브 내부 섹션에 게시해 모든 리전이 같은 중지 순서 체크리스트를 물려받게 하세요. 서울 팀이 싱가포르와 다른 플러그인 세트를 필요로 하면 한 락 그래프로 싸우지 말고 리스를 나누세요.
