OpenClaw 装不上？10 个常见报错对照解决

OpenClaw 安装报错 10 条：现象、原因和解决

开查之前先记下三样东西：操作系统、node -v 的输出、装的方式（官方脚本 / npm / Docker），下面的排查要用到。装好了但不对劲的，跑一遍 openclaw doctor，它会把配置、服务、版本的问题列出来。

1. 命令找不到：openclaw: command not found

现象：装的过程没报错，一敲 openclaw 却说 command not found（Windows 是「不是内部或外部命令」）。

原因：npm 的全局 bin 目录没在你 shell 的 PATH 里。用 nvm / fnm 这类版本管理器时，没在 shell 启动文件里初始化它，新开的终端也找不到 Node 的 bin。

解决：先问 npm 全局包装在哪，再看 PATH 里有没有它，没有就加上并重开终端：

npm prefix -g
echo "$PATH"
# 没有的话，把下面这行加进 ~/.zshrc 或 ~/.bashrc
export PATH="$(npm prefix -g)/bin:$PATH"

Windows 是把 npm prefix -g 的输出加进「系统环境变量 → Path」。

2. Node 版本不对：装好了却起不来，或压根不让装

现象：报 Node 版本不受支持，或 node:sqlite 之类的模块找不到。

原因：Node 版本，或者它实际加载的 SQLite，不在支持范围里。当前支持 24.16.0+（24.x）或 26.1.0+，推荐 26.1.0+；Node 22、23、25 都不支持，见官方兼容表。

解决：node -v 确认。版本不够就装一个新的（macOS brew install node，Ubuntu 走 NodeSource 的 setup_26.x 脚本，Windows winget install OpenJS.NodeJS.LTS），或者干脆用官方一键脚本——它发现 Node 缺了会自己装。换完 Node 再跑一遍 openclaw doctor，看它还报不报版本问题。

3. npm 把安装脚本拦了：blocked because they are not covered by allowScripts

现象：npm install -g openclaw 跑完，报上面那句，龙虾装得不完整。

原因：npm 12 起默认拦住包的 preinstall / postinstall 脚本，OpenClaw 恰好要跑这两个。npm 11.16 只警告不拦；11.15 及更老的压根没这个机制。

解决：命令后面加 --allow-scripts=openclaw（老 npm 不认识这个参数，去掉即可）。pnpm 对应的是 --allow-build=openclaw，bun 是 --trust。用官方一键脚本的话它自己会处理。

4. 端口被占：Gateway 说地址已被使用

现象：启动时报 EADDRINUSE 或 address already in use，openclaw gateway status 显示起不来。

原因：龙虾的 Gateway 默认监听 18789 端口，被别的程序占着——比如上一次没关干净的龙虾自己，或者你同时跑了本机装的和 Docker 装的两份。

解决：查出占端口的进程号（PID），把它停掉：

# macOS / Linux：输出里 PID 那一列就是进程号
lsof -i :18789
kill <PID>

# Windows：最后一列是进程号
netstat -ano | findstr 18789
taskkill /PID <PID> /F

占着端口的是另一份龙虾（比如 Docker 里那份），就只留一份在跑；Docker 那份用 docker compose down 停。

5. 权限不足：全局装包时 EACCES

现象：npm install -g 报 EACCES: permission denied。

原因：npm 的全局目录归 root 所有，你的普通用户写不进去。

解决：不要加 sudo 硬装——root 装出来的环境后面升级、装插件更麻烦。把 npm 的全局目录换到自己家目录下：

mkdir -p "$HOME/.npm-global"
npm config set prefix "$HOME/.npm-global"
export PATH="$HOME/.npm-global/bin:$PATH"   # 这行也加进 ~/.bashrc 或 ~/.zshrc

6. 网络超时：下载卡住或失败

现象：一键脚本或 npm 长时间不动，最后报 timeout、ETIMEDOUT 或 connection reset。

原因：npm 源和 GitHub 在境外，网络不稳。

解决：给 npm 换一个国内镜像源再装：

npm config set registry https://registry.npmmirror.com
npm install -g openclaw@latest --allow-scripts=openclaw

一键脚本卡在下载这一步的，本机已有版本合格的 Node 时也可以改用上面这两条 npm 命令装，装完手动跑 openclaw onboard --install-daemon 走引导。

7. WSL 里后台服务装不上

现象：Windows 的 WSL 里装完，openclaw gateway status 说服务不存在，或 systemctl --user 报连不上 systemd。

原因：WSL 的 Ubuntu 默认没开 systemd，龙虾的后台服务靠它拉起。

解决：在 /etc/wsl.conf 里加上 [boot] 段的 systemd=true，回 PowerShell 跑 wsl --shutdown 再进来，然后 openclaw gateway install 补装服务。详见 WSL 装法。

8. 磁盘 / 内存不够：No space left，或构建镜像被杀

现象：No space left on device；Docker 路线则是构建到一半 exit 137。

原因：前者是磁盘或临时目录满了；后者是你让 Docker 在本机从源码构建镜像，而官方 Docker 文档写本机构建至少要 6 GB 内存。

解决：清理空间；装本地模型前先看模型文件有多大，按它留出磁盘（各档模型的文件大小见 跑 OpenClaw 要什么配置）；Docker 用户设 OPENCLAW_IMAGE 用现成镜像，内存不到 6 GB 的机器别在本机构建。

9. 开着代理装不上：npm、git、curl 各认各的代理设置

现象：系统代理开着，终端里的 npm 或 curl 还是报连接失败；关掉代理又下不动境外源。

原因：系统代理只管到一部分程序，终端里的 npm、git、curl 要各自配了才走代理。

解决：两种做法挑一种。要走代理，就给这三样都配上，端口换成你代理软件的本地端口：

npm config set proxy http://127.0.0.1:<端口>
npm config set https-proxy http://127.0.0.1:<端口>
git config --global http.proxy http://127.0.0.1:<端口>
export https_proxy=http://127.0.0.1:<端口>   # curl 和一键脚本读这个环境变量

export 是 bash / zsh 的写法，只对当前终端有效。PowerShell 里对应的是 $env:HTTPS_PROXY = "http://127.0.0.1:<端口>"。

不走代理，就把代理关掉，把上面四样都撤掉，再按第 6 条换国内镜像源来装。git 那一条别漏，留着它会一直指向已经关掉的端口：

npm config delete proxy
npm config delete https-proxy
git config --global --unset http.proxy
unset https_proxy   # PowerShell 里是 Remove-Item Env:HTTPS_PROXY

10. 检查项：Gateway token 是不是照抄了文档里的示例值

看哪里：~/.openclaw/.env 里的 OPENCLAW_GATEWAY_TOKEN 一行，以及 openclaw config get gateway.auth.token 的输出。看里面的值是不是从文档或教程里原样抄来的示例 token。

为什么要查：2026.9.3 的更新记录里有一条：占位的 Gateway token 会被拒绝或修复（reject or repair placeholder Gateway tokens）。

怎么改：用 openssl rand -hex 32 生成一个随机值，换掉那个示例值，再跑 openclaw gateway restart。模型服务商那一侧的 key 填错是另一类问题，见 连不上模型怎么排。

10 条都对不上：重装 OpenClaw 怎么不丢数据

逐条对完还是不行，跑一遍 openclaw doctor，把输出留下来。确实要重装时按这个顺序：

1. 备份。openclaw backup create --verify，写完即校验。
2. 预演。openclaw uninstall --dry-run，只打印它打算删什么，不动文件。
3. 卸载。不带范围参数直接运行 openclaw uninstall，它会让你逐项勾选，默认只选 Gateway 服务。只是为了重装就保持这个默认，别勾状态（state）和工作区（workspace）。不要用 openclaw uninstall --all：--all 是 --service --state --workspace --app 的简写，状态、配置和工作区会一起删掉。
4. 重装。openclaw uninstall 不卸 CLI 本体，官方写明没有单独卸 CLI 的范围；卸完再跑一次官方脚本 curl -fsSL https://openclaw.ai/install.sh | bash，就是在原地重装。

参数说明见官方卸载命令文档。不想在本机管 Node 环境的，也可以换 Docker 部署，它另有挂载权限、容器连宿主机这几类问题要处理。模型那一侧连不上是另一类问题，看 连不上模型怎么排。

常见问题

用 Docker 装是不是能少踩很多坑？

Docker 能避开宿主机上 Node、PATH 和 npm 依赖这几类问题，换来的是镜像版本、容器用户与挂载权限、网络和内存这几类。官方把它定位成可选的部署方式。

报错本文也没有怎么办？

记下版本、安装方式和完整报错，按官方排障文档的顺序依次跑 openclaw status、openclaw gateway status、openclaw logs --follow、openclaw doctor。logs --follow 会一直跟着输出，看完按 Ctrl+C 退出再跑下一条。拿输出里的报错原文到官方排障文档里找对应的小节。