From 989129c5bb1473481d91ee94b6c30244e2a2f2cf Mon Sep 17 00:00:00 2001 From: Samantha Song Date: Mon, 3 Aug 2026 16:36:04 -0700 Subject: [PATCH 1/6] docs: clean up README to match main repo polish - Remove outdated screenshots (will add fresh ones separately) - Add badge row (CI, .NET, license, Discord) - Condense intro to one punchy sentence - Add quick-links row and install table - Replace verbose feature lists with concise grid - Move Mac parity table, Quick Send troubleshooting, node capabilities reference, deep links table, and Command Center diagnostics to linked docs - Keep essential dev workflow: setup, build, run, test - Add Documentation links table - Consistent structure: Install > Features > Projects > Dev > Config > Docs > License Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 049e0978-76d3-4105-82c7-898a2fd7f4fd --- README.md | 483 +++--------------- .../Windows/HubWindow.xaml | 3 + .../Windows/HubWindow.xaml.cs | 1 + 3 files changed, 89 insertions(+), 398 deletions(-) diff --git a/README.md b/README.md index 5b39cb96d..db9136b30 100644 --- a/README.md +++ b/README.md @@ -1,441 +1,128 @@ -# 🦞 OpenClaw Windows Hub +# OpenClaw Windows Companion ![OpenClaw Windows Node banner](docs/assets/readme-banner.jpg) -A native Windows companion suite for [OpenClaw](https://openclaw.ai) - the AI-powered personal assistant. +[![CI](https://img.shields.io/github/actions/workflow/status/openclaw/openclaw-windows-node/ci.yml?branch=main&style=flat-square&label=ci)](https://github.com/openclaw/openclaw-windows-node/actions/workflows/ci.yml) +[![.NET](https://img.shields.io/badge/.NET-10.0-512bd4?style=flat-square)](https://dotnet.microsoft.com/download/dotnet/10.0) +[![License: MIT](https://img.shields.io/badge/license-MIT-green?style=flat-square)](LICENSE) +[![Discord](https://img.shields.io/discord/1456350064065904867?label=discord&logo=discord&logoColor=white&color=5865F2&style=flat-square)](https://discord.gg/clawd) -*Made with 🦞 love by Scott Hanselman and Molty* +The native **Windows Hub** companion app for [OpenClaw](https://github.com/openclaw/openclaw). A desktop app with setup, tray status, chat, Command Center diagnostics, and Windows node capabilities. When connected to your gateway, the agent can act on your PC β€” running commands, capturing your screen, presenting UI, speaking aloud β€” all permission-gated and sandboxed. -![OpenClaw Windows Hub tray menu](docs/images/openclawwindows1.png) +[Download](https://docs.openclaw.ai/platforms/windows) Β· [Docs](https://docs.openclaw.ai/platforms/windows) Β· [Setup Guide](docs/SETUP.md) Β· [Discord](https://discord.gg/clawd) -![OpenClaw Windows Hub command center](docs/images/openclawwindows2.png) - -![OpenClaw Windows Hub pairing and connection settings](docs/images/openclawwindows3.png) +--- -![OpenClaw Windows Hub activity and diagnostics](docs/images/openclawwindows4.png) +## Install -## Projects +| Architecture | Installer | +|---|---| +| x64 | [OpenClawCompanion-Setup-x64.exe](https://github.com/openclaw/openclaw-windows-node/releases/latest/download/OpenClawCompanion-Setup-x64.exe) | +| ARM64 | [OpenClawCompanion-Setup-arm64.exe](https://github.com/openclaw/openclaw-windows-node/releases/latest/download/OpenClawCompanion-Setup-arm64.exe) | -This monorepo contains the Windows hub, shared client libraries, and CLI utilities: +[Checksums](https://github.com/openclaw/openclaw-windows-node/releases/latest/download/OpenClawCompanion-SHA256SUMS.txt) Β· Windows 10 20H2+ or Windows 11 Β· No build required. -| Project | Description | -|---------|-------------| -| **OpenClaw.Tray.WinUI** | System tray application (WinUI 3) for quick access to OpenClaw | -| **OpenClaw.Connection** | Gateway registry, credential resolution, and connection manager | -| **OpenClaw.Shared** | Shared gateway client library, capabilities, and MCP bridge | -| **OpenClaw.Chat** | Native chat model and timeline reducer | -| **OpenClaw.Cli** | CLI validator for WebSocket connect/send/probe using tray settings | -| **OpenClaw.WinNode.Cli** | `winnode` CLI for invoking local Windows node/MCP capabilities | -| **OpenClaw.SetupEngine** | Local gateway setup, WSL installation, and setup-code support | -| **OpenClaw.SetupEngine.UI** | WinUI setup wizard pages hosted by the tray app | -| **OpenClawTray.FunctionalUI** | In-repo declarative WinUI helper used by native chat and newer UI surfaces | +On first launch, a setup wizard walks you through connecting to an existing gateway or installing one locally in WSL. -## πŸš€ Quick Start +--- -> **End-user installer?** Download the latest stable x64 or ARM64 installer from the [OpenClaw Windows docs](https://docs.openclaw.ai/platforms/windows), or see [docs/SETUP.md](docs/SETUP.md) for step-by-step installation (no build required). -> -> **Managed WSL gateway?** Local setup creates a locked-down app-owned `OpenClawGateway` distro. See [docs/WSL_GATEWAY_ADMIN.md](docs/WSL_GATEWAY_ADMIN.md) for editing `openclaw.json` as the `openclaw` user and using root for protected-file administration. -> -> **Operator or node?** Start with [Operator and node concepts](docs/OPERATOR_NODE_CONCEPTS.md) for the beginner-facing glossary of gateway, operator, node, pairing, reapproval, and allowlisted node capabilities. +## Node Mode -Direct downloads from the latest OpenClaw Windows release: +Once paired with your gateway, the agent can act on your PC through these capabilities: -- [OpenClawCompanion-Setup-x64.exe](https://github.com/openclaw/openclaw-windows-node/releases/latest/download/OpenClawCompanion-Setup-x64.exe) -- [OpenClawCompanion-Setup-arm64.exe](https://github.com/openclaw/openclaw-windows-node/releases/latest/download/OpenClawCompanion-Setup-arm64.exe) -- [OpenClawCompanion-SHA256SUMS.txt](https://github.com/openclaw/openclaw-windows-node/releases/latest/download/OpenClawCompanion-SHA256SUMS.txt) +| | What the agent can do | +|---|---| +| **Run commands** | Execute shell commands, scripts, and tools (`system.run`) | +| **Show things** | Toast notifications, WebView2 canvas windows, A2UI rendering | +| **See your screen** | Screenshots and short screen recordings | +| **Use your camera** | List cameras, take photos, record short clips | +| **Speak** | Text-to-speech via Windows SAPI or ElevenLabs | +| **Know context** | Device info, geolocation, microphone transcription | -### Prerequisites -- Windows 10 (20H2+) or Windows 11 -- .NET 10.0 SDK - https://dotnet.microsoft.com/download/dotnet/10.0 -- Node.js LTS with npm (for WinUI build assets) -- Windows 10 SDK (for WinUI build) - install via Visual Studio or standalone -- WebView2 Runtime - pre-installed on modern Windows, or get from https://developer.microsoft.com/microsoft-edge/webview2 +### Connect in 3 steps -### Developer / Agent Setup +1. **Enable Node Mode** in the app settings (on by default) +2. **Approve the device** on your gateway: `openclaw devices approve ` +3. **Allow capabilities** in your gateway's `allowCommands` config -Use the setup script to install or verify local Windows build prerequisites: +That's it. The agent can now use your PC. See [Node Concepts](docs/OPERATOR_NODE_CONCEPTS.md) for the full pairing and approval model, and [Windows Node Testing](docs/WINDOWS_NODE_TESTING.md) for the capabilities reference. -```powershell -# Install missing prerequisites with winget, trust the checkout, and verify setup -.\scripts\setup-dev.ps1 - -# Check only; do not install packages or change git safe.directory -.\scripts\setup-dev.ps1 -CheckOnly +--- -# Install/verify prerequisites without adding the checkout to git safe.directory -.\scripts\setup-dev.ps1 -NoTrustRepository +## Sandboxing -# Setup and run the required build/test validation -.\scripts\setup-dev.ps1 -RunValidation -``` +Every command the agent runs on your PC goes through **MXC process isolation**. You control what the sandbox allows: -### Build +- **Files** β€” per-folder grants (Documents, Downloads, Desktop, custom paths). SSH keys and browser profiles are always blocked. +- **Network** β€” internet on/off. LAN is always blocked. +- **Clipboard** β€” none, read, write, or both. +- **Limits** β€” per-command timeout and output cap. -Use the build script to check prerequisites and build: +Choose a preset (Locked Down, Recommended, Unprotected) or configure each control individually. See [Sandboxing docs](https://docs.openclaw.ai/gateway/sandboxing) for details. -```powershell -# Check prerequisites -.\build.ps1 -CheckOnly +--- -# Build all projects -.\build.ps1 +## Also included -# Build specific project -.\build.ps1 -Project WinUI -``` +- πŸ’¬ **Native chat** β€” WebView2 chat UI and Quick Send hotkey (Ctrl+Alt+Shift+C) +- 🧭 **Command Center** β€” diagnostics hub for sessions, nodes, channels, and usage +- πŸ”” **Toast notifications** β€” clickable Windows notifications with smart categorization +- πŸ”„ **Auto-updates** β€” background updates from GitHub Releases +- πŸ”— **Deep links** β€” `openclaw://` URL scheme for automation +- πŸ“‘ **Local MCP server** β€” Model Context Protocol endpoint for tool integration +- 🎯 **First-run setup** β€” guided WSL gateway install with permissions and onboarding -Or build directly with dotnet: +--- -```powershell -# Build all (use build.ps1 for best results) -dotnet build +## For contributors -# Build WinUI (requires runtime identifier for WebView2 support) -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 +### Projects -# Build MSIX package (for camera/mic consent prompts) -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 -``` +| Project | What it is | +|---|---| +| **OpenClaw.Tray.WinUI** | System tray app (WinUI 3) | +| **OpenClaw.Connection** | Gateway registry and connection manager | +| **OpenClaw.Shared** | Gateway client, capabilities, MCP bridge | +| **OpenClaw.Chat** | Chat model and timeline reducer | +| **OpenClaw.WinNode.Cli** | `winnode` CLI for local node/MCP invocation | +| **OpenClaw.SetupEngine** | WSL gateway setup and setup-code pairing | +| **OpenClaw.SetupEngine.UI** | WinUI setup wizard pages | +| **OpenClaw.Cli** | CLI WebSocket validator | +| **OpenClawTray.FunctionalUI** | Declarative WinUI helpers | -### Run Tray App +### Build and run ```powershell -# Build and launch the unpackaged WinUI tray app -.\run-app-local.ps1 - -# If you already built, skip rebuild and launch the existing Debug output -.\run-app-local.ps1 -NoBuild - -# Run isolated from your normal tray settings so multiple worktrees can run together -.\run-app-local.ps1 -Isolated - -# Opt into side-by-side dev identity (separate mutex, protocol, gateway distro, and port) -.\run-app-local.ps1 -Dev -Isolated - -# Alpha update testing from a Release build -.\run-app-local.ps1 -Configuration Release -Isolated -UpdateChannel alpha - -# Optional: launch through WinAppCLI with Package.appxmanifest -.\run-app-local.ps1 -UseWinApp -NoBuild +.\scripts\setup-dev.ps1 # One-time: install prerequisites +.\build.ps1 # Build all +.\run-app-local.ps1 # Build and launch +.\run-app-local.ps1 -Isolated # Separate settings per worktree ``` -The default path starts the unpackaged executable directly. `-UseWinApp` requires -Microsoft WinAppCLI (`winget install Microsoft.WinAppCLI`) and is only needed when -you want manifest/MSIX-adjacent launch validation. - -### Run CLI WebSocket Validator - -Use the CLI to validate gateway connectivity and `chat.send` outside the tray UI. +### Test ```powershell -# Show help -dotnet run --project src/OpenClaw.Cli -- --help - -# Use tray settings from %APPDATA%\OpenClawTray\settings.json and send one message -dotnet run --project src/OpenClaw.Cli -- --message "quick send validation" +dotnet test tests/OpenClaw.Shared.Tests +dotnet test tests/OpenClaw.Tray.Tests +``` -# Loop sends and also probe sessions/usage/nodes APIs -dotnet run --project src/OpenClaw.Cli -- --repeat 5 --delay-ms 1000 --probe-read --verbose +### Docs -# Override gateway URL/token for isolated testing -dotnet run --project src/OpenClaw.Cli -- --url ws://127.0.0.1:18789 --token "" --message "override test" -``` +| Topic | Link | +|---|---| +| Setup (no build required) | [docs/SETUP.md](docs/SETUP.md) | +| Operator and node concepts | [docs/OPERATOR_NODE_CONCEPTS.md](docs/OPERATOR_NODE_CONCEPTS.md) | +| Windows node testing | [docs/WINDOWS_NODE_TESTING.md](docs/WINDOWS_NODE_TESTING.md) | +| MCP mode | [docs/MCP_MODE.md](docs/MCP_MODE.md) | +| Connection architecture | [docs/CONNECTION_ARCHITECTURE.md](docs/CONNECTION_ARCHITECTURE.md) | +| Onboarding wizard | [docs/ONBOARDING_WIZARD.md](docs/ONBOARDING_WIZARD.md) | +| WSL gateway admin | [docs/WSL_GATEWAY_ADMIN.md](docs/WSL_GATEWAY_ADMIN.md) | +| Development | [DEVELOPMENT.md](DEVELOPMENT.md) | -## πŸ“¦ OpenClaw.Tray (Molty) - -Modern Windows 11-style system tray companion that connects to your local OpenClaw gateway. - -### Features -- 🎨 **OpenClaw branding** - OpenClaw tray icon with status colors -- 🎨 **Modern UI** - Windows 11 flyout menu with dark/light mode support -- πŸ’¬ **Quick Send** - Send messages via global hotkey (Ctrl+Alt+Shift+C) -- πŸ”„ **Auto-updates** - Automatic updates from GitHub Releases -- 🌐 **Web Chat** - Embedded chat window with WebView2 -- πŸ“Š **Live Status** - Real-time sessions, channels, and usage display -- 🧭 **Command Center** - Dense gateway, channel, usage, node, pairing, and allowlist diagnostics from one window -- ⚑ **Activity Stream** - Command Center page for live session, usage, node, and notification events -- πŸ”” **Toast Notifications** - Clickable Windows notifications with [smart categorization](docs/NOTIFICATION_CATEGORIZATION.md) -- πŸ“‘ **Channel Control** - Start/stop Telegram & WhatsApp from the menu -- πŸ–₯️ **Node Observability** - Node inventory with online/offline state and copyable summary -- ⏱ **Cron Jobs** - Quick access to scheduled tasks -- πŸš€ **Auto-start** - Launch with Windows -- βš™οΈ **Settings** - Full configuration page -- 🎯 **First-run onboarding** β€” native WSL gateway setup with capability, permission, install, onboard, and completion screens - -#### Quick Send scope requirement - -Quick Send uses the gateway `chat.send` method and requires the operator device to have `operator.write` scope. - -If Quick Send fails with `missing scope: operator.write`, Molty now copies identity + remediation guidance to your clipboard, including: - -- operator role and `client.id` used by the tray app -- gateway-reported operator device id (if provided) -- currently granted scopes (if provided) - -For this specific error (`missing scope: operator.write`), the cause is an **operator token scope issue**. Update the token used by the tray app so it includes `operator.write`, then retry Quick Send. - -If Quick Send fails with `pairing required` / `NOT_PAIRED`, that is a **device approval** issue. Approve the tray device in gateway pairing approvals, reconnect, and retry. - -### Menu Sections -- **Status** - Gateway connection status with click-to-view details -- **Command Center** - Hub with diagnostics, channel health, usage, sessions, nodes, and copyable repair commands -- **Sessions** - Active agent sessions with preview and per-session controls -- **Usage** - Provider/cost summary with quick jump to activity details -- **Channels** - Telegram/WhatsApp status with toggle control -- **Nodes** - Online/offline node inventory and copyable summary -- **Recent Activity** - Timestamped event stream for sessions, usage, nodes, and notifications -- **Actions** - Dashboard, Web Chat, Quick Send, Activity Stream, History -- **Support & Debug** - Logs, config, diagnostics folder, redacted support context, browser setup, port/capability/node/channel/activity summaries, and managed SSH tunnel restart -- **Settings** - Configuration and auto-start - -### Mac Parity Status - -Comparing against [openclaw-menubar](https://github.com/magimetal/openclaw-menubar) (macOS Swift menu bar app): - -| Feature | Mac | Windows | Notes | -|---------|-----|---------|-------| -| Menu bar/tray icon | βœ… | βœ… | Color-coded status | -| Gateway status display | βœ… | βœ… | Connected/Disconnected | -| PID display | βœ… | βœ… | Command Center shows gateway listener process/PID | -| Channel status | βœ… | βœ… | Mac: Discord / Win: Telegram+WhatsApp | -| Sessions count | βœ… | βœ… | | -| Last check timestamp | βœ… | βœ… | Shown in tray tooltip | -| Gateway start/stop/restart | βœ… | ⚠️ | Windows can restart the managed SSH tunnel from tray Support & Debug and Command Center; external gateway process control is not implemented | -| View Logs | βœ… | βœ… | | -| Open Web UI | βœ… | βœ… | | -| Refresh | βœ… | βœ… | Auto-refresh on menu open | -| Launch at Login | βœ… | βœ… | | -| Notifications toggle | βœ… | βœ… | | - -### Windows-Only Features - -These features are available in Windows but not in the Mac app: - -| Feature | Description | -|---------|-------------| -| Quick Send hotkey | Ctrl+Alt+Shift+C global hotkey | -| Embedded Web Chat | WebView2-based chat window | -| Toast notifications | Clickable Windows notifications | -| Channel control | Start/stop Telegram & WhatsApp | -| Modern flyout menu | Windows 11-style with dark/light mode | -| Deep links | `openclaw://` URL scheme with IPC | -| First-run onboarding | Native setup flow: Security notice β†’ Welcome/Advanced β†’ Capabilities and permissions β†’ Install progress β†’ OpenClaw onboard β†’ Complete | - -### πŸ”Œ Node Mode (Agent Control) - -If the operator/node split is new to you, read [Operator and node concepts](docs/OPERATOR_NODE_CONCEPTS.md) before enabling Node Mode. - -When Node Mode is enabled in Settings, your Windows PC becomes a **node** that the OpenClaw agent can control - just like the Mac app! The agent can: - -| Capability | Commands | Description | -|------------|----------|-------------| -| **System** | `system.notify`, `system.run`, `system.run.prepare`, `system.which`, `system.execApprovals.get`, `system.execApprovals.set` | Show Windows toast notifications, execute commands with policy controls | -| **Canvas** | `canvas.present`, `canvas.hide`, `canvas.navigate`, `canvas.eval`, `canvas.snapshot`, `canvas.a2ui.push`, `canvas.a2ui.pushJSONL`, `canvas.a2ui.reset` | Display and control a WebView2 window | -| **Screen** | `screen.snapshot`, `screen.record` | Capture screenshots and fixed-duration MP4 screen recordings | -| **Camera** | `camera.list`, `camera.snap`, `camera.clip` | Enumerate cameras and capture still photos or short video clips | -| **Speech-to-text** | `stt.transcribe` | Capture audio from the default microphone for a bounded duration and return transcribed text. Default-off; opt-in via Settings. When enabled, advertised to both gateway callers (subject to gateway allowlist) and local MCP clients (subject to bearer token). | -| **Location** | `location.get` | Return Windows geolocation when permission is available | -| **Device** | `device.info`, `device.status` | Return Windows host/app metadata and lightweight status | -| **Text-to-speech** | `tts.speak` | Speak text aloud through Windows speech synthesis, or ElevenLabs when configured | - -Packaged installs declare camera, microphone, and location capabilities. Windows may ask for consent the first time a node capability uses one of those protected resources. - -#### Node Setup - -1. **Enable Node Mode** in Settings (enabled by default) -2. **First connection** creates a pairing request on the gateway -3. **Approve the device** on your gateway: - ```bash - openclaw devices list # Find your Windows device - openclaw devices approve # Approve it - ``` -4. **Configure gateway allowCommands** - Add the commands you want to allow under `gateway.nodes` in `~/.openclaw/openclaw.json`: - ```json - { - "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" - ] - } - } - } - ``` - > ⚠️ **Important**: The gateway has a server-side allowlist. Commands must be listed explicitly - wildcards like `canvas.*` don't work! Privacy-sensitive commands such as `screen.record` and agent-driven audio playback via `tts.speak` should only be added to `allowCommands` when you explicitly want to allow them. - -5. **Test it** from your Mac/gateway: - ```bash - # Show a notification - openclaw nodes notify --node --title "Hello" --body "From Mac!" - - # Open a canvas window - openclaw nodes canvas present --node --url "https://example.com" - - # Execute JavaScript (note: CLI sends "javaScript" param) - openclaw nodes canvas eval --node --javaScript "document.title" - - # Render A2UI JSONL in the canvas (pass the file contents as a string) - openclaw nodes canvas a2ui push --node --jsonl "$(cat ./ui.jsonl)" - - # Take a screenshot - openclaw nodes invoke --node --command screen.snapshot --params '{"screenIndex":0,"format":"png"}' - - # Record a short screen clip (requires explicitly allowing screen.record on the gateway) - openclaw nodes screen record --node --duration 3000 --fps 10 --screen 0 --no-audio --out /tmp/openclaw-windows-screen-record-test.mp4 --json - - # List cameras - openclaw nodes invoke --node --command camera.list - - # Take a photo (NV12/MediaCapture fallback) - openclaw nodes invoke --node --command camera.snap --params '{"deviceId":"","format":"jpeg","quality":80}' - - # Speak text aloud on the Windows node (requires TTS enabled in Settings and tts.speak allowed on the gateway) - openclaw nodes invoke --node --command tts.speak --params '{"text":"Hello from OpenClaw","provider":"windows"}' - - # Execute a command on the Windows node (raw node.invoke requires canonical argv) - openclaw gateway call node.invoke --params '{"nodeId":"","command":"system.run","params":{"command":["cmd.exe","/d","/s","/c","echo hello"],"rawCommand":"echo hello","timeoutMs":10000}}' --json - - # View exec approval policy - openclaw nodes invoke --node --command system.execApprovals.get - - # Update exec approvals using baseHash from the preceding get response - openclaw nodes invoke --node --command system.execApprovals.set --params '{"baseHash":"","file":{"version":1,"defaults":{"security":"allowlist","ask":"on-miss","askFallback":"deny","autoAllowSkills":false},"agents":{"main":{"security":"allowlist","ask":"on-miss","askFallback":"deny","autoAllowSkills":false,"allowlist":[]}}}}' - ``` - > πŸ“· **Camera permission**: Desktop builds rely on Windows Privacy settings. Packaged MSIX builds will show the system consent prompt. - - > πŸ”’ **Exec approvals**: `system.run` is gated by the V2 approval coordinator and `%APPDATA%\OpenClawTray\exec-approvals.json`. The file uses the same `defaults`/`agents`/`allowlist` model as the macOS node host. `system.execApprovals.set` requires the current `baseHash` and rejects stale or unsafe remote updates. - > - > Allowlist rules match resolved executable paths, using path-aware wildcards such as `**/git.exe`. Script interpreters and command hosts cannot receive reusable grants. Non-empty custom environments are rejected until they can be identity-bound and displayed safely. - > - > **V2 caller migration**: raw MCP, direct `node.invoke`, plugin, and `winnode` callers must replace string-form `{"command":"echo hello","shell":"cmd"}` with canonical `{"command":["cmd.exe","/d","/s","/c","echo hello"],"rawCommand":"echo hello"}`. The normal gateway `exec host=node` path already performs this wrapping. Remove custom `env`; non-empty environments are rejected. - -#### Command Center diagnostics - -Open the status detail/Command Center from the tray menu or with `openclaw://commandcenter`. It shows: - -- channel health from gateway `health` events, including node-mode health received without a separate operator connection -- active sessions, usage/cost data, node inventory, declared commands, and Mac parity notes -- allowlist diagnostics that separate safe companion commands from privacy-sensitive opt-ins like `screen.record`, `camera.snap`, and `camera.clip` -- copyable repair commands for safe allowlist fixes and pending pairing approval -- recent activity and node invoke results through the Activity Stream, storing command names/status/duration only (not payloads, screenshots, recordings, or secrets) - > - > ```bash - > openclaw nodes invoke --node --command system.execApprovals.set --params '{"baseHash":"","file":{"version":1,"defaults":{"security":"allowlist","ask":"off","askFallback":"deny","autoAllowSkills":false},"agents":{"main":{"security":"allowlist","ask":"off","askFallback":"deny","autoAllowSkills":false,"allowlist":[]}}}}' - > ``` - - > πŸ” **Web Chat secure context**: Remote web chat requires `https://` (or localhost). If using a self-signed cert, trust it in Windows (Trusted Root Certification Authorities) or use an SSH tunnel to localhost. - -#### Node Status in Tray Menu - -The tray menu shows node connection status: -- **πŸ”Œ Node Mode** section appears when enabled -- **⏳ Waiting for approval...** - Device needs approval on gateway -- **βœ… Paired & Connected** - Ready to receive commands -- Click the device ID to copy it for the approval command - -### Deep Links - -OpenClaw registers the `openclaw://` URL scheme for automation and integration: - -| Link | Description | -|------|-------------| -| `openclaw://settings` | Open the Settings page | -| `openclaw://setup` | Open Setup Wizard | -| `openclaw://chat` | Open the Chat page | -| `openclaw://commandcenter` | Open Command Center diagnostics | -| `openclaw://activity` | Open the Activity page | -| `openclaw://history` | Open the Activity page filtered to notification history | -| `openclaw://dashboard` | Open Dashboard in browser | -| `openclaw://dashboard/sessions` | Open specific dashboard page | -| `openclaw://dashboard/channels` | Open Channels dashboard page | -| `openclaw://dashboard/skills` | Open Skills dashboard page | -| `openclaw://dashboard/cron` | Open Cron dashboard page | -| `openclaw://healthcheck` | Run a manual health check | -| `openclaw://check-updates` | Run a manual update check | -| `openclaw://logs` | Open the current tray log file | -| `openclaw://log-folder` | Open the logs folder | -| `openclaw://config` | Open the config folder | -| `openclaw://diagnostics` | Open the diagnostics JSONL folder | -| `openclaw://support-context` | Copy redacted support context | -| `openclaw://debug-bundle` | Copy a combined debug bundle for support | -| `openclaw://browser-setup` | Copy browser.proxy/browser-control setup guidance | -| `openclaw://port-diagnostics` | Copy gateway/browser/tunnel port diagnostics with owner PID stop hints | -| `openclaw://capability-diagnostics` | Copy permissions, allowlist, and parity diagnostics | -| `openclaw://node-inventory` | Copy node capabilities, commands, and policy status | -| `openclaw://channel-summary` | Copy channel health and start/stop availability | -| `openclaw://activity-summary` | Copy recent tray activity for troubleshooting | -| `openclaw://extensibility-summary` | Copy channel, skills, and cron dashboard surface guidance | -| `openclaw://restart-ssh-tunnel` | Restart the tray-managed SSH tunnel when enabled | -| `openclaw://send?message=Hello` | Open Quick Send with pre-filled text | -| `openclaw://agent?message=Hello` | Send message directly to the connected gateway | - -Deep links work even when Molty is already running - they're forwarded via IPC. - -## πŸ“¦ OpenClaw.Shared - -Shared library containing: -- `OpenClawGatewayClient` - WebSocket client for gateway protocol -- `IOpenClawLogger` - Logging interface -- Data models (SessionInfo, ChannelHealth, etc.) -- Channel control (start/stop channels via gateway) - -## Development - -### Project Structure - -See [DEVELOPMENT.md](DEVELOPMENT.md#project-structure) for the complete and current `src/` and `tests/` project inventory. - -### Configuration - -Settings are stored in: -- Settings: `%APPDATA%\OpenClawTray\settings.json` -- Logs: `%LOCALAPPDATA%\OpenClawTray\openclaw-tray.log` -- Easy-button setup summary: `%LOCALAPPDATA%\OpenClawTray\Logs\Setup\easy-setup-latest.txt` -- Easy-button setup JSONL: `%LOCALAPPDATA%\OpenClawTray\Logs\Setup\easy-setup-latest.jsonl` - -Default gateway: `ws://localhost:18789` - -### First Run - -On first run, Molty launches a guided setup flow: - -1. **Security notice** β€” confirms this is a trusted PC before local setup starts. -2. **Welcome** β€” choose **Install a local gateway (WSL)** or connect to an existing gateway from Connections. -3. **Capabilities** β€” choose a profile, review matching Windows permission status, and see exactly what setup will install. -4. **Progress** β€” installs the app-owned `OpenClawGateway` WSL instance and keeps Live activity available but collapsed by default. -5. **Gateway installed** β€” confirms the WSL gateway is running before moving into OpenClaw onboard. -6. **OpenClaw onboard** β€” gateway-driven provider/model/key setup rendered as a transcript. -7. **All set** β€” summary of available features, startup preference, and Finish. - -For detailed setup instructions, see [docs/SETUP.md](docs/SETUP.md). For the full onboarding architecture, see [docs/ONBOARDING_WIZARD.md](docs/ONBOARDING_WIZARD.md). +--- ## License -MIT License - see [LICENSE](LICENSE) - ---- +[MIT](LICENSE) -*Formerly known as Moltbot, formerly known as Clawdbot* +*Made with 🦞 by Scott Hanselman, Molty, and contributors* diff --git a/src/OpenClaw.Tray.WinUI/Windows/HubWindow.xaml b/src/OpenClaw.Tray.WinUI/Windows/HubWindow.xaml index aefd79884..31c5589b4 100644 --- a/src/OpenClaw.Tray.WinUI/Windows/HubWindow.xaml +++ b/src/OpenClaw.Tray.WinUI/Windows/HubWindow.xaml @@ -480,6 +480,9 @@ + + + diff --git a/src/OpenClaw.Tray.WinUI/Windows/HubWindow.xaml.cs b/src/OpenClaw.Tray.WinUI/Windows/HubWindow.xaml.cs index 550f847a6..a961b9661 100644 --- a/src/OpenClaw.Tray.WinUI/Windows/HubWindow.xaml.cs +++ b/src/OpenClaw.Tray.WinUI/Windows/HubWindow.xaml.cs @@ -1170,6 +1170,7 @@ public void SetActivityFilter(string? filter) "voice" => typeof(VoiceSettingsPage), "permissions" => typeof(PermissionsPage), "sandbox" => typeof(SandboxPage), + "sandbox-sessions" => typeof(SandboxSessionPrototypePage), // ActivityPage has been removed; legacy "activity"/"history" deep links // redirect to ChannelsPage via DeepLinkHandler. "activity" => typeof(ChannelsPage), From c04aebab2190dd25fa44fe2c75721db1e16368d6 Mon Sep 17 00:00:00 2001 From: Samantha Song Date: Mon, 3 Aug 2026 17:02:45 -0700 Subject: [PATCH 2/6] docs: tighten README based on critical review - Title: 'OpenClaw Windows Hub' (matches product name) - Intro: one sentence what-it-is, one what-it-does (no feature-list sentence) - Install: mention 'Set up locally' happy path - Step 3: concrete CLI example instead of vague config reference - 'Also included' -> 'Features' (proper header) - Docs table: split contributor-facing (table) from user-facing (inline links) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 049e0978-76d3-4105-82c7-898a2fd7f4fd --- README.md | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index db9136b30..5ab4d60fa 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# OpenClaw Windows Companion +# OpenClaw Windows Hub ![OpenClaw Windows Node banner](docs/assets/readme-banner.jpg) @@ -7,7 +7,7 @@ [![License: MIT](https://img.shields.io/badge/license-MIT-green?style=flat-square)](LICENSE) [![Discord](https://img.shields.io/discord/1456350064065904867?label=discord&logo=discord&logoColor=white&color=5865F2&style=flat-square)](https://discord.gg/clawd) -The native **Windows Hub** companion app for [OpenClaw](https://github.com/openclaw/openclaw). A desktop app with setup, tray status, chat, Command Center diagnostics, and Windows node capabilities. When connected to your gateway, the agent can act on your PC β€” running commands, capturing your screen, presenting UI, speaking aloud β€” all permission-gated and sandboxed. +The native Windows companion for [OpenClaw](https://github.com/openclaw/openclaw). Connect your PC to your gateway and let the agent run commands, capture your screen, present UI, and speak aloud, all permission-gated and sandboxed. [Download](https://docs.openclaw.ai/platforms/windows) Β· [Docs](https://docs.openclaw.ai/platforms/windows) Β· [Setup Guide](docs/SETUP.md) Β· [Discord](https://discord.gg/clawd) @@ -22,7 +22,7 @@ The native **Windows Hub** companion app for [OpenClaw](https://github.com/openc [Checksums](https://github.com/openclaw/openclaw-windows-node/releases/latest/download/OpenClawCompanion-SHA256SUMS.txt) Β· Windows 10 20H2+ or Windows 11 Β· No build required. -On first launch, a setup wizard walks you through connecting to an existing gateway or installing one locally in WSL. +On first launch, a setup wizard walks you through connecting to an existing gateway or installing one locally in WSL. No gateway yet? Choose "Set up locally" and the wizard handles everything. --- @@ -43,7 +43,7 @@ Once paired with your gateway, the agent can act on your PC through these capabi 1. **Enable Node Mode** in the app settings (on by default) 2. **Approve the device** on your gateway: `openclaw devices approve ` -3. **Allow capabilities** in your gateway's `allowCommands` config +3. **Allow capabilities** on your gateway: `openclaw nodes allow system.run canvas.present screen.capture` That's it. The agent can now use your PC. See [Node Concepts](docs/OPERATOR_NODE_CONCEPTS.md) for the full pairing and approval model, and [Windows Node Testing](docs/WINDOWS_NODE_TESTING.md) for the capabilities reference. @@ -62,7 +62,7 @@ Choose a preset (Locked Down, Recommended, Unprotected) or configure each contro --- -## Also included +## Features - πŸ’¬ **Native chat** β€” WebView2 chat UI and Quick Send hotkey (Ctrl+Alt+Shift+C) - 🧭 **Command Center** β€” diagnostics hub for sessions, nodes, channels, and usage @@ -110,15 +110,13 @@ dotnet test tests/OpenClaw.Tray.Tests | Topic | Link | |---|---| -| Setup (no build required) | [docs/SETUP.md](docs/SETUP.md) | -| Operator and node concepts | [docs/OPERATOR_NODE_CONCEPTS.md](docs/OPERATOR_NODE_CONCEPTS.md) | -| Windows node testing | [docs/WINDOWS_NODE_TESTING.md](docs/WINDOWS_NODE_TESTING.md) | -| MCP mode | [docs/MCP_MODE.md](docs/MCP_MODE.md) | | Connection architecture | [docs/CONNECTION_ARCHITECTURE.md](docs/CONNECTION_ARCHITECTURE.md) | | Onboarding wizard | [docs/ONBOARDING_WIZARD.md](docs/ONBOARDING_WIZARD.md) | | WSL gateway admin | [docs/WSL_GATEWAY_ADMIN.md](docs/WSL_GATEWAY_ADMIN.md) | | Development | [DEVELOPMENT.md](DEVELOPMENT.md) | +**User-facing docs** (also linked above): [Setup](docs/SETUP.md) Β· [Node Concepts](docs/OPERATOR_NODE_CONCEPTS.md) Β· [Windows Node Testing](docs/WINDOWS_NODE_TESTING.md) Β· [MCP Mode](docs/MCP_MODE.md) + --- ## License From 963fe968c8dcafffd4f6c9bae5b7c9c2513d9970 Mon Sep 17 00:00:00 2001 From: Samantha Song Date: Mon, 3 Aug 2026 17:04:33 -0700 Subject: [PATCH 3/6] docs: restore build/run flags that contributors actually need Bring back setup-dev.ps1 flags, build.ps1 -Project, dotnet build with RID (WebView2 gotcha), run-app-local.ps1 -NoBuild/-Dev/-Isolated, and MSIX build command. Organized into Prerequisites/Build/Run/Test subsections instead of one dense block. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 049e0978-76d3-4105-82c7-898a2fd7f4fd --- README.md | 35 ++++++++++++++++++++++++++++++----- 1 file changed, 30 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 5ab4d60fa..d597e123d 100644 --- a/README.md +++ b/README.md @@ -90,13 +90,38 @@ Choose a preset (Locked Down, Recommended, Unprotected) or configure each contro | **OpenClaw.Cli** | CLI WebSocket validator | | **OpenClawTray.FunctionalUI** | Declarative WinUI helpers | -### Build and run +### Prerequisites ```powershell -.\scripts\setup-dev.ps1 # One-time: install prerequisites -.\build.ps1 # Build all -.\run-app-local.ps1 # Build and launch -.\run-app-local.ps1 -Isolated # Separate settings per worktree +.\scripts\setup-dev.ps1 # Install missing prerequisites (winget, .NET, etc.) +.\scripts\setup-dev.ps1 -CheckOnly # Verify without installing +.\scripts\setup-dev.ps1 -RunValidation # Install + run full build/test validation +``` + +### Build + +```powershell +.\build.ps1 # Build all projects +.\build.ps1 -Project WinUI # Build only the tray app +.\build.ps1 -CheckOnly # Check prerequisites without building +``` + +Or build directly with `dotnet` (note: WinUI requires a runtime identifier): + +```powershell +dotnet build src/OpenClaw.Tray.WinUI -r win-x64 # x64 +dotnet build src/OpenClaw.Tray.WinUI -r win-arm64 # ARM64 +dotnet build src/OpenClaw.Tray.WinUI -r win-x64 -p:PackageMsix=true # MSIX package +``` + +### Run + +```powershell +.\run-app-local.ps1 # Build and launch +.\run-app-local.ps1 -NoBuild # Launch existing build (skip rebuild) +.\run-app-local.ps1 -Isolated # Separate settings per worktree +.\run-app-local.ps1 -Dev -Isolated # Side-by-side dev identity (own mutex, port, distro) +.\run-app-local.ps1 -Configuration Release -Isolated -UpdateChannel alpha # Test updates ``` ### Test From bab0125c09cdcf91422e1788fab614b5c75f14f1 Mon Sep 17 00:00:00 2001 From: Samantha Song Date: Mon, 3 Aug 2026 17:10:51 -0700 Subject: [PATCH 4/6] docs: restore user-facing setup detail that people actually need - Node Mode: expand to 4 steps with actual allowCommands JSON config - Add privacy warning (no wildcards, screen.record/camera are opt-in) - Add verify step with test commands from gateway side - Add Deep Links table (key links, not all 30+) - Add File Paths table (settings, logs, gateways, exec-approvals) - Link MCP Mode doc from features list Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 049e0978-76d3-4105-82c7-898a2fd7f4fd --- README.md | 74 ++++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 65 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index d597e123d..f8d361779 100644 --- a/README.md +++ b/README.md @@ -39,13 +39,41 @@ Once paired with your gateway, the agent can act on your PC through these capabi | **Speak** | Text-to-speech via Windows SAPI or ElevenLabs | | **Know context** | Device info, geolocation, microphone transcription | -### Connect in 3 steps - -1. **Enable Node Mode** in the app settings (on by default) -2. **Approve the device** on your gateway: `openclaw devices approve ` -3. **Allow capabilities** on your gateway: `openclaw nodes allow system.run canvas.present screen.capture` - -That's it. The agent can now use your PC. See [Node Concepts](docs/OPERATOR_NODE_CONCEPTS.md) for the full pairing and approval model, and [Windows Node Testing](docs/WINDOWS_NODE_TESTING.md) for the capabilities reference. +### Connect in 4 steps + +1. **Enable Node Mode** in Settings (on by default). +2. **Approve the device** on your gateway: + ```bash + openclaw devices list # Find your Windows device + openclaw devices approve # Approve it + ``` +3. **Allow capabilities** in your gateway config (`~/.openclaw/openclaw.json`): + ```json + { + "gateway": { + "nodes": { + "allowCommands": [ + "system.notify", + "system.run", + "canvas.present", + "canvas.hide", + "screen.snapshot", + "device.info", + "tts.speak" + ] + } + } + } + ``` + > Commands must be listed explicitly. Wildcards like `canvas.*` don't work. Privacy-sensitive commands (`screen.record`, `camera.snap`, `camera.clip`, `stt.transcribe`) should only be added when you explicitly want to allow them. + +4. **Verify from your gateway**: + ```bash + openclaw nodes notify --node --title "Hello" --body "From gateway!" + openclaw nodes invoke --node --command screen.snapshot --params '{"format":"png"}' + ``` + +See [Node Concepts](docs/OPERATOR_NODE_CONCEPTS.md) for the full pairing and approval model, and [Windows Node Testing](docs/WINDOWS_NODE_TESTING.md) for the complete capabilities reference and test commands. --- @@ -68,10 +96,38 @@ Choose a preset (Locked Down, Recommended, Unprotected) or configure each contro - 🧭 **Command Center** β€” diagnostics hub for sessions, nodes, channels, and usage - πŸ”” **Toast notifications** β€” clickable Windows notifications with smart categorization - πŸ”„ **Auto-updates** β€” background updates from GitHub Releases -- πŸ”— **Deep links** β€” `openclaw://` URL scheme for automation -- πŸ“‘ **Local MCP server** β€” Model Context Protocol endpoint for tool integration +- πŸ”— **Deep links** β€” `openclaw://` URL scheme for automation (see below) +- πŸ“‘ **Local MCP server** β€” Model Context Protocol endpoint for tool integration ([MCP Mode](docs/MCP_MODE.md)) - 🎯 **First-run setup** β€” guided WSL gateway install with permissions and onboarding +### Deep links + +The app registers `openclaw://` for automation. Key links: + +| Link | What it does | +|---|---| +| `openclaw://settings` | Open Settings | +| `openclaw://setup` | Open Setup Wizard | +| `openclaw://chat` | Open Chat | +| `openclaw://commandcenter` | Open Command Center diagnostics | +| `openclaw://send?message=Hello` | Quick Send with pre-filled text | +| `openclaw://logs` | Open current log file | +| `openclaw://support-context` | Copy redacted support context | +| `openclaw://capability-diagnostics` | Copy permissions and allowlist diagnostics | + +Deep links work when the app is already running (forwarded via IPC). + +### File paths + +| What | Where | +|---|---| +| Settings | `%APPDATA%\OpenClawTray\settings.json` | +| Gateway registry | `%APPDATA%\OpenClawTray\gateways.json` | +| Logs | `%LOCALAPPDATA%\OpenClawTray\openclaw-tray.log` | +| Exec approvals | `%APPDATA%\OpenClawTray\exec-approvals.json` | + +Default gateway: `ws://localhost:18789` + --- ## For contributors From 6f61a7a3a1cbf716d43d63bc40a6261e58fa15c7 Mon Sep 17 00:00:00 2001 From: Samantha Song Date: Wed, 5 Aug 2026 13:44:08 -0700 Subject: [PATCH 5/6] docs: add OpenClaw bot icon to README title Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 049e0978-76d3-4105-82c7-898a2fd7f4fd --- README.md | 2 +- docs/assets/openclaw-icon.png | Bin 0 -> 2120 bytes 2 files changed, 1 insertion(+), 1 deletion(-) create mode 100644 docs/assets/openclaw-icon.png diff --git a/README.md b/README.md index f8d361779..17a7f1b5d 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# OpenClaw Windows Hub +# OpenClaw OpenClaw Windows Hub ![OpenClaw Windows Node banner](docs/assets/readme-banner.jpg) diff --git a/docs/assets/openclaw-icon.png b/docs/assets/openclaw-icon.png new file mode 100644 index 0000000000000000000000000000000000000000..f7ad456112092a7b6f990bb04995ca4dd059d86c GIT binary patch literal 2120 zcmV-O2)Fl%P)#nb(I&B1G$mE{@>j!}MpWnUWyJxL`*9Gat7yVSPU9+iBtDlEBfjEcvfFpoB z5~ar3+LzRu6F2>1@4kQjb)kOG1n_zt7#}*$@jK$c!HpZXp3!J-3*UEv5@$)Yz{)!> z)Kr-O$iR+tpp@2OfX3K34i(G~E*v}jMG#9il~N~$Uxr@prKBNeuTqHa_}ruCtX(st zSNBsgTX9J}A`K{It<}a_SYugf3k97f2{meUkDij>(ARr+bnR77jXwT(2NYD!tG5dP z<+2tQM_cZAs5Cx#XHuE>WQ;L3usR4d84b>v(n8w?4P^tZlr{{QTD{>*Q*$@2erD&B zqDis290+~F?%NWI?!D`l(%ATxcx)^qYjmJBl3Eprn+UDVS2B4pQEtBgpgCWG&Jq+P z+YD2gnodiT)7MvTzW$rJEX(B+{OP3+gM))wv^;^X7-mKo$6*g04t?5{@{zWQ3++c$tw5DLujKrlZs?ZfHW`{uuX>$}A^i;v|1 zaJg)@?b>BTtA$th+*Uj~y*gfK5HWNCj7KXq45uE?)gyd+;wW^IfQaCkV3Pz7HWIwl zS;Eg|=de9aQP2uZtdcn8@MtB}2gbMLbzo@7EUk`qk#z0KA9IIn-#O49O03# zDsz5<;o+7~fE5oyt07SR^Pl}pN3-z-7bl(B=%J0-K$0<kXHoH-v-jB~jiONRSULR6k9jLg zVFGG5-Ec$q)a=u69@k%&tWXLiUx4!jWi)i|`K_9o17Oab=ADLG5y*&7PZ7eb>qHJ~y{N;OW*-;x9$3@lRb^H6IrNU6M%$etza z#}p(WBnl!uW;iBzVmKni0QN=;=rIOtj8B~-=Y24x@q7+o5YVqoPj8>5q9L zyxNR0&x}iyLX#MQ61`HpPq)&LyBA7G5Cn`kUIammln71X6ck?f4z+3(7lxsUiOo@_ z-_3S*KG0Ueu}xt+%oU{|7#P$1!vW&nO`V-wvPRi<_^ptRIA72*Eg}#Ek`^gE+zLMt z95W(Mn9m&Vb(xB+iOwXt+Yya_&HLXkR&TXf2ilv-#}g}8{<;t+*Q^Nw-z^H{-(7pz)a3LX;M;$vyl z)d|h0eQNn-Z{M?l%Qh3>N=94hw^BdlxkeF{dxK%Ll0 z5if+DaFED*`N)IA^~&m;Z^hWoBmp z8yYj$+o7+yX|BF|x$|IKNXw$4oq)NnTK!9=)JGEF<&4NqImfd^m?Oe05zP_#_C+Gw zijdBG_6!>s^GZ)xxJ;ajt>v7bGy;o57JjO&xW|gcFVAOwd(32vRw|HVk5Vn^@#4;j zt=2pc1oz!@@x|Nac)r92{;NajAYg|i!kahu{QOV5kBrB0=fN!Hl=gLrXd+;Inr{&vy zFgKo4?6|Z)2r?1N-z!-^fSDz2alg^3 z3kaIdRZ|ns2}c*#{x5zTDlzyi;QS6_HthF)atE+`>Gy9~`{5quRny+@`yMc|wAlP# y5A{waOXrldy#es>am*IB?`!v`ll=@^Zu}em3B^4gR2#wo0000 Date: Wed, 5 Aug 2026 17:30:19 -0700 Subject: [PATCH 6/6] docs: make Windows README app-first Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- README.md | 274 +++++++++--------- docs/assets/openclaw-icon.png | Bin 2120 -> 0 bytes .../Windows/HubWindow.xaml | 3 - .../Windows/HubWindow.xaml.cs | 1 - 4 files changed, 145 insertions(+), 133 deletions(-) delete mode 100644 docs/assets/openclaw-icon.png diff --git a/README.md b/README.md index 17a7f1b5d..2498e9939 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# OpenClaw OpenClaw Windows Hub +# OpenClaw Windows Hub ![OpenClaw Windows Node banner](docs/assets/readme-banner.jpg) @@ -7,11 +7,9 @@ [![License: MIT](https://img.shields.io/badge/license-MIT-green?style=flat-square)](LICENSE) [![Discord](https://img.shields.io/discord/1456350064065904867?label=discord&logo=discord&logoColor=white&color=5865F2&style=flat-square)](https://discord.gg/clawd) -The native Windows companion for [OpenClaw](https://github.com/openclaw/openclaw). Connect your PC to your gateway and let the agent run commands, capture your screen, present UI, and speak aloud, all permission-gated and sandboxed. +The native Windows companion for [OpenClaw](https://github.com/openclaw/openclaw). Connect your PC to a gateway, chat with your agents, and choose which Windows capabilities they can use. -[Download](https://docs.openclaw.ai/platforms/windows) Β· [Docs](https://docs.openclaw.ai/platforms/windows) Β· [Setup Guide](docs/SETUP.md) Β· [Discord](https://discord.gg/clawd) - ---- +[Download](https://docs.openclaw.ai/platforms/windows) | [Setup guide](docs/SETUP.md) | [Windows docs](https://docs.openclaw.ai/platforms/windows) | [Discord](https://discord.gg/clawd) ## Install @@ -20,188 +18,206 @@ The native Windows companion for [OpenClaw](https://github.com/openclaw/openclaw | x64 | [OpenClawCompanion-Setup-x64.exe](https://github.com/openclaw/openclaw-windows-node/releases/latest/download/OpenClawCompanion-Setup-x64.exe) | | ARM64 | [OpenClawCompanion-Setup-arm64.exe](https://github.com/openclaw/openclaw-windows-node/releases/latest/download/OpenClawCompanion-Setup-arm64.exe) | -[Checksums](https://github.com/openclaw/openclaw-windows-node/releases/latest/download/OpenClawCompanion-SHA256SUMS.txt) Β· Windows 10 20H2+ or Windows 11 Β· No build required. +Requires Windows 10 20H2 or later, or Windows 11. No source build is required. + +On first launch, the setup wizard can install a dedicated local gateway in WSL or connect OpenClaw Companion to an existing gateway. If you do not have a gateway yet, choose **Install a local gateway (WSL)**. + +## πŸ”Œ Node mode (agent control) -On first launch, a setup wizard walks you through connecting to an existing gateway or installing one locally in WSL. No gateway yet? Choose "Set up locally" and the wizard handles everything. +Use OpenClaw Companion for normal setup. You should not need to edit `openclaw.json` by hand. ---- +1. Open **Companion Settings…** from the tray menu. +2. Open **Connection** and connect to your gateway. Complete any pending pairing approval shown by the app. +3. Open **Sandbox** and choose how agent-run programs should be contained. +4. Open **Permissions** and turn on **Node mode**. +5. Choose the capabilities this PC should offer. Changes save automatically. +6. Open **Command Center** to verify the node is connected and to resolve any gateway allowlist or reapproval warnings. -## Node Mode +Node mode registers this PC as a node and advertises only the capabilities enabled in **Permissions**. Gateway policy and local Windows checks can still block a capability. -Once paired with your gateway, the agent can act on your PC through these capabilities: +### Capabilities -| | What the agent can do | +| Capability | What it lets agents do | |---|---| -| **Run commands** | Execute shell commands, scripts, and tools (`system.run`) | -| **Show things** | Toast notifications, WebView2 canvas windows, A2UI rendering | -| **See your screen** | Screenshots and short screen recordings | -| **Use your camera** | List cameras, take photos, record short clips | -| **Speak** | Text-to-speech via Windows SAPI or ElevenLabs | -| **Know context** | Device info, geolocation, microphone transcription | - -### Connect in 4 steps - -1. **Enable Node Mode** in Settings (on by default). -2. **Approve the device** on your gateway: - ```bash - openclaw devices list # Find your Windows device - openclaw devices approve # Approve it - ``` -3. **Allow capabilities** in your gateway config (`~/.openclaw/openclaw.json`): - ```json - { - "gateway": { - "nodes": { - "allowCommands": [ - "system.notify", - "system.run", - "canvas.present", - "canvas.hide", - "screen.snapshot", - "device.info", - "tts.speak" - ] - } - } - } - ``` - > Commands must be listed explicitly. Wildcards like `canvas.*` don't work. Privacy-sensitive commands (`screen.record`, `camera.snap`, `camera.clip`, `stt.transcribe`) should only be added when you explicitly want to allow them. - -4. **Verify from your gateway**: - ```bash - openclaw nodes notify --node --title "Hello" --body "From gateway!" - openclaw nodes invoke --node --command screen.snapshot --params '{"format":"png"}' - ``` - -See [Node Concepts](docs/OPERATOR_NODE_CONCEPTS.md) for the full pairing and approval model, and [Windows Node Testing](docs/WINDOWS_NODE_TESTING.md) for the complete capabilities reference and test commands. - ---- - -## Sandboxing - -Every command the agent runs on your PC goes through **MXC process isolation**. You control what the sandbox allows: - -- **Files** β€” per-folder grants (Documents, Downloads, Desktop, custom paths). SSH keys and browser profiles are always blocked. -- **Network** β€” internet on/off. LAN is always blocked. -- **Clipboard** β€” none, read, write, or both. -- **Limits** β€” per-command timeout and output cap. - -Choose a preset (Locked Down, Recommended, Unprotected) or configure each control individually. See [Sandboxing docs](https://docs.openclaw.ai/gateway/sandboxing) for details. - ---- +| **System tools** | Run shell commands and scripts, subject to local exec approvals and sandbox policy | +| **Browser control** | Drive a compatible Chromium browser on this PC | +| **Camera** | Capture still images and short camera clips | +| **Canvas** | Present and interact with visual content in a hosted window | +| **Screen capture** | Take screenshots and short screen recordings | +| **Location** | Read this PC's approximate location | +| **Text-to-speech** | Speak text aloud through this PC's speakers | +| **Speech-to-text** | Transcribe microphone audio locally | + +Notifications and basic device status are available when Node mode is active. Windows may request consent before camera, microphone, location, or screen features can run. + +Privacy-sensitive capabilities should stay off unless you intend to use them. This includes camera capture, screen recording, microphone transcription, spoken output, and command execution. + +### Gateway approvals and allowlists + +OpenClaw applies more than one trust check: + +- **Permissions** controls what this PC advertises. +- **Connection** shows pairing and reapproval requests. +- **Command Center** explains commands filtered by gateway policy and provides copyable repair commands for safe capabilities. +- **Advanced > Config** provides a schema-guided editor for the connected gateway's configuration. + +After changing gateway command policy, approve any `pending-reapproval` request shown by the app and reconnect the node. The app never silently opts into privacy-sensitive gateway commands. + +
+Advanced: externally managed gateway allowlist shape + +Use your gateway's supported configuration tools when OpenClaw Companion cannot manage that gateway. Preserve existing entries and add only the exact commands you need. Wildcards such as `canvas.*` are not expanded. + +```json +{ + "gateway": { + "nodes": { + "allowCommands": [ + "system.notify", + "canvas.present", + "canvas.hide", + "screen.snapshot", + "device.info", + "device.status" + ] + } + } +} +``` -## Features +Commands such as `system.run`, `system.run.prepare`, `system.which`, `screen.record`, `camera.snap`, `camera.clip`, `stt.transcribe`, and `tts.speak` require deliberate opt-in. Reapprove and reconnect the node after changing the effective command set. + +
+ +See [Operator and node concepts](docs/OPERATOR_NODE_CONCEPTS.md) for the pairing and trust model, and [Windows node testing](docs/WINDOWS_NODE_TESTING.md) for command-level reference material. + +## Sandbox command execution + +The **Sandbox** page controls programs launched through the Windows node's `system.run` capability: + +- **Locked Down** blocks internet, clipboard, and standard user folders. +- **Recommended** enables internet, read-only access to common folders, and clipboard read access. +- **Unprotected** allows broad folder and clipboard access. Use it only when you accept the added risk. +- Custom controls set folder access, network access, clipboard access, timeout, and output limits. -- πŸ’¬ **Native chat** β€” WebView2 chat UI and Quick Send hotkey (Ctrl+Alt+Shift+C) -- 🧭 **Command Center** β€” diagnostics hub for sessions, nodes, channels, and usage -- πŸ”” **Toast notifications** β€” clickable Windows notifications with smart categorization -- πŸ”„ **Auto-updates** β€” background updates from GitHub Releases -- πŸ”— **Deep links** β€” `openclaw://` URL scheme for automation (see below) -- πŸ“‘ **Local MCP server** β€” Model Context Protocol endpoint for tool integration ([MCP Mode](docs/MCP_MODE.md)) -- 🎯 **First-run setup** β€” guided WSL gateway install with permissions and onboarding +When enabled and available, the Windows node uses MXC process isolation for `system.run`. If MXC is unavailable and strict fallback blocking is off, OpenClaw can fall back to uncontained host execution for compatibility. The **Sandbox** page shows the current state and lets you choose the appropriate policy. -### Deep links +This sandbox covers commands run through the Windows node. Commands run directly on the gateway use the gateway's separate security controls. -The app registers `openclaw://` for automation. Key links: +## Features + +- Native tray flyout with gateway, session, usage, channel, node, and activity status +- Companion Settings for connections, permissions, gateway configuration, diagnostics, and updates +- Native chat and Quick Send with the `Ctrl+Alt+Shift+C` global hotkey +- Command Center diagnostics with copyable repair guidance +- Toast notifications with smart categorization +- WebView2 Canvas and A2UI rendering +- Local MCP server for local tool integrations +- Background updates from GitHub Releases +- `openclaw://` deep links for automation + +### Useful deep links -| Link | What it does | +| Link | Action | |---|---| -| `openclaw://settings` | Open Settings | -| `openclaw://setup` | Open Setup Wizard | +| `openclaw://settings` | Open Companion Settings | +| `openclaw://setup` | Open the setup wizard | | `openclaw://chat` | Open Chat | -| `openclaw://commandcenter` | Open Command Center diagnostics | -| `openclaw://send?message=Hello` | Quick Send with pre-filled text | -| `openclaw://logs` | Open current log file | +| `openclaw://commandcenter` | Open Command Center | +| `openclaw://send?message=Hello` | Open Quick Send with pre-filled text | +| `openclaw://logs` | Open the current log file | | `openclaw://support-context` | Copy redacted support context | -| `openclaw://capability-diagnostics` | Copy permissions and allowlist diagnostics | +| `openclaw://capability-diagnostics` | Copy capability and allowlist diagnostics | -Deep links work when the app is already running (forwarded via IPC). +Deep links are forwarded through IPC when OpenClaw Companion is already running. -### File paths +### Local files -| What | Where | +| Data | Default path | |---|---| -| Settings | `%APPDATA%\OpenClawTray\settings.json` | +| App settings | `%APPDATA%\OpenClawTray\settings.json` | | Gateway registry | `%APPDATA%\OpenClawTray\gateways.json` | | Logs | `%LOCALAPPDATA%\OpenClawTray\openclaw-tray.log` | | Exec approvals | `%APPDATA%\OpenClawTray\exec-approvals.json` | -Default gateway: `ws://localhost:18789` - ---- +The default local gateway URL is `ws://localhost:18789`. ## For contributors ### Projects -| Project | What it is | +| Project | Purpose | |---|---| -| **OpenClaw.Tray.WinUI** | System tray app (WinUI 3) | -| **OpenClaw.Connection** | Gateway registry and connection manager | -| **OpenClaw.Shared** | Gateway client, capabilities, MCP bridge | -| **OpenClaw.Chat** | Chat model and timeline reducer | -| **OpenClaw.WinNode.Cli** | `winnode` CLI for local node/MCP invocation | -| **OpenClaw.SetupEngine** | WSL gateway setup and setup-code pairing | +| **OpenClaw.Tray.WinUI** | WinUI 3 tray app and Companion Settings | +| **OpenClaw.Connection** | Gateway registry, credential resolution, and connection manager | +| **OpenClaw.Shared** | Gateway client, Windows capabilities, diagnostics, and MCP bridge | +| **OpenClaw.Chat** | Native chat model and timeline reducer | +| **OpenClaw.WinNode.Cli** | `winnode` CLI for local Windows node and MCP invocation | +| **OpenClaw.SetupEngine** | WSL gateway installation and setup-code pairing | | **OpenClaw.SetupEngine.UI** | WinUI setup wizard pages | -| **OpenClaw.Cli** | CLI WebSocket validator | -| **OpenClawTray.FunctionalUI** | Declarative WinUI helpers | +| **OpenClaw.Cli** | Gateway WebSocket validation CLI | +| **OpenClawTray.FunctionalUI** | Declarative WinUI helpers used by newer surfaces | -### Prerequisites +### Prepare the checkout ```powershell -.\scripts\setup-dev.ps1 # Install missing prerequisites (winget, .NET, etc.) -.\scripts\setup-dev.ps1 -CheckOnly # Verify without installing -.\scripts\setup-dev.ps1 -RunValidation # Install + run full build/test validation +.\scripts\setup-dev.ps1 +.\scripts\setup-dev.ps1 -CheckOnly +.\scripts\setup-dev.ps1 -RunValidation ``` ### Build ```powershell -.\build.ps1 # Build all projects -.\build.ps1 -Project WinUI # Build only the tray app -.\build.ps1 -CheckOnly # Check prerequisites without building +.\build.ps1 +.\build.ps1 -Project WinUI +.\build.ps1 -CheckOnly ``` -Or build directly with `dotnet` (note: WinUI requires a runtime identifier): +Direct WinUI builds require a runtime identifier: ```powershell -dotnet build src/OpenClaw.Tray.WinUI -r win-x64 # x64 -dotnet build src/OpenClaw.Tray.WinUI -r win-arm64 # ARM64 -dotnet build src/OpenClaw.Tray.WinUI -r win-x64 -p:PackageMsix=true # MSIX package +dotnet build .\src\OpenClaw.Tray.WinUI\OpenClaw.Tray.WinUI.csproj -r win-x64 +dotnet build .\src\OpenClaw.Tray.WinUI\OpenClaw.Tray.WinUI.csproj -r win-arm64 +dotnet build .\src\OpenClaw.Tray.WinUI\OpenClaw.Tray.WinUI.csproj -r win-x64 -p:PackageMsix=true ``` ### Run +`run-app-local.ps1` allows `main` by default. Pass `-AllowNonMain` when previewing a feature branch or linked worktree. + ```powershell -.\run-app-local.ps1 # Build and launch -.\run-app-local.ps1 -NoBuild # Launch existing build (skip rebuild) -.\run-app-local.ps1 -Isolated # Separate settings per worktree -.\run-app-local.ps1 -Dev -Isolated # Side-by-side dev identity (own mutex, port, distro) -.\run-app-local.ps1 -Configuration Release -Isolated -UpdateChannel alpha # Test updates +.\run-app-local.ps1 +.\run-app-local.ps1 -NoBuild +.\run-app-local.ps1 -AllowNonMain -Isolated +.\run-app-local.ps1 -AllowNonMain -Dev -Isolated +.\run-app-local.ps1 -AllowNonMain -Configuration Release -Isolated -UpdateChannel alpha ``` ### Test +Set the repository root explicitly so tests also work in linked worktrees: + ```powershell -dotnet test tests/OpenClaw.Shared.Tests -dotnet test tests/OpenClaw.Tray.Tests +$env:OPENCLAW_REPO_ROOT = (Get-Location).Path +dotnet test .\tests\OpenClaw.Shared.Tests\OpenClaw.Shared.Tests.csproj +dotnet test .\tests\OpenClaw.Tray.Tests\OpenClaw.Tray.Tests.csproj ``` -### Docs +These commands restore and build the test projects when needed. Use `--no-restore` only after each test project has built successfully in the current worktree. + +### Documentation -| Topic | Link | +| Topic | Document | |---|---| -| Connection architecture | [docs/CONNECTION_ARCHITECTURE.md](docs/CONNECTION_ARCHITECTURE.md) | +| Architecture ownership | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | +| Connection and pairing | [docs/CONNECTION_ARCHITECTURE.md](docs/CONNECTION_ARCHITECTURE.md) | | Onboarding wizard | [docs/ONBOARDING_WIZARD.md](docs/ONBOARDING_WIZARD.md) | -| WSL gateway admin | [docs/WSL_GATEWAY_ADMIN.md](docs/WSL_GATEWAY_ADMIN.md) | +| Windows node behavior | [docs/WINDOWS_NODE_TESTING.md](docs/WINDOWS_NODE_TESTING.md) | +| Local MCP mode | [docs/MCP_MODE.md](docs/MCP_MODE.md) | +| Managed WSL gateway | [docs/WSL_GATEWAY_ADMIN.md](docs/WSL_GATEWAY_ADMIN.md) | | Development | [DEVELOPMENT.md](DEVELOPMENT.md) | -**User-facing docs** (also linked above): [Setup](docs/SETUP.md) Β· [Node Concepts](docs/OPERATOR_NODE_CONCEPTS.md) Β· [Windows Node Testing](docs/WINDOWS_NODE_TESTING.md) Β· [MCP Mode](docs/MCP_MODE.md) - ---- - ## License [MIT](LICENSE) - -*Made with 🦞 by Scott Hanselman, Molty, and contributors* diff --git a/docs/assets/openclaw-icon.png b/docs/assets/openclaw-icon.png deleted file mode 100644 index f7ad456112092a7b6f990bb04995ca4dd059d86c..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 2120 zcmV-O2)Fl%P)#nb(I&B1G$mE{@>j!}MpWnUWyJxL`*9Gat7yVSPU9+iBtDlEBfjEcvfFpoB z5~ar3+LzRu6F2>1@4kQjb)kOG1n_zt7#}*$@jK$c!HpZXp3!J-3*UEv5@$)Yz{)!> z)Kr-O$iR+tpp@2OfX3K34i(G~E*v}jMG#9il~N~$Uxr@prKBNeuTqHa_}ruCtX(st zSNBsgTX9J}A`K{It<}a_SYugf3k97f2{meUkDij>(ARr+bnR77jXwT(2NYD!tG5dP z<+2tQM_cZAs5Cx#XHuE>WQ;L3usR4d84b>v(n8w?4P^tZlr{{QTD{>*Q*$@2erD&B zqDis290+~F?%NWI?!D`l(%ATxcx)^qYjmJBl3Eprn+UDVS2B4pQEtBgpgCWG&Jq+P z+YD2gnodiT)7MvTzW$rJEX(B+{OP3+gM))wv^;^X7-mKo$6*g04t?5{@{zWQ3++c$tw5DLujKrlZs?ZfHW`{uuX>$}A^i;v|1 zaJg)@?b>BTtA$th+*Uj~y*gfK5HWNCj7KXq45uE?)gyd+;wW^IfQaCkV3Pz7HWIwl zS;Eg|=de9aQP2uZtdcn8@MtB}2gbMLbzo@7EUk`qk#z0KA9IIn-#O49O03# zDsz5<;o+7~fE5oyt07SR^Pl}pN3-z-7bl(B=%J0-K$0<kXHoH-v-jB~jiONRSULR6k9jLg zVFGG5-Ec$q)a=u69@k%&tWXLiUx4!jWi)i|`K_9o17Oab=ADLG5y*&7PZ7eb>qHJ~y{N;OW*-;x9$3@lRb^H6IrNU6M%$etza z#}p(WBnl!uW;iBzVmKni0QN=;=rIOtj8B~-=Y24x@q7+o5YVqoPj8>5q9L zyxNR0&x}iyLX#MQ61`HpPq)&LyBA7G5Cn`kUIammln71X6ck?f4z+3(7lxsUiOo@_ z-_3S*KG0Ueu}xt+%oU{|7#P$1!vW&nO`V-wvPRi<_^ptRIA72*Eg}#Ek`^gE+zLMt z95W(Mn9m&Vb(xB+iOwXt+Yya_&HLXkR&TXf2ilv-#}g}8{<;t+*Q^Nw-z^H{-(7pz)a3LX;M;$vyl z)d|h0eQNn-Z{M?l%Qh3>N=94hw^BdlxkeF{dxK%Ll0 z5if+DaFED*`N)IA^~&m;Z^hWoBmp z8yYj$+o7+yX|BF|x$|IKNXw$4oq)NnTK!9=)JGEF<&4NqImfd^m?Oe05zP_#_C+Gw zijdBG_6!>s^GZ)xxJ;ajt>v7bGy;o57JjO&xW|gcFVAOwd(32vRw|HVk5Vn^@#4;j zt=2pc1oz!@@x|Nac)r92{;NajAYg|i!kahu{QOV5kBrB0=fN!Hl=gLrXd+;Inr{&vy zFgKo4?6|Z)2r?1N-z!-^fSDz2alg^3 z3kaIdRZ|ns2}c*#{x5zTDlzyi;QS6_HthF)atE+`>Gy9~`{5quRny+@`yMc|wAlP# y5A{waOXrldy#es>am*IB?`!v`ll=@^Zu}em3B^4gR2#wo0000 - - - diff --git a/src/OpenClaw.Tray.WinUI/Windows/HubWindow.xaml.cs b/src/OpenClaw.Tray.WinUI/Windows/HubWindow.xaml.cs index a961b9661..550f847a6 100644 --- a/src/OpenClaw.Tray.WinUI/Windows/HubWindow.xaml.cs +++ b/src/OpenClaw.Tray.WinUI/Windows/HubWindow.xaml.cs @@ -1170,7 +1170,6 @@ public void SetActivityFilter(string? filter) "voice" => typeof(VoiceSettingsPage), "permissions" => typeof(PermissionsPage), "sandbox" => typeof(SandboxPage), - "sandbox-sessions" => typeof(SandboxSessionPrototypePage), // ActivityPage has been removed; legacy "activity"/"history" deep links // redirect to ChannelsPage via DeepLinkHandler. "activity" => typeof(ChannelsPage),