openclaw-windows-node

OpenClaw AI 个人助手的 Windows 原生伴侣套件，包含系统托盘应用、共享库和 CLI 工具。亮点是由 Scott Hanselman 和 Molty 打造，支持全局热键快速发送消息、嵌入式 WebView2 聊天、节点模式让 Windows 成为可被 AI 控制的节点（屏幕截图、摄像头、文本转语音等），深度整合 OpenClaw 生态，提供丰富的诊断和自动化能力。

README

🦞 OpenClaw Windows Hub

OpenClaw Windows Node 横幅

为 OpenClaw（AI 驱动的个人助手）打造的原生 Windows 配套套件。

由 Scott Hanselman 和 Molty 用 🦞 爱心制作

OpenClaw Windows Hub 托盘菜单

OpenClaw Windows Hub 命令中心

OpenClaw Windows Hub 配对与连接设置

OpenClaw Windows Hub 活动与诊断

项目

本单仓包含 Windows Hub、共享客户端库和 CLI 工具：

项目	描述
OpenClaw.Tray.WinUI	系统托盘应用程序（WinUI 3），用于快速访问 OpenClaw
OpenClaw.Shared	共享网关客户端库
OpenClaw.Cli	CLI 验证器，用于使用托盘设置进行 WebSocket 连接/发送/探测

🚀 快速开始

最终用户安装程序？ 从 OpenClaw Windows 文档下载最新的稳定版 x64 或 ARM64 安装程序，或参阅 docs/SETUP.md 了解分步安装说明（无需构建）。

托管的 WSL 网关？ 本地设置会创建一个锁定的、由应用拥有的 OpenClawGateway 发行版。请参阅 docs/WSL_GATEWAY_ADMIN.md 了解如何以 openclaw 用户身份编辑 openclaw.json，以及如何使用 root 用户进行保护文件的管理。

从最新的 OpenClaw 版本直接下载：

前提条件

Windows 10（20H2+）或 Windows 11
.NET 10.0 SDK - https://dotnet.microsoft.com/download/dotnet/10.0
Windows 10 SDK（用于 WinUI 构建） - 通过 Visual Studio 或独立安装
WebView2 Runtime - 现代 Windows 预装，或从 https://developer.microsoft.com/microsoft-edge/webview2 获取

构建

使用构建脚本检查前提条件并构建：

# 检查前提条件
.\build.ps1 -CheckOnly

# 构建所有项目
.\build.ps1

# 构建特定项目
.\build.ps1 -Project WinUI

或直接使用 dotnet 构建：

# 构建所有项目（使用 build.ps1 可获得最佳效果）
dotnet build

# 构建 WinUI（需要运行时标识符以支持 WebView2）
dotnet build src/OpenClaw.Tray.WinUI/OpenClaw.Tray.WinUI.csproj -r win-arm64  # ARM64
dotnet build src/OpenClaw.Tray.WinUI/OpenClaw.Tray.WinUI.csproj -r win-x64    # x64

# 构建 MSIX 包（用于摄像头/麦克风权限提示）
dotnet build src/OpenClaw.Tray.WinUI -r win-arm64 -p:PackageMsix=true  # ARM64 MSIX
dotnet build src/OpenClaw.Tray.WinUI -r win-x64 -p:PackageMsix=true    # x64 MSIX

运行托盘应用

# 构建并启动未打包的 WinUI 托盘应用
.\run-app-local.ps1

# 如果已经构建过，跳过重新构建直接启动已有的 Debug 输出
.\run-app-local.ps1 -NoBuild

# 隔离运行，不与正常托盘设置关联，允许多个工作目录同时运行
.\run-app-local.ps1 -Isolated

# 从 Release 构建进行 Alpha 更新测试
.\run-app-local.ps1 -Configuration Release -Isolated -UpdateChannel alpha

# 可选：通过 WinAppCLI 和 Package.appxmanifest 启动
.\run-app-local.ps1 -UseWinApp -NoBuild

默认路径直接启动未打包的可执行文件。-UseWinApp 需要 Microsoft WinAppCLI（winget install Microsoft.WinAppCLI），仅在需要清单/MSIX 相关启动验证时才需要。

运行 CLI WebSocket 验证器

使用 CLI 在托盘 UI 之外验证网关连接性和 chat.send。

# 显示帮助
dotnet run --project src/OpenClaw.Cli -- --help

# 使用 %APPDATA%\OpenClawTray\settings.json 中的托盘设置，发送一条消息
dotnet run --project src/OpenClaw.Cli -- --message "快速发送验证"

# 循环发送并探测 sessions/usage/nodes API
dotnet run --project src/OpenClaw.Cli -- --repeat 5 --delay-ms 1000 --probe-read --verbose

# 覆盖网关 URL/令牌以进行隔离测试
dotnet run --project src/OpenClaw.Cli -- --url ws://127.0.0.1:18789 --token "<token>" --message "覆盖测试"

📦 OpenClaw.Tray (Molty)

现代 Windows 11 风格系统托盘伴侣，连接到您的本地 OpenClaw 网关。

功能

🦞 龙虾品牌 - 像素艺术龙虾托盘图标，带有状态颜色
🎨 现代 UI - Windows 11 弹出菜单，支持深色/浅色模式
💬 快速发送 - 通过全局热键发送消息（Ctrl+Alt+Shift+C）
🔄 自动更新 - 从 GitHub Releases 自动更新
🌐 Web 聊天 - 使用 WebView2 的内嵌聊天窗口
📊 实时状态 - 实时显示会话、频道和使用情况
🧭 命令中心 - 在一个窗口中密集显示网关、频道、使用、节点、配对和允许列表诊断信息
⚡ 活动流 - 命令中心页面，显示实时会话、使用、节点和通知事件
🔔 Toast 通知 - 可点击的 Windows 通知，带有智能分类
📡 频道控制 - 从菜单启动/停止 Telegram 和 WhatsApp
🖥️ 节点可观测性 - 节点清单，含在线/离线状态和可复制的摘要
⏱ Cron 任务 - 快速访问计划任务
🚀 自启动 - 随 Windows 启动
⚙️ 设置 - 完整配置页面
🎯 首次运行引导 — 6 屏设置向导（连接、权限、聊天、配置）

快速发送范围要求

快速发送使用网关的 chat.send 方法，要求操作设备具有 operator.write 作用域。

如果快速发送失败并提示 missing scope: operator.write，Molty 现会将身份信息和修复指南复制到剪贴板，包括：

操作角色和托盘应用使用的 client.id
网关报告的操作设备 ID（如果提供）
当前授予的作用域（如果提供）

对于此特定错误（missing scope: operator.write），原因是操作令牌作用域问题。更新托盘应用使用的令牌，使其包含 operator.write，然后重试快速发送。

如果快速发送失败并提示 pairing required / NOT_PAIRED，这是设备审批问题。在网关配对审批中批准托盘设备，然后重新连接并重试。

菜单部分

状态 - 网关连接状态，可点击查看详情
命令中心 - 集诊断、频道健康、使用情况、会话、节点和可复制的修复命令于一体的枢纽
会话 - 活跃的代理会话，带预览和每个会话的控制
使用 - 提供商/成本摘要，可快速跳转到活动详情
频道 - Telegram/WhatsApp 状态，带开关控制
节点 - 在线/离线节点清单和可复制摘要
最近活动 - 带时间戳的事件流，涵盖会话、使用、节点和通知
操作 - 仪表盘、Web 聊天、快速发送、活动流、历史
支持与调试 - 日志、配置、诊断文件夹、脱敏支持上下文、浏览器设置、端口/能力/节点/频道/活动摘要，以及托管 SSH 隧道重启
设置 - 配置和自启动

Mac 功能对等状态

与 openclaw-menubar（macOS Swift 菜单栏应用）比较：

功能	Mac	Windows	备注
菜单栏/托盘图标	✅	✅	颜色编码状态
网关状态显示	✅	✅	已连接/已断开
PID 显示	✅	✅	命令中心显示网关监听进程/PID
频道状态	✅	✅	Mac: Discord / Win: Telegram+WhatsApp
会话计数	✅	✅
上次检测时间戳	✅	✅	显示在托盘工具提示中
网关启动/停止/重启	✅	⚠️	Windows 可以从托盘支持与调试及命令中心重启托管 SSH 隧道；外部网关进程控制未实现
查看日志	✅	✅
打开 Web UI	✅	✅
刷新	✅	✅	菜单打开时自动刷新
登录时启动	✅	✅
通知开关	✅	✅

Windows 专属功能

这些功能在 Windows 中可用，但 Mac 应用中没有：

功能	描述
快速发送热键	Ctrl+Alt+Shift+C 全局热键
内嵌 Web 聊天	基于 WebView2 的聊天窗口
Toast 通知	可点击的 Windows 通知
频道控制	启动/停止 Telegram 和 WhatsApp
现代弹出菜单	Windows 11 风格，支持深色/浅色模式
深度链接	`openclaw://` URL 方案，带 IPC
首次运行引导	6 屏引导式设置向导（欢迎 → 连接 → 向导 → 权限 → 聊天 → 就绪）

🔌 节点模式（代理控制）

在设置中启用节点模式后，您的 Windows PC 将成为一个节点，可供 OpenClaw 代理控制——就像 Mac 应用一样！代理可以：

能力	命令	描述
系统	`system.notify`, `system.run`, `system.run.prepare`, `system.which`, `system.execApprovals.get`, `system.execApprovals.set`	显示 Windows toast 通知，执行带策略控制的命令
画布	`canvas.present`, `canvas.hide`, `canvas.navigate`, `canvas.eval`, `canvas.snapshot`, `canvas.a2ui.push`, `canvas.a2ui.pushJSONL`, `canvas.a2ui.reset`	显示和控制一个 WebView2 窗口
屏幕	`screen.snapshot`, `screen.record`	截取屏幕截图和固定时长的 MP4 屏幕录制
摄像头	`camera.list`, `camera.snap`, `camera.clip`	枚举摄像头并拍摄静态照片或短视频片段
语音转文字	`stt.transcribe`	从默认麦克风捕获音频（限定时长），返回转录文本。默认关闭；通过设置选择加入。启用后，会同时向网关调用者（受网关允许列表限制）和本地 MCP 客户端（受 bearer token 限制）广播。
位置	`location.get`	在有权限时返回 Windows 地理位置
设备	`device.info`, `device.status`	返回 Windows 主机/应用元数据和轻量状态
文本转语音	`tts.speak`	通过 Windows 语音合成朗读文本，或配置为 ElevenLabs

打包安装会声明摄像头、麦克风和位置功能。Windows 可能在节点能力首次使用这些受保护资源时请求许可。

节点设置

在设置中启用节点模式（默认启用）
首次连接会在网关上创建一个配对请求

批准设备：

openclaw devices list          # 找到您的 Windows 设备
openclaw devices approve <id>  # 批准它

配置网关 allowCommands - 在 ~/.openclaw/openclaw.json 的 gateway.nodes 下添加您想允许的命令：

{
  "gateway": {
    "nodes": {
      "allowCommands": [
        "system.notify",
        "system.run",
        "system.run.prepare",
        "system.which",
        "system.execApprovals.get",
        "system.execApprovals.set",
        "canvas.present",
        "canvas.hide",
        "canvas.navigate",
        "canvas.eval",
        "canvas.snapshot",
        "canvas.a2ui.push",
        "canvas.a2ui.pushJSONL",
        "canvas.a2ui.reset",
        "screen.snapshot",
        "camera.list",
        "camera.snap",
        "camera.clip",
        "location.get",
        "device.info",
        "device.status",
        "tts.speak"
      ]
    }
  }
}

⚠️ 重要：网关有服务端允许列表。命令必须显式列出——像 canvas.* 这样的通配符不起作用！涉及隐私的命令如 screen.record 和代理驱动的音频播放（通过 tts.speak）只有在您明确希望允许时才应添加到 allowCommands 中。

从您的 Mac/网关测试：

 # 显示通知
 openclaw nodes notify --node <id> --title "Hello" --body "From Mac!"
 
 # 打开画布窗口
 openclaw nodes canvas present --node <id> --url "https://example.com"
 
 # 执行 JavaScript（注意：CLI 发送 "javaScript" 参数）
 openclaw nodes canvas eval --node <id> --javaScript "document.title"
 
 # 在画布中渲染 A2UI JSONL（将文件内容作为字符串传递）
 openclaw nodes canvas a2ui push --node <id> --jsonl "$(cat ./ui.jsonl)"
 
 # 截取屏幕截图
 openclaw nodes invoke --node <id> --command screen.snapshot --params '{"screenIndex":0,"format":"png"}'

 # 录制短屏幕片段（需要网关显式允许 screen.record）
 openclaw nodes screen record --node <id> --duration 3000 --fps 10 --screen 0 --no-audio --out /tmp/openclaw-windows-screen-record-test.mp4 --json

 # 列出摄像头
 openclaw nodes invoke --node <id> --command camera.list

 # 拍照（NV12/MediaCapture 回退）
 openclaw nodes invoke --node <id> --command camera.snap --params '{"deviceId":"<device-id>","format":"jpeg","quality":80}'

 # 在 Windows 节点上朗读文本（需要在设置中启用 TTS 并在网关上允许 tts.speak）
 openclaw nodes invoke --node <id> --command tts.speak --params '{"text":"Hello from OpenClaw","provider":"windows"}'

 # 在 Windows 节点上执行命令
 openclaw nodes invoke --node <id> --command system.run --params '{"command":"Get-Process | Select -First 5","shell":"powershell","timeoutMs":10000}'

 # 查看执行审批策略
 openclaw nodes invoke --node <id> --command system.execApprovals.get

 # 更新执行审批策略（添加自定义规则）
 openclaw nodes invoke --node <id> --command system.execApprovals.set --params '{"rules":[{"pattern":"echo *","action":"allow"},{"pattern":"*","action":"deny"}],"defaultAction":"deny"}'

📷 摄像头权限：桌面构建依赖 Windows 隐私设置。打包的 MSIX 构建会显示系统许可提示。

🔒 执行策略：system.run 受 Windows 节点上的审批策略控制，文件位于 %LOCALAPPDATA%\OpenClawTray\exec-policy.json（模式：{ "defaultAction": "...", "rules": [...] }）。这与网关侧的 ~/.openclaw/exec-approvals.json 是分开的。

规则会与完整命令行进行匹配。已知的包装器负载如 cmd /c ...、powershell -Command ...、pwsh -EncodedCommand ... 和 bash -c ... 也会在执行前被评估。危险的环墶覆盖如 PATH、PATHEXT、NODE_OPTIONS、GIT_SSH_COMMAND、LD_* 和 DYLD_* 会被拒绝。

命令中心诊断

通过托盘菜单或 openclaw://commandcenter 打开状态详情/命令中心。它将显示：

来自网关 health 事件的频道健康状态，包括无需单独操作员连接即可接收的节点模式健康
活跃会话、使用/成本数据、节点清单、声明的命令以及 Mac 功能对等备注
允许列表诊断，区分安全的伴侣命令和隐私敏感可选命令如 screen.record、camera.snap 和 camera.clip
可复制的修复命令，用于安全允许列表修复和待处理的配对审批
通过活动流展示的近期活动和节点调用结果，只存储命令名称/状态/时长（不存储负载、截图、录制或密钥）
```
openclaw nodes invoke --node <id> --command system.execApprovals.set --params '{"rules":[{"pattern":"powershell.exe","action":"allow"},{"pattern":"pwsh.exe","action":"allow"},{"pattern":"echo *","action":"allow"},{"pattern":"*","action":"deny"}],"defaultAction":"deny"}'
```
🔐 Web 聊天安全上下文：远程 Web 聊天需要 https://（或 localhost）。如果使用自签名证书，请在 Windows 中信任它（受信任的根证书颁发机构），或使用 SSH 隧道到 localhost。

托盘菜单中的节点状态

托盘菜单显示节点连接状态：

🔌 节点模式 部分在启用时显示
⏳ 等待审批... - 设备需要在网关上进行审批
✅ 已配对并连接 - 准备接收命令
点击设备 ID 可复制到剪贴板以用于审批命令

深度链接

OpenClaw 注册了 openclaw:// URL 方案，用于自动化和集成：

链接	描述
`openclaw://settings`	打开设置页面
`openclaw://setup`	打开设置向导
`openclaw://chat`	打开聊天页面
`openclaw://commandcenter`	打开命令中心诊断
`openclaw://activity`	打开活动页面
`openclaw://history`	打开活动页面，过滤为通知历史
`openclaw://dashboard`	在浏览器中打开仪表盘
`openclaw://dashboard/sessions`	打开特定的仪表盘页面
`openclaw://dashboard/channels`	打开频道仪表盘页面
`openclaw://dashboard/skills`	打开技能仪表盘页面
`openclaw://dashboard/cron`	打开 Cron 仪表盘页面
`openclaw://healthcheck`	运行手动健康检查
`openclaw://check-updates`	运行手动更新检查
`openclaw://logs`	打开当前托盘日志文件
`openclaw://log-folder`	打开日志文件夹
`openclaw://config`	打开配置文件夹
`openclaw://diagnostics`	打开诊断 JSONL 文件夹
`openclaw://support-context`	复制脱敏支持上下文
`openclaw://debug-bundle`	复制组合调试包以供支持
`openclaw://browser-setup`	复制 browser.proxy/browser-control 设置指南
`openclaw://port-diagnostics`	复制网关/浏览器/隧道端口诊断及所有者 PID 停止提示
`openclaw://capability-diagnostics`	复制权限、允许列表和对等性诊断
`openclaw://node-inventory`	复制节点能力、命令和策略状态
`openclaw://channel-summary`	复制频道健康和启动/停止可用性
`openclaw://activity-summary`	复制近期托盘活动以排除故障
`openclaw://extensibility-summary`	复制频道、技能和 Cron 仪表盘界面指南
`openclaw://restart-ssh-tunnel`	重启托盘管理的 SSH 隧道（启用时）
`openclaw://send?message=Hello`	打开快速发送并预填充文本
`openclaw://agent?message=Hello`	直接向已连接的网关发送消息

即使 Molty 已在运行，深度链接也能生效——它们通过 IPC 转发。

📦 OpenClaw.Shared

共享库，包含：

OpenClawGatewayClient - 用于网关协议的 WebSocket 客户端
IOpenClawLogger - 日志接口
数据模型（SessionInfo、ChannelHealth 等）
频道控制（通过网关启动/停止频道）

开发

项目结构

openclaw-windows-node/
├── src/
│   ├── OpenClaw.Shared/           # 共享网关库
│   └── OpenClaw.Tray.WinUI/       # 系统托盘应用（WinUI 3）
├── tests/
│   ├── OpenClaw.Shared.Tests/     # 共享库测试
│   └── OpenClaw.Tray.Tests/       # 托盘应用辅助测试
├── docs/
│   └── images/                    # 截图
├── openclaw-windows-node.slnx     # 解决方案文件
├── README.md
├── LICENSE
└── .gitignore

配置

设置存储位置：

设置：%APPDATA%\OpenClawTray\settings.json
日志：%LOCALAPPDATA%\OpenClawTray\openclaw-tray.log
简易按钮设置摘要：%LOCALAPPDATA%\OpenClawTray\Logs\Setup\easy-setup-latest.txt
简易按钮设置 JSONL：%LOCALAPPDATA%\OpenClawTray\Logs\Setup\easy-setup-latest.jsonl

默认网关：ws://localhost:18789

首次运行

首次运行时，Molty 会启动一个引导式设置向导，引导您完成设置：

欢迎 — 介绍 OpenClaw 并启动设置流程
连接 — 选择本地网关、远程网关或稍后配置。粘贴设置代码或手动输入网关 URL 和令牌。使用 Ed25519 设备身份验证测试连接。
向导 — 网关驱动的配置步骤（AI 提供商选择、个性设置、通信频道）。步骤由您的网关定义。
权限 — 审查 Windows 系统权限（通知、摄像头、麦克风、屏幕捕获、位置），并链接到系统设置以授予权限。
聊天 — 在由网关 Web UI 驱动的实时聊天中与您的代理见面。
就绪 — 可用功能摘要、是否启动时启动的选项，以及完成按钮。

有关详细设置说明，请参阅 docs/SETUP.md。有关完整的引导架构，请参阅 docs/ONBOARDING_WIZARD.md。

许可证

MIT 许可证 - 请参阅 LICENSE

曾用名：Moltbot，再曾用名：Clawdbot

开源项目openclaw2026-06-04原文

打开互动版