npm install -g openclaw(또는 패키지 관리자 동등물)를 돌리다가 로그가 오래sharp에서 멈추거나, prebuild-install·node-gyp가 libvips를 찾다 실패하는 경우는 2026년에도 흔합니다. 원인은 대개 「글로벌로 깔린 libvips와 번들된 바이너리가 섞였다」거나 「한 호스트에 install.sh 축과 npm prefix 축이 공존한다」처럼환경이 두 갈래인 경우입니다. 이 글은 SHARP_IGNORE_GLOBAL_LIBVIPS, 공식 install.sh·install-cli.sh 접두 경로, npm -g 한 축 전략, 그리고 싱가포르·일본·한국·홍콩·미동·미서에 깔린 Mac mini M4 클라우드 Mac에서 이미지를 고정할 때의 습관과 openclaw doctor로 한 번에 검수하는 FAQ를 묶었습니다.
launchd가같은 Node·같은 npm prefix를 바라보게 맞춘 뒤 sharp를 다시 설치하십시오. 계정이 갈라지면 doctor 출력도 갈라집니다.1. 왜 sharp에서 멈추는가: 네이티브 계층을 한 줄로 정리
OpenClaw 의존 트리 안에는 이미지 파이프에 쓰는 sharp가 들어 있고, macOS에서는 사전 빌드된 바이너리를 쓰거나 소스에서 링크합니다. 시스템에 Homebrew 등으로전역 libvips가 있으면 sharp가 그것을 끌어오려다 버전이 어긋나링크·심볼 단계에서 멈춥니다. 먼저 Node.js 22를 문서가 말하는 메이저로 고정하고, Xcode CLT·파이썬(일부 스크립트)·디스크 여유를 맞춘 뒤 같은 셸에서 npm config get prefix와 which node를 찍으십시오. 상주 게이트웨이와 개발용 노트북을 섞지 말고, 한 역할마다 한 베이스라인만 유지하는 편이 비용 대비 가장 빠릅니다.
2. SHARP_IGNORE_GLOBAL_LIBVIPS는 언제 켜는가
이 환경 변수를 1로 두면 sharp가 시스템 libvips를 무시하고 패키지가 동봉한 바이너리 쪽으로 기울어집니다. 글로벌 libvips가 꼬였거나 보안팀이 시스템 패키지를 건드리지 못하게 막은 호스트에서 설치를 통과시키는 데 유용합니다. 반대로, 회사 정책상 반드시 공유 libvips를 써야 한다면 이 플래그는 끄고, brew 쪽 버전을 핀으로 맞추는 쪽이 맞습니다. CI·이미지에서는 변수를 Dockerfile·launchd plist·GitHub Actions env에같은 이름으로 박아 두고, 대화형 SSH와 데몬 양쪽에서 값이 일치하는지 확인하십시오.
3. install.sh 전체 vs install-cli.sh vs npm -g: 「접두 한 축」만 고르면 된다
공식 install.sh는 문서가 가정하는 디렉터리와 권한을 한 번에 깔아 주므로매번 새로 뜨는 클라우드 Mac에 잘 맞습니다. 이미 Node를 팀 표준으로 깔아 둔 워크스테이션에는 install-cli.sh처럼CLI 접두만 덧붙이는 경로가 덜 침습적일 때가 있습니다. npm install -g는 유연하지만 prefix·PATH·코드 서명 정책에 따라 다른 디렉터리를 바라봅니다. 세 가지를한 호스트에서 섞지 마십시오——한쪽으로 설치한 openclaw 바이너리와 다른 쪽에 깔린 설정 디렉터리가 엇갈리면 doctor만 돌려도 원인이 흐려집니다. 설치 축을 하나로 고른 뒤 문서에 나온 대로 셸 프로파일과 launchd의 EnvironmentVariables를 동기화하십시오. 상주 게이트웨이와 공식 스크립트 선택지는 더 알아보기: OpenClaw Gateway 상주·공식 설치 스크립트·npm 배포 FAQ에서 한 번 더 정리했습니다.
4. 여섯 메트로·Mac mini M4 클라우드에서 「고정 환경」으로 굴리기
싱가포르·도쿄·서울·홍콩·미국 동부·미국 서부처럼 리전을 나눈 팀은, 각 메트로마다같은 Node 메이저·같은 설치 스크립트 버전·같은 sharp 플래그를 적어 둔 작은 런북을 두는 편이 안전합니다. 클라우드 Mac을 매일 새로 받는다면 이미지 단계에서 SHARP_IGNORE_GLOBAL_LIBVIPS를 박아 넣고, 첫 부팅 스크립트에서 npm doctor 대신 openclaw doctor까지 한 번에 돌려 로그를 아티팩트로 남기십시오. 원격 접속과 루프백·보안 경계를 맞출 때는 더 알아보기: Tailscale·SSH 포워딩·doctor로 게이트웨이 보안 FAQ를 같이 보시면 split-brain 진단이 빨라집니다.
5. openclaw doctor 한 장 검수 FAQ
아래는 온콜이 붙여 넣기 좋은짧은 질문과 답입니다. 출력 전체를 티켓에 넣고, 한 줄이라도 빨간 플래그면 설치 축부터 다시 고릅니다.
- Q. doctor가 다른 Node를 가리킨다. A. 대화형 셸과
launchd의PATH를 동일하게 맞추고 다시 설치하십시오. - Q. sharp만 재설치하고 싶다. A. 한 축으로 고른 뒤
npm rebuild sharp --verbose로 로그를 확보하고, 필요 시SHARP_IGNORE_GLOBAL_LIBVIPS=1을 시험하십시오. - Q. install.sh 후에도 npm 전역이 남았다. A. 이전 prefix의
bin을PATH에서 제거하고 doctor로 중복 바이너리를 확인하십시오. - Q. 리전마다 설치 속도가 다르다. A. 캐시 미러·egress 차이입니다. 버전 문자열은 리전 간에도 같아야 합니다.
vpszap 클라우드에서는 네이티브 계층이 덜 흔들린다
위 런북은가상화 없이 물리 Mac mini M4 한 대를 독점할 때 특히 잘 맞습니다. CPU·메모리·NVMe를 이웃 워크로드와 나누지 않으니 sharp 프리빌드가 같은 조건으로 반복되고, 약 5분 안에 SSH와 VNC를 함께 받아 GUI로도 동일 호스트를 검증할 수 있습니다. 과금은 일·주·월·분기이며 장기 약정이 없어 메트로별로 스냅샷을 남기며 그레이스케일하기 좋습니다. Apple Silicon 단일 아키텍처이므로 아티팩트 캐시를 리전 간에 재사용하기도 수월합니다.
고정 베이스라인을 실제 하드웨어에 붙이고 싶다면 vpszap 클라우드 Mac mini 홈에서 가까운 메트로를 고르십시오.