问题描述
在安装 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
诊断步骤
首先确认你的系统架构和操作系统版本：
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
解决方案
方案一：设置 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 库，转而下载并使用与当前平台匹配的预编译二进制文件。
方案二：手动安装系统依赖
如果预编译包不可用（比如在 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
方案三：使用 Docker 避免编译问题
如果你的本地环境编译问题难以解决，可以考虑使用 Docker 部署 OpenClaw，官方镜像已预装所有依赖：
docker pull openclaw/openclaw:latest
docker run -v ~/.openclaw:/root/.openclaw openclaw/openclaw:latest
方案四：跳过 sharp（降级方案）
如果你的使用场景不涉及图片处理，可以配置 OpenClaw 禁用图片处理功能。在 ~/.openclaw/openclaw.json 中添加：
{
"imageProcessing": {
"enabled": false
}
}
然后使用 --ignore-scripts 安装（注意这会跳过所有 postinstall 脚本）：
npm install -g openclaw --ignore-scripts
这种方式下 OpenClaw 仍然可以运行，但发送和接收图片消息的功能将不可用。
网络代理导致的下载失败
如果错误信息显示的是预编译包下载超时，可能是网络问题。设置 npm 镜像或代理：
# 使用淘宝镜像
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 已正确安装。