DOCSEARCHbyAlgolia
Submit Docs

OpenClaw Windows Hub

repository·main·Indexed 24 days ago

https://github.com/openclaw/openclaw-windows-node

A native Windows companion suite for the OpenClaw AI personal assistant. It provides a system tray interface, connection management, and local node capabilities. The repository includes a Native WinUI implementation of the A2UI v0.8 specification, documentation on the A2UI wire protocol and standard catalog, and guides for managing a WSL gateway and configuring Node Mode for agent control.

Tokens
82.4K
Snippets
125
Records
329
Agent score
84%

What's inside openclaw-windows-node

  1. Overview of A2UI v0.8 Implementation

    main

    A2UI (Agent-to-User Interface) v0.8 is a specification for UI components and protocols used to bridge agents and users. This repository contains a Native WinUI implementation (src/OpenClaw.Tray.WinUI/A2UI/) which is compared against the Lit reference implementation (web components) and the official specification.

    Key implementation details for the WinUI version include:

    • Component Coverage: Full coverage of the 18 standard catalog components.
    • Data Model: Uses strict RFC 6901 JSON-pointer paths.
    • Action Transport: Uses a debounced dispatcher that sends requests to a gateway via agent.request.
    • Security: Includes HTTPS+allowlist for media components, DNS-rebinding protection via SocketsHttpHandler.ConnectCallback for Image, and secret redaction for paths containing password, secret, or token.
    • List Virtualization: Implemented via ItemsRepeater with cached child templates.

  2. Review Setup Wizard Screen Flow

    main

    The setup wizard follows a standardized sequence of screens for gateway configuration and onboarding:

    #ScreenDescription
    01Welcome + security noticeIncludes a selectable RichTextBlock body.
    02Setup modeUses a single-selection ListView (ItemContainer) with the first item selected by default.
    03Config handlingSingle-selection list with a standardized bottom bar.
    04Model/auth provider (collapsed)Features a "Skip for now" option pinned to the top and a More ▾ expander.
    05Model/auth provider (expanded)Full provider list view; expanding keeps "Skip for now" visible.
    06Auth methodSingle-selection list.
    07Text input stepUsed for API-key entry.
    08CapabilitiesRadio group with accessible names.

    Standard Navigation UI: All steps include a bottom action bar containing:

    • A standard Back button.
    • A primary Continue button (using AccentButtonStyle).
    • Subtle controls for More options, Skip, or Start over.

  3. A2UI v0.8 Component Catalog Overview

    main

    A2UI v0.8 defines a standard catalog of 18 components categorized into Containers, Display, and Interactive elements.

    Catalog-strict mode: A conformant client must recognize all 18 components. If an unknown component is encountered, the client must render an "unknown" placeholder rather than throwing an error.

    Data Binding Notation:

    • BoundValue: An A2UIValue tagged union, typically { literalString } or { path }.
    • Children: Represented as { explicitList: string[] } or { template: { dataBinding, componentId } }.

  4. Understand the Windows Platform Strategy and Node Roadmap

    main

    OpenClaw is evolving its Windows support from a limited WSL2-based setup to a native Windows experience. The goal is to transform OpenClaw.Tray.WinUI from a simple gateway client into a native Windows node.

    Currently, Windows users often rely on WSL2 for the gateway, which results in a headless experience lacking native UI integration, camera access, canvas surfaces, and native Windows notifications. The roadmap aims to provide the agent with 'eyes, hands, and a voice' on Windows by leveraging native Windows APIs through the tray app, allowing it to function as a first-class node with capabilities like screen capture, camera access, and system execution.

  5. Review historical code quality and architecture findings

    main

    This document contains a point-in-time audit from May 2021. Note: Many findings regarding connection state machines, credential storage, and test coverage have been addressed in newer documentation.

    Before acting on recommendations in this file, consult the following for current status:

  6. What is the Gateway Protocol Drift Guard

    main

    The drift guard is a static testing mechanism in the Windows companion that prevents the OpenClawGatewayClient from silently drifting away from the upstream OpenClaw gateway protocol.

    While behavioral tests (like GatewayProtocolModelsTests) check if the client can parse specific JSON samples, the drift guard ensures the entire surface of methods, request fields, and response envelopes matches a pinned, hand-maintained mirror of the upstream schema. This prevents regressions where an upstream rename or a dropped API might otherwise pass unit tests if the test payloads remain static.

    Key Files

    • tests/OpenClaw.Shared.Tests/Protocol/gateway-protocol-snapshot.json: The pinned canonical schema mirror. You must edit this file when the upstream protocol changes.
    • tests/OpenClaw.Shared.Tests/Protocol/GatewayProtocolDriftTests.cs: The guard implementation that cross-checks the snapshot against the client code.

  7. Implement A2A Extension for A2UI v0.8

    main

    A2UI is implemented as a typed extension of A2A.

    • Extension URI: https://a2ui.org/a2a-extension/a2ui/v0.8
    • MIME Type: application/json+a2ui

    Capability Negotiation:

    • Agent: Advertises supportedCatalogIds (string array) and acceptsInlineCatalogs (boolean) in AgentCapabilities.extensions.
    • Client: Declares support via transport-specific signaling (e.g., X-A2A-Extensions HTTP header). Clients can also include a2uiClientCapabilities in A2A message metadata, specifying supportedCatalogIds and inlineCatalogs.

    Note: Push/pull operations, retry, backpressure, and authentication are handled by the underlying A2A layer.

  8. Understand Tray action UX and error handling

    main

    Tray actions are designed to guide users toward configuration when prerequisites are missing rather than failing silently:

    • Chat: Resolves credentials from the active registry record and per-gateway identity. If no usable credential exists, it opens Connection settings.
    • Canvas: Opens only when the Windows node is initialized, paired, and the Canvas capability is enabled in settings; otherwise, it opens Connection settings.
    • Quick Send: Uses the live operator client and surfaces scope/pairing errors from gateway calls.
    • system.run and system.run.prepare: These commands are gated by the NodeSystemRunEnabled setting (defaults to true). If disabled, these commands are removed from advertised capabilities and any invocations will be rejected.

  9. Understand the architectural ownership rules

    main

    The project follows a strict decomposition pattern to avoid 'god objects'. When implementing or refactoring code, adhere to these layer responsibilities:

    • View (XAML + code-behind): Responsible for layout, named-control wiring, lifecycle event forwarding, and minimal WinUI-only adapters. Prohibited: Gateway JSON parsing, polling loops, settings mutation, or imperative row factories.
    • ViewModel / Presenter: Responsible for observable state, commands, and pure projection. These should be WinUI-free where practical (no Microsoft.UI.Xaml, Application.Current, Window, Frame, Brush, Color, or concrete SettingsManager) and must be unit-tested.
    • Service: Responsible for IO, gateway calls, registry/settings persistence, timers, process execution, and WebSocket/MCP hosting. Prohibited: UI types and starting background work from constructors.
    • App (App.xaml.cs): Acts strictly as the composition root and handles top-level lifecycle only.

  10. Secure action context with dataBinding

    main

    To prevent sensitive data from leaking into outbound actions, the renderer uses dataBinding to scope which paths are allowed to be read into the action context.

    • Explicit Scope (Recommended): Declare dataBinding on the component as an array of paths or { "path": "..." } objects. Only these paths (and their subtrees) are included in the action.
    • Implicit Scope (Fallback): If no dataBinding is set, the scope is the union of all paths referenced by the component's non-action properties.
    • Secret Paths: Any path bound to a TextField of type obscured is automatically dropped from the implicit scope. To include a secret in an action, you must list it explicitly in the dataBinding array.

  11. Security: Action context scoping and secret redaction

    main

    The WinUI implementation enforces strict security boundaries for component actions to prevent data exfiltration.

    1. Action Context Scoping: When a component triggers an action, the BuildActionContext (defined in Rendering/IComponentRenderer.cs) restricts the available data. It collects allowed paths from the component's dataBinding array. If no explicit binding exists, it implicitly walks every A2UIValue.path referenced by the component's properties. An action's context[] entry is only resolved if it matches an allowed path (exact match or an ancestor with a / boundary).

    2. Secret Redaction: The SecretRedactor (Rendering/SecretRedactor.cs) strips sensitive paths from the context. It uses both registered paths (e.g., obscured TextField fields) and a substring denylist including password, secret, and token.

  12. Telemetry data boundaries and prohibited content

    main

    Telemetry must only contain low-cardinality operational diagnostics.

    Allowed data includes:

    • Component or operation names
    • Protocol choices
    • Coarse status and outcome values
    • Durations and counts
    • Coarse error categories or exception type names

    Prohibited data (DO NOT EXPORT):

    • User prompts, chat contents, or document contents
    • Screenshots, camera frames, audio, clipboard contents, or raw UI text
    • File contents or raw document text
    • Credentials, API keys, gateway tokens, bootstrap tokens, or device tokens
    • Full command input/output (unless specifically reviewed)
    • Arbitrary existing local logs exported wholesale