一、前言
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 https://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 # 升级版本
七、总结
- 新手建议直接使用国内一键脚本，99% 的概率一次成功。
- 遇到报错优先检查Node 版本、PATH、端口、编译环境，这几个方向基本能覆盖大部分常见问题。
- 路径避免使用中文，权限要足够，日志是排查故障的利器——别害怕查看日志，它比想象中更有帮助。
