OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

平台概览

Windows

OpenClaw 提供原生 Windows Hub 配套应用以及 Windows CLI 支持。 使用 Windows Hub 可获得具备设置、托盘状态、聊天、命令中心诊断和 Windows 节点能力的桌面应用。使用 PowerShell 安装程序可直接安装 CLI/Gateway 网关。 使用 WSL2 可获得与 Linux 最兼容的 Gateway 网关运行时。

推荐：Windows Hub

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 的访问入口。
  • 命令中心诊断，涵盖会话、用量、渠道、节点、配对 和修复命令。
  • Windows 节点模式，支持由智能体控制的画布、屏幕、摄像头、 通知、设备状态、Talk、以及受控的 system.run。
  • 面向 Claude Desktop、Claude Code 和 Cursor 等 MCP 客户端的 本地 MCP 服务器模式。

首次启动

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

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

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

设置完成后，托盘图标会变为绿色。从托盘打开 命令中心，确认连接、配对、 节点状态和渠道健康状况。

Windows 节点模式

Windows Hub 可以注册为 OpenClaw 节点，使智能体能够通过 Gateway 网关使用 已声明的 Windows 原生能力。节点命令必须由节点声明，并且在运行前获得 Gateway 网关策略允许；完整的允许/拒绝模型请参阅节点。

常用命令：

类别 命令
画布 canvas.present, canvas.hide, canvas.navigate, canvas.eval, canvas.snapshot
屏幕 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 talk.ptt.start, talk.ptt.stop, talk.ptt.cancel, talk.ptt.once, talk.speak

节点模式需要与 Gateway 网关配对。如果应用显示配对请求，请从 Gateway 网关 主机批准：

powershell
openclaw devices listopenclaw devices approve <requestId>openclaw nodes status

Gateway 网关仅转发节点声明且服务器策略允许的命令。涉及隐私的命令（例如 screen.record、camera.snap 和 camera.clip）需要显式 选择启用 gateway.nodes.commands.allow。

本地 MCP 模式

Windows Hub 可以在 local loopback 上将同一套 Windows 原生能力注册表公开为 本地 MCP 服务器，使本地 MCP 客户端无需运行 OpenClaw Gateway 网关即可驱动 Windows 能力。

在 Windows Hub 设置的开发者/高级部分启用此功能。服务器启用后，应用会显示 local loopback 端点和 bearer 令牌。

模式矩阵：

节点模式 MCP 服务器 行为
off off 仅供操作员使用的桌面应用
on off 已连接 Gateway 网关的 Windows 节点
off on 仅本地 MCP 服务器
on on Gateway 网关节点加本地 MCP 服务器

原生 Windows CLI 和 Gateway 网关

若以终端为主，请通过 PowerShell 安装 OpenClaw：

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

验证：

powershell
openclaw --versionopenclaw doctoropenclaw gateway status --json

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

安装 Gateway 网关服务：

powershell
openclaw gateway installopenclaw gateway status --json

若仅使用 CLI，而不使用托管 Gateway 网关服务：

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

WSL2 Gateway 网关

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

手动设置：

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

在 WSL 内启用 systemd：

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

从 PowerShell 重启 WSL：

powershell
wsl --shutdown

然后按照 Linux 快速开始指南在 WSL 内安装 OpenClaw：

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

在 Windows 登录前自动启动 Gateway 网关

对于无头 WSL 设置，请确保即使无人登录 Windows，也会运行完整的启动链。

在 WSL 内：

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

在以管理员身份运行的 PowerShell 中：

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

将 Ubuntu 替换为以下命令显示的发行版名称：

powershell
wsl --list --verbose

重启后，从 WSL 验证：

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

通过局域网公开 WSL 服务

WSL 拥有自己的虚拟网络。如果另一台机器必须访问 WSL 内的服务，请将 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 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。
  • 局域网访问使用 listenaddress=0.0.0.0，仅限本地访问使用 127.0.0.1。

故障排查

托盘图标未出现

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

本地设置失败

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

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

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

应用提示需要配对

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

powershell
openclaw devices listopenclaw devices approve <requestId>

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

Web 聊天无法访问远程 Gateway 网关

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

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

确认 Windows 已授予摄像头、麦克风、屏幕捕获和通知权限。打包安装版本会声明 受保护的能力，但 Windows 仍可能在命令首次使用这些能力时弹出提示。

Git 或 GitHub 连接失败

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

要在当前会话中使用基于令牌的 gh 身份验证：

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

切勿提交令牌，也不要将其粘贴到 issue 或 PR 中。

相关内容

Was this useful?
On this page

On this page