OpenClaw 설치 시 Sharp 모듈 빌드 실패 해결

문제 설명

OpenClaw이나 채널 어댑터를 설치할 때 sharp 모듈의 빌드 오류가 발생할 수 있습니다. sharp는 OpenClaw이 채팅에서 이미지 메시지를 처리하는 데 사용하는 고성능 이미지 처리 라이브러리입니다. 일반적인 오류 출력은 다음과 같습니다:

npm ERR! ../src/common.cc:25:10: fatal error: vips/vips8: No such file or directory
npm ERR!  #include <vips/vips8>
npm ERR!           ^~~~~~~~~~~~
npm ERR! compilation terminated.

또는 Windows에서는 다음과 같은 오류가 나타날 수 있습니다:

gyp ERR! find VS
gyp ERR! find VS msvs_version not set from command line or npm config
gyp ERR! find VS VCINSTALLDIR not set, not running in VS Command Prompt
gyp ERR! find VS could not use PowerShell to find Visual Studio 2017 or newer

사전 빌드 바이너리 다운로드가 실패하는 경우도 있습니다:

npm ERR! sharp: Installation error: connect ETIMEDOUT
npm ERR! sharp: Prebuilt libvips 8.15.2 binaries are not yet available for linux-arm64v8

진단 단계

먼저 시스템 아키텍처와 OS 버전을 확인합니다:

node -e "console.log(process.platform, process.arch)"

sharp가 해당 시스템에 사전 빌드 바이너리를 가지고 있는지 확인합니다. sharp는 대부분의 주류 플랫폼(linux-x64, darwin-arm64, win32-x64)에 대해 사전 빌드 패키지를 제공하지만, 일부 비주류 아키텍처는 소스에서 빌드해야 할 수 있습니다.

npm 설치 로그를 상세히 확인합니다:

npm install -g openclaw --verbose 2>&1 | grep sharp

해결 방법

방법 1: SHARP_IGNORE_GLOBAL_LIBVIPS 설정 (권장)

가장 빠른 수정 방법은 sharp에게 전역 설치된 libvips를 무시하고 자체 사전 빌드 버전을 강제로 사용하도록 지시하는 것입니다:

SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw

Windows(PowerShell)에서:

$env:SHARP_IGNORE_GLOBAL_LIBVIPS="1"
npm install -g openclaw

Windows(CMD)에서:

set SHARP_IGNORE_GLOBAL_LIBVIPS=1
npm install -g openclaw

이 환경 변수는 sharp가 시스템에 설치된 libvips 라이브러리의 감지를 건너뛰고 현재 플랫폼에 맞는 사전 빌드 바이너리를 다운로드하여 사용하도록 합니다.

방법 2: 시스템 의존성 수동 설치

사전 빌드 패키지를 사용할 수 없는 경우(예: ARM 장치 또는 비주류 Linux 배포판), 빌드 의존성을 설치해야 합니다.

Ubuntu / Debian:

sudo apt-get update
sudo apt-get install -y build-essential libvips-dev

CentOS / RHEL / Fedora:

sudo dnf install gcc-c++ make vips-devel

macOS:

brew install vips

의존성 설치 후 OpenClaw을 재설치합니다:

npm install -g openclaw

방법 3: Docker를 사용하여 빌드 문제 회피

로컬 빌드 문제를 해결하기 어려운 경우, Docker로 OpenClaw을 배포하는 것을 고려하세요. 공식 이미지에는 모든 의존성이 사전 설치되어 있습니다:

docker pull openclaw/openclaw:latest
docker run -v ~/.openclaw:/root/.openclaw openclaw/openclaw:latest

방법 4: sharp 건너뛰기 (대체 방안)

이미지 처리를 사용하지 않는 경우, OpenClaw에서 이미지 처리를 비활성화하도록 설정할 수 있습니다. ~/.openclaw/openclaw.json에 다음을 추가합니다:

{
  "imageProcessing": {
    "enabled": false
  }
}

그런 다음 --ignore-scripts로 설치합니다 (이 옵션은 모든 postinstall 스크립트를 건너뜁니다):

npm install -g openclaw --ignore-scripts

이 방식으로 OpenClaw은 여전히 실행되지만, 이미지 메시지 송수신은 사용할 수 없습니다.

네트워크 프록시로 인한 다운로드 실패

오류 메시지가 사전 빌드 패키지 다운로드 타임아웃을 나타내는 경우, 네트워크 문제일 수 있습니다. npm 미러 또는 프록시를 설정합니다:

# npmmirror 사용
npm config set sharp_binary_host "https://npmmirror.com/mirrors/sharp"
npm config set sharp_libvips_binary_host "https://npmmirror.com/mirrors/sharp-libvips"
npm install -g openclaw

또는 HTTP 프록시를 설정합니다:

npm config set proxy http://127.0.0.1:7890
npm config set https-proxy http://127.0.0.1:7890
npm install -g openclaw

수정 확인

성공적으로 설치한 후 sharp 모듈이 올바르게 로드되는지 확인합니다:

node -e "const sharp = require('sharp'); console.log('sharp version:', sharp.versions)"
openclaw doctor

openclaw doctor가 이미지 처리 관련 경고를 보고하지 않으면 sharp가 올바르게 설치된 것입니다.