Windows (WSL2)

OpenClaw 在 Windows 上通过 WSL2（Windows Subsystem for Linux 2，适用于 Linux 的 Windows 子系统）运行。WSL2 提供完整的 Linux 环境，性能接近原生。

系统要求

项目	要求
Windows 版本	Windows 10 (21H2+) 或 Windows 11
CPU	支持虚拟化的 x86_64 处理器
内存	8 GB+（WSL2 + OpenClaw）
磁盘	20 GB 可用空间

安装 WSL2

一键安装（推荐）

以管理员身份打开 PowerShell：

wsl --install

这会自动完成：

• 启用 WSL 功能
• 安装 WSL2 内核
• 安装 Ubuntu 默认发行版

重启

安装完成后需要重启计算机。重启后 Ubuntu 会自动弹出完成初始化。

手动安装

如果一键安装失败，按以下步骤手动操作：

# 1. 启用 WSL 功能
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

# 2. 启用虚拟机平台
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

# 3. 重启电脑
Restart-Computer

# 4. 设置 WSL 默认版本为 2
wsl --set-default-version 2

# 5. 安装 Ubuntu
wsl --install -d Ubuntu-22.04

确认 WSL2 版本

wsl -l -v

输出应显示 VERSION 为 2：

  NAME            STATE           VERSION
* Ubuntu-22.04    Running         2

在 WSL2 中安装 OpenClaw

进入 WSL2 Ubuntu 环境：

wsl

然后按照 Linux 安装步骤操作：

# 更新系统
sudo apt update && sudo apt upgrade -y

# 快速安装
curl -fsSL https://openclaw.ai/install.sh | bash

# 或手动安装 Node.js + OpenClaw
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs
npm install -g openclaw

# 启动
openclaw gateway start

端口转发

WSL2 默认使用 NAT 网络，需要配置端口转发才能从 Windows 宿主机或局域网其他设备访问。

自动转发（WSL2 新版默认）

在较新版本的 Windows 11 中，WSL2 端口会自动转发到 localhost。在 Windows 浏览器中直接访问：

http://localhost:7681

手动端口转发

如果自动转发不生效，使用 PowerShell 设置：

# 获取 WSL2 的 IP 地址
wsl hostname -I

# 添加端口转发（以管理员身份运行）
netsh interface portproxy add v4tov4 listenport=7681 listenaddress=0.0.0.0 connectport=7681 connectaddress=$(wsl hostname -I)

# 添加防火墙规则
New-NetFirewallRule -DisplayName "OpenClaw" -Direction Inbound -LocalPort 7681 -Protocol TCP -Action Allow

WSL2 IP 变化

WSL2 每次启动时 IP 地址可能改变。建议创建一个启动脚本自动更新端口转发。

启动脚本示例

创建 start-openclaw.ps1：

start-openclaw.ps1

# 获取 WSL IP
$wslIp = (wsl hostname -I).Trim()
Write-Host "WSL2 IP: $wslIp"

# 更新端口转发
netsh interface portproxy delete v4tov4 listenport=7681 listenaddress=0.0.0.0
netsh interface portproxy add v4tov4 listenport=7681 listenaddress=0.0.0.0 connectport=7681 connectaddress=$wslIp

# 启动 OpenClaw
wsl -e openclaw gateway start

Native Windows 注意事项

原生 Windows 支持

OpenClaw 目前不提供原生 Windows 二进制文件，建议通过 WSL2 或 Docker Desktop 运行。

Docker Desktop 替代方案

如果不想使用 WSL2 命令行，可以用 Docker Desktop：

1. 安装 Docker Desktop for Windows
2. 确保启用 WSL2 后端
3. 运行 OpenClaw 容器：

docker run -d --name openclaw -p 7681:7681 -v openclaw-data:/app/data openclaw/openclaw:latest

PowerShell 集成

在 PowerShell 中直接调用 WSL 中的 OpenClaw 命令：

# 直接执行 OpenClaw 命令
wsl openclaw status
wsl openclaw nodes
wsl openclaw logs --tail 20

# 创建 PowerShell 别名
function openclaw { wsl openclaw $args }

将别名添加到 PowerShell 配置文件：

# 编辑 PowerShell 配置
notepad $PROFILE

# 添加以下内容
function openclaw { wsl openclaw $args }

WSL2 资源限制

WSL2 默认会占用较多内存，建议配置限制：

%UserProfile%\.wslconfig

[wsl2]
memory=4GB
processors=2
swap=2GB
localhostForwarding=true

# 修改后重启 WSL
wsl --shutdown
wsl

音频和摄像头

硬件限制

WSL2 不直接支持 Windows 的音频设备和摄像头。如果需要这些功能：

• 音频：使用 PulseAudio 桥接（配置复杂），或在手机上运行音频节点
• 摄像头：在手机上运行摄像头节点
• 推荐方案：Windows 上仅运行网关，使用手机作为感知节点

故障排查

问题	解决方案
WSL2 安装失败	确认 BIOS 中开启了虚拟化 (VT-x/AMD-V)
wsl --install 无响应	检查 Windows Update，或手动安装
端口无法访问	检查 Windows 防火墙规则
WSL 内存占用过高	配置 .wslconfig 限制内存
DNS 解析失败	在 WSL 中：echo "nameserver 8.8.8.8" > /etc/resolv.conf
文件系统性能差	将项目放在 WSL 文件系统（/home/）而不是 /mnt/c/

🇨🇳 中国用户须知

Windows 在中国使用最广泛，以下是一些注意事项：

• WSL 安装：wsl --install 需要访问 Microsoft Store，如果网络不通，可以手动下载安装包
• Docker Desktop：Docker Desktop 的 WSL2 后端是另一个不错的选择，GUI 操作更直观
• npm 镜像：在 WSL 中配置淘宝镜像加速安装：

npm config set registry https://registry.npmmirror.com