入门教程

OpenClaw 安装避坑全指南：7 大常见报错逐一击破

· 约 8 分钟阅读
目录

OpenClaw 安装看似一行命令，实际踩坑点不少。本文汇总 7 大最常见安装失败场景，帮你少走弯路。

安装前的环境要求

  • Node.js ≥ 22.x（硬性要求，低版本直接报错）
  • 路径不含中文或空格（Windows 用户必须注意）
  • 端口 18789 未被占用
  • 可用内存 ≥ 2GB
  • 操作系统：Windows 10+、macOS 12+、Ubuntu 20.04+

一键安装命令

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

# Windows PowerShell
iwr -useb https://open-claw.org.cn/install-cn.ps1 | iex

# Docker（强烈推荐新手）
docker run -d --name openclaw -p 18789:18789 openclaw/openclaw:latest

坑 #1：Node.js 版本过低

报错信息：Error: node version 18.x detected, OpenClaw requires node ≥ 22.0.0

解决方案：用 nvm 管理 Node 版本

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc
nvm install 22
nvm use 22
nvm alias default 22
node --version  # 确认显示 v22.x.x

坑 #2：端口 18789 被占用

报错信息：Error: listen EADDRINUSE :::18789

# 查看谁在占用
lsof -i :18789           # macOS/Linux
netstat -ano | findstr :18789  # Windows

# 换一个端口启动
openclaw gateway --port 18800

坑 #3：国内网络下载超时

症状：安装卡住，报 ETIMEDOUT 或 ENOTFOUND

# 配置 npm 国内镜像
npm config set registry https://registry.npmmirror.com

# 使用国内安装脚本
curl -fsSL https://open-claw.org.cn/install-cn.sh | bash

坑 #4：Windows 路径包含中文

症状：安装成功但运行报错，路径找不到或乱码

报错示例：ENOENT: no such file or directory, open 'C:Users张三AppData...'

解决方案：在 openclaw.json 配置自定义数据目录：

{
  "dataDir": "C:/openclaw-data"
}

坑 #5：Linux/macOS 权限不足

报错信息：EACCES: permission denied, mkdir '/usr/local/lib/node_modules'

不要用 sudo！ 正确做法是修复 npm 全局目录权限：

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g openclaw@latest

坑 #6：WhatsApp 扫码后一直显示 Pending

可能原因：

  • 服务器与手机时间不同步 → 同步系统时间
  • WhatsApp 账号在其他设备登录过多 → 退出所有已连接设备
  • 网络无法访问 WhatsApp 服务器 → 检查代理设置
# 同步系统时间
ntpdate pool.ntp.org

手机端：进入 WhatsApp → 设置 → 已连接的设备 → 退出所有设备 → 重新扫码。

坑 #7：访问 http://127.0.0.1:18789 空白或无法连接

# 检查服务状态
openclaw status

# 查看错误日志
openclaw logs --tail 50

# 手动启动 Gateway
openclaw gateway

验证安装成功

openclaw --version   # 显示版本号
openclaw status      # 所有服务显示 running

两个命令都正常，说明安装成功。接下来运行 openclaw onboard 进入新手引导，配置你的第一个 LLM。

还是解决不了？

去 OpenClaw GitHub Issues 搜索错误信息，或加入官方 Discord 社区提问。社区活跃，通常几小时内就能得到回应。

相关阅读：

📚 相关文章

#Discord #Docker #GitHub #OpenClaw #WhatsApp
分享到： QQ 微博

📚 相关文章