用 npm 安装 OpenClaw 踩了哪些坑？经验总结

OpenClaw 的安装流程看起来就一行命令，但 GitHub Issues 里光是安装相关的 bug 报告就有几百条。这篇文章把最高频的坑整理出来，每个问题都说清楚报什么错、为什么报、怎么解决。

遇到任何问题，先跑这一条：

openclaw doctor --fix

它能自动检测并修复很多常见配置问题。如果它解决不了，再往下看。

坑一：EACCES 权限报错

这是最常见的报错，在 Linux 和 macOS 上几乎必踩：

npm ERR! code EACCES
npm ERR! syscall mkdir
npm ERR! path /usr/local/lib/node_modules/openclaw
npm ERR! errno -13
npm ERR! Error: EACCES: permission denied

原因是 npm 的全局安装目录属于系统，当前用户没有写入权限。

错误做法：加 sudo。

# 不要这样做
sudo npm install -g openclaw

用 sudo 装上去之后，二进制文件归 root 所有，后续 Gateway 写配置文件时会遇到更难排查的权限问题。

正确做法：把 npm 全局目录改到用户目录下：

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

如果用的是 zsh：

echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

配置好之后再执行：

npm install -g openclaw

不需要 sudo，也不会再报权限错误。

更省事的办法：用 nvm 管理 Node.js。nvm 安装的 npm 天然使用用户目录，完全不存在权限问题：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
nvm install 22
nvm use 22
npm install -g openclaw

坑二：装完之后 openclaw 命令找不到

npm 安装成功，但输入 openclaw 报：

command not found: openclaw

这不是安装失败，是 npm 全局 bin 目录没有加入 PATH。

先查全局安装路径在哪：

npm config get prefix

输出类似 /home/yourname/.npm-global，那么 openclaw 的二进制文件在 /home/yourname/.npm-global/bin/ 里。把这个路径加入 PATH：

export PATH="$(npm config get prefix)/bin:$PATH"

写入 shell 配置文件让它永久生效：

# bash 用户
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# zsh 用户
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Windows PowerShell 用户，运行：

npm config get prefix

把输出的路径加上 \bin 后缀，手动加入系统的用户 PATH 环境变量。加完之后重开一个 PowerShell 窗口生效。

坑三：Node.js 版本太低

OpenClaw 需要 Node.js 22 或更高版本。如果版本不对，安装过程中会报类似这样的错：

Error: OpenClaw requires Node.js 22 or newer. You have v18.x.x

先确认当前版本：

node --version

版本不对的话，用 nvm 切换：

nvm install 22
nvm use 22
node --version  # 确认是 v22.x.x

如果没有安装 nvm，参考前面坑一里的安装方式。

坑四：sharp / node-gyp 编译失败（macOS Apple Silicon）

这是 GitHub Issue #4592 记录的真实问题，在 macOS Apple Silicon 机器上用 npm 全局安装时概率触发：

npm error sharp: Attempting to build from source via node-gyp
npm error sharp: Found node-addon-api
npm error sharp: Please add node-gyp to your dependencies
npm error code 1

原因是 OpenClaw 的依赖 sharp 找不到预编译二进制，尝试从源码编译，但 node-gyp 没有可用的编译工具链。

解决方式一：安装 Xcode 命令行工具，提供编译所需的工具链：

xcode-select --install

装完之后重新安装 OpenClaw：

npm install -g openclaw

解决方式二：改用官方安装脚本，它在安装时会设置 SHARP_IGNORE_GLOBAL_LIBVIPS=1 环境变量，绕过这个问题：

curl -fsSL https://openclaw.ai/install.sh | bash

坑五：安装过程被系统 Kill（低内存 VPS）

这是 GitHub Issue #39447 记录的问题，在内存较小的 VPS 上（比如 DigitalOcean 1GB 内存的 Droplet）高概率触发：

Installing OpenClaw v2026.x.x
main: line 638: 9438 Killed   "${cmd[@]}" > "$log" 2>&1
! npm install failed for openclaw@latest
! npm install failed; retrying
main: line 638: 9542 Killed   "${cmd[@]}" > "$log" 2>&1
! npm install failed for openclaw@latest

日志里的 Killed 是 Linux OOM Killer 强制终止了进程，不是 OpenClaw 的 bug，而是内存不够用。

临时解决：添加 swap 空间凑够内存：

sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

然后重新安装：

npm install -g openclaw

根本解决：升级 VPS 内存到至少 2GB，官方文档推荐 4GB 以上用于正常运行。

坑六：Linux 上缺少编译工具（build-essential / git）

在精简版 Linux 镜像（常见于 VPS 初始化镜像）上，npm 安装时会报：

npm install failed
gyp ERR! find Python
gyp ERR! not ok

或者因为缺少 git 导致依赖拉取失败。

Ubuntu / Debian 一次性装齐所需工具：

sudo apt update
sudo apt install -y build-essential git python3

Fedora / CentOS：

sudo dnf groupinstall 'Development Tools'
sudo dnf install -y git python3

装完再重新执行 npm install。

混用 sudo 之后怎么清理

如果之前用 sudo npm install -g openclaw 装过，文件归属变成了 root，后续会出现各种奇怪的权限问题。彻底清理重来：

sudo npm uninstall -g openclaw
rm -rf ~/.openclaw
npm install -g openclaw

清理完之后按正确方式重装，再跑 openclaw onboard --install-daemon 重新初始化。

一张表：报错 → 原因 → 解决