古法编程

Appearance

OpenClaw 在 Windows 上有两条安装路径：WSL2（推荐）和原生 Windows。WSL2 提供完整的 CLI、Gateway 和工具链兼容性；原生 Windows 支持核心 CLI 但 Gateway 服务安装有回退机制（计划任务→启动文件夹）。建议先在 WSL2 中按 Linux 流程安装，如需原生 CLI 仅用 openclaw onboard --non-interactive --skip-health 或 openclaw gateway run。高级用户可配置 Gateway 在 Windows 登录前自启动及通过 portproxy 暴露 WSL 服务到局域网。

OpenClaw Windows 安装教程：WSL2 方案与原生方案完整对比 ​

OpenClaw 同时支持 原生 Windows 和 WSL2。WSL2 是更稳定的方案，推荐用于完整体验——CLI、Gateway 和工具链在 Linux 内部运行，兼容性完整。原生 Windows 支持核心 CLI 和 Gateway 使用，但有部分限制（见下文）。原生 Windows 伴侣 App 正在规划中。

WSL2 方案（推荐） ​

原生 Windows 安装方案及限制 ​

原生 Windows CLI 流程正在持续改进，但 WSL2 仍是推荐路径。

目前原生 Windows 上运行良好的功能 ​

  • 通过 install.ps1 进行网站安装
  • 本地 CLI 使用，如 openclaw --version、openclaw doctor、openclaw plugins list --json
  • 嵌入式本地 agent/provider 冒烟测试，例如：
powershell
openclaw agent --local --agent main --thinking low -m "Reply with exactly WINDOWS-HATCH-OK."

当前原生 Windows 限制 ​

  • openclaw onboard --non-interactive 除非传入 --skip-health，否则仍需要可访问的本地 Gateway
  • openclaw onboard --non-interactive --install-daemon 和 openclaw gateway install 会优先尝试 Windows 计划任务
  • 如果计划任务创建被拒绝，OpenClaw 会回退到当前用户启动文件夹中的登录项，并立即启动 Gateway
  • 如果 schtasks 本身卡死或停止响应，OpenClaw 现在会快速中止该路径并回退，而不会无限挂起
  • 计划任务在可用时仍为首选，因为它能提供更好的守护进程状态监控

原生 Windows 配置命令 ​

如果只需要原生 CLI、不需要安装 Gateway 服务，可使用以下命令之一：

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

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

powershell
openclaw gateway install
openclaw gateway status --json

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

Gateway ​

Gateway 服务安装（CLI） ​

在 WSL2 内部：

bash
openclaw onboard --install-daemon

或：

bash
openclaw gateway install

或：

bash
openclaw configure

提示时选择 Gateway service。

修复/迁移：

bash
openclaw doctor

Gateway 在 Windows 登录前自启动配置 ​

对于无头部署，确保完整启动链在无人登录 Windows 时也能运行。

1）保持用户服务在无登录状态下运行 ​

在 WSL 内部：

bash
sudo loginctl enable-linger "$(whoami)"

2）安装 OpenClaw Gateway 用户服务 ​

在 WSL 内部：

bash
openclaw gateway install

3）在 Windows 启动时自动运行 WSL ​

以管理员身份在 PowerShell 中执行：

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

将 Ubuntu 替换为你的发行版名称（通过以下命令查看）：

powershell
wsl --list --verbose

验证启动链 ​

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

bash
systemctl --user is-enabled openclaw-gateway.service
systemctl --user status openclaw-gateway.service --no-pager

将 WSL 服务暴露到局域网（portproxy） ​

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

示例（PowerShell 以管理员身份运行）：

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 防火墙放行端口（一次性）：

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

WSL 重启后刷新 portproxy：

powershell
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：

powershell
wsl --install
# 或显式选择发行版：
wsl --list --online
wsl --install -d Ubuntu-24.04

如果 Windows 要求重启，请重启。

2）启用 systemd（Gateway 安装必须） ​

在 WSL 终端中：

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

然后在 PowerShell 中：

powershell
wsl --shutdown

重新打开 Ubuntu，验证：

bash
systemctl --user status

3）在 WSL 内部安装 OpenClaw ​

在 WSL 内部按 Linux 快速入门流程操作：

bash
git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm ui:build
pnpm build
pnpm openclaw onboard --install-daemon

如果你是从源码开发而非首次安装，使用源开发循环：

bash
pnpm install
pnpm openclaw setup    # 首次运行或重置配置后
pnpm gateway:watch

完整指南：快速入门

Windows 伴侣 App ​

目前尚无 Windows 伴侣 App。欢迎贡献代码推动它成为现实。

Git 与 GitHub 连通性问题（贡献者） ​

部分网络屏蔽或限速 GitHub HTTPS 连接。如果 git clone 出现超时或连接重置，请尝试更换网络、使用 VPN，或设置组织提供的 HTTP/HTTPS 代理。

如果 gh auth login 在浏览器设备流中失败（例如访问 github.com:443 超时），可用个人访问令牌替代认证：

  1. 创建一个至少包含 repo 作用域（经典 PAT）或同等精细权限的令牌。
  2. 在当前 PowerShell 会话中设置环境变量：
powershell
$env:GH_TOKEN="<your-token>"
gh auth status
gh auth setup-git
  1. 如果 gh auth status 提示缺少 read:org，请创建包含该作用域的令牌，并重新赋值变量：
powershell
$env:GH_TOKEN="<your-token-with-repo-and-read:org>"
gh auth status

注意：gh auth refresh -s read:org 仅在你通过 gh auth login 认证并已存储证书时适用（使用 GH_TOKEN 时无效）。

切勿将令牌提交到代码或粘贴到 Issue/PR 中。

常见问题 ​

OpenClaw 在 Windows 上到底选 WSL2 还是原生？ ​

推荐 WSL2，因为 CLI、Gateway 和工具链在 Linux 内运行，兼容性最好。原生 Windows 可用但部分功能受限：onboard 可能需加 --skip-health，Gateway 服务安装依靠计划任务，失败后会回退到启动文件夹。如果你只需要 CLI 测试，原生够用；要完整体验请用 WSL2。

原生 Windows 下 Gateway 服务安装失败怎么办？ ​

Gateway 服务安装会优先尝试创建计划任务。若被拒绝（如权限不足），OpenClaw 会自动回退到当前用户启动文件夹，并在登录后启动 Gateway。测试服务状态可用 openclaw gateway status --json；如需手动运行而不安装服务，用 openclaw gateway run。

如何让 OpenClaw 在 Windows 开机后自动运行（无登录）？ ​

分三步：1）在 WSL 中开启用户服务驻留 sudo loginctl enable-linger "$(whoami)"；2）安装 Gateway 服务 openclaw gateway install；3）用管理员 PowerShell 创建计划任务启动 WSL（示例 schtasks /create /tn "WSL Boot" /sc onstart）。完成后重启并验证 systemctl --user status openclaw-gateway.service。

友情链接： 能跑吗 · 打工算 · 车主算 · 开发工具 · 人工不智能

Copyright © 2026 古法编程 | 蜀ICP备2021007188号 | 关于本站 | 隐私政策