From ac5abcd3e18fb2619ff9d7813c4a9dad3ca8648e Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Thu, 26 Mar 2026 12:53:10 +0000 Subject: [PATCH] docs: add SETUP.md and POWERTOYS.md, fix stale CommandPalette section in README MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - docs/SETUP.md: step-by-step installer guide covering prerequisites, first-run configuration, tray icon status, deep links, troubleshooting, and uninstall - docs/POWERTOYS.md: PowerToys Command Palette extension guide covering installation, available commands (accurate vs. stale README), and troubleshooting - README.md: fix CommandPalette section — was listing 6 commands that don't exist (Full Status, Sessions, Channels, Health Check); replace with the 4 actual commands (Open Dashboard, Web Chat, Quick Send, Settings); update install instructions to reference the installer rather than Visual Studio MSIX deploy; add links to new SETUP.md and POWERTOYS.md docs Closes #103 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- README.md | 23 +++++---- docs/POWERTOYS.md | 92 +++++++++++++++++++++++++++++++++ docs/SETUP.md | 127 ++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 231 insertions(+), 11 deletions(-) create mode 100644 docs/POWERTOYS.md create mode 100644 docs/SETUP.md diff --git a/README.md b/README.md index b0c3e40..fb998cf 100644 --- 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 new file mode 100644 index 0000000..b0f3b8f --- /dev/null +++ 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 new file mode 100644 index 0000000..b521efb --- /dev/null +++ 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 +``` + +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.