OpenClaw npm 피어 의존성 드리프트와 클라우드 Mac 클린 리빌드 2026: MacLogin Apple Silicon 게이트웨이에서 ERESOLVE 진동 중단
MacLogin 미니에서 무해한 플러그인 범프 뒤 npm install 이 빨간색이 되면 원인은 거의 항상 피어 의존성 드리프트입니다. 선택 피어, 중복 메이저, 문서화된 Node 22 기선과 어긋난 호이스트입니다. 이 2026년 4월 가이드는 스냅샷, 삭제, npm ci, doctor, launchd의 재현 절차를 HK·JP·KR·SG·US에 제공합니다. doctor 런북 독자에게 적합합니다.
install.sh vs npm 전역, 헤드리스 온보딩, 요금, 도움말, VNC, OpenClaw 허브, 상태 백업, 컷오버.
공유 미니에서 피어가 아픈 이유
~/.npm 아래 3–7개의 병렬 실험, 미완 npm link 가 호이스트를 망칩니다.
- 한 엔지니어의
--legacy-peer-deps가 다음 설치를 오염. - 오프라인 미러 24–72시간 지연.
- LaunchAgents 가 로그 전에 재시작.
node_modules 볼륨 최소 18GB 여유.증상 매트릭스
| 증상 | 근본 | 완화 | 검증 |
|---|---|---|---|
| 시작 시 ERESOLVE | 플러그인 메이저 충돌 | 부모 고정 | npm explain |
| 조용한 exit 1 | 누락 선택 피어 | dev 포함 npm ci | openclaw doctor |
| 핫 리로드 루프 | 부분 설치 | rm -rf node_modules | diskutil + df |
7단계 클린 리빌드
- 상태 가이드대로 스냅샷.
- LaunchAgent 중지 15초.
- 정책 허용 시
node_modules삭제. npm cache verify.- 프로덕션과 맞는 optional 정책으로
npm ci. openclaw doctor --json.- launchd 재시작 후 헬스 5회 curl.
pnpm 과 npm 혼합 금지.잠금 파일 정책과 CI 동등성
package-lock.json을 게이트웨이를 배포하는 브랜치와 함께 커밋합니다. 가능하면 macOS 러너에서 npm ci를 실행하세요. Linux 전용 CI는 macOS가 다르게 풀어내는 optional을 놓치며 2026년 4월 MacLogin 지원 티켓의 약 12%에 나타납니다.
머지 게이트에 게이트웨이 프로필에서 npm ls --all --omit=dev가 비정상 종료면 실패시키세요. 개발 설치가 멀쩡해 보여도 통과시키지 않습니다. 매주 임대 미니에서 동일 명령을 재실행하는 작업을 더해 launchd가 서비스를 재순환하기 전에 CI 이미지와 호스트 APFS 레이아웃의 드리프트를 잡습니다.
overrides、bundledDependencies와 engines 규율
피어가 충돌하면 플래그부터 쓰기 쉽습니다. MacLogin 호스트에서는인수인계에 남는 선언적 수정을 선호하세요: overrides를 package.json에 적고(티켓에 담당·만료), 원문 그대로 배포해야 하는 작은 벤더 심은 bundledDependencies, 런북이 이미 인용하는 Node 22 기준에 맞춘 engines.npm / engines.node 범위.
- overrides 감사: 각 overrides는 완화하는 CVE·회귀·업스트림 이슈를 적습니다. 초록만을 위한 빈 overrides는 다음 정리 때 제거합니다.
- bundled 의존성: 재배포가 합법이고 티켓 첨부에 체크섬까지 남긴 패키지에만 씁니다.
- 비공개 registry: Verdaccio나 Artifactory 미러가 메타데이터를 재배열하면 미러 버전을 고정하고 lockfile bump와 함께
npm view출력을 로그합니다. - 워크스페이스 배치: 모노레포 게이트웨이는
npx --no-install경계를 선언해 형제 패키지의 실수npm link가 런타임에 피어 그래프를 덮어쓰지 않게 합니다.
.npmrc에서 engine-strict=true를 켭니다. 마이너 불일치는 CI에서는 피어가 만족되는데 미니에서는 아닌 현상의 숨은 원인입니다.인수인계 템플릿 필드
변경 요청에 포함: lockfile 해시 전후, 충돌 패키지별 npm explain 발췌, doctor JSON diff, 재시작한 LaunchAgent plist 경로. 보안 검토는 이 필드로 overrides가 일시 부채인지 정책 전환인지 판단합니다.
node_modules 디스크 예산
주간 du -sh ~/.openclaw/**/node_modules 합계 9GB 넘으면 선제 리빌드. inode 및 7일 _cacache 정리.
launchd 전 doctor 게이트
doctor JSON을 릴리스 산출물로 diff. 새 경고 2건 초과 무소유 시 거부.컷오버 기사와 병행.
FAQ
--force? 일회성 클론만. 공유 리스에는 금지.
HK와 US Node? 도움말과 동일 LTS 마이너.
MacLogin이 지워주나? 비상 리셋은 가능하지만 루틴은 runbook 소유.
npm overrides는 언제 --legacy-peer-deps보다 안전한가요? overrides는 리뷰·버전 관리·git blame에 남습니다. legacy 플래그는 셸 기록에 숨고 다음 엔지니어의 단순 npm install에서 사라집니다—일회용 디렉터리가 아니면 공유 임대 미니에서 금지가 안전합니다.
Mac mini M4
M4는 npm 추출이 빠르고 통합 메모리로 TS 서비스를 유지. 다지역으로 tarball 왜곡을 줄이고 디스크 병목 시 요금에서 큰 미니로.
