这篇不是"另一种安装教程"。我看过太多安装教程了，它们的问题在于：写得太顺利了。作者自己装的时候一帆风顺，就默认读者也会一帆风顺。但现实是——我第一次装OpenClaw的时候踩了三个坑，来回折腾了快两小时。所以这篇文章重点不在安装步骤本身，而在"哪些地方容易出错、怎么避开"。

OpenClaw最新版本一键部署包下载地址：https://top.wokk.cn/

坑1：Node.js版本不对

这是排名第一的坑。如果你走源码安装路线，Node版本低于18会直接报错。

错误表现：
Error: The engine “node” is incompatible with this module.

排查：
node --version

低于18？用nvm升级：
nvm install 18
nvm use 18

Windows用户如果没有nvm，去GitHub搜nvm-windows下载安装。别用 --force 跳过版本检查——能装上但后续运行会出各种奇怪的问题。

坑2：端口被Hyper-V保留

Windows用户独有的坑。默认端口3456可能在Hyper-V的保留端口范围内，导致启动时报"端口被占用"但实际查不到占用进程。

排查命令：
netsh interface ipv4 show excludedportrange protocol=tcp

如果3456落在某个保留区间：
解决：改端口，修改config.yaml
gateway:
port: 3780

这个问题我查了半小时，一直在找谁占的端口，最后才发现是Hyper-V保留的。

坑3：.env文件名多了.txt后缀

Windows文件管理器默认隐藏扩展名。你以为创建了一个 .env 文件，实际系统创建的是 .env.txt。OpenClaw读不到，API Key就是空的。

解决：
文件夹选项 → 查看 → 取消勾选"隐藏已知文件扩展名"
然后检查文件名是否真的是 .env
坑4：npm install超时

国内网络环境下npm install卡住是家常便饭。

先配镜像：
npm config set registry https://registry.npmmirror.com

还不行？试试cnpm：
npm install -g cnpm --registry=https://registry.npmmirror.com
cnpm install
坑5：API Key填了但不生效

检查清单：

□ .env文件在 ~/.qclaw/ 目录下？
□ 文件编码是UTF-8 without BOM？
□ Key前后没有多余空格或换行？
□ 环境变量名拼写正确？
智谱是 ZHIPU_API_KEY，不是 ZHUPU_API_KEY

最后一条我犯过——把ZHIPU打成了ZHUPU，查了半天才发现拼写错误。

坑6：Docker卷映射没加

错误（数据全在容器内，容器删了就没了）

docker run -d -p 3456:3456 nicepkg/openclaw:latest

正确（数据持久化到宿主机）

docker run -d -p 3456:3456 -v ~/.qclaw:/root/.qclaw nicepkg/openclaw:latest
坑7：macOS安全策略阻止运行

从网上下载的dmg文件，首次打开时macOS会提示"无法验证开发者"。

解决：
系统偏好设置 → 安全性与隐私 → 点"仍要打开"
或者终端执行：xattr -cr /Applications/OpenClaw.app
坑8：启动后浏览器空白

端口通了服务也跑着，但浏览器一片白。大概率是缓存问题。

Ctrl+Shift+Delete清除浏览器缓存
或者用无痕模式（Ctrl+Shift+N）打开 http://localhost:3456

以上8个坑覆盖了我在Windows、macOS和Linux上安装OpenClaw时遇到的全部问题。提前了解这些，你的安装过程应该能控制在10分钟以内。