【OpenClaw 全面解析：从零到精通】第 006 篇：OpenClaw 在 Windows/WSL2 上的安装与部署实战

系列说明 ：本系列共计约 20 篇，全面介绍 OpenClaw 开源 AI 智能体框架。本文为系列第 006 篇，聚焦于 OpenClaw 在Windows/WSL2 上的安装与部署实战。建议先阅读第 005 篇：OpenClaw 在 Linux/Ubuntu 上的安装与部署实战。

摘要

本文详细介绍在 Windows 系统上通过 WSL2(Windows Subsystem for Linux 2)安装和部署 OpenClaw 的完整流程,包括 WSL2 环境搭建、Ubuntu 子系统配置、网络互通设置、OpenClaw 安装、初始化配置、防火墙配置以及常见问题排查。文章提供了两种部署方案(原生 Windows 和 WSL2),帮助 Windows 用户快速搭建本地 AI 助手。

一、Windows 上部署 OpenClaw 的两种方案

在 Windows 上部署 OpenClaw 有两种主要方案,各有优劣:

方案	优点	缺点	适用场景
WSL2 部署 (推荐)	接近原生 Linux 性能,生态兼容性好,配置简单	需要 Windows 10/11 专业版,占用额外资源	推荐所有用户使用
原生 Windows 部署	无需虚拟化,资源占用少	部分功能受限,问题较多,维护复杂	仅在特殊需求下使用

推荐选择: WSL2 部署方案,具有更好的稳定性和兼容性。

二、WSL2 环境搭建

2.1 系统要求

操作系统: Windows 10(版本 2004 及以上)或 Windows 11
处理器: 支持 SLAT 的 64 位处理器
内存: 至少 4GB RAM(推荐 8GB+)
虚拟化: BIOS/UEFI 中启用虚拟化技术

2.2 启用 WSL2 功能

以管理员身份打开 PowerShell,执行以下命令:

powershell 复制代码

# 启用 Windows Subsystem for Linux
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 内核更新包,下载并安装。

或使用 PowerShell 下载:

powershell 复制代码

Invoke-WebRequest -Uri https://wslstorestorage.blob.core.windows.net/wslblob/wsl_update_x64.msi -OutFile wsl_update_x64.msi
Start-Process wsl_update_x64.msi

2.4 设置 WSL2 为默认版本

powershell 复制代码

# 将 WSL2 设置为默认版本
wsl --set-default-version 2

# 验证配置
wsl --status

三、安装 Ubuntu Linux 子系统

3.1 安装 Ubuntu(推荐 Ubuntu 22.04 或 24.04)

打开 Microsoft Store,搜索 "Ubuntu",选择以下版本之一:

Ubuntu 22.04 LTS (推荐,长期支持)
Ubuntu 24.04 LTS (最新版本,功能更全面)

点击"获取"或"安装"按钮,等待下载和安装完成。

命令行方式(可选):

powershell 复制代码

# 直接安装指定版本的 Ubuntu
wsl --install -d Ubuntu-22.04

# 或安装 Ubuntu 24.04
wsl --install -d Ubuntu-24.04

3.2 首次启动 Ubuntu

安装完成后,从开始菜单启动 Ubuntu,首次启动会提示:

设置用户名 : 输入用户名(如 openclaw)
设置密码: 输入密码并确认
完成初始化: 等待系统初始化完成

3.3 验证 WSL2 版本

在 Windows PowerShell 中执行:

powershell 复制代码

wsl -l -v

应该显示类似输出:

复制代码

  NAME            STATE           VERSION
* Ubuntu-22.04    Running         2

确认 VERSION 列显示为 2。

四、WSL2 网络配置与 Windows 主机互通

WSL2 默认使用 NAT 网络,需要配置才能实现与 Windows 主机的网络互通。

4.1 配置 .wslconfig 文件

在 Windows 用户目录下创建 .wslconfig 文件:

路径 : C:\Users\<你的用户名>\.wslconfig

文件内容:

ini 复制代码

[wsl2]
memory=4GB                        # 分配给 WSL2 的内存大小
processors=2                      # 分配给 WSL2 的 CPU 核心数
localhostForwarding=true          # 启用 localhost 转发

[experimental]
autoMemoryReclaim=gradual         # 自动回收内存
networkingMode=mirrored           # 镜像网络模式(WSL 2.0.0+)
dnsTunneling=true                 # DNS Tunneling
firewall=true                     # 启用 Windows 防火墙
autoProxy=true                    # 自动同步代理
sparseVhd=true                    # 自动释放虚拟硬盘空间

重启 WSL2 使配置生效:

powershell 复制代码

wsl --shutdown
wsl

4.2 配置 Windows 防火墙规则

WSL2 默认被 Windows 防火墙阻止,需要添加入站规则:

方法 1: 通过 PowerShell 添加规则 (管理员 PowerShell):

powershell 复制代码

# 允许 WSL2 访问
New-NetFirewallRule -DisplayName "WSL" -Direction Inbound -InterfaceAlias "vEthernet (WSL)" -Action Allow

方法 2: 手动添加规则:

打开"控制面板" → "系统和安全" → "Windows Defender 防火墙"
点击"高级设置"
选择"入站规则" → "新建规则"
规则类型: 自定义
程序: 所有程序
协议和端口: 默认即可
作用域:
- 本地 IP 地址: 任何 IP 地址
- 远程 IP 地址: 下列 IP 地址,添加 WSL2 的 IP 网段(如 172.22.176.0/20)
操作: 允许连接
配置文件: 全部勾选
名称: WSL

4.3 验证网络互通

在 WSL2 中测试 Windows 主机连接:

bash 复制代码

# 获取 Windows 主机 IP
cat /etc/resolv.conf | grep nameserver | awk '{print $2}'
# 输出示例: 172.22.176.1

# 测试连接
ping 172.22.176.1

在 Windows 中测试 WSL2 连接:

powershell 复制代码

# 获取 WSL2 IP
wsl hostname -I
# 输出示例: 172.22.176.55

# 测试连接
ping 172.22.176.55

4.4 配置端口转发(可选)

如果需要从局域网访问 WSL2 中的服务,需要配置端口转发:

powershell 复制代码

# 查找 WSL2 IP
$wslIP = wsl hostname -I
$wslIP = $wslIP.Trim()

# 添加端口转发(示例:转发 18789 端口)
netsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=18789 connectaddress=$wslIP connectport=18789

# 查看端口转发规则
netsh interface portproxy show all

五、在 WSL2 中安装 OpenClaw

5.1 更新系统包

进入 WSL2 终端(打开 Ubuntu),执行以下命令:

bash 复制代码

# 更新软件包列表
sudo apt update

# 升级已安装的软件包
sudo apt upgrade -y

5.2 安装基础依赖

bash 复制代码

# 安装基础工具
sudo apt install -y curl wget git build-essential

各工具说明:

curl: 下载工具,用于下载安装脚本
wget: 网络下载工具
git: 版本控制工具,用于克隆 OpenClaw 源码
build-essential: 编译工具链,包含 gcc、g++、make 等

5.3 安装 Node.js(≥22.0.0)

方法 1: 使用 nvm 安装(推荐)

bash 复制代码

# 安装 nvm(Node Version Manager)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# 重新加载 shell 配置
source ~/.bashrc

# 安装 Node.js 22
nvm install 22

# 设置为默认版本
nvm use 22
nvm alias default 22

# 验证安装
node -v
npm -v

方法 2: 使用 NodeSource 安装

bash 复制代码

# 下载并执行 NodeSource 安装脚本
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -

# 安装 Node.js
sudo apt install -y nodejs

# 验证安装
node -v
npm -v

5.4 安装 pnpm 包管理器

OpenClaw 依赖 pnpm 作为包管理器:

bash 复制代码

# 全局安装 pnpm
npm install -g pnpm

# 验证安装
pnpm -v

5.5 安装 OpenClaw

方法 1: 使用一键安装脚本(推荐)

bash 复制代码

# 执行安装脚本
curl -fsSL https://openclaw.ai/install.sh | bash

# 配置 PATH(如果提示)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# 验证安装
openclaw --version

方法 2: 通过 npm 全局安装

bash 复制代码

# 全局安装 OpenClaw
pnpm add -g openclaw@latest

# 验证安装
openclaw --version

六、初始化配置向导

6.1 启动配置向导

bash 复制代码

openclaw

首次运行会进入交互式配置向导(onboarding)。

6.2 配置向导流程

步骤 1: 安全警告确认

复制代码

Security warning: OpenClaw is an AI agent framework that can execute commands on your system.
Are you sure you want to continue? (Y/n)

选择 : 输入 Y 确认继续

步骤 2: 选择配置模式

复制代码

Select onboarding mode:
[1] QuickStart (推荐) - 快速配置,使用默认设置
[2] Advanced - 高级配置,自定义所有选项

步骤 3: 网关端口配置

复制代码

Gateway port (default: 18789):

推荐: 直接回车使用默认端口 18789

步骤 4: 选择模型提供商

复制代码

Select model provider:
[1] OpenAI (需要 API Key)
[2] Claude (需要 API Key)
[3] DeepSeek (需要 API Key)
[4] 阿里云百炼 DashScope (国内推荐)
[5] 暂时跳过(后续配置)

推荐 : 选择 5(暂时跳过),后续配置

步骤 5: 选择 Channels 通道

复制代码

Select channels to install:
[1] WhatsApp
[2] Telegram
[3] 飞书
[4] 暂时跳过

步骤 6: 安装 Hooks

复制代码

Install hooks? (Y/n)

步骤 7: 安装 Skills

复制代码

Select skills to install (comma-separated, or press Enter to skip):

6.3 配置完成验证

bash 复制代码

# 检查服务状态
openclaw status

# 启动 Gateway
openclaw gateway start

6.4 访问 Web 控制台

由于已配置 localhostForwarding=true,可以直接在 Windows 浏览器中访问:

复制代码

http://127.0.0.1:18789

或

复制代码

http://localhost:18789

七、启动与管理 OpenClaw

7.1 启动服务

bash 复制代码

# 启动所有服务
openclaw start

# 仅启动 Gateway
openclaw gateway start

# 查看服务状态
openclaw status

7.2 停止服务

bash 复制代码

# 停止所有服务
openclaw stop

# 仅停止 Gateway
openclaw gateway stop

7.3 设置开机自启动

在 WSL2 中设置 systemd 服务:

bash 复制代码

# 安装后台服务
openclaw gateway install

# 启用开机自启动
sudo systemctl enable openclaw-gateway

# 启动服务
sudo systemctl start openclaw-gateway

# 查看服务状态
sudo systemctl status openclaw-gateway

在 Windows 中设置 WSL 开机启动:

创建启动脚本 start_openclaw.bat:

batch 复制代码

@echo off
wsl -d Ubuntu-22.04 -u openclaw -e bash -c "openclaw start"

将此脚本放入 Windows 启动文件夹:

复制代码

C:\Users\<用户名>\AppData\Roaming\Microsoft\Windows\Start Menu\Programs\Startup

7.4 常用管理命令

bash 复制代码

# 查看日志
openclaw logs --follow

# 查看版本
openclaw --version

# 更新 OpenClaw
openclaw update

# 重启服务
openclaw restart

八、配置文件详解

OpenClaw 配置文件位于 ~/.openclaw/openclaw.json,支持 JSON5 格式。

8.1 基本配置结构

json5 复制代码

{
  // Agents 配置
  "agents": {
    "defaults": {
      "workspace": "~/.openclaw/workspace"
    }
  },

  // Gateway 配置
  "gateway": {
    "port": 18789,
    "host": "0.0.0.0"
  },

  // 模型配置
  "models": {
    "default": "deepseek-chat",
    "providers": {
      "deepseek": {
        "apiKey": "YOUR_API_KEY",
        "baseUrl": "https://api.deepseek.com/v1"
      }
    }
  },

  // Hooks 配置
  "hooks": {
    "memory": {
      "enabled": true
    }
  }
}

8.2 修改配置文件

bash 复制代码

# 使用编辑器打开配置文件
vim ~/.openclaw/openclaw.json

# 修改后重启服务
openclaw restart

九、防火墙与安全配置

9.1 Windows 防火墙配置

前文已添加 WSL 防火墙规则,如需开放特定端口:

powershell 复制代码

# 开放 18789 端口
New-NetFirewallRule -DisplayName "OpenClaw Gateway" -Direction Inbound -LocalPort 18789 -Protocol TCP -Action Allow

9.2 WSL2 内防火墙配置

bash 复制代码

# 安装并启用 firewalld
sudo apt install firewalld
sudo systemctl start firewalld
sudo systemctl enable firewalld

# 开放 18789 端口
sudo firewall-cmd --permanent --add-port=18789/tcp
sudo firewall-cmd --reload

# 查看防火墙状态
sudo firewall-cmd --list-all

9.3 API Key 安全管理

bash 复制代码

# 创建环境变量文件
cat > ~/.openclaw/.env << EOF
OPENAI_API_KEY=your_openai_api_key
DEEPSEEK_API_KEY=your_deepseek_api_key
EOF

# 设置文件权限
chmod 600 ~/.openclaw/.env

# 在配置文件中引用环境变量

9.4 沙盒隔离配置

json5 复制代码

{
  "sandbox": {
    "enabled": true,
    "allowedPaths": [
      "/home/openclaw/Documents",
      "/home/openclaw/Downloads"
    ]
  }
}

十、常见问题排查

10.1 WSL2 无法启动

问题 : 执行 wsl 命令无反应或报错

解决方法:

powershell 复制代码

# 重启 WSL 服务
net stop LxssManager
net start LxssManager

# 或重启 WSL
wsl --shutdown
wsl

10.2 网络连接失败

问题: WSL2 无法访问 Windows 主机或外网

解决方法:

powershell 复制代码

# 重启 WSL 网络服务
wsl --shutdown
wsl

# 检查 DNS 配置
# 在 WSL2 中
cat /etc/resolv.conf

10.3 端口被占用

问题: Gateway 启动失败,提示端口 18789 被占用

解决方法:

bash 复制代码

# 查找占用端口的进程
sudo lsof -i :18789

# 杀死进程
sudo kill -9 <PID>

# 或修改端口
# 编辑 ~/.openclaw/openclaw.json
{
  "gateway": {
    "port": 18790
  }
}

10.4 权限不足

问题: 文件操作失败,提示权限不足

解决方法:

bash 复制代码

# 修改文件权限
sudo chown -R openclaw:openclaw ~/.openclaw
chmod -R 755 ~/.openclaw

10.5 localhost 无法访问

问题: Windows 浏览器无法访问 http://localhost:18789

解决方法:

确认 .wslconfig 中已配置 localhostForwarding=true
重启 WSL: wsl --shutdown 然后 wsl
检查 WSL2 防火墙是否已允许端口访问
尝试直接使用 WSL2 IP 访问

10.6 性能问题

问题: OpenClaw 运行缓慢或卡顿

解决方法:

ini 复制代码

# 优化 .wslconfig 配置
[wsl2]
memory=8GB                # 增加内存
processors=4              # 增加 CPU 核心数
swap=4GB                  # 增加 swap 空间

[experimental]
autoMemoryReclaim=gradual # 启用自动内存回收

十一、原生 Windows 部署方案(备选)

如需在原生 Windows 上部署(不推荐),可参考以下步骤:

11.1 安装 Node.js

访问 Node.js 官网,下载 Windows 安装包(.msi):

选择 LTS 版本(如 v22.x.x)
安装时勾选 "Add to PATH"

11.2 配置 PowerShell 执行策略

powershell 复制代码

# 允许执行脚本
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

11.3 安装 OpenClaw

powershell 复制代码

# 使用一键安装脚本
iwr -useb https://openclaw.ai/install.ps1 | iex

# 或通过 npm 安装
npm install -g openclaw

11.4 初始化配置

powershell 复制代码

openclaw

按照提示完成配置向导。

注意事项:

原生 Windows 部署可能遇到更多兼容性问题
某些 Linux 依赖功能可能不可用
建议优先使用 WSL2 部署方案

十二、生产环境部署建议

12.1 使用高性能 Windows 机器

推荐配置:

CPU: Intel i7/i9 或 AMD Ryzen 7/9
内存: 16GB+ RAM(推荐 32GB)
存储: NVMe SSD 512GB+
网络: 稳定宽带连接

12.2 监控与告警

使用 Windows 任务计划程序设置定时任务:

powershell 复制代码

# 创建监控脚本 monitor_openclaw.ps1
$process = Get-Process | Where-Object {$_.ProcessName -like "*openclaw*"}
if (-not $process) {
    Send-MailMessage -From "monitor@example.com" -To "admin@example.com" -Subject "OpenClaw 服务异常" -Body "OpenClaw 服务未运行"
    # 重启服务
    wsl -d Ubuntu-22.04 -u openclaw -e bash -c "openclaw start"
}

12.3 数据备份

bash 复制代码

# 在 WSL2 中创建备份脚本
cat > ~/backup_openclaw.sh << EOF
#!/bin/bash
rsync -av ~/.openclaw /mnt/c/backup/openclaw_$(date +%Y%m%d)
EOF

chmod +x ~/backup_openclaw.sh

# 使用 crontab 设置定时备份
crontab -e
# 添加: 0 2 * * * ~/backup_openclaw.sh

12.4 性能优化

json5 复制代码

{
  "performance": {
    "maxConcurrency": 3,
    "cacheSize": "2GB",
    "logLevel": "warn"
  }
}

十三、总结

在 Windows 上通过 WSL2 部署 OpenClaw 是最推荐的方式,具有以下优势:

性能优越: 接近原生 Linux 性能,稳定可靠
兼容性好: 完整支持 OpenClaw 所有功能
配置简单: 一键安装,自动配置
生态完整: 充分利用 Linux 工具链

本文详细介绍了从 WSL2 环境搭建、网络配置、OpenClaw 安装到生产部署的完整流程。通过遵循本文的步骤,Windows 用户可以快速搭建自己的本地 AI 助手。后续文章将深入介绍 OpenClaw 的 Gateway 网关、Agent 循环机制、Skills 系统等核心技术原理。

上一篇 ： $第 005 篇$ OpenClaw 在 macOS 上的安装与部署实战

下一篇 ： $第 007 篇$ OpenClaw Gateway 网关详解

【OpenClaw 全面解析：从零到精通】第 006 篇：OpenClaw 在 Windows/WSL2 上的安装与部署实战

摘要

一、Windows 上部署 OpenClaw 的两种方案

二、WSL2 环境搭建

2.1 系统要求

2.2 启用 WSL2 功能

2.3 下载并安装 WSL2 更新包

2.4 设置 WSL2 为默认版本

三、安装 Ubuntu Linux 子系统

3.1 安装 Ubuntu(推荐 Ubuntu 22.04 或 24.04)

3.2 首次启动 Ubuntu

3.3 验证 WSL2 版本

四、WSL2 网络配置与 Windows 主机互通

4.1 配置 .wslconfig 文件

4.2 配置 Windows 防火墙规则

4.3 验证网络互通

4.4 配置端口转发(可选)

五、在 WSL2 中安装 OpenClaw

5.1 更新系统包

5.2 安装基础依赖

5.3 安装 Node.js(≥22.0.0)

5.4 安装 pnpm 包管理器

5.5 安装 OpenClaw

六、初始化配置向导

6.1 启动配置向导

6.2 配置向导流程

步骤 1: 安全警告确认

步骤 2: 选择配置模式

步骤 3: 网关端口配置

步骤 4: 选择模型提供商

步骤 5: 选择 Channels 通道

步骤 6: 安装 Hooks

步骤 7: 安装 Skills

6.3 配置完成验证

6.4 访问 Web 控制台

七、启动与管理 OpenClaw

7.1 启动服务

7.2 停止服务

7.3 设置开机自启动

7.4 常用管理命令

八、配置文件详解

8.1 基本配置结构

8.2 修改配置文件

九、防火墙与安全配置

9.1 Windows 防火墙配置

9.2 WSL2 内防火墙配置

9.3 API Key 安全管理

9.4 沙盒隔离配置

十、常见问题排查

10.1 WSL2 无法启动

10.2 网络连接失败

10.3 端口被占用

10.4 权限不足

10.5 localhost 无法访问

10.6 性能问题

十一、原生 Windows 部署方案(备选)

11.1 安装 Node.js

11.2 配置 PowerShell 执行策略

11.3 安装 OpenClaw

11.4 初始化配置

十二、生产环境部署建议

12.1 使用高性能 Windows 机器

12.2 监控与告警

12.3 数据备份

12.4 性能优化

十三、总结

参考资源