Windows 11 环境下 WSL 安装 OpenClaw 完整指南
目录
前提条件（必读！）
- Windows 11 22H2（build 22621）及以上（运行 winver 检查）。低于此版本 mirrored 模式会自动回退为 NAT。
- BIOS/UEFI 已开启 Virtualization Technology（Intel VT-x / AMD-V）和 Hyper-V。
- 至少 16GB 物理内存（推荐 32GB+），WSL 建议分配 50-75%。
- 以管理员身份运行 PowerShell。
- 关闭公司/学校的安全软件（部分企业 VPN/EDR 可能干扰）。
- 推荐使用 Ubuntu-24.04。
一、WSL 安装与网络配置
微软在 Windows 11 中极大地简化了安装流程，通过单一命令即可完成核心组件的启用。
1.1 WSL 版本说明
WSL（适用于 Linux 的 Windows 子系统）目前有两个主要版本：
- WSL 1：早期版本，采用系统调用转换层
- WSL 2：最新版本，运行完整的 Linux 内核，性能更佳
强烈建议使用 WSL 2，因为它提供了完整的内核支持和更好的性能。
1.2 一键安装 WSL（优化版）
在管理员 PowerShell 中执行：
wsl --install -d Ubuntu-24.04 wsl --set-default-version 2
此操作将自动执行以下逻辑：
- 启用虚拟机平台（Virtual Machine Platform）
- 启用适用于 Linux 的 Windows 子系统
- 下载并安装最新的 Linux 内核
- 默认下载并安装 Ubuntu-24.04
安装完成后，必须重启计算机。
1.3 验证安装状态
重启后执行：
wsl --update --web-download wsl --status wsl --version
预期输出 中 WSL 版本应为 2.0 以上。
1.4 Ubuntu 初始化配置
首次启动 Ubuntu 时，创建 UNIX 用户名和密码（不要和 Windows 用户名相同）。
1.5 系统更新与国内镜像源（TUNA 一键）
替换为清华大学 TUNA 源（速度最快）：
sudo sed -i 's/archive.ubuntu.com/mirrors.tuna.tsinghua.edu.cn/g' /etc/apt/sources.list sudo sed -i 's/security.ubuntu.com/mirrors.tuna.tsinghua.edu.cn/g' /etc/apt/sources.list sudo apt update && sudo apt upgrade -y sudo apt install -y curl wget git vim htop
1.6 启用 systemd（OpenClaw daemon 必须）
sudo tee /etc/wsl.conf > /dev/null <
然后Windows 终端中执行 wsl --shutdown 重启 Ubuntu。
二、WSL 网络架构详解与配置
2.1 WSL 2 网络架构原理
NAT 模式（默认）
┌─────────────────────────────────────────────────────────┐ │ Windows 主机 │ │ │ │ ┌─────────────────────────────────────────────────┐ │ │ │ WSL 2 虚拟机 (NAT) │ │ │ │ │ │ │ │ eth0: 172.23.64.x (独立虚拟子网) │ │ │ │ Gateway: 172.23.64.1 │ │ │ │ DNS: 172.23.64.1 │ │ │ └─────────────────────────────────────────────────┘ │ │ │ │ │ │ ▼ ▼ │ │ ┌─────────────────┐ ┌─────────────────┐ │ │ │ 虚拟交换机 │ │ Windows │ │ │ │ (Hyper-V) │ │ 网络适配器 │ │ │ └─────────────────┘ └─────────────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────────────────────────────────────────┐ │ │ 物理网络 / Internet │ │ └─────────────────────────────────────────────────┘
NAT 模式特点：
- WSL 2 拥有独立的 IP 地址（172.x.x.x 范围）
- 外部网络无法直接访问 WSL 2
- 需要端口转发才能实现局域网访问
- VPN 兼容性较差，经常出现 DNS 解析问题
镜像模式（推荐）
┌─────────────────────────────────────────────────────────┐ │ Windows 主机 │ │ │ │ ┌─────────────────────────────────────────────────┐ │ │ │ WSL 2 虚拟机 (镜像) │ │ │ │ │ │ │ │ eth0: 与宿主机共享相同局域网 IP │ │ │ │ 直接暴露在 Windows 防火墙中 │ │ │ └─────────────────────────────────────────────────┘ │ │ │ │ │ │ (网络接口直接同步) │ │ ▼ │ │ ┌─────────────────────────────────────────────────┐ │ │ 物理网络 / Internet │ │ └─────────────────────────────────────────────────┘
镜像模式特点：
- 与宿主机共享相同的局域网 IP
- 原生 IPv6 支持
- VPN 兼容性显著提升
- 局域网内其他设备可直接发现
- 防火墙规则直接作用于 WSL 应用
2.2 镜像模式技术优势对比
| 维度 | NAT 模式 (默认) | 镜像模式 (推荐) |
|---|---|---|
| IP 地址一致性 | 独立虚拟 IP (172.x.x.x) | 与宿主机共享相同局域网 IP |
| IPv6 支持 | 极其有限 | 全面原生支持 |
| localhost 行为 | 跨平台回环复杂 | 原生双向回环支持 |
| VPN 兼容性 | 经常导致 DNS 丢包 | 显著提升兼容性 |
| 局域网可见性 | 需要手动端口转发 | 局域网内其他设备可直接发现 |
| 防火墙控制 | 独立规则 | 直接使用 Windows 防火墙 |
| 端口转发 | 需要手动配置 | 无需配置 |
2.3 配置 .wslconfig 文件（增强版）
在 C:\Users\你的用户名\.wslconfig（注意前面的点号）：
[wsl2] networkingMode=mirrored dnsTunneling=true autoProxy=true firewall=true memory=12GB # 根据物理内存调整（建议 50-75%） processors=8 # CPU 核心数一半或更多 localhostForwarding=true [experimental] autoMemoryReclaim=gradual hostAddressLoopback=true
在终端中应用：
wsl --shutdown
等待 10 秒。
验证镜像模式：
# WSL 内 ip addr show eth0 # 应显示与 Windows 相同的局域网 IP wslinfo --networking-mode # 应显示 mirrored # Windows PowerShell ipconfig
2.4 防火墙与安全策略调整
方法一：标准防火墙命令（镜像模式下优先推荐）
# 管理员 PowerShell New-NetFirewallRule -DisplayName "OpenClaw-Service" ` -Direction Inbound ` -Action Allow ` -Protocol TCP ` -LocalPort 18789 Get-NetFirewallRule -DisplayName "OpenClaw-Service" | Format-Table
方法二：Hyper-V 防火墙命令（动态 VMCreatorId）
Get-NetFirewallHyperVVMCreator | ForEach-Object {
Set-NetFirewallHyperVVMSetting -Name $_.Name -DefaultInboundAction Allow
}
New-NetFirewallHyperVRule -DisplayName "OpenClaw-Service" -Direction Inbound -Action Allow -Protocol TCP -LocalPorts 18789
验证：
Test-NetConnection -ComputerName localhost -Port 18789
2.5 NAT 模式下的端口转发（备选）
$wslIp = wsl hostname -I netsh interface portproxy delete v4tov4 listenport=18789 listenaddress=0.0.0.0 netsh interface portproxy add v4tov4 listenport=18789 listenaddress=0.0.0.0 connectport=18789 connectaddress=$wslIp
三、WSL 环境下安装 OpenClaw
3.1 基础环境配置（免密设置）
sudo visudo
在文件末尾添加（替换为你的用户名）：
你的用户名 ALL=(ALL) NOPASSWD: ALL
按 Ctrl + O（先按 Ctrl 再按 O）
直接按 Enter 确认保存。
再按 Ctrl + X 退出 nano 编辑器。
3.2 安装基础工具
sudo apt install -y curl wget git
3.3 安装 Opencode 工具
curl -fsSL https://opencode.ai/install | bash
# 验证
which opencode opencode –version
3.4 安装 OpenClaw 官方脚本
curl -fsSL https://molt.bot/install.sh | bash
优化建议：强烈推荐把项目放在 Linux 原生目录：
cd ~
git clone https://github.com/openclaw/openclaw.git
# 如需手动
如果没反应，或者网络中断，试试国内加速的方式：新官方 + npm 国内镜像
apt install npm
npm config set registry https://registry.npmmirror.com
curl -fsSL https://openclaw.ai/install.sh | bash
3.5 运行初始化向导
openclaw onboard --install-daemon
按照向导提示完成配置。
3.6 验证安装
which openclaw openclaw --version openclaw gateway status
四、国内 API 配置
4.1 前置条件检查
which openclaw openclaw --version
4.2 获取 API Key
| 服务商 | 控制台地址 | API Key 获取位置 |
|---|---|---|
| MiniMax | https://www.minimaxi.com | 控制台 → API Keys |
| 智谱 AI | https://bigmodel.cn | 控制台 → API Keys |
4.3 备份配置文件
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.backup
4.4 MiniMax 国内版配置
{
"models": {
"mode": "merge",
"providers": {
"minimax-cn": {
"baseUrl": "https://api.minimaxi.com/anthropic",
"apiKey": "YOUR_MINIMAX_API_KEY_HERE",
"api": "anthropic-messages",
"models": [
{
"id": "MiniMax-M2.1",
"name": "MiniMax M2.1 (China)",
"reasoning": true,
"input": ["text"],
"contextWindow": 204800,
"maxTokens": 131072
}
]
}
}
}
}
4.5 智谱（GLM）配置
{
"models": {
"mode": "merge",
"providers": {
"zhipu-cn": {
"baseUrl": "https://open.bigmodel.cn/api/coding/paas/v4",
"apiKey": "YOUR_ZHIPU_API_KEY_HERE",
"api": "anthropic-messages",
"models": [
{
"id": "glm-4.7",
"name": "GLM-4.7 (China)",
"reasoning": true,
"input": ["text"],
"contextWindow": 200000,
"maxTokens": 8192
}
]
}
}
}
}
4.6 重启与验证
openclaw gateway restart openclaw models list
五、局域网访问配置
5.1 获取本机局域网 IP
ip addr show | grep -E "inet " | awk '{print $2}' | cut -d'/' -f1 | grep -v "^127"
5.2 编辑配置文件
nano ~/.openclaw/openclaw.json
5.3 修改 Gateway 配置
{
"gateway": {
"port": 18789,
"mode": "local",
"bind": "lan",
"auth": {
"mode": "token",
"token": "your_token_here"
},
"controlUi": {
"allowInsecureAuth": true
}
}
}
5.4 重启 Gateway
openclaw gateway restart openclaw gateway status
5.5 访问 Web UI
http://<你的局域网 IP>:18789/
六、安装与使用常见问题及解决方案
| 序号 | 问题现象 | 原因 | 解决方案（按优先级） |
|---|---|---|---|
| 1 | Mirrored networking mode is not supported | Windows 版本 < 22H2 | winver 检查 → 更新 Windows 11 → wsl –update |
| 2 | 无网络 / ping 不通 | mirrored 未生效 | wsl –shutdown 等 10s；临时 dnsTunneling=false；重启电脑 |
| 3 | VPN 连上后 “No route to host” | 企业 VPN / KB 更新 | 更新 Windows；dnsTunneling=false；联系 IT |
| 4 | 服务启动失败 / gateway unreachable | 未启用 systemd | 启用 systemd；添加 trustedProxies 到 openclaw.json |
| 5 | 端口冲突 (address already in use) | Windows 占用 | .wslconfig 加 ignoredPorts=18789 或改端口 |
| 6 | 局域网无法访问 | 仍在 NAT | 确认 .wslconfig + shutdown + 验证 IP |
| 7 | npm/pnpm 极慢 | 项目在 /mnt/c | 移到 ~/openclaw |
| 8 | 重启后配置不生效 | 未等够时间 | wsl –shutdown + 等 10-15 秒 |
| 9 | localhost 访问失败 | localhostForwarding 未开 | 添加到 .wslconfig |
| 10 | 内存/CPU 卡顿 | 默认分配低 | 设置 memory/processors |
| 11 | Windows 更新后断网 | KB 补丁 | wsl –update + 重启 + 检查 HNS 服务 |
快速修复脚本
保存为 wsl-fix.ps1：
wsl --shutdown wsl --update Get-Service vmcompute, HNS | Start-Service
