OpenClaw 在 Windows 上的完整安装指南

目录

• 概述
• 第一步：安装 WSL2 和 Ubuntu
• 1.1 快速安装
• 1.2 重启系统
• 1.3 首次启动配置
• 第二步：启用 systemd
• 2.1 配置 WSL
• 2.2 重启 WSL
• 2.3 验证 systemd
• 第三步：安装 OpenClaw
• 3.1 克隆仓库
• 3.2 安装依赖
• 3.3 构建 UI
• 3.4 构建项目
• 3.5 初始化配置
• 第四步：安装 Gateway 服务
• 方式一：自动安装（推荐）
• 方式二：直接安装
• 方式三：通过配置向导
• 修复或迁移
• 高级配置：局域网访问（可选）
• 为什么需要端口转发？
• 配置端口转发
• 配置防火墙规则（一次性）
• WSL 重启后刷新转发
• 重要提示
• 验证安装
• 检查服务状态
• 查看 Gateway 状态
• 查看日志
• 常见问题
• WSL2 安装失败？
• systemd 无法启动？
• 端口转发不工作？
• Gateway 服务无法启动？

OpenClaw 推荐在 Windows 上通过 WSL2（Windows Subsystem for Linux 2） 运行，建议使用 Ubuntu 发行版。CLI 和 Gateway 运行在 Linux 环境中，这样可以保持运行时的一致性，并使工具链（Node/Bun/pnpm、Linux 二进制文件、技能包）具有更好的兼容性。

虽然原生 Windows 支持可能会更复杂，但 WSL2 为您提供了完整的 Linux 体验——只需一条命令即可安装。

注意： 原生 Windows 配套应用正在计划中。

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

wsl --install

如果想指定特定的发行版（推荐 Ubuntu 24.04）：

# 查看可用发行版
wsl --list --online
# 安装指定版本
wsl --install -d Ubuntu-24.04

如果 Windows 提示需要重启，请重启计算机以完成 WSL2 安装。

重启后，从开始菜单启动 Ubuntu，系统会要求您：

• 创建 Linux 用户名
• 设置密码

完成后，您就进入了 Ubuntu 终端环境。

OpenClaw 的 Gateway 服务需要 systemd 支持。

在 Ubuntu 终端中执行：

sudo tee /etc/wsl.conf >/dev/null <<'EOF'
[boot]
systemd=true
EOF

回到 Windows PowerShell 执行：

wsl --shutdown

重新打开 Ubuntu 终端，验证 systemd 是否正常运行：

systemctl --user status

如果看到服务列表输出，说明配置成功。

在 WSL Ubuntu 终端中执行：

git clone https://github.com/openclaw/openclaw.git
cd openclaw

pnpm install

pnpm ui:build  # 首次运行会自动安装 UI 依赖

pnpm build

openclaw onboard

按照交互式提示完成初始配置。

Gateway 是 OpenClaw 的核心服务组件。有多种安装方式：

openclaw onboard --install-daemon

openclaw gateway install

openclaw configure

在提示时选择 “Gateway service”。

如果遇到问题，可以运行诊断工具：

openclaw doctor

WSL2 拥有独立的虚拟网络。如果您需要从其他设备访问 WSL 内运行的服务（如 SSH、本地 TTS 服务器或 Gateway），必须将 Windows 端口转发到 WSL 的 IP 地址。

注意： WSL 的 IP 地址在每次重启后会变化，因此可能需要刷新转发规则。

以管理员身份打开 PowerShell，执行以下脚本：

# 配置参数
$Distro = "Ubuntu-24.04"
$ListenPort = 2222  # Windows 监听端口
$TargetPort = 22    # WSL 内目标端口
# 获取 WSL IP 地址
$WslIp = (wsl -d $Distro -- hostname -I).Trim().Split(" ")[0]
if (-not $WslIp) { throw "无法获取 WSL IP 地址" }
# 添加端口转发规则
netsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=$ListenPort `
  connectaddress=$WslIp connectport=$TargetPort

New-NetFirewallRule -DisplayName "WSL SSH $ListenPort" -Direction Inbound `
  -Protocol TCP -LocalPort $ListenPort -Action Allow

每次 WSL 重启后，需要刷新端口转发规则：

# 删除旧规则
netsh interface portproxy delete v4tov4 listenport=$ListenPort listenaddress=0.0.0.0 | Out-Null
# 重新获取 IP 并添加规则
$WslIp = (wsl -d $Distro -- hostname -I).Trim().Split(" ")[0]
netsh interface portproxy add v4tov4 listenport=$ListenPort listenaddress=0.0.0.0 `
  connectaddress=$WslIp connectport=$TargetPort | Out-Null

• 局域网访问： 使用 listenaddress=0.0.0.0 允许局域网访问；使用 127.0.0.1 仅限本机访问
• 远程连接示例： ssh user@windows-host -p 2222（使用 Windows 主机的 IP 地址）
• Gateway 配置： 远程节点必须指向可访问的 Gateway URL（不能是 127.0.0.1），使用 openclaw status --all 确认配置
• 自动化： 可以创建 Windows 计划任务，在登录时自动运行刷新脚本

openclaw status --all

systemctl --user status openclaw-gateway

journalctl --user -u openclaw-gateway -f

确保您的 Windows 版本支持 WSL2（Windows 10 版本 2004 及更高版本，或 Windows 11）。

检查 /etc/wsl.conf 配置是否正确，并确保执行了 wsl --shutdown。

1. 确认 Windows 防火墙规则已添加
2. 检查 WSL IP 地址是否正确：wsl -- hostname -I
3. 使用 netsh interface portproxy show all 查看当前转发规则

运行诊断工具：

openclaw doctor

项目地址：https://github.com/openclaw/openclaw

到此这篇关于OpenClaw 在 Windows 上的完整安装教指南的文章就介绍到这了,更多相关Windows OpenClaw安装内容请搜索风君子博客以前的文章或继续浏览下面的相关文章，希望大家以后多多支持风君子博客！