openclaw · github-actions · Mar 26, 2026
diff --git a/README.md b/README.md
@@ -20,12 +20,14 @@ This monorepo contains three projects:
 
 ## 🚀 Quick Start
 
+> **End-user installer?** See [docs/SETUP.md](docs/SETUP.md) for a step-by-step installation guide (no build required).
+
 ### Prerequisites
 - Windows 10 (20H2+) or Windows 11
 - .NET 10.0 SDK - https://dotnet.microsoft.com/download/dotnet/10.0
 - 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
-- PowerToys (optional, for Command Palette extension)
+- PowerToys (optional, for Command Palette extension) — see [docs/POWERTOYS.md](docs/POWERTOYS.md)
 
 ### Build
 
@@ -251,18 +253,17 @@ Deep links work even when Molty is already running - they're forwarded via IPC.
 PowerToys Command Palette extension for quick OpenClaw access.
 
 ### Commands
-- **🦞 Open Dashboard** - Launch web dashboard
-- **💬 Quick Send** - Send a message
-- **📊 Full Status** - View gateway status
-- **⚡ Sessions** - View active sessions
-- **📡 Channels** - View channel health
-- **🔄 Health Check** - Trigger health refresh
+- **🦞 Open Dashboard** - Launch the OpenClaw web dashboard
+- **💬 Web Chat** - Open the embedded Web Chat window
+- **📝 Quick Send** - Open the Quick Send dialog to compose a message
+- **⚙️ Settings** - Open the OpenClaw Tray Settings dialog
 
 ### Installation
-1. Build the solution in Release mode
-2. Deploy the MSIX package via Visual Studio
-3. Open Command Palette (Win+Alt+Space)
-4. Type "OpenClaw" to see commands
+1. Run the OpenClaw Tray installer and tick **"Install PowerToys Command Palette extension"**, or
+2. Register manually: `Add-AppxPackage -Register "$env:LOCALAPPDATA\OpenClawTray\CommandPalette\AppxManifest.xml" -ForceApplicationShutdown`
+3. Open Command Palette (`Win+Alt+Space`) and type "OpenClaw" to see commands
+
+See [docs/POWERTOYS.md](docs/POWERTOYS.md) for detailed setup and troubleshooting.
 
 ## 📦 OpenClaw.Shared
 

diff --git a/docs/POWERTOYS.md b/docs/POWERTOYS.md
@@ -0,0 +1,92 @@
+# PowerToys Command Palette — OpenClaw Extension
+
+The OpenClaw Command Palette extension integrates with [PowerToys Command Palette](https://learn.microsoft.com/windows/powertoys/command-palette) to give you fast keyboard-driven access to OpenClaw from anywhere on your desktop.
+
+## Prerequisites
+
+- [PowerToys](https://github.com/microsoft/PowerToys) installed (v0.90 or later recommended — this is the version that shipped Command Palette).
+- OpenClaw Tray (Molty) installed and configured.
+
+## Installation
+
+### Via the OpenClaw Installer (recommended)
+
+When running the OpenClaw Tray installer, tick the **"Install PowerToys Command Palette extension"** checkbox. The installer will register the extension automatically.
+
+### Manual Registration
+
+If you installed without the Command Palette option, or need to re-register after a repair:
+
+1. Open **PowerShell** (no admin needed).
+2. Run:
+
+   ```powershell
+   Add-AppxPackage -Register "$env:LOCALAPPDATA\OpenClawTray\CommandPalette\AppxManifest.xml" -ForceApplicationShutdown
+   ```
+
+3. Restart PowerToys if it was running.
+
+### Verifying Registration
+
+Open Command Palette (`Win+Alt+Space`), type **"OpenClaw"** — you should see the OpenClaw commands appear.
+
+## Available Commands
+
+| Command | Action |
+|---------|--------|
+| **🦞 Open Dashboard** | Opens the OpenClaw web dashboard in your default browser |
+| **💬 Web Chat** | Opens the embedded Web Chat window in OpenClaw Tray |
+| **📝 Quick Send** | Opens the Quick Send dialog to compose a message |
+| **⚙️ Settings** | Opens the OpenClaw Tray Settings dialog |
+
+## Usage
+
+1. Press `Win+Alt+Space` to open Command Palette.
+2. Type `OpenClaw` (or just `oc`) to filter to OpenClaw commands.
+3. Select the action with arrow keys and press `Enter`.
+
+Commands are also surfaced as deep links — you can invoke them from a browser or script using `openclaw://` URIs (see [SETUP.md](./SETUP.md#deep-links)).
+
+## Troubleshooting
+
+### OpenClaw commands don't appear in Command Palette
+
+1. Make sure PowerToys Command Palette is enabled: **PowerToys Settings → Command Palette → Enable Command Palette**.
+2. Try re-registering the extension (see [Manual Registration](#manual-registration) above).
+3. Restart PowerToys after registration.
+4. Check that the extension files exist at `%LOCALAPPDATA%\OpenClawTray\CommandPalette\`.
+
+### Commands appear but do nothing
+
+The extension communicates with OpenClaw Tray via `openclaw://` deep links. Make sure:
+- OpenClaw Tray (`OpenClaw.Tray.WinUI.exe`) is running.
+- The `openclaw://` URI scheme is registered. If not, re-run the OpenClaw Tray installer.
+
+### Extension was removed after a PowerToys update
+
+PowerToys updates can sometimes unregister third-party extensions. Re-register with:
+
+```powershell
+Add-AppxPackage -Register "$env:LOCALAPPDATA\OpenClawTray\CommandPalette\AppxManifest.xml" -ForceApplicationShutdown
+```
+
+### Unregistering the extension
+
+To remove the OpenClaw extension from Command Palette without uninstalling Tray:
+
+```powershell
+Get-AppxPackage -Name '*OpenClaw*' | Remove-AppxPackage
+```
+
+## Notes
+
+- The extension is a **sparse MSIX package** registered per-user, so no administrator rights are required.
+- It is built against the `Microsoft.CommandPalette.Extensions` SDK and communicates with Tray exclusively via `openclaw://` deep links — there is no direct IPC between the extension and Tray.
+- Command Palette extension commands and their deep link targets:
+
+  | Command | Deep link |
+  |---------|-----------|
+  | Open Dashboard | `openclaw://dashboard` |
+  | Web Chat | `openclaw://chat` |
+  | Quick Send | `openclaw://send` |
+  | Settings | `openclaw://settings` |
diff --git a/docs/SETUP.md b/docs/SETUP.md
@@ -0,0 +1,127 @@
+# OpenClaw Tray — Installation & Setup Guide
+
+This guide covers installing OpenClaw Tray (Molty) on Windows using the pre-built installer. For building from source, see [DEVELOPMENT.md](../DEVELOPMENT.md).
+
+## Prerequisites
+
+Before installing, make sure you have:
+
+- **Windows 10 (20H2 or later)** or **Windows 11**
+- **WebView2 Runtime** — pre-installed on Windows 11 and most up-to-date Windows 10 systems. If missing, download from [Microsoft Edge WebView2](https://developer.microsoft.com/microsoft-edge/webview2/).
+- An active **OpenClaw account** with a gateway token — sign up at [openclaw.ai](https://openclaw.ai).
+
+## Step-by-Step Installation
+
+### 1. Download the Installer
+
+Go to the [Releases page](https://github.com/openclaw/openclaw-windows-node/releases) and download the latest installer for your architecture:
+
+| File | Architecture |
+|------|-------------|
+| `OpenClawTray-Setup-x64.exe` | Intel / AMD (most PCs) |
+| `OpenClawTray-Setup-arm64.exe` | ARM64 (Surface Pro X, Snapdragon laptops) |
+
+If you're unsure, use the **x64** installer.
+
+### 2. Run the Installer
+
+Double-click the downloaded `.exe`. Windows may show a SmartScreen prompt — click **More info → Run anyway** (this is normal for code-signed apps that haven't yet accumulated reputation).
+
+The installer runs without requiring administrator privileges.
+
+### 3. Choose Optional Components
+
+The installer offers two optional components:
+
+- **Create Desktop Icon** — adds a shortcut to your desktop.
+- **Start OpenClaw Tray when Windows starts** — launches Molty automatically at login (recommended).
+- **Install PowerToys Command Palette extension** — enables OpenClaw commands in PowerToys Command Palette (requires [PowerToys](https://github.com/microsoft/PowerToys) to be installed). See [POWERTOYS.md](./POWERTOYS.md) for details.
+
+### 4. First Launch
+
+After the installer finishes, OpenClaw Tray starts automatically. Look for the 🦞 lobster icon in the system tray (bottom-right corner of the taskbar, near the clock).
+
+If you don't see it, check the **hidden icons** area (the `^` arrow next to the tray).
+
+### 5. Configure the Connection
+
+On first launch, a **Welcome** dialog appears. Click **Open Settings** to configure:
+
+| Setting | What to enter |
+|---------|--------------|
+| **Gateway URL** | `ws://localhost:18789` (if running OpenClaw locally) or your remote gateway address |
+| **Token** | Your OpenClaw API token from [openclaw.ai](https://openclaw.ai) |
+
+Click **Save**. Molty will connect to the gateway and the tray icon will turn green when connected.
+
+## Tray Icon Status
+
+| Icon colour | Meaning |
+|-------------|---------|
+| 🟢 Green | Connected to gateway |
+| 🟡 Amber | Connecting / reconnecting |
+| 🔴 Red | Error |
+| ⚫ Grey | Disconnected |
+
+Left-click the icon to open the quick-access menu. Right-click for context options.
+
+## Deep Links
+
+OpenClaw Tray responds to `openclaw://` deep links, which can be invoked from a browser or another app:
+
+| Link | Action |
+|------|--------|
+| `openclaw://dashboard` | Open the OpenClaw web dashboard |
+| `openclaw://chat` | Open the embedded Web Chat window |
+| `openclaw://send` | Open the Quick Send dialog |
+| `openclaw://send?message=Hello` | Open Quick Send with pre-filled text |
+| `openclaw://settings` | Open the Settings dialog |
+| `openclaw://agent?message=Hello` | Send a message directly (with confirmation) |
+
+## Troubleshooting
+
+### Tray icon doesn't appear
+
+1. Check Task Manager for `OpenClaw.Tray.WinUI.exe` — if it's running, the icon may be hidden.
+2. Drag the icon out of the hidden overflow area to always show it.
+3. If the process isn't running, try launching from Start Menu → **OpenClaw Tray**.
+
+### "WebView2 Runtime is missing" error
+
+Download and install WebView2 from [Microsoft](https://developer.microsoft.com/microsoft-edge/webview2/). The **Evergreen Standalone Installer** is the easiest option.
+
+### Can't connect to gateway
+
+- Verify the gateway URL in Settings (default: `ws://localhost:18789`).
+- Make sure the OpenClaw gateway process is running.
+- Check Windows Firewall — if your gateway runs on a different machine, allow inbound traffic on port 18789.
+- See the log at `%LOCALAPPDATA%\OpenClawTray\openclaw-tray.log` for connection errors.
+
+### "Not yet paired" message on reconnect
+
+If the tray shows **Pending approval** after reconnecting, run the approval command shown in the tray or log:
+
+```
+openclaw devices approve <device-id>
+```
+
+See [issue #81](https://github.com/openclaw/openclaw-windows-node/issues/81) for context on this flow.
+
+### Settings are not saved
+
+Settings are stored at `%APPDATA%\OpenClawTray\settings.json`. If this file is corrupt, delete it and reconfigure from scratch.
+
+### Auto-start isn't working
+
+1. Open Settings and toggle **Start with Windows** off, then on again.
+2. Check `HKCU\Software\Microsoft\Windows\CurrentVersion\Run` for a `OpenClawTray` entry.
+
+## Updating
+
+OpenClaw Tray checks for updates automatically and shows a notification when a new version is available. Click **Update** to download and apply the update. You can also manually check by re-downloading from the [Releases page](https://github.com/openclaw/openclaw-windows-node/releases).
+
+## Uninstalling
+
+Go to **Settings → Apps → Installed apps**, find **OpenClaw Tray**, and click **Uninstall**. Alternatively, use **Add or Remove Programs** in the Control Panel.
+
+Your settings file at `%APPDATA%\OpenClawTray\settings.json` and device key at `%LOCALAPPDATA%\OpenClawTray\device-key-ed25519.json` are not removed automatically — delete them manually if you want a clean uninstall.