当前位置：首页 > news >正文

OpenClaw 全网最简单搭建步骤 + 最全避错坑位指南（2026 最新版）

news 2026/3/26 18:44:39

🔥 小白零门槛｜全平台通用｜一键脚本｜报错直接抄答案

一、前言

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 管理员）

powershell

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

macOS/Linux/WSL

bash

运行

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

✅ 安装完成验证

bash

运行

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

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

bash

运行

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

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

bash

运行

# 克隆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 部署（服务器 / 隔离环境）

bash

运行

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

四、初始化与启动

bash

运行

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

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

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

原因：npm 全局路径未加入系统 PATH

解决：

bash

运行

# 查看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 执行

powershell

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser -Force

🔴 坑 3：端口 18789 被占用

报错：address already in use

解决：

bash

运行

# 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）

解决：

bash

运行

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

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

解决：

bash

运行

SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest

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

解决：

bash

运行

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

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

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

🔴 坑 9：WSL2 运行异常

解决：

bash

运行

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

六、常用命令速查

bash

运行

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