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

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.

# 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, 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 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.

{
  "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 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) 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.

# 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:

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, 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) 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:

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, 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 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 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. 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. 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. 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. Each command must appear in both the gateway configuration and the local exec-policy.json file at %LOCALAPPDATA%\OpenClawTray\exec-policy.json.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}