# How to Debug OpenClaw-Windows-Node Applications: A Complete Guide

> Debug openclaw-windows-node applications effectively using runtime logs, diagnostic UI, and portable debug bundles for seamless troubleshooting. Get the complete guide.

- Repository: [openclaw/openclaw-windows-node](https://github.com/openclaw/openclaw-windows-node)
- Tags: how-to-guide
- Published: 2026-06-06

---

**OpenClaw-Windows-Node provides a layered debugging system combining runtime logs, an in-app diagnostic UI, and portable debug bundles that you can export and share.**

The `openclaw/openclaw-windows-node` repository contains a WinUI 3 desktop application that manages local gateways and node connections. When you need to troubleshoot issues with gateway pairing, canvas rendering, or unexpected crashes, understanding the three-tier debugging architecture—centralized logging, interactive diagnostics, and traditional debugger attachment—will help you resolve problems efficiently.

## Logging Infrastructure

All core components write to a centralized logger implemented in [`src/OpenClaw.Tray.WinUI/Services/Logger.cs`](https://github.com/openclaw/openclaw-windows-node/blob/main/src/OpenClaw.Tray.WinUI/Services/Logger.cs). This static class provides severity-based methods including `Logger.Debug(string)`, `Logger.Info(string)`, `Logger.Warning(string)`, and `Logger.Error(string)`.

The logger forwards messages to two simultaneous sinks:

- **DebugView / ETW**: Messages route through `System.Diagnostics.Debug.WriteLine`, making them visible when a debugger is attached or whenusing Sysinternals DebugView.
- **File logger**: Persistent logs write to `%LOCALAPPDATA%\OpenClawTray\Logs\OpenClaw.Tray.log`, which the Debug UI reads for display.

In [`src/OpenClaw.Tray.WinUI/AppLogger.cs`](https://github.com/openclaw/openclaw-windows-node/blob/main/src/OpenClaw.Tray.WinUI/AppLogger.cs), the application wires up the static `Logger` instance and configures the file sink location during app startup.

## In-App Diagnostic UI

The tray application includes a built-in **Debug page** that surfaces logs without requiring external tools.

### DebugPage.xaml

The page implementation in [`src/OpenClaw.Tray.WinUI/Pages/DebugPage.xaml.cs`](https://github.com/openclaw/openclaw-windows-node/blob/main/src/OpenClaw.Tray.WinUI/Pages/DebugPage.xaml.cs) reads the latest log file and displays it in a scrollable text box. It provides two primary actions: **Copy Debug Bundle** and **Open Log Folder**.

### Diagnostics Bundle Dialog

When exporting diagnostics, [`src/OpenClaw.Tray.WinUI/Windows/DiagnosticsBundleDialog.xaml.cs`](https://github.com/openclaw/openclaw-windows-node/blob/main/src/OpenClaw.Tray.WinUI/Windows/DiagnosticsBundleDialog.xaml.cs) handles the UI interactions and coordinates with helper services to assemble the archive.

## Portable Debug Bundles

When you select *Copy debug bundle* (or invoke the `openclaw://debug-bundle` deep link), the **CommandCenterTextHelper** class assembles a tar-gzip archive in [`src/OpenClaw.Tray.WinUI/Helpers/CommandCenterTextHelper.cs`](https://github.com/openclaw/openclaw-windows-node/blob/main/src/OpenClaw.Tray.WinUI/Helpers/CommandCenterTextHelper.cs).

The `BuildDebugBundle` method packages:

- All recent log files from the local data directory
- `%APPDATA%\OpenClawTray\settings.json` (current configuration state)
- The list of registered gateways from [`gateways.json`](https://github.com/openclaw/openclaw-windows-node/blob/main/gateways.json)

The resulting byte array copies to your clipboard, ready to paste into support tickets or Slack messages.

## Debugging with Visual Studio or WinDbg

Because OpenClaw-Windows-Node is a standard WinUI 3 desktop app, you can attach any Windows debugger.

1. Build the solution in **Debug** configuration using `dotnet build`.
2. Launch `OpenClaw.Tray.WinUI.exe`.
3. In Visual Studio, navigate to **Debug → Attach to Process** and select `OpenClaw.Tray.WinUI`.
4. Set breakpoints in key components like [`GatewayConnectionManager.cs`](https://github.com/openclaw/openclaw-windows-node/blob/main/GatewayConnectionManager.cs) or [`NodeConnector.cs`](https://github.com/openclaw/openclaw-windows-node/blob/main/NodeConnector.cs).

When execution breaks, the **Output** window displays the same debug lines the in-app logger writes because both call `System.Diagnostics.Debug.WriteLine`.

## Runtime Flags and Environment Variables

Several command-line flags and environment variables help control debugging behavior:

- **`--no-rollback-on-failure`**: Disables automatic cleanup of partial setups, leaving artifacts on disk for inspection. Documented in [`docs/SETUP.md`](https://github.com/openclaw/openclaw-windows-node/blob/main/docs/SETUP.md).
- **`OPENCLAW_TRAY_DATA_DIR`**: Overrides the default `%LOCALAPPDATA%` path for logs and settings, useful when running inside CI containers or isolated test environments.

## Common Debugging Scenarios

**Gateway pairing fails:** Open the Debug page and search for `GatewayConnectionManager` entries. Verify that [`gateways.json`](https://github.com/openclaw/openclaw-windows-node/blob/main/gateways.json) contains the expected device token.

**A2UI canvas does not render:** Check the log for entries prefixed with `[Canvas]` generated by `Logger.Debug` calls in [`src/OpenClaw.Tray.WinUI/Windows/CanvasWindow.xaml.cs`](https://github.com/openclaw/openclaw-windows-node/blob/main/src/OpenClaw.Tray.WinUI/Windows/CanvasWindow.xaml.cs).

**Unexpected crash:** Attach a debugger, enable first-chance exceptions, and reproduce the crash. The stack trace appears in both the debugger and the log file at `%LOCALAPPDATA%\OpenClawTray\Logs\`.

**Support escalation:** Click *Copy debug bundle* in the Debug page and paste the archive into your support ticket. This provides the OpenClaw team with logs, configuration, and gateway registration data in a single file.

## Code Examples

```csharp
// Writing debug output from any component
using OpenClaw.Tray.WinUI.Services;

public void SomeMethod()
{
    Logger.Debug("[MyComponent] entered SomeMethod");
    // Component logic here
}

```

```csharp
// Generating a debug bundle programmatically
using OpenClaw.Tray.WinUI.Helpers;

public void ExportDebugInfo()
{
    var bundle = CommandCenterTextHelper.BuildDebugBundle(
        GatewayCommandCenterState.Current);
    // bundle is a byte[] ready for clipboard or disk
    System.Windows.Clipboard.SetData(
        DataFormats.CommaSeparatedValue, bundle);
}

```

```csharp
// Setting a breakpoint in the logger implementation
// In Visual Studio, break on this line in Logger.cs:
public static void Debug(string message) => Log("DEBUG", message);

```

## Summary

- **Centralized logging** via [`Logger.cs`](https://github.com/openclaw/openclaw-windows-node/blob/main/Logger.cs) writes to both DebugView and persistent log files in `%LOCALAPPDATA%\OpenClawTray\Logs\`.
- **In-app diagnostics** in [`DebugPage.xaml.cs`](https://github.com/openclaw/openclaw-windows-node/blob/main/DebugPage.xaml.cs) provide a user-friendly log viewer and one-click bundle export.
- **Portable bundles** generated by `CommandCenterTextHelper.BuildDebugBundle` contain logs, settings, and gateway state for support handoffs.
- **Traditional debugging** works by attaching to the `OpenClaw.Tray.WinUI` process and setting breakpoints in connection managers or UI components.
- **Runtime flags** like `--no-rollback-on-failure` and `OPENCLAW_TRAY_DATA_DIR` help preserve state and redirect log locations for specialized environments.

## Frequently Asked Questions

### How do I view logs without attaching a debugger?

Open the tray application, navigate to the **Debug page**, and view the live log output. Alternatively, open `%LOCALAPPDATA%\OpenClawTray\Logs\OpenClaw.Tray.log` in any text editor.

### What information does the debug bundle contain?

The debug bundle is a tar-gzip archive containing recent log files, your [`settings.json`](https://github.com/openclaw/openclaw-windows-node/blob/main/settings.json) configuration, and the [`gateways.json`](https://github.com/openclaw/openclaw-windows-node/blob/main/gateways.json) registry. This gives the OpenClaw team complete context to reproduce connectivity or configuration issues.

### Can I redirect where OpenClaw-Windows-Node stores its logs?

Yes. Set the `OPENCLAW_TRAY_DATA_DIR` environment variable before launching the application. This overrides the default `%LOCALAPPDATA%\OpenClawTray` path, allowing you to store logs on different drives or in containerized environments.

### Where should I place breakpoints to diagnose gateway connection issues?

Set breakpoints in [`src/OpenClaw.Connection/GatewayConnectionManager.cs`](https://github.com/openclaw/openclaw-windows-node/blob/main/src/OpenClaw.Connection/GatewayConnectionManager.cs), specifically around methods that call `Logger.Debug` for pairing events. This file handles reconnection logic and device token validation, making it the primary location for troubleshooting connectivity problems.