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

柯儿的天空2026-03-21 14:28

系列说明 ：本系列共计约 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,首次启动会提示:

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

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: 手动添加规则:

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

推荐 : 选择 1(QuickStart)

步骤 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] 暂时跳过

推荐 : 选择 4(暂时跳过)

步骤 6: 安装 Hooks
复制代码 
Install hooks? (Y/n)

推荐 : 输入 Y 安装 Hooks

步骤 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

解决方法:

  1. 确认 .wslconfig 中已配置 localhostForwarding=true
  2. 重启 WSL: wsl --shutdown 然后 wsl
  3. 检查 WSL2 防火墙是否已允许端口访问
  4. 尝试直接使用 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 是最推荐的方式,具有以下优势:

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

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

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

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

参考资源

相关推荐
freewlt3 小时前
科技热点速递：AI技术集中爆发
人工智能·深度学习·计算机视觉
驕傲的兎孒3 小时前
基于 SpringBoot + Vue3 + AI 打造企业级售后服务支持平台 | 实战方案分享
人工智能·spring boot·后端
guoji77883 小时前
2026年AI编程辅助实战：国内镜像站如何使用Claude提升开发效率？
人工智能·ai编程
程序猿炎义3 小时前
Agent Skills入门 - Datawhale共学
人工智能
大傻^3 小时前
Spring AI Alibaba 可观测性实践：AI应用监控与链路追踪
java·人工智能·后端·spring·springaialibaba
星辰yzy3 小时前
AI 聚合 Token 平台怎么选？我为什么开始长期使用 jige.io
人工智能·语言模型
视***间3 小时前
京聚全球智，算力观新程——视程空间赴2026北京国际人工智能应用与机器人创新博览会
大数据·人工智能·机器人·边缘计算·ai算力开发板
云烟成雨TD3 小时前
Spring AI Alibaba 1.x 系列【1】阿里巴巴 AI 生态
java·人工智能·spring
柯儿的天空3 小时前
【OpenClaw 全面解析：从零到精通】第 005 篇：OpenClaw 在 macOS 上的安装与部署实战
人工智能·macos·自然语言处理·ai作画
热门推荐
01GitHub 镜像站点02Qwen3.5 开源全解析：从 0.8B 到 397B，代际升级 + 全场景选型指南03小黑课堂计算机二级WPSoffice题库软件下载安装教程（2026年3月最新版）04Labelme从安装到标注：零基础完整指南05OpenClaw 使用和管理 MCP 完全指南06班级宠物园部署指南07AI 编程三剑客：Spec-Kit、OpenSpec、Superpowers 深度对比与实战指南08UV安装并设置国内源09OpenClaw Control UI安全上下文访问配置10“wsl --install -d Ubuntu-22.04”下载慢，中国地区离线安装 Ubuntu 22.04 WSL方法（亲测2025年5月6日）