OpenClaw 在 Windows 上的完整安装指南

概述

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

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

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

第一步：安装 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 拥有独立的虚拟网络。如果您需要从其他设备访问 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

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

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

最新评论