OpenClaw Windows 安装详细教程（2026最新版）- 附带环境版本说明

摘要：本文从零开始，逐步详解 OpenClaw 在 Windows 10/11 系统中的完整安装流程。包含环境检查、WSL2 配置、Node.js 安装、OpenClaw 安装、配置向导、验证测试等每一个步骤，附带命令输出示例和错误处理。适合零基础用户参考。

关键词：OpenClaw；Windows 安装；Node.js；WSL2；详细教程；从零开始

---

一、环境准备阶段

1.1 系统版本检查

步骤 1：按 Win + R 组合键，打开"运行"对话框

步骤 2：输入 winver，点击"确定"或按回车

步骤 3：查看弹出的"关于 Windows"窗口

要求：

• Windows 10：版本号 ≥ 2004，内部版本 ≥ 19041

• Windows 11：任意版本均可

示例输出：

Microsoft Windows 版本 22H2 (内部版本 22621.1413)

⚠️ 如果版本过低：需要先更新 Windows 系统

---

1.2 检查虚拟化支持

WSL2 需要 CPU 支持虚拟化并已启用。

步骤 1：按 Ctrl + Shift + Esc 打开任务管理器

步骤 2：点击"性能"选项卡

步骤 3：选择"CPU"

步骤 4：查看右下角"虚拟化"状态

要求：显示"已启用"

⚠️ 如果显示"已禁用"：

---

1.3 检查 PowerShell 版本

步骤 1：按 Win + X，选择"Windows PowerShell（管理员）"或"终端（管理员）"

步骤 2：输入以下命令：

$PSVersionTable.PSVersion

要求：Major 版本号 ≥ 5

示例输出：

Major Minor Build Revision ----- ----- ----- -------- 5 1 19041 1

---

二、安装 WSL2（Windows Subsystem for Linux）

2.1 以管理员身份打开 PowerShell

方法一（推荐）：

1. 右键点击开始菜单图标

2. 选择"Windows PowerShell（管理员）"或"Windows 终端（管理员）"

方法二：

1. 按 Win + S 搜索"PowerShell"

2. 右键点击"Windows PowerShell"

3. 选择"以管理员身份运行"

方法三：

1. 按 Win + R

2. 输入 powershell

3. 按 Ctrl + Shift + Enter（以管理员身份运行）

⚠️ 确认 管理员 权限：窗口标题应显示"管理员：Windows PowerShell"

---

2.2 启用 WSL 功能

步骤 1：在管理员 PowerShell 中输入以下命令：

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

预期输出：

部署映像服务和管理工具 版本：10.0.19041.2673 映像版本：10.0.19044.2364 启用了一个或多个功能。

步骤 2：启用虚拟机平台功能

dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

预期输出：

部署映像服务和管理工具 版本：10.0.19041.2673 映像版本：10.0.19044.2364 启用了一个或多个功能。

---

2.3 重启计算机

必须重启才能使上述更改生效。

方法一（命令行）：

shutdown /r /t 0

方法二（手动）：

1. 点击开始菜单

2. 选择"电源" → "重启"

---

2.4 下载 WSL2 Linux 内核更新包

步骤 1：打开浏览器，访问微软官方下载页面

URL：https://aka.ms/wsl2kernel

步骤 2：点击"下载 WSL2 Linux 内核更新包"

步骤 3：运行下载的 .msi 安装包

步骤 4：点击"下一步" → "我接受" → "下一步" → "安装"

步骤 5：点击"完成"

---

2.5 设置 WSL 默认版本为 WSL2

步骤 1：重启后，再次以管理员身份打开 PowerShell

步骤 2：输入以下命令：

wsl --set-default-version 2

预期输出：

有关与 WSL 2 的关键区别的信息，请访问 https://aka.ms/wsl2 已将 WSL 默认版本设置为 2。

⚠️ 如果出现错误："请启用虚拟机平台可选组件"

---

2.6 安装 Linux 发行版（Ubuntu）

步骤 1：在 PowerShell 中输入：

wsl --install

预期输出：

正在下载：Ubuntu 正在安装：Ubuntu 部署完成。 已将 WSL 默认版本设置为 2。

步骤 2：关闭 PowerShell 窗口

步骤 3：重启电脑（如果系统提示）

---

2.7 完成 Ubuntu 初始化设置

步骤 1：重启后，系统会自动打开 Ubuntu 窗口（如果没有，按 Win + R，输入 wsl，回车）

步骤 2：等待安装完成，会提示输入用户名

Installing, this may take a few minutes... Please create a default UNIX user account. The username does not need to match your Windows username. For more information visit: https://aka.ms/wslusers Enter new UNIX username:

步骤 3：输入用户名（建议使用小写字母，如 openclaw），按回车

步骤 4：输入密码

Enter new UNIX password:

⚠️ 注意：Linux 下输入密码时 不会显示任何字符（包括星号），这是正常的，直接输入后回车即可

步骤 5：确认密码

Retype new UNIX password:

步骤 6：看到以下提示表示成功：

Installation successful!

---

2.8 验证 WSL2 安装

步骤 1：打开 PowerShell（不需要管理员）

步骤 2：输入：

wsl --list --verbose

预期输出：

NAME STATE VERSION * Ubuntu Running 2

检查项：

• VERSION 列必须显示 2

• STATE 显示 Running 或 Stopped 均可

⚠️ 如果显示版本 1：

---

三、安装 Node.js

3.1 在 WSL2 中打开 Ubuntu 终端

方法一：

1. 按 Win + R

2. 输入 wsl

3. 按回车

方法二：

1. 按 Win + S

2. 搜索"Ubuntu"

3. 点击打开

方法三：

1. 在 PowerShell 中输入 wsl

2. 按回车

---

3.2 检查是否已安装 Node.js

步骤 1：在 Ubuntu 终端中输入：

node -v

情况 A：如果显示版本号（如 v18.x.x）

• 继续下一步检查版本是否符合要求

情况 B：如果显示 command not found

• Node.js 未安装，继续步骤 3.3

---

3.3 安装 Node.js（使用 nvm 推荐方式）

步骤 1：更新系统包

sudo apt update && sudo apt upgrade -y

预期输出：

Hit:1 http://security.ubuntu.com/ubuntu jammy-security InRelease Hit:2 http://cn.archive.ubuntu.com/ubuntu jammy InRelease ... 正在升级软件包...

步骤 2：安装 curl（如果未安装）

sudo apt install -y curl

步骤 3：安装 nvm（Node Version Manager）

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

预期输出：

=> Downloading nvm as script to '/home/你的用户名/.nvm' => Appending nvm source string to /home/你的用户名/.bashrc => Appending bash_completion source string to /home/你的用户名/.bashrc

步骤 4：重新加载配置文件

source ~/.bashrc

步骤 5：验证 nvm 安装

nvm --version

预期输出：0.39.7（或类似版本号）

步骤 6：安装 Node.js 22 LTS 版本

nvm install 22

预期输出：

Downloading and installing node v22.x.x... Downloading https://nodejs.org/dist/v22.x.x/node-v22.x.x-linux-x64.tar.xz... Computing checksum with sha256sum Checksums matched! Now using node v22.x.x (npm v10.x.x)

步骤 7：验证 Node.js 和 npm 版本

node -v npm -v

预期输出：

v22.x.x 10.x.x

✅ 要求：Node.js ≥ v22.0.0，npm ≥ v10.0.0

---

3.4 备选方案：直接安装 Node.js

如果 nvm 安装失败，使用此方法：

步骤 1：安装 NodeSource 仓库

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -

步骤 2：安装 Node.js

sudo apt-get install -y nodejs

步骤 3：验证安装

node -v npm -v

---

四、安装 OpenClaw

4.1 确认前置条件

在 Ubuntu 终端中依次执行：

# 检查 Node.js 版本 node -v # 检查 npm 版本 npm -v # 检查网络连接 curl -I https://openclaw.ai

预期输出：

v22.x.x 10.x.x HTTP/2 200

⚠️ 如果网络检查失败：检查网络连接，或配置代理

---

4.2 方法一：使用官方安装脚本（强烈推荐）

步骤 1：在 Ubuntu 终端中输入：

curl -fsSL https://openclaw.ai/install.sh | bash

预期输出：

Downloading OpenClaw installer... Installing OpenClaw... Detecting Node.js installation... ✓ Node.js v22.x.x detected Installing openclaw package... npm warn deprecated ... added 150 packages in 30s ✓ OpenClaw CLI installed successfully! Starting onboarding wizard...

步骤 2：等待安装脚本自动运行配置向导

---

4.3 方法二：使用 npm 手动安装

如果安装脚本失败，使用此方法：

步骤 1：全局安装 OpenClaw

npm install -g openclaw@latest

预期输出：

npm warn deprecated ... added 150 packages in 30s 20 packages are looking for funding run `npm fund` for details

步骤 2：验证安装

openclaw --version

预期输出：显示版本号（如 1.0.0）

步骤 3：运行配置向导

openclaw onboard --install-daemon

预期输出：

Welcome to OpenClaw! Starting onboarding wizard...

---

4.4 方法三：使用 pnpm 安装

步骤 1：安装 pnpm

npm install -g pnpm

步骤 2：安装 OpenClaw

pnpm add -g openclaw@latest

步骤 3：批准构建脚本

pnpm approve-builds -g

步骤 4：运行配置向导

openclaw onboard --install-daemon

---

五、配置向导（Onboarding）

5.1 启动配置向导

如果安装后未自动启动，手动运行：

openclaw onboard

5.2 配置步骤

步骤 1：选择安装类型

? How would you like to install OpenClaw? ○ Quick Setup (Recommended) ○ Advanced Setup

选择 Quick Setup（按回车）

步骤 2：选择消息渠道

? Which messaging platform would you like to configure? ○ Telegram ○ Discord ○ WhatsApp ○ Skip for now

根据需求选择，或选择 Skip for now 稍后配置

步骤 3：配置 AI 模型

? Which AI provider would you like to use? ○ OpenAI ○ Anthropic ○ Local (Ollama) ○ Skip for now

根据需求选择

步骤 4：输入 API 密钥（如果选择了 AI 提供商）

? Enter your API key:

输入密钥后回车（输入内容不会显示）

步骤 5：确认配置

? Confirm configuration? ○ Yes ○ No

选择 Yes

步骤 6：安装守护进程

? Install OpenClaw Gateway as a system service? ○ Yes (Recommended) ○ No

选择 Yes

步骤 7：完成配置

✓ Configuration complete! ✓ Gateway installed and started

---

六、验证安装

6.1 检查 OpenClaw 状态

步骤 1：在终端中输入：

openclaw status

预期输出：

OpenClaw Gateway Status ━━━━━━━━━━━━━━━━━━━━━━ Status: Running Version: 1.x.x Uptime: 0h 0m PID: 12345 Channels: None configured Models: None configured Dashboard: http://localhost:3000

6.2 运行诊断检查

openclaw doctor

预期输出：

OpenClaw Doctor ━━━━━━━━━━━━━━━━ ✓ Gateway is running ✓ Configuration file exists ✓ Node.js version is compatible ✓ Network connectivity OK No issues detected.

6.3 打开管理界面

方法一（命令行）：

openclaw dashboard

方法二（浏览器）：

1. 打开浏览器

2. 访问：http://localhost:3000

预期：看到 OpenClaw 管理界面

---

七、常见问题与解决方案

7.1 问题：openclaw 命令找不到

症状：

openclaw --version # bash: openclaw: command not found

解决方案：

步骤 1：检查 npm 全局路径

npm prefix -g

步骤 2：将路径添加到 PATH

echo 'export PATH=$(npm prefix -g)/bin:$PATH' >> ~/.bashrc

步骤 3：重新加载配置

source ~/.bashrc

步骤 4：验证

openclaw --version

---

7.2 问题：WSL2 网络无法连接

症状：

curl https://google.com # curl: (6) Could not resolve host: google.com

解决方案：

步骤 1：编辑 resolv.conf

sudo nano /etc/resolv.conf

步骤 2：添加 DNS 服务器

nameserver 8.8.8.8 nameserver 8.8.4.4

步骤 3：保存退出（Ctrl+O，回车，Ctrl+X）

步骤 4：防止被覆盖

sudo chattr +i /etc/resolv.conf

---

7.3 问题：sharp 模块安装失败

症状：

npm ERR! sharp: Installation error

解决方案：

SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest

---

7.4 问题：权限错误

症状：

npm ERR! Error: EACCES: permission denied

解决方案：

不要使用 sudo！ 正确做法：

步骤 1：创建 npm 全局目录

mkdir ~/.npm-global

步骤 2：配置 npm

npm config set prefix '~/.npm-global'

步骤 3：添加到 PATH

echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc source ~/.bashrc

步骤 4：重新安装

npm install -g openclaw@latest

---

八、卸载 OpenClaw

8.1 停止并卸载 Gateway

openclaw gateway stop

8.2 卸载 npm 包

npm uninstall -g openclaw

8.3 删除配置和数据

rm -rf ~/.config/openclaw rm -rf ~/.local/share/openclaw

---

九、完整安装检查清单

安装完成后，逐项检查：

• Windows 版本 ≥ 10 (2004) 或 Windows 11

• 虚拟化已启用

• WSL2 已安装且版本为 2

• Ubuntu 发行版已安装

• Node.js ≥ v22.0.0

• npm ≥ v10.0.0

• OpenClaw CLI 已安装

• openclaw --version 显示版本号

• openclaw status 显示 Gateway 运行中

• 可以访问 http://localhost:3000

---

十、参考资料

• OpenClaw 官方文档

• OpenClaw GitHub

• Node.js 官网

• WSL2 官方文档

• nvm GitHub