跳转至

Windows

OpenClaw 附带原生 Windows Hub 伴侣应用，并提供 Windows CLI 支持。 使用 Windows Hub 可获得桌面应用，包含设置、托盘状态、聊天、Command Center 诊断以及 Windows 节点功能。若要直接安装 CLI/Gateway，请使用 PowerShell 安装程序。若要使用 Linux 兼容性最高的 Gateway 运行时，请使用 WSL2。

Windows Hub 是面向 Windows 10 20H2+ 和 Windows 11 的原生 WinUI 伴侣应用。它无需管理员权限即可安装，并从其自己的发布页面提供已签名的 x64 和 ARM64 安装程序。

Windows Hub 独立于 OpenClaw CLI 和 Gateway 发布。请从 Windows Hub 发布页面 下载最新稳定版 Hub 安装程序，或直接通过 releases/latest/download 下载：

如果上述链接返回 404，请访问 Windows Hub 发布页面 并打开最新的稳定版 Windows Hub 发布。常规 OpenClaw 稳定版发布 也会镜像一个固定且经过发布验证的 Windows Hub 构建；该镜像可能落后于 更新的独立 Hub 发布。

安装完成后，从开始菜单或系统 托盘启动 OpenClaw Companion。安装程序还会添加 Gateway 设置、聊天、设置、 检查更新和卸载的快捷方式。

Windows Hub 包含内容

  • 系统托盘状态和登录时启动。
  • 首次运行设置，用于本地应用拥有的 WSL Gateway。
  • 本地、远程和 SSH 隧道 Gateway 的连接设置。
  • 原生聊天窗口，并可访问浏览器 Control UI。
  • 用于会话、用量、通道、节点、配对 和修复命令的 Command Center 诊断。
  • Windows 节点模式，支持屏幕、摄像头、通知、设备状态、语音 以及受控的 system.run。
  • 本地 MCP 服务器模式，适用于 Claude Desktop、Claude Code、 Cursor 等 MCP 客户端。

首次启动

首次启动时，如果没有可用的已保存 Gateway，Windows Hub 会打开设置。最快的方式是 本地设置，它会创建一个 应用拥有的 OpenClawGateway WSL 发行版，在其中安装 Gateway，并 配对应用。这不会导出或修改你现有的 Ubuntu 发行版。

如果你已有 Gateway，请选择 高级设置 或打开 Connections 选项卡。你可以连接到：

  • 此电脑上的本地 Gateway
  • 此电脑上的 WSL Gateway
  • 通过 URL 和 token 或设置代码连接的远程 Gateway
  • 通过 SSH 隧道访问的 Gateway

设置完成后，托盘图标会变为绿色。从托盘打开 Command Center， 以确认连接、配对、节点状态和通道健康状况。

Windows 节点模式

Windows Hub 可以注册为 OpenClaw 节点，以便代理能够通过 Gateway 使用已声明的 Windows 原生功能。节点命令必须由节点声明、包含在其已批准的命令面中，并在运行前获得 Gateway 策略允许；完整的允许/拒绝模型请参见 节点。

常用命令：

类别 命令
屏幕 screen.snapshot；screen.record 需要显式选择加入
摄像头 camera.list；camera.snap、camera.clip 需要显式选择加入
系统 system.notify、system.run、system.run.prepare、system.which
设备 location.get、device.info、device.status
语音 talk.ptt.start、talk.ptt.stop、talk.ptt.cancel、talk.ptt.once、talk.speak

节点模式需要 Gateway 配对。如果应用显示配对请求， 请在 Gateway 主机上批准它：

openclaw devices list
openclaw devices approve <deviceRequestId>

设备批准仅允许连接。如果节点模式因手动 配对而暂停，请重启节点模式或应用以重新连接。此重新连接会创建 一个独立的命令面请求。在 Gateway 上：

openclaw nodes pending
openclaw nodes approve <nodeRequestId>
openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>

这两个请求 ID 是不同的。初始未批准的命令面没有有效 命令。在待处理的扩展期间，仍然保持声明且被允许的已批准命令 可以继续运行。SSH 验证和 bootstrap 注册可以自动批准 第一个命令面；仅受信任网络的设备批准则不能。 后续的命令、功能或权限扩展仍需要批准。

Gateway 仅转发节点声明且服务器策略 允许的命令。诸如 screen.record、camera.snap、 camera.clip 等隐私敏感命令需要显式的 gateway.nodes.commands.allow 选择加入。

本地 MCP 模式

Windows Hub 可以将相同的 Windows 原生功能注册表作为本地 MCP 服务器暴露在回环地址上，使本地 MCP 客户端无需运行 OpenClaw Gateway 即可驱动 Windows 功能。

在 Windows Hub 设置的开发者/高级部分启用它。服务器启用后， 应用会显示回环端点和 bearer token。

模式矩阵：

节点模式 MCP 服务器 行为
关闭 关闭 仅操作员使用的桌面应用
开启 关闭 连接 Gateway 的 Windows 节点
关闭 开启 仅本地 MCP 服务器
开启 开启 Gateway 节点加本地 MCP 服务器

原生 Windows CLI 和 Gateway

若要以终端优先方式使用，请从 PowerShell 安装 OpenClaw：

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

验证：

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

受管启动在可用时使用 Windows 计划任务。该任务会在 OpenClaw 状态目录中保留可读的 gateway.cmd 脚本，但通过生成的 gateway.vbs WScript 包装器启动它，因此后台 Gateway 不会打开可见的控制台窗口。如果任务创建被拒绝，OpenClaw 会回退到每用户 Startup 文件夹登录项。

如果你向 gateway.cmd 启动行追加输出重定向，请为整个目标加引号，例如 >> "%USERPROFILE%\.openclaw\logs\gateway-stdout.log" 2>&1。 完整的尾部重定向会被排除在进程所有权检查之外。 未加引号的环境变量展开可能会在 Gateway 的参数中留下文件名片段；OpenClaw 会保留有歧义的启动器命令，并拒绝终止无法验证所有权的监听器。重试前请为目标加引号。

隐藏启动器拥有受监督的 Gateway 进程树。通过 schtasks /end /tn "OpenClaw Gateway"、Stop-ScheduledTask 或 Task Scheduler 的 End 操作结束任务，会终止 Gateway 及其后代进程。更新旧安装后，如果更新未刷新启动器，请运行 openclaw gateway install --force 以重新生成启动器。

Gateway 状态和 Doctor 读取计划任务的数值当前状态，独立于 Windows 显示语言或控制台代码页。之前的任务退出结果不能证明它当前是否正在运行。排队或未知任务在 Doctor 维护中不计为已安全停止。通过其服务所有者停止排队任务；如果检查不可访问，请在重试前恢复 Task Scheduler 检查权限。

严格维护检查遵循任务已注册的 CMD 或 VBS 启动器，或直接注册的可执行文件及其字面参数，并在使用结果前重新检查其捕获的定义。运行时检查使用该已注册命令，而不是默认启动器。直接可执行文件检查不会授予重写该可执行文件或其任务定义的所有权。自动更新服务管理仍会报告这些自定义操作不可用，并保持它们不变，因为它无法恢复受管启动器；环境变量展开和有歧义的参数引号仍不可检查。深度发现会根据可执行文件或启动器证据识别 OpenClaw 和旧版辅助程序；仅凭无关任务的显示名称无法识别服务。规范任务名称和选定任务名称仅在注册操作是现代 Gateway 时抑制额外服务发现；旧版和 Node 操作仍可见。Doctor 会将检查不完整与符合现有清理条件的服务分开报告。

openclaw gateway status --deep 和 openclaw doctor --deep 会报告当前账户 Startup 文件夹中的同级配置。如果其计划任务不存在，则选定的现代 Gateway 回退项会从额外服务列表中省略。即使任务具有相同名称，每个 Startup 文件仍是一个独立的服务定义。检查遵循该确切文件及其捕获的 Gateway 脚本。完整清单会保留无法读取或格式错误的 Gateway 启动器的错误；Doctor 和状态仅列出成功检查的额外服务。Startup 检查提示使用确切文件路径，并且不授予 Task Scheduler 对其的控制。 本地构建也会使用该安装的 dist 检查这些定义中正在运行的 Gateway。在重建其文件之前，请停止匹配的 Gateway。

Doctor 和深度状态会为额外计划任务（包括 Node 主机）提供只读 schtasks /Query 提示。发现功能在清单查询、Startup 目录扫描和启动器检查之间共享一个 60 秒预算。如果预算过期，已完成的发现仍可用，Doctor 会报告某些服务无法检查。在通过服务所有者选择移除之前，请审查已注册的命令和用途。

Doctor 在已拥有服务的刷新期间会识别随 2026.9.3 发布的等待中的 VBS 启动器。自定义启动器行为仍会保留现有定义。

Doctor 使用 Task Scheduler 的默认值比较任务定义。省略的 Enabled 元素表示任务和其登录触发器均为 true，因此 XML 导出差异不会导致漂移警告或刷新验证失败。显式禁用的任务和触发器仍会被报告。

任务探测允许 Windows PowerShell 继承或创建控制台，因为某些 PowerShell 5.1 主机在禁用控制台创建时检查失败。从没有控制台的应用程序调用它可能会短暂显示控制台窗口。如果没有显式调用方截止时间，每个探测最多允许 60 秒用于 PowerShell 冷启动。注册检查使用相同的原生探测，并与任何 Startup 文件夹检查共享其预算。显式检查预算会取代默认允许时间。直接生命周期命令保留其现有限制。访问被拒绝和超时结果仍是检查失败，而不是任务不存在的证明。 如果检查失败，Doctor 和更新拒绝会包含底层探测详情；空响应会标识退出代码，并报告 PowerShell 未产生输出。

在先前 Gateway 就绪验证期间，每个计划任务运行时探测最多允许五秒，或更短的剩余预算。其他服务检查保留其调用方的预算，包括用于验证运行时重建安全的较长允许时间。

在更新预检期间，计划任务检查使用更新的 --timeout 预算。注册或运行时超时会重试一次完整的严格检查。如果检查仍不可用，更新会报告强制执行的预算和探测详情，保留已记录的服务定义，并跳过自动服务重启。使用 openclaw gateway status --deep 检查服务，然后在更新后手动重启它。在准入后失去已验证的所有权会阻止服务变更。

Gateway 启动会通过 Windows API 创建私有 SQLite 暂存目录， 无需为其权限编译 C# 或启动 PowerShell。所有者、 SYSTEM 和 Administrators 保留完全访问权限；创建时会移除其他继承的访问权限。更新重启辅助程序也会避免运行时 C# 编译和 Invoke-Expression。如果防病毒软件仍然中断启动，请在报告中包含其 检测名称以及 openclaw gateway status --json 的输出。

安装 Gateway 服务：

openclaw gateway install
openclaw gateway status --json

如果仅使用 CLI 而不使用受管理的 Gateway 服务：

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

从 2026.9.4 更新

已发布的 2026.9.4 Windows 更新程序在其服务交接中保留了一个旧数据库读取器。 如果目标将共享状态迁移到 schema 17 以上，可能导致该回调在激活后失败。 在正在运行的 9.4 更新期间，候选包的包生命周期会要求 Doctor 的只读预检在更新程序驱动未被确认停止之前拒绝此迁移。 失败的 npm 阶段会在旧更新程序进入修复之前，保留原始包和 Gateway 不变。 当包脚本被跳过时，CLI 预检也会保留此检查；之后的拒绝可能被旧修复路径中的清理错误掩盖。 此遏制措施不会完成自动更新。

等待更新程序退出并查看其结果。要升级，请创建 已验证的备份 ，并在独立 shell 中使用现有的手动包管理器流程 。保留原始服务账户、包前缀、profile 以及状态/配置覆盖。在替换包之前，通过其所有者停止 Gateway，运行新安装的 Doctor，然后启动并验证 Gateway。不要降低 schema 标记，也不要针对已迁移的数据运行旧版本构建。

WSL2 Gateway

WSL2 仍然是 Windows 上 Linux 兼容性最高的 Gateway 运行时。Windows Hub 可以为你设置应用拥有的 WSL Gateway，或者你可以在自己的发行版中手动安装。

手动设置：

wsl --install
# Or pick a distro explicitly:
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：

wsl --shutdown

然后在 WSL 内使用 Linux 快速入门安装 OpenClaw：

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

Gateway 在 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

Note

与旧教程相比有两处更改：

  • 使用 dbus-launch true 而不是 /bin/true：在 WSL >= 2.6.1.0 中，一个 回归问题（microsoft/WSL #13416） 会在最后一个客户端退出后 15-20 秒空闲终止发行版，即使已启用 linger。 dbus-launch true 作为变通方法，可保持一个 init 子进程存活 （社区讨论，microsoft/WSL #9245）。
  • 使用 /ru "$env:USERNAME" 而不是 /ru SYSTEM：按用户划分的 WSL 发行版（默认设置） 对 SYSTEM 账户不可见，因此任务看似运行，但发行版从未启动。以你自己的账户运行可避免 此问题；创建任务时 Windows 会提示输入你的密码。

重启后，从 WSL 中验证：

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

通过 LAN 暴露 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。
  • 远程节点必须指向可访问的 Gateway URL，而不是 127.0.0.1。
  • 对于 LAN 访问使用 listenaddress=0.0.0.0，对于仅限本地访问使用 127.0.0.1。

故障排查

计划任务在 Gateway 就绪前停止

运行 openclaw gateway status --json，然后检查本地 Gateway 日志。 来自 gateway/task-supervisor 的条目会记录子进程退出代码、信号以及 stderr 的最后 8,192 个字符，包括 Gateway 日志开始之前的失败。子进程 stdout 会被丢弃。失败的子进程或 supervisor 会以非零状态退出； 有意执行的干净停止仍以零状态退出。仅任务结果成功并不能证明 Gateway 健康。

任务计划程序的 RestartOnFailure 策略 会重试失败的启动条件或操作启动。不要依赖它来重启 一个成功启动后以错误退出的 Gateway，例如端口被占用。修复日志中记录的原因，然后运行 openclaw gateway start。

托盘图标未出现

在任务管理器中检查 OpenClaw.Tray.WinUI.exe。如果它正在运行，请打开隐藏的托盘图标区域并将其固定。如果没有，请从开始菜单启动 OpenClaw Companion。

本地设置失败

从 Windows Hub 打开设置日志，或检查：

notepad "$env:LOCALAPPDATA\OpenClawTray\Logs\Setup\easy-setup-latest.txt"

常见原因：WSL 已禁用、虚拟化被阻止、应用拥有的 WSL 状态过期，或安装 Gateway 包时发生网络故障。

应用提示需要配对

从 Gateway 批准操作员或节点请求：

openclaw devices list
openclaw devices approve <requestId>

如果设备已有 token，请在批准后从 Connections 选项卡重新连接。

对于节点请求，请在 Windows 节点模式 中完成单独的命令界面批准：重启已暂停的节点模式，然后运行 openclaw nodes pending 并批准其独立的节点请求 ID。仅批准操作员设备无法完成该节点流程。

网页聊天无法连接到远程 Gateway

远程网页聊天需要 HTTPS 或 localhost。对于自签名证书，请在 Windows 中信任该证书，或使用 SSH 隧道连接到 localhost URL。

screen.snapshot、摄像头或音频命令失败

确认 Windows 对摄像头、麦克风、屏幕捕获和通知的权限。打包安装声明了受保护的能力，但 Windows 仍可能在命令首次使用它们时提示。

Git 或 GitHub 连接失败

某些网络会阻止或限制到 GitHub 的 HTTPS。如果 git clone 或 gh auth login 失败，请尝试其他网络、VPN 或 HTTP/HTTPS 代理。

对于当前会话中基于 token 的 gh 身份验证：

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

切勿提交 token，或将其粘贴到 issue 或 pull request 中。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw