pnpm으로 OpenClaw 설치 시 postinstall 스크립트 실패

문제 설명

pnpm으로 OpenClaw을 전역 설치할 때 postinstall 스크립트가 실행되지 않았다는 경고 또는 오류가 표시됩니다:

$ pnpm add -g openclaw

 WARN  Lifecycle script `postinstall` of package `[email protected]` was blocked by pnpm.
 WARN  Lifecycle script `postinstall` of package `[email protected]` was blocked by pnpm.
 WARN  To allow scripts from packages, run:
 WARN    pnpm approve-builds -g

설치가 완료된 것처럼 보이지만 openclaw start 실행 시 오류가 발생합니다:

Error: Cannot find module '../build/Release/sharp-linux-x64.node'

또는:

Error: Could not locate the bindings file. Tried:
 → /path/to/better-sqlite3/build/better_sqlite3.node

이는 pnpm이 v9부터 보안 향상을 위해 패키지의 lifecycle 스크립트(예: postinstall)를 기본적으로 차단하기 때문입니다. sharp, better-sqlite3와 같은 일부 패키지는 postinstall 단계에서 미리 컴파일된 네이티브 바이너리 파일을 다운로드하거나 로컬 컴파일을 수행해야 하며, 스크립트가 차단되면 이러한 패키지가 정상적으로 작동하지 않습니다.

원인 분석

pnpm의 이 보안 정책은 악성 패키지가 설치 시 위험한 스크립트를 실행하는 것을 방지하기 위한 것입니다. 하지만 OpenClaw이 의존하는 일부 합법적인 패키지는 실제로 postinstall 스크립트 실행이 필요합니다:

sharp: postinstall 단계에서 해당 플랫폼의 libvips 미리 컴파일된 바이너리 다운로드
better-sqlite3: postinstall 단계에서 SQLite의 네이티브 바인딩 컴파일 또는 다운로드
@napi-rs 시리즈 패키지: postinstall 단계에서 Rust로 컴파일된 네이티브 모듈 다운로드

이러한 스크립트가 실행되지 않으면 해당 네이티브 모듈이 올바르게 설치되지 않으며, 런타임에 바이너리 파일을 찾을 수 없다는 오류가 발생합니다.

해결 방법

방법 1: pnpm approve-builds 사용 (권장)

pnpm은 특정 패키지의 빌드 스크립트를 명시적으로 승인하는 approve-builds 명령을 제공합니다. 전역 설치의 경우:

pnpm approve-builds -g

실행하면 pnpm이 차단된 모든 패키지와 해당 스크립트 내용을 나열하고, 하나씩 실행을 허용할지 확인을 요청합니다:

? Allow build scripts for the following packages?
  [email protected] (postinstall: node install/sharp)
  [email protected] (postinstall: prebuild-install -r napi || node-gyp rebuild)

  ✔ [email protected]
  ✔ [email protected]

승인할 패키지를 선택하면 pnpm이 해당 패키지의 postinstall 스크립트를 다시 실행합니다.

승인 후 OpenClaw을 다시 설치하여 모든 네이티브 모듈이 올바르게 빌드되었는지 확인합니다:

pnpm add -g openclaw

방법 2: 설치 시 스크립트 실행 허용

OpenClaw과 그 의존성을 신뢰한다면 설치 시 --unsafe-perm 플래그를 사용하여 스크립트 실행을 허용할 수 있습니다:

pnpm add -g openclaw --unsafe-perm

또는 pnpm 설정에서 특정 패키지의 빌드 스크립트를 전역적으로 허용합니다:

pnpm config set approve-builds-automatically true -g

주의: approve-builds-automatically는 모든 패키지의 빌드 스크립트를 자동으로 승인하므로 보안성이 낮아집니다. 설치하는 모든 패키지를 신뢰하는 경우에만 사용하세요.

방법 3: .pnpmfile.cjs 설정 사용

전역 pnpm 설정을 만들어 OpenClaw 관련 패키지의 빌드 스크립트를 미리 승인합니다.

먼저 pnpm의 전역 설정 디렉토리를 찾습니다:

pnpm config get global-dir

해당 디렉토리에 .pnpmfile.cjs를 생성하거나 편집합니다:

module.exports = {
  hooks: {
    readPackage(pkg) {
      // 이 패키지들의 빌드 스크립트 허용
      const allowedPackages = ['sharp', 'better-sqlite3', '@napi-rs'];
      if (allowedPackages.some(name => pkg.name.includes(name))) {
        pkg.allowBuild = true;
      }
      return pkg;
    }
  }
};

방법 4: npm으로 전환하여 설치

pnpm의 빌드 스크립트 관리가 지속적으로 문제를 일으킨다면 전역 설치에 npm을 사용하는 것을 고려할 수 있습니다. npm은 기본적으로 postinstall 스크립트 실행을 허용합니다:

npm install -g openclaw

프로젝트에서는 여전히 pnpm을 사용할 수 있으며, OpenClaw이라는 전역 도구만 npm으로 설치합니다. 두 가지는 충돌하지 않습니다.

방법 5: 수동으로 빌드 트리거

이미 OpenClaw을 설치했지만 네이티브 모듈이 빌드되지 않은 경우 수동으로 rebuild를 트리거할 수 있습니다:

pnpm rebuild -g

이렇게 하면 모든 전역 패키지의 빌드 스크립트가 다시 실행됩니다. 일부 패키지가 여전히 차단된다면 먼저 pnpm approve-builds -g를 실행한 후 rebuild하세요.

특정 패키지만 rebuild할 수도 있습니다:

pnpm rebuild -g sharp
pnpm rebuild -g better-sqlite3

수정 확인

네이티브 모듈이 올바르게 빌드되었는지 확인합니다:

# sharp 확인
node -e "require('sharp')" && echo "sharp OK" || echo "sharp FAILED"

# better-sqlite3 확인
node -e "require('better-sqlite3')" && echo "sqlite OK" || echo "sqlite FAILED"

OpenClaw의 환경 검사를 실행합니다:

openclaw doctor

모든 검사를 통과하면 서비스를 시작합니다:

openclaw start

예방 권장사항

이후 OpenClaw 업데이트 시 같은 문제를 방지하려면 최초 해결 후 승인 기록을 영속화하는 것이 좋습니다. pnpm은 승인된 패키지 목록을 전역 설정에 저장하며, 이후 설치나 업데이트 시 이미 승인된 패키지의 빌드 스크립트를 자동으로 허용합니다.

현재 승인된 빌드 목록 확인:

pnpm audit --fix -g
pnpm approve-builds -g --list

pnpm을 정기적으로 최신 버전으로 업데이트하세요. 새 버전에서 빌드 스크립트 관리 메커니즘이 개선될 수 있습니다:

pnpm self-update