OpenClaw 全网最简单搭建步骤+最全避错坑位指南

OpenClaw 全网最简单搭建步骤+最全避错坑位指南需要先看清适用场景和关键步骤，避免只记结论却忽略实际限制。

一、前言

OpenClaw（小龙虾）作为热门本地 AI 助手，很多同学卡在安装失败、命令不存在、端口占用、编译报错等问题。本文整理最简安装流程 + 高频报错全集，Windows/macOS/Linux/WSL 全覆盖，跟着走一次成功。

二、环境要求（必看）

1. Node.js ≥ 22.0.0（低于此版本必报错）
2. 内存 ≥ 2GB（推荐 4GB+）
3. 系统：Windows 10+/macOS 12+/Linux（Ubuntu 20.04+）
4. 工具：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.gitcd openclaw-cn# 安装pnpmnpm install -g pnpm# 安装依赖+构建pnpm installpnpm ui:buildpnpm 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 UIhttp://localhost:18789

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

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

1. 原因：npm 全局路径未加入系统 PATH
2. 解决：

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

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

1. 报错：cannot be loaded because running scripts is disabled
2. 解决：管理员 PowerShell 执行

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser -Force

? 坑 3：端口 18789 被占用

1. 报错：address already in use
2. 解决：

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

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

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

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

1. 解决：

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

? 坑 6：sharp 安装失败（macOS）

1. 解决：

SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest

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

1. 解决：

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

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

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

? 坑 9：WSL2 运行异常

1. 解决：

# 安装依赖sudo apt install pulseaudio -yexport 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. 路径别用中文，权限给足，日志是排错神器