Windows (WSL2)

Windows 上推荐 通过 WSL2 运行 OpenClaw（建议用 Ubuntu）。CLI + Gateway 跑在 Linux 里，运行时一致性更好，工具兼容性也高得多（Node/Bun/pnpm、Linux 二进制、技能）。原生 Windows 可能会遇到更多问题。WSL2 给你完整的 Linux 体验——一条命令就能装好：wsl --install。

原生 Windows 伴侣应用在计划中。

安装（WSL2）

• 快速上手（在 WSL 内操作）
• 安装与更新
• 微软官方 WSL2 指南：https://learn.microsoft.com/windows/wsl/install

原生 Windows 状态

原生 Windows 的 CLI 支持在持续改善，但 WSL2 仍是推荐路径。

原生 Windows 上目前已可用的功能：

• 通过 install.ps1 的网站安装器
• 本地 CLI 操作，如 openclaw --version、openclaw doctor、openclaw plugins list --json
• 内嵌本地 agent/provider 冒烟测试：

openclaw agent --local --agent main --thinking low -m "Reply with exactly WINDOWS-HATCH-OK."

当前注意事项：

• openclaw onboard --non-interactive 仍然需要本地 Gateway 可达，除非传 --skip-health
• openclaw onboard --non-interactive --install-daemon 和 openclaw gateway install 优先尝试 Windows 计划任务
• 如果计划任务创建被拒绝，OpenClaw 会回退到用户启动文件夹的登录启动项，并立即启动 Gateway
• 如果 schtasks 本身卡住或无响应，OpenClaw 现在会快速中止该路径并回退，而不是无限等待
• 计划任务在可用时仍是首选，因为它提供更好的服务状态管理

如果只想要原生 CLI 而不安装 Gateway 服务，用以下方式：

openclaw onboard --non-interactive --skip-health
openclaw gateway run

如果需要原生 Windows 上的托管启动：

openclaw gateway install
openclaw gateway status --json

如果计划任务创建被阻止，回退服务模式仍会通过当前用户的启动文件夹在登录后自动启动。

Gateway

• Gateway 操作手册
• 配置参考

Gateway 服务安装（CLI）

在 WSL2 内：

openclaw onboard --install-daemon

或者：

openclaw gateway install

或者：

openclaw configure

出现提示时选择 Gateway service。

修复/迁移：

openclaw doctor

Gateway 在 Windows 登录前自启

headless 场景需要确保完整启动链在无人登录 Windows 时也能运行。

1) 保持用户服务在无登录时运行

在 WSL 内：

sudo loginctl enable-linger "$(whoami)"

2) 安装 OpenClaw Gateway 用户服务

在 WSL 内：

openclaw gateway install

3) Windows 开机时自动启动 WSL

在管理员 PowerShell 中：

schtasks /create /tn "WSL Boot" /tr "wsl.exe -d Ubuntu --exec /bin/true" /sc onstart /ru SYSTEM

把 Ubuntu 替换为你的发行版名称：

wsl --list --verbose

验证启动链

重启后（Windows 登录前），在 WSL 中检查：

systemctl --user is-enabled openclaw-gateway
systemctl --user status openclaw-gateway --no-pager

进阶：通过局域网暴露 WSL 服务（portproxy）

WSL 有自己的虚拟网络。如果其他机器需要访问 WSL 内部运行的服务（SSH、本地 TTS 服务器或 Gateway），必须把 Windows 端口转发到当前 WSL IP。WSL IP 在重启后会变，所以可能需要刷新转发规则。

示例（管理员 PowerShell）：

$Distro = "Ubuntu-24.04"
$ListenPort = 2222
$TargetPort = 22

$WslIp = (wsl -d $Distro -- hostname -I).Trim().Split(" ")[0]
if (-not $WslIp) { throw "WSL IP not found." }

netsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=$ListenPort `
  connectaddress=$WslIp connectport=$TargetPort

允许该端口通过 Windows 防火墙（一次性）：

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

WSL 重启后刷新 portproxy：

netsh interface portproxy delete v4tov4 listenport=$ListenPort listenaddress=0.0.0.0 | Out-Null
netsh interface portproxy add v4tov4 listenport=$ListenPort listenaddress=0.0.0.0 `
  connectaddress=$WslIp connectport=$TargetPort | Out-Null

说明：

• 从其他机器 SSH 连接时目标是 Windows 主机 IP（例如 ssh user@windows-host -p 2222）。
• 远程节点必须指向可达的 Gateway URL（不是 127.0.0.1）；用 openclaw status --all 确认。
• 用 listenaddress=0.0.0.0 支持局域网访问；127.0.0.1 只限本地。
• 如果想自动化，注册一个计划任务在登录时运行刷新步骤。

WSL2 分步安装

1) 安装 WSL2 + Ubuntu

打开管理员 PowerShell：

wsl --install
# 或者明确指定发行版：
wsl --list --online
wsl --install -d Ubuntu-24.04

Windows 要求重启就重启。

2) 启用 systemd（Gateway 安装必需）

在 WSL 终端中：

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

然后在 PowerShell 中：

wsl --shutdown

重新打开 Ubuntu，验证：

systemctl --user status

3) 在 WSL 内安装 OpenClaw

按照 Linux 快速上手流程在 WSL 内操作：

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm ui:build # 首次运行时自动安装 UI 依赖
pnpm build
openclaw onboard

完整指南：快速上手

Windows 伴侣应用

目前还没有 Windows 伴侣应用。欢迎贡献代码。