新手小白安装OpenClaw详细教程(全系统通用,附避坑指南)

核心说明：OpenClaw是一款开源AI智能体工具，可实现聊天式操控电脑、对接各类大模型，新手安装核心是搞定「环境依赖」和「初始化配置」，全程跟着步骤走，避免跳过环节。本教程覆盖Windows（推荐WSL2）、macOS、Linux三大系统，优先推荐「一键脚本安装」（最适合小白，少踩坑），同时补充npm安装、源码安装方案，适配不同需求。

前置提醒：安装前关闭电脑杀毒软件（避免拦截安装文件），全程保持网络稳定；所有命令直接复制粘贴，不要手动输入（防止输错符号）；如果之前装过旧版本，先彻底卸载清理（步骤见文末）。

一、安装前准备（必做，否则安装必失败）

1.系统要求（新手优先选这些系统）

✅ 推荐系统：macOS 10.15+、Linux（Ubuntu/Debian，最兼容）
✅ Windows系统：必须用WSL2（Windows子系统），原生Windows直接安装易报错（WSL2安装见下文专属步骤）
❌ 不推荐：Windows XP、Windows 7，以及精简版Windows 10/11（易缺失核心组件，参考摘要1踩坑案例）

2.必备环境（所有系统通用，提前安装）

核心依赖：Node.js（版本≥22.0.0，低于此版本会导致安装失败）、包管理器（npm，随Node.js自带）、Git（可选，源码安装需用）

补充：如果用一键脚本安装，部分环境会自动安装，无需手动操作，新手优先选一键脚本。

二、分系统详细安装步骤（新手优先一键脚本）

（一）Windows系统（最常用，重点讲解）

第一步：安装WSL2（Windows子系统，必做）

以管理员身份打开「PowerShell」（按下Win+X，选择“Windows PowerShell(管理员)”）；
复制粘贴命令，启用WSL功能：wsl --install（默认安装Ubuntu系统，等待10-15分钟，期间会自动重启电脑）；
重启后，会自动弹出Ubuntu终端，设置用户名和密码（密码输入时不显示，正常输入即可，记住密码）；
验证WSL2是否安装成功：在Ubuntu终端输入 wsl --version，显示版本信息即为成功。

第二步：安装OpenClaw（3种方法，新手选方法1）

方法1：官方一键脚本（最推荐，小白首选）

打开Ubuntu终端（Win+R输入wsl，回车即可）；
复制粘贴一键安装脚本，回车执行：curl -fsSL openclaw.ai/install.sh | bash；
等待安装（5-10分钟，取决于网络速度），期间会自动安装Node.js、Git等依赖，无需手动操作；
安装完成后，执行初始化命令：openclaw onboard --install-daemon（启动配置向导）。

方法2：npm安装汉化版（稳定，适合国内用户）

打开Ubuntu终端，先配置npm国内镜像（加速下载）：npm config set registry https://registry.npmmirror.com；
卸载旧版本（如有）：npm uninstall -g openclaw；
安装中文汉化版：npm install -g @qingchencloud/openclaw-zh@latest；
验证安装：输入openclaw --version，显示带“-zh”后缀的版本号（如v2026.2.2-zh）即为成功；
执行初始化：openclaw onboard。

方法3：源码安装（国内网络更快，适合有基础的小白）

克隆中文仓库：git clone https://gitee.com/OpenClaw-CN/openclaw-cn.git；
进入源码目录：cd openclaw-cn；
切换稳定版：git checkout v2026.2.2-cn；
安装依赖（推荐pnpm，速度更快）：pnpm config set registry https://registry.npmmirror.com→ pnpm install→ pnpm build；
初始化：pnpm openclaw onboard --install-daemon。

（二）macOS系统（兼容性好，步骤简单）

方法1：官方一键脚本（首选）

打开「终端」（启动台→其他→终端）；
复制粘贴脚本，回车执行：curl -fsSL openclaw.ai/install.sh | bash；
若提示“权限不足”，在命令前加sudo：sudo curl -fsSL openclaw.ai/install.sh | bash，输入电脑开机密码（输入时不显示）；
安装完成后，执行初始化：openclaw onboard --install-daemon。

方法2：npm安装汉化版

打开终端，配置npm国内镜像：npm config set registry https://registry.npmmirror.com；
卸载旧版本（如有）：sudo npm uninstall -g openclaw；
安装汉化版：sudo npm install -g @qingchencloud/openclaw-zh@latest；
验证安装：openclaw --version，显示带“-zh”后缀即为成功；
初始化：openclaw onboard。

（三）Linux系统（Ubuntu/Debian，最兼容）

打开终端，更新系统依赖：sudo apt update && sudo apt upgrade -y；
执行一键安装脚本：curl -fsSL openclaw.ai/install.sh | bash；
安装完成后，初始化：openclaw onboard --install-daemon；
验证安装：openclaw -v，显示版本号即为成功。

三、关键步骤：初始化配置向导（所有系统通用，必做）

执行openclaw onboard后，会进入交互式配置界面，新手按以下指引操作（不要选默认，避免出错）：

模式选择（Mode）：选择「QuickStart」（自动配置基础参数，适合新手）；
模型提供商（Provider）：

国内用户：选「Qwen（通义千问）」，后续会弹出网页，登录阿里云账号即可完成授权（免费额度足够新手使用）；
国外用户：选「OpenAI/Claude」，需要输入对应API Key（可参考摘要2的一步API获取方法）；
暂时不想配置：选「Skip for now」，后续可在配置文件中修改。

Skill管理器安装：输入「Skip for now」（后续再装，避免新手出错）；
聊天平台连接：输入「Skip for now」（新手先用水印版，后续再配置飞书/企业微信）；
配置完成：提示“Onboard completed”即为成功。

四、启动与验证安装（确认OpenClaw能正常使用）

1.启动网关服务（核心，提供网页管理界面）：

临时启动（关闭终端即停止）：openclaw gateway；
后台启动（开机自启，推荐）：openclaw gateway start。

2.验证启动成功：在浏览器中输入http://127.0.0.1:18789，能打开OpenClaw中文管理面板即为成功；

3.获取登录Token：在终端输入 openclaw config get gateway.auth.token，复制Token粘贴到网页登录框，即可进入管理界面。

五、新手避坑指南（高频报错解决方案）

1. npm安装报错（code 128、code 1）

原因：Node.js版本过低、权限不足、旧版本残留或网络问题（参考摘要1）；

解决方案：升级Node.js：用nvm安装22版本（终端输入）：curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash→ source ~/.bashrc→ nvm install 22→ nvm use 22；清理缓存：npm cache clean --force；删除残留：Remove-Item -Recurse -Force "C:\Users\用户名\AppData\Roaming\npm\node_modules\openclaw"（Windows），或 rm -rf ~/.npm/node_modules/openclaw（macOS/Linux）；权限不足：命令前加sudo（macOS/Linux），或用管理员身份打开终端（Windows）。

2. Git报错（npm ERR! syscall spawn git）

原因：系统缺少Git环境，OpenClaw部分依赖需要通过Git拉取（参考摘要1）；

解决方案： Windows：访问，下载64-bit安装包，全程默认下一步安装，安装后重启电脑；macOS：brew install git（需先安装Homebrew）；Linux：sudo apt install git -y。

3.浏览器无法访问管理面板（http://127.0.0.1:18789）

原因：网关未启动、端口被占用，或防火墙拦截（参考摘要4）；

解决方案：重启网关：openclaw gateway restart；更换端口：openclaw gateway --port 12345（将12345替换为未占用端口）；开放端口：Linux输入 sudo ufw allow 18789，Windows在防火墙中允许“OpenClaw”访问网络。

4.编译失败（node-llama-cpp编译报错）

原因：缺少C++编译环境和CMake工具（参考摘要1）；

解决方案： Windows：安装Visual Studio Build Tools（勾选“C++ build tools”）；macOS：xcode-select --install（安装Xcode命令行工具）；Linux：sudo apt install build-essential cmake -y。

六、进阶技巧（新手可选，提升使用体验）

1. Windows系统将配置文件转移到非C盘（避免重装丢失）

在D盘创建目录：D:\SOFT_WARE\OpenClaw\data（存放配置）、D:\SOFT_WARE\OpenClaw\workspace（存放AI生成文件）；
新建系统环境变量：OPENCLAW_HOME = D:\SOFT_WARE\OpenClaw\data（参考摘要5）；
重启终端，重新安装OpenClaw，配置文件会自动存到D盘。

2.配置飞书通道（国内用户远程操控）

前往飞书开放平台，创建“企业自建应用”，获取App ID和App Secret；
编辑配置文件（路径：~/.openclaw/openclaw.json），添加飞书配置（参考摘要3）；
重启网关：openclaw gateway restart，即可通过飞书发指令操控OpenClaw。

七、卸载OpenClaw（如需重装）

卸载核心程序：npm uninstall -g openclaw（npm安装版），或 sudo rm -rf /usr/local/bin/openclaw（一键脚本版）；
删除配置文件：rm -rf ~/.openclaw（macOS/Linux），或删除 C:\Users\用户名\.openclaw（Windows）；
清理缓存：npm cache clean --force；
重启电脑，完成卸载。

总结：新手最稳妥的流程是「安装WSL2（Windows）→ 一键脚本安装OpenClaw → 初始化配置 → 启动验证」，全程复制命令，遇到报错先看避坑指南，基本都能解决。如果仍有问题，可参考OpenClaw官方GitHub（）或国内中文仓库获取帮助。