OpenClaw Windows 安装全攻略

概述

在 Windows 上运行 OpenClaw 时，借助 WSL2 是实现最小折腾路径的上策。官方项目强烈推荐选用 Ubuntu 发行版作为宿主环境，将 CLI 与 Gateway 统一部署在 Linux 内，既确保运行环境的一致性，也让 Node/Bun/pnpm 等工具链、Linux 二进制文件以及技能包的兼容性达到最佳状态。

有人会问：原生 Windows 支持难道不行吗？坦白说，并非不可行，但配置复杂度显著上升，且当前官方正排期开发原生的 Windows 配套应用。现阶段，采用 WSL2 即可获得完整的 Linux 体验，安装仅需一条命令。

第一步：安装 WSL2 和 Ubuntu

1.1 快速安装

以管理员身份启动 PowerShell，直接执行：

wsl --install

若对发行版有明确需求——例如 Ubuntu 24.04——可参照以下操作：

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

1.2 重启系统

若 Windows 提示需要重启，请务必重启一次，以使 WSL2 完成安装。

1.3 首次启动配置

重启后，从开始菜单启动 Ubuntu，系统将引导完成两项基础设置：

• 创建一个 Linux 用户名
• 设置对应的密码

按提示操作完毕，即可进入 Ubuntu 终端。

第二步：启用 systemd

此步至关重要——OpenClaw 的 Gateway 服务依赖 systemd 支持。

2.1 配置 WSL

在 Ubuntu 终端中执行：

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

2.2 重启 WSL

返回 Windows PowerShell 运行：

wsl --shutdown

2.3 验证 systemd

重新打开 Ubuntu 终端，检查 systemd 是否正常工作：

systemctl --user status

若看到服务列表输出，说明配置已生效。

第三步：安装 OpenClaw

3.1 克隆仓库

在 WSL Ubuntu 终端中执行：

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

3.2 安装依赖

pnpm install

3.3 构建 UI

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

3.4 构建项目

pnpm build

3.5 初始化配置

openclaw onboard

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

第四步：安装 Gateway 服务

Gateway 是 OpenClaw 的核心服务组件，提供多种安装方式，可根据实际情况选择：

方式一：自动安装（推荐）

openclaw onboard --install-daemon

方式二：直接安装

openclaw gateway install

方式三：通过配置向导

openclaw configure

在提示时选择 “Gateway service”。

修复或迁移

遇到问题时，可先用诊断工具排查：

openclaw doctor

高级配置：局域网访问（可选）

为什么需要端口转发？

WSL2 拥有独立的虚拟网络，与 Windows 主机的网络相互隔离。若希望从局域网内其他设备访问 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 重启后刷新转发

每次 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

查看 Gateway 状态

systemctl --user status openclaw-gateway

查看日志

journalctl --user -u openclaw-gateway -f

常见问题

WSL2 安装失败？

请先确认 Windows 版本是否支持 WSL2——Windows 10 版本 2004 及以上，或 Windows 11 均可。

systemd 无法启动？

检查 /etc/wsl.conf 配置是否书写正确，然后务必执行 wsl --shutdown 使配置生效。

端口转发不工作？

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

Gateway 服务无法启动？

直接运行诊断工具：

openclaw doctor

来源：互联网