最简单易学OpenClaw详细搭建步骤与避坑完整指南

一、前言

OpenClaw（小龙虾）作为一款本地 AI 助手，近期备受关注。然而，许多用户在安装阶段就遇到阻碍——命令找不到、端口冲突、编译报错……折腾数小时仍无法运行。本文为你一次性梳理最简化的安装流程与最全面的报错解决方案，覆盖 Windows、macOS、Linux、WSL 全平台，按照步骤操作即可一次成功。

二、环境要求（必读）

• Node.js 版本：要求 ≥ 22.0.0，低于该版本几乎必然报错。
• 内存：至少 2GB，建议 4GB 及以上。
• 系统：Windows 10+、macOS 12+、Linux（Ubuntu 20.04+）。
• 工具：Git、pnpm（推荐）、curl，建议提前安装。

三、4 种安装方式（新手优先选择方式 1）

方式 1：一键脚本（强烈推荐，全自动）

Windows（PowerShell 管理员）

# 解锁执行权限
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser -Force
# 国内镜像一键安装
iwr -useb https://open-claw.org.cn/install-cn.ps1 | iex

macOS/Linux/WSL

# 国内镜像一键安装
curl -fsSL https://open-claw.org.cn/install-cn.sh | bash

安装完成验证

openclaw --version
# 显示版本号即成功

方式 2：npm/pnpm 手动安装（有 Node 环境首选）

# 配置国内镜像（加速）
npm config set registry https://registry.npmmirror.com
# 全局安装
npm install -g openclaw@latest
# 初始化配置
openclaw onboard

方式 3：源码编译（开发者 / 二次开发）

# 克隆Gitee国内镜像
git clone https://gitee.com/OpenClaw-CN/openclaw-cn.git
cd openclaw-cn
# 安装pnpm
npm install -g pnpm
# 安装依赖+构建
pnpm install
pnpm ui:build
pnpm build
# 全局链接
pnpm link --global
# 初始化
openclaw onboard --install-daemon

方式 4：Docker 部署（服务器 / 隔离环境）

# 拉取镜像
docker pull openclaw/openclaw:latest
# 启动容器
docker run -d --name openclaw -p 18789:18789 openclaw/openclaw:latest

四、初始化与启动

# 配置向导（设置API Key、端口、权限）
openclaw onboard
# 启动网关
openclaw gateway start
# 查看状态
openclaw gateway status
# 访问Web UI
http://localhost:18789

五、全网最全避坑指南（按报错搜索）

坑 1：命令不存在（openclaw: command not found）

• 原因：npm 全局路径未被加入系统 PATH
• 解决方法：

# 查看npm全局路径
npm config get prefix
# Windows：将路径加入系统环境变量
# macOS/Linux：
echo 'export PATH=$(npm config get prefix)/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

坑 2：Windows 执行策略禁止运行脚本

• 报错：cannot be loaded because running scripts is disabled
• 解决方法：以管理员身份运行 PowerShell

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser -Force

坑 3：端口 18789 被占用

• 报错：address already in use
• 解决方法：

# Windows
netstat -ano | findstr :18789
taskkill /F /PID 进程号
# macOS/Linux
lsof -i :18789
kill -9 进程号
# 或修改端口
openclaw config set gateway.port 18790
openclaw gateway restart

坑 4：node-llama-cpp 编译失败

• 原因：缺少 C++ 编译环境
• 解决方法：
  • Windows：安装 VS Build Tools，勾选C++ 生成工具
  • macOS：xcode-select --install
  • Linux：sudo apt install build-essential cmake -y

坑 5：npm 安装权限错误（EACCES）

• 解决方法：

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

坑 6：sharp 安装失败（macOS）

• 解决方法：

SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest

坑 7：Gateway 启动失败 / 服务异常

• 解决方法：

# 停止服务
openclaw gateway stop
# 强制清理进程
pkill -9 -f openclaw-gateway
# 重启
openclaw gateway run --force
# 查看日志
# Windows：C:Users用户名.openclawlogs
# macOS/Linux：~/.openclaw/logs

坑 8：路径含中文 / 空格导致异常

• 规则：安装目录、工作路径禁止包含中文、空格、特殊字符
• 示例：D:AIopenclaw ✅；D:我的文件open claw ❌

坑 9：WSL2 运行异常

• 解决方法：

# 安装依赖
sudo apt install pulseaudio -y
export SDL_AUDIODRIVER=pulseaudio

六、常用命令速查

openclaw --version        # 查看版本
openclaw onboard          # 初始化配置
openclaw gateway start    # 启动网关
openclaw gateway stop     # 停止网关
openclaw gateway restart  # 重启网关
openclaw gateway status   # 查看状态
openclaw doctor           # 自动检测环境问题
npm update -g openclaw@latest  # 升级版本

七、总结

1. 新手建议直接使用国内一键脚本，99% 的概率一次成功。
2. 遇到报错优先检查Node 版本、PATH、端口、编译环境，这几个方向基本能覆盖大部分常见问题。
3. 路径避免使用中文，权限要足够，日志是排查故障的利器——别害怕查看日志，它比想象中更有帮助。