OpenClaw 常见安装错误

OpenClaw（前 Clawdbot / Moltbot）安装过程在大多数情况下通过一键脚本非常顺畅，但由于 Node.js 环境、权限、旧版本残留、系统差异等因素，仍然会出现一些高频错误。本文汇总了 GitHub Issues、官方文档、Reddit、Discord 和社区博客中最常见的安装/Onboarding 问题及实测有效的修复方法，按出现频率排序。

适用于 macOS、Linux（Ubuntu/Debian/Fedora）、Windows（WSL 或原生 PowerShell）用户。优先检查 Node.js 版本 和 权限，90% 的问题出在这两点。

1. Node.js 版本过低或不匹配（最常见，占 ~40%）

错误表现：

• npm install 报语法错误、dependency 失败
• ERR! sharp ... node-gyp 或构建失败
• 安装卡住、无明确报错

症状关键词：node --version 显示 v18.x / v16.x / v14.x，或 v23+ / v24+

解决方法：

• OpenClaw 官方要求 Node.js v22.x LTS（不要用 v20 或 v24+，部分依赖不兼容）
• 推荐使用 nvm 安装干净版本：
  Bash

   

  curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
  source ~/.bashrc   # 或 ~/.zshrc
  nvm install 22
  nvm use 22
  nvm alias default 22

   

   
• 清理缓存后重装：
  Bash

   

  npm cache clean --force
  curl -fsSL https://openclaw.ai/install.sh | bash

   

   
• Windows 用户：用 nvm-windows 或直接官网下载 v22 LTS 安装包

2. EACCES: permission denied（全局 npm 安装权限问题，macOS/Linux 经典错误）

错误表现：

• npm error code EACCES ... mkdir '/usr/local/lib/node_modules/openclaw'
• permission denied, mkdir '/usr/lib/node_modules/openclaw'

解决方法（选一种，优先第1种）：

方案A：修改 npm 全局安装目录到用户目录（最推荐）

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

方案B：使用 sudo（快速但不优雅）

sudo npm install -g openclaw@latest
# 之后 onboarding 不要用 sudo
openclaw onboard

3. install.sh / install.ps1 运行失败，但无明确原因

错误表现：

• 脚本执行完但 openclaw --version command not found
• Windows：npm error spawn git / ENOENT

解决方法：

• Windows：先安装 Git（必须！）
  PowerShell

   

  winget install git.git
  # 关闭所有 PowerShell 窗口，重新以管理员打开，再运行
  iwr -useb https://openclaw.ai/install.ps1 | iex

   

   
• 所有系统：手动安装查看真实错误
  Bash

   

  npm install -g openclaw@latest

   

   
• 清理临时文件（Windows 常见）
  PowerShell

   

  Remove-Item "$env:TEMP\OpenClaw\*" -ErrorAction SilentlyContinue

   

   

4. Onboarding 阶段 “gateway connect failed: pairing required” 或 “device token mismatch”

错误表现：

• TUI 显示 connected 但收不到消息
• 无限循环 pairing required / unauthorized

解决方法：

• 确保 Gateway 已启动：
  Bash

   

  openclaw gateway status
  sudo systemctl status openclaw-gateway   # Linux systemd

   

   
• 强制重装 Gateway 服务：
  Bash

   

  openclaw gateway install --force
  openclaw gateway restart

   

   
• 检查并重置 token：
  Bash

   

  openclaw token create --name default --expires-in 365d
  # 把新 token 填到 ~/.openclaw/openclaw.json 的 gateway.auth.token
  openclaw gateway restart

   

   
• 确认 config 中 gateway.mode = "local"
  Bash

   

  openclaw config set gateway.mode local

   

   

5. Docker 安装相关错误（EACCES / volume permission）

错误表现：

• EACCES: permission denied, mkdir '/home/node/.openclaw/...'
• Docker Desktop (Windows/Mac) 特别常见

解决方法：

• 预创建目录并 chown：
  Bash

   

  mkdir -p ~/.openclaw
  sudo chown -R $USER:$USER ~/.openclaw

   

   
• 使用官方 docker-compose：
  Bash

   

  git clone https://github.com/openclaw/openclaw
  cd openclaw/docker
  docker compose up -d
  docker compose run --rm openclaw-cli onboard

   

   
• Windows Docker Desktop：关闭 “Use gRPC FUSE for file sharing” 或用 WSL2 后端

6. Chromium / 浏览器工具安装失败（间接影响 onboarding）

错误表现：

• Onboarding 卡在浏览器工具检测

解决方法（Linux）：

sudo apt update
sudo apt install -y chromium-browser libnss3 libatk-bridge2.0-0 ...

7. Windows Defender / Antivirus 拦截

错误表现：

• 安装中途突然失败、无日志
• Node.js 被标记为 access violation

解决方法：

• 临时关闭 Windows Defender（实时保护）
• 或把安装目录加到排除列表
• 安装完成后重新开启

快速诊断命令合集（复制粘贴排查）

node --version                  # 必须 v22.x
npm --version
which node                      # 确认路径
openclaw --version              # 已安装？
openclaw gateway status
journalctl -u openclaw-gateway -n 50   # Linux 日志
openclaw logs                   # CLI 日志
cat ~/.openclaw/openclaw.json   # 检查 config

最后建议

• 先跑官方一键脚本 → 失败 → 手动 npm i -g openclaw@latest 看详细错误
• 所有操作不要混用 sudo 和普通用户，容易导致权限混乱
• 卡住超过 5 分钟 → 直接去官方 Discord（https://discord.gg/clawd）贴日志，或 GitHub Issues 搜索关键词 + “installation”
• 最新版本（2026.3.x）已修复大量早期权限/兼容问题，保持更新：openclaw update