装 OpenClaw 报错，第一步该看什么？

看报错的最后几行，别被前面一堆栈吓到。真正的原因通常在最后一句，比如 command not found、EADDRINUSE、EACCES、blocked because they are not covered by allowScripts。先把这句拷出来对照本文；装好了但不对劲的，先跑一遍 openclaw doctor，它会把配置、服务、版本的问题列出来。

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

能绕开一部分。Node 版本、PATH、npm 权限这几类坑，Docker 镜像里都固定好了。但 Docker 有自己的一套坑：挂载目录权限（镜像里是 uid 1000）、容器里连不上宿主机的本地模型、小内存机器构建镜像被杀。官方也把 Docker 定位成可选项，本机能直接装就直接装。

报错本文也没有怎么办？

先 openclaw doctor 让它自检一遍。再把最后一行报错原样搜索，加上 OpenClaw 关键词，多数安装问题别人都遇到过。实在不行，openclaw uninstall --all 清干净再用官方脚本重装一遍，往往比逐行排查更快——配置和数据在 ~/.openclaw，卸载时可以选择保留工作区。

排错 · 安装

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

钳叔 · 龙虾AI 编辑部 · 2026-08-23 · 约 12 分钟

装龙虾时满屏红字弹出来，很多人第一反应是慌——其实大可不必。安装失败九成都逃不出下面这十类，而且报错信息本身就在告诉你属于哪一类，会读就等于解决了一半。下面每类都按「现象 → 原因 → 解决」排好，对号入座即可。先教你一招通用的：报错只看最后几行，前面那一长串调用栈基本是噪音，真正的病因往往藏在最后一句。

动手前的两条通用建议

先认清它是 Node 项目。OpenClaw 靠 Node.js 跑，不是 Python。网上（包括本站早期版本）那些教你 python -m venv、pip install -r requirements.txt 的安装法是错的，照着走到第一步就失败——你遇到的“报错”可能根本不是龙虾的错，是教程的错。正确装法见三平台部署教程。
记下你的环境三件套：操作系统、node -v 的输出、装的方式（官方脚本 / npm / Docker）。下面很多坑跟这三个直接相关。装好了但不对劲的，先跑一遍 openclaw doctor，它会把配置、服务、版本的问题列出来，比自己猜快。

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

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

原因：十有八九是 PATH——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 太老，或者偏偏是 Node 23——它不在支持范围内。要求是 22.22.3+、24.15+ 或 25.9+，官方推荐直接上 26。

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

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 装的两份。

解决：先查谁占着，然后停掉它：

lsof -i :18789                 # macOS / Linux
netstat -ano | findstr 18789   # Windows

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

现象：npm install -g 报 EACCES: permission denied，常见于 Linux。

原因：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

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 在本机从源码构建镜像，1G 内存扛不住（官方要求 2G 以上）。

解决：清理空间，装本地模型前预留几十 GB；Docker 用户设 OPENCLAW_IMAGE 用现成镜像，别在小机器上构建。

9. 代理把安装搅黄：开了梯子反而连不上

现象：开着代理时装包各种失败，关掉又下不动境外源。

原因：代理只代理了一部分流量，npm 或 curl 没走代理，状态错乱。

解决：要么给 npm / git 也显式配上代理，要么干脆关代理 + 换国内镜像源，两条路别混着走。

10. Gateway 拒绝启动：token 是文档里的示例值

现象：装是装好了，Gateway 一起就退，日志里提示 gateway token 的问题。

原因：你把文档或教程里的示例 token 原样抄进了 ~/.openclaw/.env 的 OPENCLAW_GATEWAY_TOKEN。龙虾会认出这是占位值、拒绝启动——这是防你裸奔的安全设计。

解决：把那行留空让它首次启动自己生成，或者用 openssl rand -hex 32 造一个真随机值填进去。接模型那一侧的 key 填错是另一类问题，见接 API 还是本地模型。

避坑提示 最常见的“装不上”其实是第 1 类——装好了但找不到命令，新手以为没装成又装一遍、装三遍，越装越乱。与其反复装，不如先 npm prefix -g 看一眼东西在哪、PATH 里有没有。另一个常见的是「端口被占」（第 4 类），多半是上次没关干净的 Gateway 占着 18789，lsof -i :18789 查出来停掉即可。先看 PATH、再留意端口，安装阶段基本就顺了。

实在搞不定时

如果逐条对完还是不行，最省事的办法不是死磕——卸干净重来一遍：openclaw uninstall --all（可以选择留工作区），再跑一次官方脚本 curl -fsSL https://openclaw.ai/install.sh | bash。它走直接安装，能把装到一半的包补齐。机器上不想折腾 Node 环境的，也可以换 Docker 路线，但它有自己的一套坑（挂载权限、容器连宿主机），别指望零麻烦。模型那一侧连不上是另一类问题，单独看连不上模型怎么排。

常见问题

装 OpenClaw 报错，第一步该看什么？: 看报错的最后几行，别被前面一堆栈吓到。真正的原因通常在最后一句，比如 command not found、EADDRINUSE、EACCES、blocked because they are not covered by allowScripts。先把这句拷出来对照本文；装好了但不对劲的，先跑 openclaw doctor。
用 Docker 装是不是能少踩很多坑？: 能绕开一部分：Node 版本、PATH、npm 权限这几类在镜像里都固定好了。但 Docker 有自己的坑：挂载目录权限（镜像里是 uid 1000）、容器里连不上宿主机的本地模型、小内存机器构建被杀。官方把它定位成可选项，本机能直接装就直接装。
报错本文也没有怎么办？: 先 openclaw doctor 自检。再把最后一行报错原样搜索，加上 OpenClaw 关键词，多数安装问题别人都遇到过。实在不行，openclaw uninstall --all 清干净再用官方脚本重装，往往比逐行排查更快——配置和数据在 ~/.openclaw，卸载时可以选择保留工作区。