# Best Practices for Using openclaw-windows-node: Architecture, Security, and Deployment Guide

> Learn best practices for openclaw-windows-node security and deployment. Secure your node by storing tokens in GatewayRegistry and enabling node mode with allowlists.

- Repository: [openclaw/openclaw-windows-node](https://github.com/openclaw/openclaw-windows-node)
- Tags: best-practices
- Published: 2026-06-06

---

**Store gateway tokens only in the `GatewayRegistry`, enable node mode with explicit command allowlists, and use the provided `build.ps1` script with .NET 10.0 to keep the OpenClaw Windows Node (Molty) secure and maintainable.**

The openclaw-windows-node repository provides a full-featured Windows companion application that runs as a system-tray utility and can execute remote commands from an OpenClaw gateway. Following these architectural and operational best practices ensures the application remains secure, reliable, and aligned with the project's intended design across the `OpenClaw.Tray.WinUI`, `OpenClaw.Shared`, and `OpenClaw.Cli` projects.

## Project Structure and Build Configuration

### Managing the Three-Project Layout

Isolate the three top-level projects to prevent UI changes from breaking core functionality. Keep `OpenClaw.Tray.WinUI` (the WinUI 3 system-tray application), `OpenClaw.Shared` (the core client library), and `OpenClaw.Cli` (the command-line validator) separate in their respective `src/` directories. This separation allows the CLI to run automated tests without UI dependencies while ensuring the tray app remains lightweight.

Reference the `openclaw-windows-node.slnx` solution file to build all projects together, ensuring consistent dependencies across the shared library and the WinUI front end.

### Building with build.ps1

Always use the provided `build.ps1` script to compile rather than invoking `dotnet build` directly. The script configures MSIX packaging, WinUI-specific runtime identifier (RID) values, and verifies the correct WebView2 runtime is present.

```powershell

# Verify prerequisites only

.\build.ps1 -CheckOnly

# Build everything (WinUI + Shared + CLI)

.\build.ps1

# Build only the tray UI for a specific runtime

.\build.ps1 -Project WinUI -Runtime win-x64

```

Target the **.NET 10.0 SDK** and **Windows 10 SDK** (or newer) as specified in the project files to ensure compatibility with WinUI 3 and packaged MSIX deployments.

## Secure Configuration Management

### Credential Storage in GatewayRegistry

Never write tokens back to `SettingsData.Token`; that field exists solely for legacy migration. Instead, store all gateway credentials exclusively in the **gateway registry** (`OpenClaw.Connection.GatewayRegistry`). According to the source in [`src/OpenClaw.Connection/GatewayRegistry.cs`](https://github.com/openclaw/openclaw-windows-node/blob/main/src/OpenClaw.Connection/GatewayRegistry.cs), this centralized store enforces proper credential precedence: device token → shared token → bootstrap token.

This approach guarantees that paired devices cannot accidentally downgrade to less secure authentication methods and ensures that token updates propagate correctly across the tray app, CLI, and node-mode operations.

### Configuration File Locations

Keep configuration centralized to enable all components to share the same credentials:

- **Settings**: `%APPDATA%\OpenClawTray\settings.json`
- **Logs**: `%LOCALAPPDATA%\OpenClawTray\openclaw-tray.log`

Both the tray application and CLI read from these locations, ensuring consistent behavior whether running interactively or as a background service.

## Node Mode and Remote Execution

### Enabling Node Capabilities

Enable **node mode** in Settings (enabled by default) to allow the Windows PC to receive and execute commands from the OpenClaw gateway, mirroring the remote-control capabilities of the macOS client. When first paired, the device requires explicit approval on the gateway via `openclaw devices approve <id>`.

The [`NodeCapabilities.cs`](https://github.com/openclaw/openclaw-windows-node/blob/main/NodeCapabilities.cs) file in `src/OpenClaw.Shared/` defines the available remote functions, including `system.notify`, `canvas.present`, and `camera.list`.

### Gateway Allowlists and Local Policy

For security, each command must be explicitly allowed. Populate the gateway's `allowCommands` list with exactly the commands you need—wildcards are not supported. Keep the Windows node's local execution policy (`%LOCALAPPDATA%\OpenClawTray\exec-policy.json`) synchronized with the gateway policy to prevent unauthorized remote execution.

```json
{
  "gateway": {
    "nodes": {
      "allowCommands": [
        "system.notify",
        "canvas.present",
        "camera.list"
      ]
    }
  }
}

```

Place this configuration in `~/.openclaw/openclaw.json` on the gateway host and restart the gateway service to apply changes.

## UI and Permission Management

### Onboarding Wizard and System Permissions

The six-screen onboarding wizard automatically requests Windows system permissions for notifications, camera, microphone, screen capture, and location. The [`ONBOARDING_WIZARD.md`](https://github.com/openclaw/openclaw-windows-node/blob/main/ONBOARDING_WIZARD.md) documentation specifies that these permissions are required for node capabilities like `camera.snap`, `screen.record`, and `location.get`.

For packaged MSIX builds, these prompts appear automatically during installation. For unpackaged builds, manually open Windows Settings to grant these permissions before running the application.

### Quick-Send Hotkey Requirements

The global hotkey `Ctrl+Alt+Shift+C` only functions when the operator token includes the `operator.write` scope. If this scope is missing, Molty copies remediation instructions to the clipboard rather than failing silently. This behavior, documented in the project's README, ensures users understand authentication requirements without digging through log files.

## CLI Validation and Testing

### Using the CLI for Connectivity Tests

Use the CLI ([`src/OpenClaw.Cli/Program.cs`](https://github.com/openclaw/openclaw-windows-node/blob/main/src/OpenClaw.Cli/Program.cs)) to validate gateway connections before launching the full tray UI. The CLI supports testing with custom endpoints and tokens, making it ideal for isolated CI environments.

```powershell

# Basic message test

dotnet run --project src/OpenClaw.Cli -- --message "Hello from CLI"

# Override gateway endpoint and token for isolated testing

dotnet run --project src/OpenClaw.Cli -- `
    --url ws://127.0.0.1:18789 `
    --token "YOUR_TOKEN_HERE" `
    --message "Test via custom endpoint"

```

### Automated Testing Strategy

Run the full validation suite after any code change as mandated by [`AGENTS.md`](https://github.com/openclaw/openclaw-windows-node/blob/main/AGENTS.md):

1. Execute `./build.ps1` to verify compilation
2. Run `dotnet test ./tests/OpenClaw.Shared.Tests/...` for logic validation
3. Run `dotnet test ./tests/OpenClaw.Tray.Tests/...` for UI-related tests

Isolate tray tests by setting the `OPENCLAW_TRAY_DATA_DIR` environment variable to a temporary folder to prevent test data from polluting your development environment.

## Security and Integration

### Log Sanitization and Token Protection

All outbound logs pass through `UrlLogSanitizer` and `TokenSanitizer` to redact secrets, while `NotificationCategorizer` classifies incoming notifications to prevent information leakage. According to [`src/OpenClaw.Shared/UrlLogSanitizer.cs`](https://github.com/openclaw/openclaw-windows-node/blob/main/src/OpenClaw.Shared/UrlLogSanitizer.cs), this sanitization occurs before writing to `%LOCALAPPDATA%\OpenClawTray\openclaw-tray.log`, ensuring safe log sharing for support purposes.

Enable automatic update checking to keep end-users on secure binaries from GitHub Releases. For MSIX packages, the update process respects the Windows-certified installer chain, preserving signature validation.

### Deep-Link Integration

Register the `openclaw://` scheme (see [`docs/DEEP_LINKS.md`](https://github.com/openclaw/openclaw-windows-node/blob/main/docs/DEEP_LINKS.md)) to enable external applications or scripts to interact with Molty without UI automation. Use deep links for actions like opening settings or launching the Command Center:

```powershell
start "openclaw://commandcenter"

```

These links work even when Molty is already running; the request forwards via IPC to the existing process.

## Summary

- **Isolate projects**: Keep `OpenClaw.Tray.WinUI`, `OpenClaw.Shared`, and `OpenClaw.Cli` separate to prevent UI dependencies from breaking CLI automation.
- **Secure credentials**: Store tokens only in [`GatewayRegistry.cs`](https://github.com/openclaw/openclaw-windows-node/blob/main/GatewayRegistry.cs), never in `SettingsData.Token`, to maintain proper precedence and prevent accidental downgrades.
- **Lock down node mode**: Explicitly list allowed commands in the gateway configuration and synchronize local [`exec-policy.json`](https://github.com/openclaw/openclaw-windows-node/blob/main/exec-policy.json) files.
- **Use build.ps1**: Target .NET 10.0 with the provided script to ensure correct MSIX packaging and WebView2 validation.
- **Sanitize logs**: Rely on `UrlLogSanitizer` and `TokenSanitizer` to prevent credential exposure in log files.
- **Test with CLI**: Validate connectivity using [`OpenClaw.Cli/Program.cs`](https://github.com/openclaw/openclaw-windows-node/blob/main/OpenClaw.Cli/Program.cs) with `--url` and `--token` overrides before launching the tray UI.

## Frequently Asked Questions

### How do I store gateway credentials securely in openclaw-windows-node?

Always store credentials in the `GatewayRegistry` class located in [`src/OpenClaw.Connection/GatewayRegistry.cs`](https://github.com/openclaw/openclaw-windows-node/blob/main/src/OpenClaw.Connection/GatewayRegistry.cs). This registry enforces a precedence hierarchy (device token → shared token → bootstrap token) and prevents the legacy `SettingsData.Token` field from being used for active storage. Never write sensitive tokens to the settings JSON file directly.

### What permissions does the OpenClaw Windows Node require?

The onboarding wizard requests notifications, camera, microphone, screen capture, and location permissions. These are required for node capabilities such as `camera.snap`, `screen.record`, and `location.get` defined in [`src/OpenClaw.Shared/NodeCapabilities.cs`](https://github.com/openclaw/openclaw-windows-node/blob/main/src/OpenClaw.Shared/NodeCapabilities.cs). MSIX packaged builds prompt automatically; unpackaged builds require manual permission grants in Windows Settings.

### How do I test the gateway connection without launching the UI?

Use the CLI tool in [`src/OpenClaw.Cli/Program.cs`](https://github.com/openclaw/openclaw-windows-node/blob/main/src/OpenClaw.Cli/Program.cs). Run `dotnet run --project src/OpenClaw.Cli -- --message "test"` for basic validation, or override the gateway endpoint with `--url` and `--token` parameters for isolated testing. This approach validates WebSocket connectivity and message formatting before starting the WinUI tray application.

### What commands can I run in node mode?

Only commands explicitly listed in the gateway's `allowCommands` array are permitted; wildcards are not supported. Common commands include `system.notify`, `canvas.present`, `camera.list`, and `camera.snap`, as implemented in [`src/OpenClaw.Shared/NodeCapabilities.cs`](https://github.com/openclaw/openclaw-windows-node/blob/main/src/OpenClaw.Shared/NodeCapabilities.cs). Each command must appear in both the gateway configuration and the local [`exec-policy.json`](https://github.com/openclaw/openclaw-windows-node/blob/main/exec-policy.json) file at `%LOCALAPPDATA%\OpenClawTray\exec-policy.json`.