Windows
OpenClaw 提供原生 Windows Hub 配套应用以及 Windows CLI 支持。 将 Windows Hub 用作桌面应用,提供设置、托盘状态、聊天、Command Center 诊断和 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。
- Command Center 诊断,涵盖会话、使用情况、通道、节点、配对和修复命令。
- Windows 节点模式,支持屏幕、摄像头、通知、设备状态、语音以及受控的
system.run。 - 本地 MCP 服务器模式,适用于 Claude Desktop、Claude Code 和 Cursor 等 MCP 客户端。
首次启动¶
首次启动时,如果没有可用的已保存 Gateway,Windows Hub 会打开设置。最快的方式是 本地设置,它会创建一个应用拥有的 OpenClawGateway WSL 发行版,在其中安装 Gateway,并配对应用。这不会导出或修改你现有的 Ubuntu 发行版。
如果你已经有 Gateway,请选择 高级设置 或打开连接选项卡。你可以连接到:
- 本 PC 上的本地 Gateway
- 本 PC 上的 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 主机上批准它:
设备批准仅允许连接。如果节点模式因手动配对而暂停,请重启节点模式或应用以重新连接。此重新连接会创建一个独立的命令面请求。在 Gateway 上:
openclaw nodes pending
openclaw nodes approve <nodeRequestId>
openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>
这两个请求 ID 是不同的。初始未批准的命令面没有有效命令。在待处理扩展期间,仍然保持声明且被允许的已批准命令可以继续运行。SSH 验证和引导注册可以自动批准第一个命令面;仅受信任网络的设备批准则不能。后续的命令、功能或权限扩展仍需要批准。
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:
验证:
新工作区 也适用于原生 Windows Gateway。安装 Git for Windows,并使其在 PATH 中可用。每个空工作区都从一个独立的 Git 仓库开始,该仓库初始化时不使用你的全局 Git 配置。创建工作区还可避免 Git for Windows 在深度嵌套源仓库中出现的 '$GIT_DIR' too big 错误。工作器结果暂存、读取和清理会为每条命令启用 Git 的 Windows 长路径支持。访问同一深度嵌套仓库的其他 Git 客户端可能需要在自己的配置中设置 core.longpaths=true,例如使用 git -C "<repository>" config core.longpaths true。
受管 Gateway 启动使用一个计划任务,该任务使用当前用户的 S4U 主体、启动和登录触发器,并针对可读的 gateway.cmd 脚本使用直接的 cmd.exe 操作。它可以在登录前运行,而无需存储密码。S4U 不提供 Windows 网络凭据或对加密文件的访问;需要这些能力的安装可以保留由操作员配置的 Password 任务。重新安装会刷新其启动器文件,但不会替换其账户、凭据、操作或触发器。
安装程序会报告所选的启动模式。Node 主机保留按用户的交互式任务,用于桌面访问。如果无法识别账户或任务创建被拒绝,则桌面任务或启动文件夹回退方案需要交互式登录;它无法提供无人值守的开机启动。请以预期的服务用户身份从提升权限的终端运行安装,以注册启动任务。openclaw doctor --fix 会将识别出的旧 Gateway 定义从交互式登录迁移到无人值守启动,并在修复前备份定义和启动器。自定义定义仍由操作员拥有。
如果你在 gateway.cmd 启动行末尾追加输出重定向,请为整个目标加上引号,例如 >> "%USERPROFILE%\.openclaw\logs\gateway-stdout.log" 2>&1。完整的尾部重定向会被排除在进程所有权检查之外。未加引号的环境变量展开可能会在 Gateway 的参数中留下文件名片段;OpenClaw 会保留存在歧义的启动器命令,并拒绝终止无法验证所有权的监听器。重试前请为目标加上引号。
任务启动器拥有受监督的 Gateway 进程树。使用 schtasks /end /tn "OpenClaw Gateway"、Stop-ScheduledTask 或任务计划程序的 结束 操作结束任务,会终止 Gateway 及其子进程。更新旧安装后,如果更新未刷新启动器,请运行 openclaw gateway install --force 以重新生成启动器。
对于 pnpm 全局安装,新启动器使用经过验证的稳定 node_modules/openclaw 链接,因此替换包不会使其失效。如果旧启动器已指向已删除的包版本,请从当前安装运行 openclaw gateway install --force 以重写 gateway.cmd。如果不使用 --force,已注册的任务可能保持不变。
重新安装受管计划任务会先停止并等待其之前的进程结束,然后再发布并启动替换任务。当两个安装都使用 Node,或仅服务参数发生变化时,也是如此。状态会将正在运行的进程与已注册命令进行验证;具有相同任务名和端口的旧进程并不能证明替换任务正在运行。
安装会保留现有的服务锁和运行时固定检查。已更改的任务或启动器会阻止替换。普通安装失败会使用服务所有者的现有恢复机制,在仍可验证所有权时恢复之前的定义和运行策略。更新期间,更新程序保留恢复所有权。如果无法确认恢复,请在重试前检查报告的任务计划程序状态。
状态会报告有效的任务工作目录,同时检查运行时意图是否与生成的启动器一致。标准的无人值守任务目录不会使未更改的运行时固定失效。检查不会重新安装服务或重写其固定;自定义任务目录仍是由操作员拥有的覆盖设置。
Gateway 状态和 Doctor 会读取计划任务的数值当前状态,独立于 Windows 显示语言或控制台代码页。之前的任务退出结果并不能证明它当前是否正在运行。对于 Doctor 维护,排队或未知任务不计为已安全停止。请通过其服务所有者停止排队任务;如果无法访问检查,请在重试前恢复任务计划程序检查权限。
严格维护检查会遵循任务已注册的 CMD 或 VBS 启动器,或带有字面参数的直接注册可执行文件,并在使用结果前重新检查其捕获的定义。运行时检查使用该已注册命令,而不是默认启动器。直接可执行文件检查不会授予重写该可执行文件或其任务定义的所有权。自动更新服务管理仍会报告这些自定义操作不可用,并且保持它们不变,因为它无法恢复受管启动器;环境变量展开和参数引号歧义仍然无法检查。深度发现会根据可执行文件或启动器证据识别 OpenClaw 和旧版辅助程序;仅凭无关任务的显示名称无法识别服务。规范任务名称和所选任务名称仅在已注册操作为现代 Gateway 时抑制额外服务发现;旧版和 Node 操作仍会显示。Doctor 会将检查不完整与符合现有清理条件的服务分开报告。
openclaw gateway status --deep 和 openclaw doctor --deep 会报告当前账户启动文件夹中的同级配置文件。如果其计划任务不存在,则所选的现代 Gateway 回退方案会从额外服务列表中省略。即使任务具有相同名称,每个启动文件仍是一个独立的服务定义。检查会遵循该确切文件及其捕获的 Gateway 脚本。完整清单会保留无法读取或格式错误的 Gateway 启动器的错误;Doctor 和状态仅列出成功检查的额外服务。启动检查提示使用确切文件路径,并且不授予任务计划程序对其的控制。
本地构建也会检查这些定义,以查找使用该安装的 dist 运行的 Gateway。在重建其文件之前,请停止匹配的 Gateway。
Doctor 和 deep status 会为额外的计划任务(包括 Node 主机)提供只读 schtasks /Query 提示。发现过程在清单查询、Startup 目录扫描和启动器检查之间共享一个 60 秒预算。如果预算过期,已完成的发现仍然可用,并且 Doctor 会报告某些服务无法检查。在通过服务的所有者选择移除之前,请检查已注册的命令和用途。
Doctor 会在已拥有服务的刷新期间识别随 2026.9.3 提供的等待中的 VBS 启动器。自定义启动器行为仍会保留现有定义。
Doctor 使用任务计划程序的默认值比较任务定义。省略的 Enabled 元素表示任务和其登录触发器均为 true,因此 XML 导出差异不会导致漂移警告或刷新验证失败。显式禁用的任务和触发器仍会被报告。
任务检查允许 Windows PowerShell 继承或创建控制台,因为某些 PowerShell 5.1 主机在禁用控制台创建时会检查失败。从无控制台的应用程序中调用它时,可能会短暂显示一个控制台窗口。如果没有显式的调用方截止时间,每次检查最多允许 60 秒用于 PowerShell 的冷启动。注册检查使用相同的原生检查,并与任何 Startup 文件夹检查共享其预算。显式检查预算会替换默认允许值。直接生命周期命令保留其现有限制。访问被拒绝和超时结果仍属于检查失败,而不是任务不存在的证明。 如果检查失败,Doctor 和更新拒绝会包含底层检查详情;空响应会标识退出码,并报告 PowerShell 未产生输出。
在 previous-Gateway 就绪验证期间,每个计划任务运行时检查最多允许五秒,或更短的剩余预算。其他服务检查保留其调用方的预算,包括用于验证运行时重建是否安全的更长允许值。
在更新预检期间,计划任务检查使用更新的 --timeout 预算。注册或运行时超时会重试一次完整的严格检查。如果检查仍不可用,更新会报告强制执行的预算和检查详情,保留已记录的服务定义,并跳过自动服务重启。使用 openclaw gateway status --deep 检查服务,然后在更新后手动重启它。在准入后失去已验证的所有权会阻止服务变更。
Gateway 启动会通过 Windows API 创建私有 SQLite 暂存目录,而不会为它们的权限编译 C# 或启动 PowerShell。所有者、SYSTEM 和 Administrators 保留完全访问权限;其他继承的访问权限会在创建时移除。更新重启辅助工具也会避免运行时 C# 编译和 Invoke-Expression。如果防病毒软件仍中断启动,请在报告中包含其检测名称和 openclaw gateway status --json 的输出。
安装 Gateway 服务:
对于仅使用 CLI 且没有受管 Gateway 服务的情况:
从 2026.9.4 更新¶
已发布的 2026.9.4 Windows 更新器在其服务交接中保留了一个旧数据库读取器。如果目标将共享状态迁移到 schema 17 之外,可能会使该回调在激活后失败。在正在运行的 9.4 更新期间,候选项的包生命周期会要求 Doctor 的只读预检在更新器驱动程序未被确认停止时拒绝此迁移。失败的 npm 阶段会在旧更新器进入修复之前保留原始包和 Gateway。当包脚本被跳过时,CLI 预检也会保留此检查;该后续拒绝可能会被旧修复路径中的清理错误掩盖。此遏制措施不会完成自动更新。
等待更新器退出并审查其结果。要升级,请创建一个已验证备份,并从独立 shell 使用现有的手动包管理器流程。保留原始服务账户、包前缀、配置文件以及状态/配置覆盖。在替换包之前,通过其所有者停止 Gateway,运行新安装的 Doctor,然后启动并验证 Gateway。不要降低 schema 标记,也不要针对已迁移数据运行较旧的构建。
WSL2 Gateway¶
WSL2 仍然是 Windows 上最兼容 Linux 的 Gateway 运行时。Windows Hub 可以为你设置应用拥有的 WSL Gateway,或者在你自己的发行版中手动安装。
手动设置:
在 WSL 内启用 systemd:
从 PowerShell 重启 WSL:
然后在 WSL 内使用 Linux 快速入门安装 OpenClaw:
Gateway 在 Windows 登录前自动启动¶
对于无头 WSL 设置,请确保即使没有人登录 Windows,完整启动链也能运行。
在 WSL 内:
以管理员身份在 PowerShell 中:
schtasks /create /tn "WSL Boot" /tr "wsl.exe -d Ubuntu --exec dbus-launch true" /sc onstart /ru "$env:USERNAME"
将 Ubuntu 替换为你的发行版名称,可从以下命令获取:
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
通过局域网暴露 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。 - 局域网访问使用
listenaddress=0.0.0.0,仅本地访问使用127.0.0.1。
故障排除¶
Gateway 计划任务已禁用¶
openclaw gateway status 和 Doctor 会指出一个已注册但处于 DISABLED 状态的任务,并显示恢复命令。运行 openclaw gateway start 或 openclaw doctor --fix 以重新启用并启动受管理的 Gateway。使用与安装时相同的 profile 以及 state/config 覆盖设置。恢复过程在启用前会验证已注册的启动器和任务所有权;外部或无法验证的任务将保持不变,并附带说明。已禁用的任务在重新启用之前,无法在登录或重启后自动启动。
计划任务在 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 打开设置日志,或检查:
常见原因:WSL 被禁用、虚拟化被阻止、应用拥有的 WSL 状态过期,或安装 Gateway 包时发生网络故障。
应用提示需要配对¶
从 Gateway 批准操作员或节点请求:
如果设备已有 token,请在批准后从 Connections 选项卡重新连接。
对于节点请求,请在 Windows 节点模式 中完成独立的命令界面批准:重启已暂停的节点模式,然后运行 openclaw nodes pending 并批准其对应的节点请求 ID。仅批准操作员设备并不能完成该节点流程。
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 代理。
在当前会话中使用基于 token 的 gh 身份验证:
切勿提交 token,或将其粘贴到 issue 或 pull request 中。
相关¶
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw