奇 奇连 AI
学习路线图课程工具计算器企业服务关于加入会员

在 Windows 上跑 OpenClaw：Hub、原生 CLI 与 WSL2 三条路怎么选、怎么避坑

2026-08-17

在 Linux 上装 OpenClaw 基本是一条命令的事，到了 Windows 就开始分叉：有人装了个桌面 companion 应用，有人在 PowerShell 里直接跑 CLI，还有人干脆钻进 WSL2 里当 Linux 用。三条路都能把网关跑起来，但它们解决的问题不一样，混着用就容易出现「装完了但网关连不上」「重启后服务没起来」「另一台机器访问不到」这类问题。

官方 Windows 平台文档把这三条路写得很清楚：Windows Hub 是原生的 WinUI companion 应用，带首次配置、托盘状态、聊天窗口、Command Center 诊断和 Windows 节点能力；PowerShell 安装器直接装 CLI 和 Gateway；WSL2 则是 Windows 上「最接近 Linux 的网关运行时」——这是官方文档自己的定位表述。

下面按文档把每条路的机制、配置项和排查入口过一遍。需要说明的是，本文只讲文档写明的东西，不涉及界面长什么样、点哪个按钮，这些没跑过就没法负责任地写。

三条路分别解决什么问题

方式官方定位适合的场景
Windows Hub原生 WinUI companion 应用想要桌面应用形态：配置引导、托盘状态、聊天、Command Center 诊断、Windows 节点能力
PowerShell 安装器直接装 CLI / Gateway终端优先（terminal-first）的用法
WSL2最贴近 Linux 的网关运行时希望网关行为与 Linux 一致

这三者不是互斥的。Windows Hub 首次启动时的「Set up locally」这条路，本身就是替你在 WSL 里装网关——它会创建一个应用自有的 OpenClawGateway WSL 发行版，在里面装好 Gateway 并完成配对。文档特别写明：这个过程不会导出、也不会改动你已有的 Ubuntu 发行版。也就是说，你原来的 WSL 环境不会被动。

Windows Hub：装的是什么、从哪儿下载

Hub 支持 Windows 10 20H2 及以上和 Windows 11，安装不需要管理员权限，提供签名的 x64 与 ARM64 两个安装包。

有个容易踩的版本坑：Windows Hub 是独立于 OpenClaw CLI 和 Gateway 发版的。它有自己的 releases 页面（仓库 openclaw/openclaw-windows-node）。同时，OpenClaw 的常规 stable 发布里也会镜像一份「固定版本、经过发布验证」的 Hub 构建。文档明确提示：这个镜像版本可能落后于独立发布的更新 Hub 版本。所以你要装最新的，就去 Hub 自己的 releases 页；你要跟主线版本严格对齐，就用镜像那份。两者不是一回事，别混。

按文档，Hub 包含这些能力：

  • 托盘状态与开机自启动
  • 首次运行时为你配置一个应用自有的 WSL 网关
  • 连接设置：本地、远程、SSH 隧道网关都能连
  • 原生聊天窗口，以及访问浏览器版 Control UI
  • Command Center 诊断：会话、用量、渠道、节点、配对，以及修复命令
  • Windows 节点模式
  • 本地 MCP server 模式，供 Claude Desktop、Claude Code、Cursor 这类 MCP 客户端使用

如果你已经有网关了，就走 Advanced setup 或 Connections 标签页，可以连本机的本地网关、本机的 WSL 网关、按 URL 加令牌（或 setup code）连远程网关，或者通过 SSH 隧道连过去。

节点模式：能力要「声明 + 放行」两道关

Windows Hub 可以把自己注册成一个 OpenClaw 节点，让 Agent 通过网关使用 Windows 原生能力。这里有一条必须先立住的规则：节点命令必须由节点声明，并且被网关策略允许，才能执行。网关只转发「节点声明过 + 服务端策略允许」的命令，两个条件缺一不可。

文档列出的常见命令族：

命令族命令
Canvascanvas.present、canvas.hide、canvas.navigate、canvas.eval、canvas.snapshot
Screenscreen.snapshot；screen.record 需要显式 opt-in
Cameracamera.list；camera.snap、camera.clip 需要显式 opt-in
Systemsystem.notify、system.run、system.run.prepare、system.which
Devicelocation.get、device.info、device.status
Talktalk.ptt.start、talk.ptt.stop、talk.ptt.cancel、talk.ptt.once、talk.speak

涉及隐私的那几个——screen.record、camera.snap、camera.clip——需要在 gateway.nodes.commands.allow 里显式开启。默认不给，这个设计是对的：录屏和摄像头抓拍属于一旦误触发就很难解释的操作。

节点模式还要求完成网关配对。应用提示需要配对时，去网关那侧批准：

openclaw devices list
openclaw devices approve <requestId>
openclaw nodes status

本地 MCP 模式：不开网关也能用 Windows 能力

Hub 还能把同一套 Windows 原生能力注册表，以本地 MCP server 的形式暴露在 loopback 上。这样本地的 MCP 客户端不需要有一个在跑的 OpenClaw 网关，也能驱动 Windows 能力。开关在 Hub 设置的 developer/advanced 区域，启用后应用会显示 loopback 端点和 bearer token。

节点模式和 MCP server 是两个独立开关，四种组合的行为文档给了矩阵：

节点模式MCP server行为
offoff纯操作者用的桌面应用
onoff连接网关的 Windows 节点
offon只做本地 MCP server
onon既是网关节点，又是本地 MCP server

原生 CLI 与网关：后台启动为什么要套一层 vbs

终端优先的话，从 PowerShell 装：

iwr -useb https://openclaw.ai/install.ps1 | iex

装完先验证：

openclaw --version
openclaw doctor
openclaw gateway status --json

托管启动这块有个实现细节值得知道：有计划任务（Windows Scheduled Tasks）可用时就走计划任务。任务会在 OpenClaw 状态目录里保留可读的 gateway.cmd 脚本，但实际是通过一个生成的 gateway.vbs WScript 包装器来启动的——目的是让后台网关不弹出可见的控制台窗口。如果创建计划任务被拒绝（权限受限的机器上很常见），OpenClaw 会退回到「每用户的启动文件夹登录项」。

这两种回退路径的差别会直接影响你的排查方向：走计划任务是系统级调度，走启动文件夹则要等用户登录才触发。

安装网关服务：

openclaw gateway install
openclaw gateway status --json

只想用 CLI、不要托管的网关服务：

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

WSL2 网关：手动装法

Hub 可以替你建一个应用自有的 WSL 网关，你也可以在自己的发行版里手动装：

wsl --install
# 或者显式挑一个发行版：
wsl --list --online
wsl --install -d Ubuntu-24.04

在 WSL 里开 systemd：

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

回 PowerShell 重启 WSL，然后按 Linux 快速上手在 WSL 里装 OpenClaw：

wsl --shutdown

curl -fsSL https://openclaw.ai/install.sh | bash
openclaw gateway status

无人登录也要自启：两处和老教程不一样的改动

这一节是 Windows 上最容易踩空的地方。无头 WSL 部署要保证「哪怕没人登录 Windows，整条启动链也能跑完」。

WSL 内部：

sudo apt-get install -y dbus-x11
sudo loginctl enable-linger "$(whoami)"
openclaw gateway install

在管理员 PowerShell 里建计划任务：

schtasks /create /tn "WSL Boot" /tr "wsl.exe -d Ubuntu --exec dbus-launch true" /sc onstart /ru "$env:USERNAME"

其中 Ubuntu 换成你自己的发行版名，用 wsl --list --verbose 查。

文档明确点出两处与旧配方不同的改动，都是踩过坑才写进去的：

  1. 用 dbus-launch true 而不是 /bin/true。WSL 2.6.1.0 及以后有个回归问题（microsoft/WSL issue #13416）：最后一个客户端退出后 15 到 20 秒，发行版就会被 idle 终止，哪怕已经 enable-linger 也照样终止。dbus-launch true 的作用是留一个 init 的子进程活着，属于绕过办法（社区讨论见 microsoft/WSL #9245）。
  2. 用 /ru "$env:USERNAME" 而不是 /ru SYSTEM。默认安装的 WSL 发行版是每用户的，SYSTEM 账户看不见它，结果就是任务看起来跑了、发行版却从没启动。用自己的账户就能避开；代价是创建任务时 Windows 会要求输入你的密码。

这两条踩中任何一条，现象都一样地难查：日志里没有明显报错，就是服务没起来。重启后回 WSL 里验证：

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

把 WSL 里的服务开放给局域网

WSL 有自己的虚拟网络。别的机器要访问 WSL 里的服务，得把 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

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

配套的三条注意事项：从别的机器 SSH 时目标是 Windows 主机 IP（例如 ssh user@windows-host -p 2222）；远程节点必须指向一个可达的网关 URL，不能填 127.0.0.1；要局域网访问就用 listenaddress=0.0.0.0，只要本机访问就用 127.0.0.1。远程访问还有别的做法，可以对照远程网关的三条路一起看。

出问题先看这几处

文档给的排障条目，按「你看到的现象」对号入座：

现象官方给的检查方向
托盘图标不出现在任务管理器里找 OpenClaw.Tray.WinUI.exe；在跑就去隐藏图标区把它固定出来，没跑就从开始菜单启动 OpenClaw Companion
本地 setup 失败看 setup 日志 $env:LOCALAPPDATA\OpenClawTray\Logs\Setup\easy-setup-latest.txt；常见原因是 WSL 被禁用、虚拟化被拦、应用自有 WSL 状态残留、装网关包时网络失败
提示需要配对在网关侧 openclaw devices list / openclaw devices approve <requestId>；如果设备原本就有令牌，批准后从 Connections 标签页重连
网页聊天连不上远程网关远程网页聊天需要 HTTPS 或 localhost；自签证书就在 Windows 里信任该证书，或用 SSH 隧道转成 localhost 地址
screen.snapshot、摄像头、音频命令失败确认 Windows 的摄像头、麦克风、屏幕捕获、通知权限；打包安装虽然声明了受保护能力，Windows 仍可能在首次使用时弹窗
git 或 GitHub 连接失败有些网络会拦截或限速到 GitHub 的 HTTPS，换网络、走 VPN 或配 HTTP/HTTPS 代理

最后一条对国内环境尤其常见。文档给了当前会话内用令牌做 gh 认证的写法：

$env:GH_TOKEN="<your-token>"
gh auth status
gh auth setup-git

并且提醒：绝不要把令牌提交进仓库，也不要粘贴到 issue 或 PR 里。

网关本身起不来是另一类问题，锁文件、端口、后台进程各有各的查法，可以看网关起不来的排查思路。装之前还没定用哪种方式的，四种安装方式的适用场景先看一遍更省事。

什么时候不适合按这套走，以及文档没回答的

几个边界值得先说清楚：

你需要严格的版本一致性时，Hub 的独立发版是个变量。 Hub 和 CLI/Gateway 分开发版，意味着两边可能不在同一个版本节奏上。要可控就用 stable 发布里镜像的那份固定 Hub 构建，接受它可能不是最新的。

需要 Agent 用 Windows 原生能力（截屏、摄像头、system.run）时，权限链条比较长。 节点声明、网关策略 gateway.nodes.commands.allow、Windows 系统本身的权限提示，三层任何一层没通都会失败。文档在排障里也只给到「确认 Windows 权限」这一步，具体某个 Windows 版本上的权限入口在哪儿，文档没写。

跑无头 WSL 网关，你得接受 dbus-launch true 是个 workaround。 它绕的是 WSL 上游的 idle 终止回归问题，不是 OpenClaw 自己的机制。上游修了之后这条配方要不要改，文档没有承诺。

几个官方文档确实没给出的信息：三种方式各自的资源占用、Hub 各功能对性能的影响、WSL 网关和原生网关在行为上除「Linux 兼容性」外还有哪些具体差异——这些文档里没有数字，也没有对比结论，任何声称「哪个更快多少」的说法都不是来自官方文档。真要选，按你的使用形态选：要桌面应用和 Windows 原生能力就 Hub，纯终端就 PowerShell 安装器，想要行为跟 Linux 一致就 WSL2。想再往下理解网关、Agent、节点、渠道这几层是怎么串起来的，可以看整体架构那一篇。

延伸阅读

本文依据 OpenClaw 官方仓库（github.com/openclaw/openclaw）docs/ 下的官方文档整理，核对日 2026-08-17。 我们没有安装或运行过 OpenClaw，因此不涉及界面外观、操作手感与实测耗时的任何描述； 文中的默认值、命令与配置项均为文档口径，不构成对实际运行结果的保证。 该项目迭代很快，请以仓库最新内容为准。接入即时通讯平台前，请自行确认所在平台的规则与合规要求。

想系统学会用 AI？报名体系课或加入会员，照着学、照着用。

浏览课程 加入会员