### Bootstrap Flow Example

Source: https://github.com/openclaw/openclaw-windows-node/blob/main/docs/gateway-node-integration.md

Illustrates the step-by-step process of a Windows node bootstrapping to the gateway using a QR code or setup code.

```text
1. User runs `openclaw qr` on gateway host
2. User imports/scans QR image or pastes setup code into Windows Setup Wizard
3. Wizard decodes → { url, bootstrapToken, expiresAtMs }
4. Node connects with: auth: { bootstrapToken: "<token>" }
5. Gateway auto-approves pairing (bootstrap-token auth method)
6. Gateway returns hello-ok with: auth: { deviceToken: "<token>" }
7. Node saves deviceToken to identity store
8. Future connections use: auth: { token: "<deviceToken>" }
9. No manual `devices approve` needed!
```

--------------------------------

### UI Hosted Setup and Post-Setup Commands

Source: https://github.com/openclaw/openclaw-windows-node/blob/main/docs/SETUP_ENGINE_REDESIGN.md

Commands to launch the UI-hosted setup process and to restart the tray executable after setup is complete.

```bash
OpenClaw.Tray.WinUI.exe openclaw://setup                   # opens/focuses hosted setup window
OpenClaw.Tray.WinUI.exe --post-setup-restart --wait-for-pid <oldPid> --post-setup-launch chat
```

--------------------------------

### Run Hosted Setup

Source: https://github.com/openclaw/openclaw-windows-node/blob/main/docs/SETUP_ENGINE_REDESIGN.md

Executes the tray application to launch the hosted setup window.

```powershell
# Run hosted setup
& "src\OpenClaw.Tray.WinUI\bin\Debug\net10.0-windows10.0.22621.0\win-x64\OpenClaw.Tray.WinUI.exe" openclaw://setup
```

--------------------------------

### OnboardingV2State AdvancedSetupRequested

Source: https://github.com/openclaw/openclaw-windows-node/blob/main/docs/ONBOARDING_V2.md

Explains how requesting advanced setup triggers OnboardingV2State.AdvancedSetupRequested, leading to the setup window closing without completion and opening HubWindow on the Connections tab.

```csharp
Welcome's "Advanced setup" link raises
`OnboardingV2State.AdvancedSetupRequested`; `OnboardingWindow` closes setup
without completing it and opens `HubWindow` on the Connections tab. Users
connect to existing, remote, or manual gateways there.
```

--------------------------------

### Build Headless Setup Engine

Source: https://github.com/openclaw/openclaw-windows-node/blob/main/docs/SETUP_ENGINE_REDESIGN.md

Builds the headless OpenClaw Setup Engine project using dotnet CLI.

```powershell
# Build headless engine
dotnet build src\OpenClaw.SetupEngine\OpenClaw.SetupEngine.csproj
```

--------------------------------

### Setup Engine Architecture Diagram

Source: https://github.com/openclaw/openclaw-windows-node/blob/main/docs/SETUP_ENGINE_REDESIGN.md

Illustrates the components and interactions within the OpenClaw Setup Engine, including the pipeline library, UI, and tray host.

```text
┌─────────────────────────────────────────────────────────────┐
│  OpenClaw.SetupEngine (net10.0 library)                     │
│                                                             │
│  SetupPipeline ──→ 18 SetupStep classes ──→ StepResult      │
│       │                    │                                │
│  SetupContext         CommandRunner (WSL + Process)          │
│  SetupConfig          TransactionJournal (JSONL)            │
│  SetupLogger          RetryExecutor                         │
│                                                             │
│  refs: OpenClaw.Connection, OpenClaw.Shared                 │
└─────────────────────────────────────────────────────────────┘
         ▲ callback: Action<string, StepStatus>
         │
┌─────────────────────────────────────────────────────────────┐
│  OpenClaw.SetupEngine.UI (net10.0-windows10.0.22621, WinUI3)│
│  SetupWindow + pages, direct code-behind, no MVVM           │
│  Welcome → Capabilities → Progress → Permissions → Complete │
└─────────────────────────────────────────────────────────────┘
         ▲ hosted by project reference
         │
┌─────────────────────────────────────────────────────────────┐
│  OpenClaw.Tray.WinUI.exe                                    │
│  setup launch/focus, advanced setup route, self-restart     │
└─────────────────────────────────────────────────────────────┘
```

--------------------------------

### Setup Engine Project Structure

Source: https://github.com/openclaw/openclaw-windows-node/blob/main/docs/SETUP_ENGINE_REDESIGN.md

Details the file organization for the core `OpenClaw.SetupEngine` library and the `OpenClaw.SetupEngine.UI` component.

```text
src/OpenClaw.SetupEngine/
├── OpenClaw.SetupEngine.csproj    # net10.0 library
├── Program.cs                     # callable entry: --config, --headless, --dry-run, --rollback-on-failure
├── SetupPipeline.cs               # Sequential step orchestrator (132 lines)
├── SetupContext.cs                # Config model + shared state bag (217 lines)
├── SetupSteps.cs                  # All setup step implementations
├── TransactionJournal.cs          # Append-only JSONL journal (77 lines)
├── SetupLogger.cs                 # Structured JSONL logger (112 lines)
├── CommandRunner.cs               # Concrete WSL/process command runner
├── RetryExecutor.cs               # Exponential backoff retry
├── StubNodeCapability.cs          # Minimal capability stubs for pairing
└── default-config.json            # THE source of truth for all config values

src/OpenClaw.SetupEngine.UI/
├── OpenClaw.SetupEngine.UI.csproj # WinAppSDK 2.1.3 library referenced by tray
├── SetupWindow.xaml / .xaml.cs    # 720×820 window, Mica, title bar, navigation, setup events
└── Pages/
    ├── WelcomePage.xaml / .cs     # Logo, info card, Install button + ContentDialog
    ├── CapabilitiesPage.xaml / .cs # 2-column grid with icons + descriptions
    ├── ProgressPage.xaml / .cs    # Live step rows + streaming log viewer
    ├── PermissionsPage.xaml / .cs # 5 permission checks + Open Settings buttons
    └── CompletePage.xaml / .cs    # Party popper, amber banner, startup toggle
```

--------------------------------

### Apply Setup Code via Tray MCP

Source: https://github.com/openclaw/openclaw-windows-node/blob/main/docs/CONNECTION_PROTOCOL_RESEARCH.md

Applies a setup code through the tray MCP using the app.connection.applySetupCode tool. This is part of the RealGateway_QrSetupCodeFlow_ReconnectsThroughTrayMcp test.

```javascript
app.connection.applySetupCode
```

--------------------------------

### Build Tray-Hosted UI

Source: https://github.com/openclaw/openclaw-windows-node/blob/main/docs/SETUP_ENGINE_REDESIGN.md

Builds the tray-hosted UI for the OpenClaw Setup Engine for a specific runtime.

```powershell
# Build tray-hosted UI
dotnet build src\OpenClaw.Tray.WinUI\OpenClaw.Tray.WinUI.csproj -r win-x64
```

--------------------------------

### Build Local Inno Installer

Source: https://github.com/openclaw/openclaw-windows-node/blob/main/DEVELOPMENT.md

Builds unsigned installer EXEs locally using a PowerShell script. Use -Fast for quick iteration with ZIP compression, or -NoPublish to recompile Inno only.

```powershell
# Fast x64 installer for Windows Sandbox smoke tests
.\scripts\build-inno-local.ps1 -Arch x64 -Fast
```

```powershell
# Recompile Inno only after changing installer.iss
.\scripts\build-inno-local.ps1 -Arch x64 -Fast -NoPublish
```

```powershell
# Build both release-shaped architectures locally
.\scripts\build-inno-local.ps1 -Arch All
```

--------------------------------

### Generate Openclaw QR Setup Code

Source: https://github.com/openclaw/openclaw-windows-node/blob/main/docs/CONNECTION_PROTOCOL_RESEARCH.md

Generates a real openclaw QR setup code in JSON format within WSL. This is used to apply setup codes through the tray MCP.

```bash
openclaw qr --json
```

--------------------------------

### Copy English Resource File

Source: https://github.com/openclaw/openclaw-windows-node/blob/main/docs/LOCALIZATION.md

Start by copying the English resource file as a template for a new language.

```bash
src/OpenClaw.Tray.WinUI/Strings/en-us/Resources.resw
```

--------------------------------

### Windows Node Development Setup

Source: https://github.com/openclaw/openclaw-windows-node/blob/main/docs/WINDOWS_NODE_ARCHITECTURE.md

Steps to clone the repository, build the project, and run the OpenClaw tray application. Requires .NET 10.0 SDK and Windows 10/11.

```powershell
git clone https://github.com/shanselman/openclaw-windows-hub.git
cd openclaw-windows-hub
.\build.ps1
dotnet run --project src\OpenClaw.Tray.WinUI\OpenClaw.Tray.WinUI.csproj
```

--------------------------------

### SetupStep Base Class

Source: https://github.com/openclaw/openclaw-windows-node/blob/main/docs/SETUP_ENGINE_REDESIGN.md

Abstract base class for all setup steps in the pipeline. Defines the interface for executing a step, rolling back, and checking skip conditions.

```csharp
public abstract class SetupStep
{
    public abstract string Id { get; }
    public abstract string DisplayName { get; }
    public abstract Task<StepResult> ExecuteAsync(SetupContext ctx, CancellationToken ct);
    public virtual Task RollbackAsync(SetupContext ctx, CancellationToken ct) => Task.CompletedTask;
    public virtual bool CanSkip(SetupContext ctx) => false;
    public virtual bool CanRetry => true;
    public virtual RetryPolicy Retry => RetryPolicy.Default;
}
```

--------------------------------

### OnboardingWindow TryCompleteOnboarding

Source: https://github.com/openclaw/openclaw-windows-node/blob/main/docs/ONBOARDING_V2.md

Details how OnboardingWindow.TryCompleteOnboarding treats V2Route.AllSet as the terminal setup page. The bridge's Finished event closes the window, initiating shared completion logic.

```csharp
`OnboardingWindow.TryCompleteOnboarding` treats
`V2Route.AllSet` as the terminal setup page. The bridge's `Finished` event
closes the window, which routes through the shared completion logic —
persisting `Settings.AutoStart` via `AutoStartManager`, firing
`OnboardingCompleted`, and launching `HubWindow` on the chat tab when
setup is complete.
```

--------------------------------

### Start Local OpenClaw Gateway

Source: https://github.com/openclaw/openclaw-windows-node/blob/main/DEVELOPMENT.md

Command to start a local OpenClaw gateway instance, typically used for local development and testing.

```bash
cd ~/openclaw && npx openclaw gateway
```

--------------------------------

### Setup Code Decoding and Pairing Flow

Source: https://github.com/openclaw/openclaw-windows-node/blob/main/docs/CONNECTION_ARCHITECTURE.md

Describes the sequence of operations when applying a setup code, from decoding and validation to creating a gateway record, clearing tokens, connecting, and persisting the device token after successful pairing.

```csharp
1. `ApplySetupCodeAsync(code)` decodes and validates
2. Creates/updates a `GatewayRecord` with the bootstrap token
3. Clears stored device tokens (fresh pairing)
4. Connects to the new gateway
5. Gateway returns `hello-ok.auth.deviceToken` after pairing
6. Connection manager persists the device token to the identity file
```

--------------------------------

### Startup Wiring for Connection Management

Source: https://github.com/openclaw/openclaw-windows-node/blob/main/docs/CONNECTION_ARCHITECTURE.md

Illustrates the sequence of object creation and subscription for initializing the gateway connection system in the tray application. This setup ensures proper dependency injection and event handling.

```csharp
1. Create GatewayRegistry(dataDir)
2. Create CredentialResolver(identityReader)
3. Create GatewayClientFactory()
4. Create NodeConnector(logger)
5. Create SshTunnelManager(tunnelService, logger)
6. Create GatewayConnectionManager(resolver, factory, registry, ...,
                                    nodeConnector, tunnelManager)
7. Subscribe to StateChanged → update tray icon + hub window
8. Subscribe to OperatorClientChanged → wire/unwire 25+ data event handlers
9. Subscribe to NodeConnector.ClientCreated → NodeService.AttachClient
10. Call ConnectAsync() → connects to active gateway
```

--------------------------------

### Current Windows Setup Diagram

Source: https://github.com/openclaw/openclaw-windows-node/blob/main/docs/WINDOWS_NODE_ARCHITECTURE.md

Illustrates the current architecture where a Windows PC connects to a Mac gateway via WSL2 for headless node execution and a separate tray app for operator functions. Highlights limitations in native Windows agent capabilities.

```text
┌─────────────────────────────────────────────────┐
│  Mac mini (gateway host)                        │
│  ┌───────────────────────────────────────────┐  │
│  │ openclaw gateway  (ws://127.0.0.1:18789)  │  │
│  │ macOS native node (camera, canvas, screen) │  │
│  └───────────────────────────────────────────┘  │
└───────────────────────┬─────────────────────────┘
                        │ Tailnet / LAN
┌───────────────────────┴─────────────────────────┐
│  Windows PC                                      │
│  ┌────────────────────┐  ┌────────────────────┐ │
│  │ WSL2 (Ubuntu)      │  │ OpenClaw.Tray      │ │
│  │ openclaw node run  │  │ (WS operator only) │ │
│  │ headless: exec only│  │ Quick Send, Chat   │ │
│  └────────────────────┘  └────────────────────┘ │
└─────────────────────────────────────────────────┘
```

--------------------------------

### Check Prerequisites and Build Projects

Source: https://github.com/openclaw/openclaw-windows-node/blob/main/README.md

Use the build script to verify that all necessary prerequisites are installed before building the projects. This script can also be used to build all projects or specific ones.

```powershell
# Check prerequisites
.\build.ps1 -CheckOnly

# Build all projects
.\build.ps1

# Build specific project
.\build.ps1 -Project WinUI
```

--------------------------------

### Sign-in Form Example

Source: https://github.com/openclaw/openclaw-windows-node/blob/main/src/skills/windows-a2ui/SKILL.md

This JSONL snippet defines a sign-in form with email and password fields, and a submit button. It demonstrates component declaration, data binding, and action context for a sign-in operation.

```jsonl
{"surfaceUpdate":{"surfaceId":"main","components":[
  {"id":"root","component":{"Column":{"alignment":"stretch","children":{"explicitList":["title","emailField","pwField","submit"]}}}},
  {"id":"title","component":{"Text":{"text":{"literalString":"Sign in"},"usageHint":"h2"}}},
  {"id":"emailField","component":{"TextField":{"label":{"literalString":"Email"},"text":{"path":"/form/email"},"textFieldType":"shortText"}}},
  {"id":"pwField","component":{"TextField":{"label":{"literalString":"Password"},"text":{"path":"/form/password"},"textFieldType":"obscured"}}},
  {"id":"submit","component":{"Button":{"primary":true,"child":"submitLabel","dataBinding":["/form"],"action":{"name":"signIn","context":[
    {"key":"email","value":{"path":"/form/email"}},
    {"key":"password","value":{"path":"/form/password"}}
  ]}}}},
  {"id":"submitLabel","component":{"Text":{"text":{"literalString":"Sign in"}}}}
]}}
{"dataModelUpdate":{"surfaceId":"main","path":"/","contents":[
  {"key":"form","valueMap":[{"key":"email","valueString":""},{"key":"password","valueString":""}]}
]}}
{"beginRendering":{"surfaceId":"main","root":"root","catalogId":"a2ui-v0.8"}}
```

--------------------------------

### StepResult Record

Source: https://github.com/openclaw/openclaw-windows-node/blob/main/docs/SETUP_ENGINE_REDESIGN.md

A record type representing the outcome of a setup step, including its status, an optional message, and an exception if one occurred.

```csharp
public sealed record StepResult(StepOutcome Outcome, string? Message = null, Exception? Exception = null);
```

--------------------------------

### Synthesize Text to Stream Async

Source: https://github.com/openclaw/openclaw-windows-node/blob/main/docs/WINDOWS_NODE_ARCHITECTURE.md

Example of using Windows.Media.SpeechSynthesis to convert text to an audio stream. This is a candidate implementation path and not yet a fully integrated node command.

```csharp
var synth = new SpeechSynthesizer();
var stream = await synth.SynthesizeTextToStreamAsync(text);
// Play via MediaElement or save to file
```

--------------------------------

### Launch Tray Application

Source: https://github.com/openclaw/openclaw-windows-node/blob/main/DEVELOPMENT.md

Start the OpenClaw Tray application for manual testing and configuration. This command is used to launch the app from the command line.

```bash
# Launch the app: dotnet run --project src/OpenClaw.Tray.WinUI
dotnet run --project src/OpenClaw.Tray.WinUI
```

--------------------------------

### Node Client Creation Paths

Source: https://github.com/openclaw/openclaw-windows-node/blob/main/docs/CONNECTION_ARCHITECTURE.md

Details the two distinct paths for creating the Node client. One is for normal operation via `NodeConnector`, and the other is for local setup during WSL gateway configuration.

```csharp
// Normal path:
NodeConnector.Create() → fires ClientCreated → NodeService.AttachClient()

// Local setup path:
NodeService.ConnectAsync() creates its own client (used only during WSL local gateway setup)
```

--------------------------------

### Headless Runner CLI Arguments

Source: https://github.com/openclaw/openclaw-windows-node/blob/main/docs/SETUP_ENGINE_REDESIGN.md

Common command-line arguments for running the OpenClaw Setup Engine in headless mode. Exit codes: 0 for success, 1 for failure.

```bash
OpenClaw.SetupEngine.Program.Main(args)                    # uses bundled default-config.json
OpenClaw.SetupEngine.Program.Main(["--config", "custom.json"])
OpenClaw.SetupEngine.Program.Main(["--headless"])
OpenClaw.SetupEngine.Program.Main(["--dry-run"])           # validate config, don't execute
OpenClaw.SetupEngine.Program.Main(["--rollback-on-failure"])
OpenClaw.SetupEngine.Program.Main(["--no-rollback-on-failure"])
OpenClaw.SetupEngine.Program.Main(["--log-path", "./trace.log"])
```

--------------------------------

### Valid A2UIValue Examples

Source: https://github.com/openclaw/openclaw-windows-node/blob/main/docs/a2ui/data-and-actions.md

Demonstrates various valid configurations for A2UIValue, including literal strings, numbers, booleans, arrays, and paths into the data model. Also shows implicit initialization combining a literal with a path.

```jsonc
// All of these are valid:
{ "literalString": "Hello" }
{ "literalNumber": 42 }
{ "literalBoolean": true }
{ "literalArray": ["a", "b", "c"] }   // array-of-string only
{ "path": "/user/name" }              // bind to data-model location

// "Implicit initialization" (literal + path together):
{ "literalString": "default", "path": "/form/title" }
// → on first resolve, the client writes "default" to /form/title,
//   then binds. After that it's a path binding.
```

--------------------------------

### Clone Repository and Navigate

Source: https://github.com/openclaw/openclaw-windows-node/blob/main/DEVELOPMENT.md

Standard procedure to fork, clone the repository, and navigate into the project directory to begin development.

```bash
git clone https://github.com/YOUR_USERNAME/openclaw-windows-hub.git
cd openclaw-windows-hub
```

--------------------------------

### Build and Run Onboarding Wizard Test

Source: https://github.com/openclaw/openclaw-windows-node/blob/main/DEVELOPMENT.md

Sequence of commands to build the WinUI project and launch the application for testing the onboarding wizard locally.

```bash
./build.ps1 -Project WinUI
# Then launch the exe
```

--------------------------------

### Successful GET Probe Request

Source: https://github.com/openclaw/openclaw-windows-node/blob/main/docs/MCP_MODE.md

This curl command performs a successful GET request to probe the server's availability. It includes the necessary Authorization header.

```powershell
curl http://127.0.0.1:8765/ -H "Authorization: Bearer <token>"
```

--------------------------------

### Get Device Status

Source: https://github.com/openclaw/openclaw-windows-node/blob/main/src/OpenClaw.WinNode.Cli/skill.md

Gets live system health data for specified sections (os, cpu, memory, disk, battery). If sections are omitted, all are collected. Privacy note: reveals battery level, network type, and disk usage.

```json
{
  "sections": ["os","cpu","memory","disk","battery"]  // optional; omit for all
}
```

--------------------------------

### Run Project

Source: https://github.com/openclaw/openclaw-windows-node/blob/main/DEVELOPMENT.md

Executes the specified .NET project. Use the -c Debug flag for verbose output.

```bash
dotnet run --project src/OpenClaw.Tray.WinUI
```

```bash
dotnet run --project src/OpenClaw.Tray.WinUI -c Debug
```

--------------------------------

### system.run.prepare

Source: https://github.com/openclaw/openclaw-windows-node/blob/main/src/OpenClaw.WinNode.Cli/skill.md

Pre-flight a `system.run` invocation without executing it. Returns the parsed plan.

```APIDOC
## system.run.prepare

Pre-flight a `system.run` invocation. Same arguments as `system.run`. Returns the parsed plan (`argv`, `cwd`, `rawCommand`, `agentId`, `sessionKey`) without executing.
```

--------------------------------

### Get App Setting

Source: https://github.com/openclaw/openclaw-windows-node/blob/main/src/OpenClaw.WinNode.Cli/skill.md

Reads a local app setting by its name. The type of the returned value depends on the specific setting.

```json
{"name": "string"}
```

--------------------------------

### Get App Sessions

Source: https://github.com/openclaw/openclaw-windows-node/blob/main/src/OpenClaw.WinNode.Cli/skill.md

Retrieves a list of active sessions, optionally filtered by agent ID. Returns an array of session details.

```json
{"agentId": "string"}
```

--------------------------------

### device.status

Source: https://github.com/openclaw/openclaw-windows-node/blob/main/src/OpenClaw.WinNode.Cli/skill.md

Gets live system health data, including OS, CPU, memory, disk, and battery status. Specific sections can be requested.

```APIDOC
## device.status

### Description
Get live system health data.

### Method
(Implicitly GET or similar, as it retrieves system status)

### Endpoint
(Not explicitly defined, assumed to be a method call within the CLI context)

### Parameters
#### Request Body
- **sections** (array of strings) - Optional - An array of strings specifying which sections to collect data from (e.g., "os", "cpu", "memory", "disk", "battery"). Omit to collect all sections.

### Response
#### Success Response
A map containing:
- **collectedAt** (string) - ISO-8601 formatted timestamp of when the data was collected.
- Section-specific data (e.g., os, cpu, memory, disk, battery). Each section may contain an `error` field if data was unavailable.
- Legacy fields: `thermal`, `storage`, `network`, `uptimeSeconds`.

**Battery Sub-object**: `{ level (number), state (string, "charging"|"discharging"|"unknown"), lowPowerModeEnabled (boolean) }`.
```

--------------------------------

### Initialize and Navigate WebView2

Source: https://github.com/openclaw/openclaw-windows-node/blob/main/DEVELOPMENT.md

Initializes the WebView2 environment and navigates to the chat URL. Ensure the WebView2 control is created in XAML and the environment is initialized on window load.

```csharp
await WebView.EnsureCoreWebView2Async();
WebView.CoreWebView2.Navigate(chatUrl);
```

--------------------------------

### Get App Config Value

Source: https://github.com/openclaw/openclaw-windows-node/blob/main/src/OpenClaw.WinNode.Cli/skill.md

Reads a gateway configuration value at a specified dot-path. If the path is omitted, the full config tree is returned.

```json
{"path": "string"}
```

--------------------------------

### Run Full Repo Build

Source: https://github.com/openclaw/openclaw-windows-node/blob/main/AGENTS.md

Execute the full repository build script. This is a prerequisite for running shared and tray tests.

```bash
./build.ps1
```

--------------------------------

### Operator Client Creation

Source: https://github.com/openclaw/openclaw-windows-node/blob/main/docs/CONNECTION_ARCHITECTURE.md

Demonstrates the creation process for the operator client, which is a single instance managed by `GatewayConnectionManager`. It highlights the disposal of old instances before new ones are created.

```csharp
OpenClawGatewayClient operatorClient = GatewayClientFactory.Create();
// Old instance disposed before creating new one.
// OperatorClientChanged event notifies consumers of swaps.
```

--------------------------------

### XAML Root Element Example (Window)

Source: https://github.com/openclaw/openclaw-windows-node/blob/main/docs/XAML_COMPILER_BUG.md

This snippet shows the expected XAML root element declaration using the base 'Window' type.

```xml
<Window x:Class="CrashRepro.MainWindow" ...>
   </Window>
```

--------------------------------

### WebView2 Navigation Guard

Source: https://github.com/openclaw/openclaw-windows-node/blob/main/DEVELOPMENT.md

Implements a navigation guard to prevent the WebView2 control from navigating to external hosts. This event handler is triggered before navigation starts.

```csharp
WebView.CoreWebView2.NavigationStarting += (s, e) => {
    if (!e.Uri.StartsWith(allowedHost)) {
        e.Cancel = true;
    }
};
```

--------------------------------

### Data Model Entry Examples

Source: https://github.com/openclaw/openclaw-windows-node/blob/main/src/skills/windows-a2ui/SKILL.md

Shows the structure for entries within a dataModelUpdate. Each entry has a key and a value, which can be a string, number, boolean, or a nested map.

```json
{ "key": "name",     "valueString":  "Alice" }
```

```json
{ "key": "count",    "valueNumber":  3 }
```

```json
{ "key": "enabled",  "valueBoolean": true }
```

```json
{
  "key": "user",     "valueMap": [
  { "key": "first",  "valueString": "Alice" },
  { "key": "last",   "valueString": "Smith" }
]
}
```

--------------------------------

### OnboardingV2Bridge Service Wiring

Source: https://github.com/openclaw/openclaw-windows-node/blob/main/docs/ONBOARDING_V2.md

Illustrates the mapping between real services and V2 state fields within the OnboardingV2Bridge. This helps understand how different service events and states are integrated into the V2 onboarding flow.

```csharp
Service wiring is centralised in
[`OnboardingV2Bridge`](../src/OpenClaw.Tray.WinUI/Onboarding/V2/OnboardingV2Bridge.cs):

| Real service | V2 state field | Notes |
| --- | --- | --- |
| `LocalGatewaySetupEngine.StateChanged` | `LocalSetupRows`, `LocalSetupErrorMessage` | Re-uses `LocalSetupProgressStageMap` so setup stage behavior stays consistent. |
| `PermissionChecker.CheckAllAsync` + `SubscribeToAccessChanges` | `Permissions` | Snapshot list of `PermissionRowSnapshot`. Marshals back to UI thread. |
| `SettingsManager.GetEffectiveGatewayUrl` | `GatewayUrl` | Flips `ws://` → `http://` for the browser-launch link. |
| `SettingsManager.AutoStart` ↔ `LaunchAtStartup` | `LaunchAtStartup` | Two-way: initial value from settings; toggle change calls `_settings.Save()`. |
| `Settings.EnableNodeMode` | `NodeModeActive` | Seeded once at construction. |
| `GatewayRegistry` + WSL distro probe | `ExistingGateway` | Drives Welcome CTA/warning behavior for none, app-owned local WSL, and external-only connections.
```

--------------------------------

### Get Windows Location

Source: https://github.com/openclaw/openclaw-windows-node/blob/main/docs/WINDOWS_NODE_TESTING.md

Use the `location.get` command to retrieve the current location of the Windows device. This requires user permission and adherence to Windows location settings.

```markdown
`location.get` | Get Windows location | Uses Windows location permission/settings
```

--------------------------------

### Build WinUI Project with Platform Targets

Source: https://github.com/openclaw/openclaw-windows-node/blob/main/DEVELOPMENT.md

Execute the build script to correctly build the WinUI project with necessary platform-specific targets.

```bash
./build.ps1 -Project WinUI
```

--------------------------------

### Local Development Build and Test Commands

Source: https://github.com/openclaw/openclaw-windows-node/blob/main/DEVELOPMENT.md

Commands to build the project, run unit tests, and execute the tray application locally during development.

```bash
dotnet build
dotnet test
dotnet run --project src/OpenClaw.Tray.WinUI
```

--------------------------------

### GDI Icon Creation and Handle Management

Source: https://github.com/openclaw/openclaw-windows-node/blob/main/DEVELOPMENT.md

Demonstrates the correct pattern for creating icons from bitmaps, ensuring GDI handles are properly managed to prevent leaks. This involves cloning the icon and explicitly destroying the GDI handle.

```csharp
// Create bitmap
using var bitmap = new Bitmap(16, 16);
using var graphics = Graphics.FromImage(bitmap);
graphics.DrawSomething(...);

// Convert to icon (creates GDI handle)
var hIcon = bitmap.GetHicon();
var icon = Icon.FromHandle(hIcon);

// Clone to own the data
var result = (Icon)icon.Clone();

// CRITICAL: Destroy the GDI handle
DestroyIcon(hIcon);

return result;
```

--------------------------------

### Execute External Command with PowerShell

Source: https://github.com/openclaw/openclaw-windows-node/blob/main/docs/WINDOWS_NODE_ARCHITECTURE.md

Starts a new process to execute a command using PowerShell, capturing standard output and error. Requires local approval enforcement.

```csharp
var process = new Process {
    StartInfo = new ProcessStartInfo {
        FileName = "powershell.exe",
        Arguments = $"-Command \"{command}\"",
        RedirectStandardOutput = true,
        RedirectStandardError = true,
        UseShellExecute = false,
        CreateNoWindow = true,
        WorkingDirectory = cwd
    }
};
process.Start();
string stdout = await process.StandardOutput.ReadToEndAsync();
string stderr = await process.StandardError.ReadToEndAsync();
await process.WaitForExitAsync();
```

--------------------------------

### system.execApprovals.get Command

Source: https://github.com/openclaw/openclaw-windows-node/blob/main/src/OpenClaw.WinNode.Cli/skill.md

No parameters are required for the system.execApprovals.get command, which retrieves the active execution policy.

```json
{ enabled, defaultAction, rules: [{pattern, action, shells?, description?, enabled}] }
```

--------------------------------

### Get High Accuracy Geolocation

Source: https://github.com/openclaw/openclaw-windows-node/blob/main/docs/WINDOWS_NODE_ARCHITECTURE.md

Retrieves the current geographical position with high accuracy using the Geolocator API. Note that accuracy can vary significantly on desktop PCs.

```csharp
var geolocator = new Geolocator {
    DesiredAccuracy = PositionAccuracy.High
};
var position = await geolocator.GetGeopositionAsync();
// position.Coordinate.Point.Position.Latitude / .Longitude
```

--------------------------------

### Build Tray App for x64

Source: https://github.com/openclaw/openclaw-windows-node/blob/main/DEVELOPMENT.md

Command to build the WinUI tray application specifically for the x64 architecture. This targets Intel/AMD processors.

```bash
dotnet build src/OpenClaw.Tray.WinUI -r win-x64
```

--------------------------------

### List WSL Distros and Check Gateway Status

Source: https://github.com/openclaw/openclaw-windows-node/blob/main/docs/WSL_GATEWAY_ADMIN.md

Lists all installed WSL distributions and indicates if the OpenClawGateway is running. This command helps verify the presence and state of the gateway.

```powershell
# Lists WSL distros and shows whether OpenClawGateway is running.
wsl.exe --list --verbose
```

--------------------------------

### Run Build and Tests

Source: https://github.com/openclaw/openclaw-windows-node/blob/main/docs/MISSION_CONTROL.md

Execute the build script and run unit tests for shared and tray projects. Ensure no restore is performed before testing.

```powershell
.\build.ps1
dotnet test .\tests\OpenClaw.Shared.Tests\OpenClaw.Shared.Tests.csproj --no-restore
dotnet test .\tests\OpenClaw.Tray.Tests\OpenClaw.Tray.Tests.csproj --no-restore
```

--------------------------------

### Log and Rethrow Exception with Reconnect

Source: https://github.com/openclaw/openclaw-windows-node/blob/main/docs/CODE_REVIEW.md

This snippet demonstrates logging an exception and then rethrowing it, triggering a reconnection process. This is an example of inconsistent error handling compared to silent failures.

```csharp
// Logged and rethrown
public async Task CheckHealthAsync()
{
    catch (Exception ex)
    {
        _logger.Error("Health check failed", ex);
        StatusChanged?.Invoke(this, ConnectionStatus.Error);
        await ReconnectWithBackoffAsync();  // Line 111 - triggers reconnect
    }
}
```

--------------------------------

### system.which Command Parameters

Source: https://github.com/openclaw/openclaw-windows-node/blob/main/src/OpenClaw.WinNode.Cli/skill.md

Parameters for the system.which command, used to resolve binary names to their absolute paths.

```json
{"bins": ["git", "node", "powershell"]}
```

--------------------------------

### Get OpenClaw Version using PowerShell Script

Source: https://github.com/openclaw/openclaw-windows-node/blob/main/docs/VERSIONING.md

This snippet demonstrates how to use `Get-OpenClawVersion.ps1` to retrieve different parts of the application version, such as the full SemVer or Major.Minor.Patch, for local scripts.

```powershell
.\scripts\Get-OpenClawVersion.ps1 -Variable SemVer
.\scripts\Get-OpenClawVersion.ps1 -Variable MajorMinorPatch
```

--------------------------------

### Get Device Location

Source: https://github.com/openclaw/openclaw-windows-node/blob/main/src/OpenClaw.WinNode.Cli/skill.md

Retrieves the device's current geographic location with optional accuracy, max age, and timeout settings. Requires Location capability and OS permission.

```json
{
  "accuracy": "default|high",  // optional, default "default"
  "maxAge": 30000,             // ms; return a cached fix if younger than this
  "locationTimeout": 10000     // ms; fail if no fix within this time
}
```

--------------------------------

### List Cameras on Node

Source: https://github.com/openclaw/openclaw-windows-node/blob/main/README.md

Retrieve a list of available camera devices on the remote Windows node.

```bash
# List cameras
openclaw nodes invoke --node <id> --command camera.list
```

--------------------------------

### Run Unit Tests with Detailed Output

Source: https://github.com/openclaw/openclaw-windows-node/blob/main/DEVELOPMENT.md

Execute local development unit tests with increased verbosity to see detailed output.

```bash
# Run with detailed output
dotnet test --verbosity detailed
```

--------------------------------

### Use Inline SVG for Icons

Source: https://github.com/openclaw/openclaw-windows-node/blob/main/src/skills/windows-a2ui/SKILL.md

This example demonstrates using an inline SVG icon within an Image component, which is the preferred method for icons and other vector graphics on the Windows node.

```json
{
  "id": "checkIcon",
  "component": {
    "Image": {
      "url": {"literalString": "data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'><path d='M5 12l4 4 10-10' stroke='currentColor' stroke-width='2' fill='none'/></svg>"},
      "fit": "contain",
      "usageHint": "icon"
    }
  }
}
```

--------------------------------

### Outbound A2UIAction Example

Source: https://github.com/openclaw/openclaw-windows-node/blob/main/src/skills/windows-a2ui/SKILL.md

This JSON structure represents an outbound A2UIAction sent when a Button is clicked. The 'context' field contains flattened data from the button's 'action.context' array.

```json
{
  "name":              "submitForm",
  "surfaceId":         "main",
  "sourceComponentId": "btnPrimary",
  "context":           { "email": "alice@example.com" },
  "timestamp":         "2026-04-27T18:12:34.000Z"
}
```

--------------------------------

### Icon Caching Example

Source: https://github.com/openclaw/openclaw-windows-node/blob/main/DEVELOPMENT.md

Shows a pattern for caching icon objects to avoid repeated GDI operations. Static variables are used to hold references to frequently used icons.

```csharp
private static Icon? _connectedIcon;
private static Icon? _disconnectedIcon;
// ... etc
```

--------------------------------

### Code-Behind Example (Inheriting from WindowEx)

Source: https://github.com/openclaw/openclaw-windows-node/blob/main/docs/XAML_COMPILER_BUG.md

This C# code snippet demonstrates a code-behind class inheriting from 'WindowEx', which can trigger the XAML compiler bug if the XAML root is not also 'WindowEx'.

```csharp
public sealed partial class MainWindow : WindowEx { ... }
```

--------------------------------

### system.run

Source: https://github.com/openclaw/openclaw-windows-node/blob/main/src/OpenClaw.WinNode.Cli/skill.md

Executes a shell command. Subject to the local exec approval policy.

```APIDOC
## system.run

Execute a shell command. Subject to the local exec approval policy at `%LOCALAPPDATA%\OpenClawTray\exec-policy.json`.

### Parameters

#### Request Body

- **command** (string or string[]) - Required - The command to execute.
- **args** (string[]) - Optional - Arguments appended to the command.
- **shell** (string) - Optional - The shell to use (powershell|pwsh|cmd|bash).
- **cwd** (string) - Optional - The current working directory.
- **timeoutMs** (integer) - Optional - Timeout in milliseconds (default 30000).
- **env** (object) - Optional - Environment variables (e.g., { "KEY": "VALUE" }).

### Response

#### Success Response (200)

- **stdout** (string) - Standard output of the command.
- **stderr** (string) - Standard error of the command.
- **exitCode** (integer) - The exit code of the command.
- **timedOut** (boolean) - Whether the command timed out.
- **durationMs** (integer) - Duration of the command execution in milliseconds.
```