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

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

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

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 or 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.
• 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 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.

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

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

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

// 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);
}

// 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 writes to both DebugView and persistent log files in %LOCALAPPDATA%\OpenClawTray\Logs\.
• In-app diagnostics in 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 configuration, and the 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, 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.

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