Problem Description
When installing OpenClaw or its channel adapters, you may encounter build errors with the sharp module. sharp is a high-performance image processing library that OpenClaw uses to handle image messages in chats. Common error output looks like:
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.
Or on Windows you might see:
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
Another common scenario is when the prebuilt binary download fails:
npm ERR! sharp: Installation error: connect ETIMEDOUT
npm ERR! sharp: Prebuilt libvips 8.15.2 binaries are not yet available for linux-arm64v8
Diagnostic Steps
First, confirm your system architecture and OS version:
node -e "console.log(process.platform, process.arch)"
Check whether sharp has a prebuilt binary for your system. sharp provides prebuilt packages for most mainstream platforms (linux-x64, darwin-arm64, win32-x64), but some less common architectures may require building from source.
View the detailed npm installation log:
npm install -g openclaw --verbose 2>&1 | grep sharp
Solutions
Solution 1: Set SHARP_IGNORE_GLOBAL_LIBVIPS (Recommended)
The quickest fix is to tell sharp to ignore any globally installed libvips and force it to use its own prebuilt version:
SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw
On Windows (PowerShell):
$env:SHARP_IGNORE_GLOBAL_LIBVIPS="1"
npm install -g openclaw
On Windows (CMD):
set SHARP_IGNORE_GLOBAL_LIBVIPS=1
npm install -g openclaw
This environment variable makes sharp skip detection of any system-installed libvips library and instead download and use the prebuilt binary matching your current platform.
Solution 2: Manually Install System Dependencies
If prebuilt packages are unavailable (e.g., on ARM devices or uncommon Linux distributions), you need to install build dependencies.
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
After installing dependencies, reinstall OpenClaw:
npm install -g openclaw
Solution 3: Use Docker to Avoid Build Issues
If local build issues are difficult to resolve, consider deploying OpenClaw with Docker. The official image comes with all dependencies preinstalled:
docker pull openclaw/openclaw:latest
docker run -v ~/.openclaw:/root/.openclaw openclaw/openclaw:latest
Solution 4: Skip sharp (Fallback)
If your use case doesn't involve image processing, you can configure OpenClaw to disable image processing. Add the following to ~/.openclaw/openclaw.json:
{
"imageProcessing": {
"enabled": false
}
}
Then install with --ignore-scripts (note this skips all postinstall scripts):
npm install -g openclaw --ignore-scripts
OpenClaw will still run with this approach, but sending and receiving image messages will be unavailable.
Download Failures Due to Network Proxy
If the error message indicates a prebuilt package download timeout, it may be a network issue. Set an npm mirror or proxy:
# Use 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
Or set an HTTP proxy:
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
Verifying the Fix
After successful installation, verify that the sharp module loads correctly:
node -e "const sharp = require('sharp'); console.log('sharp version:', sharp.versions)"
openclaw doctor
If openclaw doctor reports no image processing-related warnings, sharp has been installed correctly.