openclaw/openclaw-windows-node

# 🦞 OpenClaw Windows Hub  [OpenClaw](https://openclaw.ai) 的原生 Windows 配套套件——这是一款 AI 驱动的个人助手。 *由 Scott Hanselman 和 Molty 充满 🦞 爱意地打造*     ## 项目 这个 monorepo 包含了 Windows hub、共享客户端库和 CLI 工具： | 项目 | 描述 | |---------|-------------| | **OpenClaw.Tray.WinUI** | 用于快速访问 OpenClaw 的系统托盘应用 | | **OpenClaw.Shared** | 共享的 gateway 客户端库 | | **OpenClaw.Cli** | 使用托盘设置进行 WebSocket 连接/发送/探测的 CLI 验证器 | ## 🚀 快速开始 从最新的 OpenClaw 发布版直接下载： - [OpenClawCompanion-Setup-x64.exe](https://github.com/openclaw/openclaw/releases/latest/download/OpenClawCompanion-Setup-x64.exe) - [OpenClawCompanion-Setup-arm64.exe](https://github.com/openclaw/openclaw/releases/latest/download/OpenClawCompanion-Setup-arm64.exe) - [OpenClawCompanion-SHA256SUMS.txt](https://github.com/openclaw/openclaw/releases/latest/download/OpenClawCompanion-SHA256SUMS.txt) ### 前置条件 - 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（需要 runtime identifier 以支持 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 package（用于摄像头/麦克风同意提示） 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 # 独立运行，与您的常规托盘设置隔离，以便多个 worktree 可以同时运行 .\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`），且仅在 您需要进行 manifest/MSIX 相关的启动验证时才需要。 ### 运行 CLI WebSocket 验证器 使用 CLI 在托盘 UI 之外验证 gateway 连接性和 `chat.send`。 ``` # 显示帮助 dotnet run --project src/OpenClaw.Cli -- --help # 使用 %APPDATA%\OpenClawTray\settings.json 中的托盘设置并发送一条消息 dotnet run --project src/OpenClaw.Cli -- --message "quick send validation" # 循环发送并探测 sessions/usage/nodes APIs dotnet run --project src/OpenClaw.Cli -- --repeat 5 --delay-ms 1000 --probe-read --verbose # 覆盖 gateway URL/token 以进行隔离测试 dotnet run --project src/OpenClaw.Cli -- --url ws://127.0.0.1:18789 --token "" --message "override test" ``` ## 📦 OpenClaw.Tray (Molty) 现代 Windows 11 风格的系统托盘配套应用，可连接到您本地的 OpenClaw gateway。 ### 功能 - 🦞 **龙虾品牌设计** - 带有状态颜色的像素风龙虾托盘图标 - 🎨 **现代 UI** - 带有深色/浅色模式支持的 Windows 11 浮出菜单 - 💬 **快速发送** - 通过全局热键 (Ctrl+Alt+Shift+C) 发送消息 - 🔄 **自动更新** - 从 GitHub Releases 自动获取更新 - 🌐 **Web Chat** - 带有 WebView2 的嵌入式聊天窗口 - 📊 **实时状态** - 实时显示会话、频道和使用量 - 🧭 **指挥中心** - 在一个窗口中展示密集的 gateway、频道、使用量、node、配对和白名单诊断 - ⚡ **活动流** - 用于显示实时会话、使用量、node 和通知事件的指挥中心页面 - 🔔 **Toast 通知** - 带有[智能分类](docs/NOTIFICATION_CATEGORIZATION.md)的可点击 Windows 通知 - 📡 **频道控制** - 从菜单中启动/停止 Telegram & WhatsApp - 🖥️ **Node 可观测性** - 带有在线/离线状态和可复制摘要的 Node 清单 - ⏱ **Cron 任务** - 快速访问计划任务 - 🚀 **自启动** - 随 Windows 启动 - ⚙️ **设置** - 完整的配置页面 - 🎯 **首次运行引导** — 6 屏设置向导（连接、权限、聊天、配置） #### 快速发送 scope 要求 快速发送使用 gateway 的 `chat.send` 方法，并要求 operator 设备具有 `operator.write` scope。 如果快速发送失败并提示 `missing scope: operator.write`，Molty 现在会将身份和修复指南复制到您的剪贴板，内容包括： - operator 角色以及托盘应用使用的 `client.id` - gateway 报告的 operator 设备 ID（如果有提供） - 当前授予的 scope（如果有提供） 对于这个特定的错误（`missing scope: operator.write`），原因是 **operator token 的 scope 问题**。更新托盘应用使用的 token 使其包含 `operator.write`，然后重试快速发送。 如果快速发送失败并提示 `pairing required` / `NOT_PAIRED`，这是一个**设备批准**问题。在 gateway 配对批准中批准该托盘设备，重新连接并重试。 ### 菜单部分 - **状态** - Gateway 连接状态，点击查看详情 - **指挥中心** - 包含诊断、频道健康、使用量、会话、node 和可复制修复命令的 Hub - **会话** - 活跃的 agent 会话，带有预览和单会话控制 - **使用量** - 提供商/成本摘要，可快速跳转至活动详情 - **频道** - Telegram/WhatsApp 状态及切换控制 - **Node** - 在线/离线 Node 清单及可复制摘要 - **最近活动** - 带有时间戳的会话、使用量、Node 和通知事件流 - **操作** - Dashboard、Web Chat、快速发送、活动流、历史记录 - **支持与调试** - 日志、配置、诊断文件夹、脱敏后的支持上下文、浏览器设置、端口/功能/node/频道/活动摘要，以及托管的 SSH 隧道重启 - **设置** - 配置与自启动 ### Mac 功能对齐状态 与 [openclaw-menubar](https://github.com/magimetal/openclaw-menubar)（macOS Swift 菜单栏应用）的比较： | 功能 | Mac | Windows | 备注 | |---------|-----|---------|-------| | 菜单栏/托盘图标 | ✅ | ✅ | 彩色编码状态 | | Gateway 状态显示 | ✅ | ✅ | 已连接/已断开 | | PID 显示 | ✅ | ✅ | 指挥中心显示 gateway 监听进程/PID | | 频道状态 | ✅ | ✅ | Mac: Discord / Win: Telegram+WhatsApp | | 会话计数 | ✅ | ✅ | | | 最后检查时间戳 | ✅ | ✅ | 显示在托盘提示中 | | Gateway 启动/停止/重启 | ✅ | ⚠️ | Windows 可以通过托盘的支持与调试以及指挥中心重启托管的 SSH 隧道；未实现外部 gateway 进程控制 | | 查看日志 | ✅ | ✅ | | | 打开 Web UI | ✅ | ✅ | | | 刷新 | ✅ | ✅ | 菜单打开时自动刷新 | | 登录时启动 | ✅ | ✅ | | | 通知切换 | ✅ | ✅ | | ### Windows 专属功能 这些功能在 Windows 版本中可用，但在 Mac 应用中不可用： | 功能 | 描述 | |---------|-------------| | 快速发送热键 | Ctrl+Alt+Shift+C 全局热键 | | 嵌入式 Web Chat | 基于 WebView2 的聊天窗口 | | Toast 通知 | 可点击的 Windows 通知 | | 频道控制 | 启动/停止 Telegram & WhatsApp | | 现代浮出菜单 | 带有深色/浅色模式的 Windows 11 风格 | | Deep links | 带有 IPC 的 `openclaw://` URL scheme | | 首次运行引导 | 6 屏引导设置向导 (欢迎 → 连接 → 向导 → 权限 → 聊天 → 准备就绪) | ### 🔌 Node 模式 (Agent 控制) 在设置中启用 Node 模式后，您的 Windows PC 将成为 OpenClaw agent 可以控制的 **node** —— 就像 Mac 应用一样！该 agent 可以： | 功能 | 命令 | 描述 | |------------|----------|-------------| | **System** | `system.notify`, `system.run`, `system.run.prepare`, `system.which`, `system.execApprovals.get`, `system.execApprovals.set` | 显示 Windows toast 通知，在策略控制下执行命令 | | **Canvas** | `canvas.present`, `canvas.hide`, `canvas.navigate`, `canvas.eval`, `canvas.snapshot`, `canvas.a2ui.push`, `canvas.a2ui.pushJSONL`, `canvas.a2ui.reset` | 显示并控制 WebView2 窗口 | | **Screen** | `screen.snapshot`, `screen.record` | 捕获屏幕截图和固定时长的 MP4 屏幕录像 | | **Camera** | `camera.list`, `camera.snap`, `camera.clip` | 枚举摄像头并捕获静态照片或短视频片段 | | **Speech-to-text** | `stt.transcribe` | 在限定时间内从默认麦克风捕获音频并返回转录后的文本。默认关闭；通过设置开启。启用后，将同时向 gateway 调用者（受 gateway 白名单限制）和本地 MCP 客户端（受 bearer token 限制）播报。 | | **Location** | `location.get` | 在授予权限时返回 Windows 地理位置 | | **Device** | `device.info`, `device.status` | 返回 Windows 主机/应用元数据和轻量级状态 | | **Text-to-speech** | `tts.speak` | 通过 Windows 语音合成朗读文本，或在配置后使用 ElevenLabs | 打包安装的程序会声明摄像头、麦克风和位置功能。当 node 功能首次使用这些受保护的资源之一时，Windows 可能会要求您同意。 #### Node 设置 1. 在设置中**启用 Node 模式**（默认启用） 2. **首次连接**会在 gateway 上创建一个配对请求 3. 在您的 gateway 上**批准该设备**： openclaw devices list # 查找您的 Windows 设备 openclaw devices approve # 批准它 4. **配置 gateway 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" ] } } } 5. 从您的 Mac/gateway **进行测试**： # 显示通知 openclaw nodes notify --node --title "Hello" --body "From Mac!" # 打开 canvas 窗口 openclaw nodes canvas present --node --url "https://example.com" # 执行 JavaScript (注意：CLI 发送 "javaScript" 参数) openclaw nodes canvas eval --node --javaScript "document.title" # 在 canvas 中渲染 A2UI JSONL (将文件内容作为字符串传递) openclaw nodes canvas a2ui push --node --jsonl "$(cat ./ui.jsonl)" # 截图 openclaw nodes invoke --node --command screen.snapshot --params '{"screenIndex":0,"format":"png"}' # 录制短视频片段 (需要在 gateway 上明确允许 screen.record) openclaw nodes screen record --node --duration 3000 --fps 10 --screen 0 --no-audio --out /tmp/openclaw-windows-screen-record-test.mp4 --json # 列出摄像头 openclaw nodes invoke --node --command camera.list # 拍照 (NV12/MediaCapture 回退) openclaw nodes invoke --node --command camera.snap --params '{"deviceId":"","format":"jpeg","quality":80}' # 在 Windows node 上朗读文本 (需要在设置中启用 TTS，并在 gateway 上允许 tts.speak) openclaw nodes invoke --node --command tts.speak --params '{"text":"Hello from OpenClaw","provider":"windows"}' # 在 Windows node 上执行命令 openclaw nodes invoke --node --command system.run --params '{"command":"Get-Process | Select -First 5","shell":"powershell","timeoutMs":10000}' # 查看 exec 批准策略 openclaw nodes invoke --node --command system.execApprovals # 更新 exec 批准策略 (添加自定义规则) openclaw nodes invoke --node --command system.execApprovals.set --params '{"rules":[{"pattern":"echo *","action":"allow"},{"pattern":"*","action":"deny"}],"defaultAction":"deny"}' #### 指挥中心诊断 从托盘菜单或使用 `openclaw://commandcenter` 打开状态详情/指挥中心。它显示： - 来自 gateway `health` 事件的频道健康状况，包括在没有单独 operator 连接的情况下接收到的 node 模式健康状况 - 活动会话、使用量/成本数据、Node 清单、声明的命令和 Mac 对齐说明 - 白名单诊断，将安全的配套命令与隐私敏感的可选项（如 `screen.record`、`camera.snap` 和 `camera.clip`）区分开来 - 可复制的修复命令，用于安全的白名单修复和待处理的配对批准 - 通过活动流展示的最近活动和 node 调用结果，仅存储命令名称/状态/持续时间（不包含 payload、截图、录像或机密信息） #### 托盘菜单中的 Node 状态 托盘菜单显示 node 连接状态： - 启用时出现 **🔌 Node 模式** 部分 - **⏳ 等待批准...** - 设备需要在 gateway 上进行批准 - **✅ 已配对并连接** - 准备好接收命令 - 点击设备 ID 可将其复制以用于批准命令 ### Deep links OpenClaw 注册了 `openclaw://` URL scheme 以实现自动化和集成： | 链接 | 描述 | |------|-------------| | `openclaw://settings` | 打开设置页面 | | `openclaw://setup` | 打开设置向导 | | `openclaw://chat` | 打开聊天页面 | | `openclaw://commandcenter` | 打开指挥中心诊断 | | `openclaw://activity` | 打开活动页面 | | `openclaw://history` | 打开筛选为通知历史的活动页面 | | `openclaw://dashboard` | 在浏览器中打开 Dashboard | | `openclaw://dashboard/sessions` | 打开特定的 Dashboard 页面 | | `openclaw://dashboard/channels` | 打开频道 Dashboard 页面 | | `openclaw://dashboard/skills` | 打开技能 Dashboard 页面 | | `openclaw://dashboard/cron` | 打开 Cron Dashboard 页面 | | `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` | 复制 gateway/浏览器/隧道端口诊断以及所有者 PID 停止提示 | | `openclaw://capability-diagnostics` | 复制权限、白名单和对齐诊断 | | `openclaw://node-inventory` | 复制 node 功能、命令和策略状态 | | `openclaw://channel-summary` | 复制频道健康状况和启动/停止可用性 | | `openclaw://activity-summary` | 复制最近的托盘活动以进行故障排除 | | `openclaw://extensibility-summary` | 复制频道、技能和 Cron Dashboard 表面指南 | | `openclaw://restart-ssh-tunnel` | 启用时重启由托盘管理的 SSH 隧道 | | `openclaw://send?message=Hello` | 使用预填充文本打开快速发送 | | `openclaw://agent?message=Hello` | 将消息直接发送到已连接的 gateway | 即使 Molty 已经在运行，Deep links 也能工作 - 它们通过 IPC 转发。 ## 📦 OpenClaw.Shared 包含以下内容的共享库： - `OpenClawGatewayClient` - 用于 gateway 协议的 WebSocket 客户端 - `IOpenClawLogger` - 日志记录接口 - 数据模型（SessionInfo、ChannelHealth 等） - 频道控制（通过 gateway 启动/停止频道） ## 开发 ### 项目结构 ``` openclaw-windows-node/ ├── src/ │ ├── OpenClaw.Shared/ # Shared gateway library │ └── OpenClaw.Tray.WinUI/ # System tray app (WinUI 3) ├── tests/ │ ├── OpenClaw.Shared.Tests/ # Shared library tests │ └── OpenClaw.Tray.Tests/ # Tray app helper tests ├── docs/ │ └── images/ # Screenshots ├── openclaw-windows-node.slnx # Solution file ├── 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` 默认 gateway：`ws://localhost:18789` ### 首次运行 首次运行时，Molty 会启动一个引导式向导，带您完成设置： 1. **欢迎** — 介绍 OpenClaw 并开始设置流程 2. **连接** — 选择本地 gateway、远程 gateway，或稍后配置。粘贴设置代码或手动输入 gateway URL 和 token。使用 Ed25519 设备身份验证测试连接。 3. **向导** — gateway 驱动的配置步骤（AI 提供商选择、个性化设置、通信频道）。步骤由您的 gateway 定义。 4. **权限** — 审查 Windows 系统权限（通知、摄像头、麦克风、屏幕捕获、位置）并提供指向系统设置的链接以授予这些权限。 5. **聊天** — 在由 gateway Web UI 驱动的实时聊天中与您的 agent 见面。 6. **准备就绪** — 总结可用功能，提供登录时启动的选项，以及一个完成按钮。 有关详细的设置说明，请参阅 [docs/SETUP.md](docs/SETUP.md)。有关完整的引导架构，请参阅 [docs/ONBOARDING_WIZARD.md](docs/ONBOARDING_WIZARD.md)。 ## 许可证 MIT 许可证 - 详见 [LICENSE](LICENSE) *前身为 Moltbot，原名为 Clawdbot*

标签：AI助手配套, AI合规, Windows桌面应用, WinUI 3, 系统托盘工具