Windows 从零开始安装 OpenClaw 完整教程

前言

OpenClaw 是一款支持 macOS、Linux 和 Windows 的 AI 开发工具，但在 Windows 上官方强烈推荐在 WSL2（Windows Subsystem for Linux 2）下运行。本教程将带你从零开始，在 Windows 系统上完成 OpenClaw 的完整安装。

一、系统要求检查

硬件要求

Windows 10 版本 2004 及以上（推荐 Windows 11）
64位操作系统
至少 8GB RAM（推荐 16GB+）
至少 20GB 可用磁盘空间

软件要求

Node.js 24
（推荐）或 Node 22 LTS（22.16+）
WSL2
（Windows Subsystem for Linux 2）
适用于 Linux 的 Windows 子系统功能已启用

二、第一步：安装 WSL2

1. 启用 WSL 功能

以管理员身份打开 PowerShell，执行以下命令：

# 启用适用于 Linux 的 Windows 子系统dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart# 启用虚拟机平台dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

2. 重启计算机

执行完上述命令后，必须重启计算机使更改生效。

3. 安装 WSL2 内核更新

重启后，下载并安装 WSL2 Linux 内核更新包：

访问：https://aka.ms/wsl2kernel
下载并运行 wsl_update_x64.msi

4. 设置 WSL2 为默认版本

wsl --set-default-version 2

5. 安装 Linux 发行版

打开 Microsoft Store，搜索并安装 Ubuntu（推荐）：

Ubuntu 22.04 LTS 或 Ubuntu 24.04 LTS
或者使用命令安装：wsl --install -d Ubuntu

三、第二步：在 WSL2 中配置环境

1. 启动 Ubuntu

在开始菜单中搜索 "Ubuntu" 并启动，首次启动需要设置用户名和密码。

2. 更新系统包

# 更新包列表sudo apt update# 升级已安装的包sudo apt upgrade -y

3. 安装 Node.js（推荐方法）

OpenClaw 推荐使用 Node 24，安装脚本会自动检测和安装，但我们可以先手动安装：

方法一：使用 NodeSource 安装 Node 24

# 安装 curl（如果未安装）sudo apt install curl -y# 添加 NodeSource 仓库curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -# 安装 Node.jssudo apt install nodejs -y# 验证安装node --version  # 应该显示 v24.x.xnpm --version   # 应该显示对应的 npm 版本

方法二：使用 nvm（Node 版本管理器）

# 安装 nvmcurl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash# 重新加载 bash 配置source ~/.bashrc# 安装 Node 24nvm install 24# 设置为默认版本nvm use 24nvm alias default 24

四、第三步：安装 OpenClaw

1. 使用官方推荐安装脚本（最简单）

这是 OpenClaw 官方推荐的安装方式，会自动完成所有配置：

# 下载并运行安装脚本（包含新手引导）curl -fsSL https://openclaw.ai/install.sh | bash

安装过程会：

自动检测 Node.js 环境
如果缺少 Node.js，会自动安装 Node 24
启动设置向导，引导完成初始配置

2. 跳过新手引导的安装

如果你只需要安装二进制文件，不需要交互式引导：

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

3. 使用 npm 安装（适合已有 Node 环境）

如果你已经配置好 Node 环境：

# 使用 npm 安装npm install -g openclaw@latest# 或者使用 pnpm（如果从源码构建需要）pnpm add -g openclaw@latestpnpm approve-builds -g  # 批准 openclaw、node-llama-cpp、sharp 等openclaw onboard --install-daemon

4. 安装 GitHub 最新版本

如果你想安装最新的开发版本：

npm install -g github:openclaw/openclaw#main

五、第四步：解决常见安装问题

问题1：sharp 构建错误

如果在安装过程中遇到 sharp 相关错误：

# 方法一：设置环境变量强制使用预构建二进制文件SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest# 方法二：安装构建工具链sudo apt install build-essential -ynpm install -g node-gyp

问题2：权限问题

如果遇到权限错误，尝试使用 sudo 或修复权限：

# 修复 npm 全局安装权限sudo chown -R $USER:$USER ~/.npmsudo chown -R $USER:$USER ~/.nvm# 或者使用 nvm 避免权限问题

问题3：网络问题

如果下载速度慢或连接失败：

# 设置 npm 淘宝镜像（在 WSL2 中）npm config set registry https://registry.npmmirror.com# 或者使用 nrm 管理镜像源npm install -g nrmnrm use taobao

六、第五步：验证安装

1. 检查安装是否成功

# 检查 OpenClaw 版本openclaw --version# 检查帮助文档openclaw --help

2. 运行设置向导（如果之前跳过了）

openclaw onboard

3. 测试基本功能

# 启动 OpenClaw 服务openclaw start# 或者运行一个示例命令openclaw status

七、Windows 原生安装（不推荐）

虽然官方强烈推荐使用 WSL2，但如果你坚持要在 Windows 原生环境安装：

1. 安装 Node.js for Windows

访问 https://nodejs.org/ 下载 Node 24 Windows 安装包
运行安装程序，选择默认设置
确保勾选 "Add to PATH"

2. 验证 Node.js 安装

打开 PowerShell：

node --versionnpm --version

3. 安装 OpenClaw（PowerShell）

# 使用安装脚本& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1)))# 或者跳过新手引导& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard

4. 注意 Windows 原生安装的限制

可能遇到更多兼容性问题
某些功能可能无法正常工作
官方支持有限

八、配置优化

1. 修改 npm 全局安装路径（Windows）

为了避免权限问题，可以修改 npm 的全局安装路径：

# 创建新目录mkdir C:\nodejs\node_globalmkdir C:\nodejs\node_cache# 配置 npmnpm config set prefix "C:\nodejs\node_global"npm config set cache "C:\nodejs\node_cache"# 添加到系统环境变量 PATH# 1. 系统属性 -> 高级 -> 环境变量# 2. 编辑 Path，添加：C:\nodejs\node_global# 3. 新建系统变量 NODE_PATH：C:\nodejs\node_global\node_modules

2. WSL2 与 Windows 文件系统交互

# 在 WSL2 中访问 Windows 文件cd /mnt/c/Users/你的用户名/# 在 Windows 中访问 WSL2 文件# 文件资源管理器地址栏输入：\\wsl$\Ubuntu\home\用户名

3. 性能优化

# 编辑 WSL2 配置文件sudo nano /etc/wsl.conf# 添加以下内容[automount]enabled = trueoptions = "metadata,umask=22,fmask=11"mountFsTab = false[interop]enabled = trueappendWindowsPath = true[network]generateHosts = truegenerateResolvConf = true

九、创建桌面快捷方式（可选）

为了方便启动，可以创建桌面快捷方式：

1. 创建启动脚本

在桌面上新建 OpenClaw.bat 文件，内容如下

@echo offwsl ~ -e bash -c "openclaw start"pause

2. 创建停止脚本

新建 StopOpenClaw.bat：

@echo offwsl ~ -e bash -c "openclaw stop"pause

十、下一步：开始使用 OpenClaw

安装完成后，你可以：

访问 Web 界面
：通常为 http://localhost:3000
查看文档
：运行 openclaw docs
探索示例项目
：查看官方 GitHub 仓库
加入社区
：访问 OpenClaw 官方论坛或 Discord

常见问题 FAQ

Q1：为什么推荐使用 WSL2？

A：WSL2 提供了完整的 Linux 环境，避免了 Windows 原生环境的兼容性问题，OpenClaw 在 Linux 环境下更稳定。

Q2：安装需要多长时间？

A：根据网络速度，完整安装通常需要 10-30 分钟。

Q3：我可以同时安装多个版本吗？

A：可以，使用 nvm 可以管理多个 Node.js 版本，但 OpenClaw 本身建议使用最新版本。

Q4：安装失败怎么办？

A：

确保系统满足所有要求
检查网络连接
查看错误日志
尝试使用 --verbose 标志获取详细输出
访问官方文档或社区寻求帮助

Q5：如何卸载？

# 卸载 OpenClawnpm uninstall -g openclaw# 清理缓存npm cache clean --force# 如果需要完全卸载 Node.js# 在 Windows：控制面板 -> 程序和功能# 在 WSL2：sudo apt remove nodejs

总结

通过本教程，你应该已经成功在 Windows 系统上安装了 OpenClaw。记住关键点：

优先使用 WSL2
环境
使用官方安装脚本
简化流程
确保 Node.js 版本正确
（推荐 Node 24）
遇到问题先检查文档
和常见问题

OpenClaw 是一个强大的 AI 开发工具，现在你已经搭建好了开发环境，可以开始探索 AI 应用的开发了！

提示：本文基于 OpenClaw 官方文档编写，软件版本和安装方式可能随时间变化，请以官方最新文档为准。

相关资源：

OpenClaw 官方文档：https://openclaw.ai/docs
WSL2 官方文档：https://docs.microsoft.com/windows/wsl/
Node.js 下载：https://nodejs.org/