The onboarding wizard can install an app-owned WSL gateway, acquire a native Gateway MSIX through Microsoft Store and configure it, or connect to an existing gateway.
Native Local AI setup displays the current phase and completed steps while checking GPU readiness, verifying cached runtime/model files, starting the model, publishing the provider, reconnecting and testing real Gateway inference. File verification can take a minute or more for large models; it is not a download. Artifact acquisition retains the installation progress page and its actual download progress.
Reopening an incomplete native Local AI setup uses this Companion profile's saved Gateway ownership to offer Recover and use Local AI, including pending configuration writes not yet reflected in runtime status. Recovery preserves the healthy managed listener and uses the existing exact-model verification and conditional configuration guards, rather than reinstalling it.
An existing provider without matching saved ownership remains unmanaged by this profile. Setup explains how to reopen the original Companion profile and reconnect its original Gateway. Keep the ownership receipt; do not copy credentials or replace the provider. An independently detected Use this model choice remains separate and does not claim or restore Companion management.
After setup restarts Companion, destination handoff waits for native connection
startup and any already-admitted Local AI recovery before fresh model verification.
New preparation receipts start one execution window when issued, 31 minutes at
the default startup budget and longer with OPENCLAW_NATIVE_GATEWAY_START_TIMEOUT,
before restarting Companion. This includes old-process Local AI teardown, whose
guarded WSL Gateway restart may exceed five minutes. First acquisition and retry
retain that original deadline; neither can renew it. Destination receipts and
older preparation-v1 receipts retain five-minute unused admission and start their
execution window at first exclusive acquisition. Existing 13.5-minute execution
deadlines from earlier versions also remain unchanged. A restart with a different
startup override retains the stored deadline within supported bounds: 27 to 141
minutes for new preparations, and 13.5 to 141 minutes for destination and legacy
receipts.
Before that restart, SetupCompletionPreparation bounds the production finishing
operation, including finalization and restart publication, with one execution
window using the same startup-derived budget described above. Failed
attempts and explicit retries share its original monotonic deadline. Deadline or
window cancellation ends the presentation wait, not ownership of an admitted
write or restart. Delegates receive cooperative cancellation, but cleanup still
joins the actual work and prior page drain.
Completion retries and Back are unavailable while that work remains pending, and expiry cannot
admit another attempt. An uncertain finalization cannot replay unless the existing
owner confirms that only committed finalization remains to resume. A late restart
publication, including a committed-publication failure, never authorizes a second
launch. This in-process budget is separate from the persisted post-restart
handoff deadline described above.
A failed attempt remains available for explicit Retry,
but automatic reactivation does not show the same failure dialog again. Successful
runtime checks alone do not prove that a full, potentially longer chat turn has finished.
Readiness is withdrawn when the live Gateway reports configuration changes, without replaying setup or model activation. Unrelated chat usage and metadata updates do not withdraw readiness. Finishing failures retain localized timeout-phase guidance. If safe retry or Back is unavailable, the window's title-bar close action remains available. Once a restart process has launched, failed shutdown scheduling cannot launch another restart through Retry.
On a finishing failure, Back and Check readiness again share the bottom footer row. Check readiness again first updates recovery availability, then retries completion only when the existing owner permits it. Pending, expired or uncertain work is not replayed. There is no separate Refresh or Close button. Collect logs stays left-aligned below the failure message and opens the same sanitized diagnostics preview used in Settings, including this Companion profile's latest setup logs. Review the preview before copying or saving it. Collection failures stay visible on the page and can be retried. Native pre-restart completion failures also record the failed stage and sanitized exception in the setup log. If returning with Back fails during cleanup, readiness and navigation remain unavailable. Collect logs remains visible, and the title-bar close action can close the window. A readiness refresh cannot bypass the failed cleanup.
WSL Local AI withdrawal confirms a Gateway restart even when the saved provider is already absent. A previous Companion process may have removed the saved route without confirming that the running Gateway adopted it. An in-memory flag cannot prove that uncertainty cleared across Companion restarts. A completed managed startup that remains stopped or uninstalled fails readiness promptly instead of waiting for the full recovery deadline.
Native installation keeps its actions right-aligned in the footer: Back, then
Cancel setup (or Retry setup). Both share the setup footer minimum width
(SetupFooterButtonMinWidth, 180 DIPs) and their labels can wrap. Installation
progress is shown in the page body and in the companion's step timeline, not on
a separate footer row. Other setup pages use SetupFooterPanel, which keeps
actions in one right-aligned row and stacks them one per row when the page
column is too narrow, including longer localized finishing-failure labels.
The Gateway chooser shows Local AI availability in a subtle, transparent status row below all three choices and above "Remote, local MCP or set up later", not inside the WSL choice. Its GPU details and accessible announcement describe the PC; existing hardware and WSL eligibility checks still apply. A successful native-support check enables the native choice without a redundant success line. The accent icon tile follows native availability: native uses it when available, otherwise WSL does. Unavailable/checking native support and Windows Update recovery remain visible in their existing support card.
The shared WizardOnboardingPolicy removes optional setup cards from both WinUI
paths and the headless WSL runner. Security consent, telemetry opt-in, agent name,
AI provider/authentication/model selection, permissions and actionable errors
remain explicit.
- Existing config detected, QuickStart, Model check, How channels work, Web search, Skills status and Gateway notes are acknowledged without rendering.
- Setup mode chooses the offered keep-existing-model mode, otherwise QuickStart. Config handling keeps current values. Channel and search selectors choose the offered skip value. Skill configuration/dependency installation is deferred.
- Gateway service prompts are not part of onboarding.
wizard.startrequestsinstallDaemon: false; Companion's existing WSL service installation and native runtime ownership remain unchanged. Older WSL gateways can use the existing parameter-compatibility fallback. - Before acknowledging Optional apps, setup explicitly cancels the optional tail.
It requires a confirmed
cancelledresult, valid saved configuration fromconfig.get, and authenticatedhealthsuccess. This is a deliberate handoff, not a claim that the upstream wizard completed. Arbitrary errors never qualify.
Native setup then restores reload and performs its own final config, listener ownership and health checks before publishing the staged record. WSL setup continues its existing Windows-node context step; the headless runner restores reload through its existing completion/cleanup wrapper. A user's Cancel remains an abort, not this validated handoff.
Defaults match audited English prompt kinds, labels and raw option values, never random step IDs or option positions. Unknown/localized prompts and missing skip options stay visible (or require a headless answer) rather than receiving guessed answers. Configured channels/search are deferred, not intentionally disabled.
The shortened experience is product policy, not merely a set of overridable
headless defaults. WizardAnswers still supplies and validates answers for
unmanaged prompts. For each encountered Companion-managed choice, an absent
answer uses the policy; an explicit answer must produce the same protocol value.
Equivalent encodings, such as FALSE and false for a confirmation, are accepted.
A conflicting or invalid answer fails setup before answering that step, rather
than silently overriding the caller or restoring an intentionally omitted screen.
The error identifies the step and asks the caller to remove the conflicting entry
and configure optional features after setup. It does not echo the configured value.
Managed informational notes accept an absent answer or an explicit true
acknowledgment. This also applies to the Optional apps handoff: a contradictory
answer fails before the handoff begins. Security and other unmanaged prompts
retain their existing answer handling. Only encountered steps are checked;
entries for steps beyond the deliberately cancelled optional tail are not executed
or validated.
Recovery templates list encountered unmanaged prompts that the caller can act on, not overrides for managed/deferred steps. On a policy conflict, remove the entry from the original configuration; the generated template does not reproduce that entry or its value. The bundled configuration leaves setup mode and search provider unspecified so policy can choose among the actual offered values.
For an authenticated isolated native Gateway, Install and use Local AI captures
one in-memory consent for the reviewed Gateway, endpoint binding, model and port.
Native acquisition review does not inspect .wslconfig or require consent to
mirrored WSL networking. WSL review retains its existing inspection and consent.
The Windows-only artifact pipeline then continues directly into startup, provider
publication and exact-model verification under Setting up Local AI, without
returning to provider discovery or requiring a second Use click. Acquisition itself
still never starts inference or changes the primary; the continuation uses the same
guarded Use owner. Changed targets or files fail closed, and an uncertain mutation
can only be reconciled, not replayed. Consent is not persisted across app restarts.
Confirmed startup failures retain their runtime diagnostics and immediately restore
repair/provider choices with the normal Connect your AI heading. Failure before
mutation admission drops automatic continuation, so recovering the connection or
permissions requires a new explicit Use action. Ordinary WSL setup keeps its
read-only Local AI check independent of Gateway connection availability.
Existing installations retain the explicit Start and use action. Both paths
require operator administration scope; legacy same-user native Gateways remain unsupported.
Use starts the human-owned authenticated loopback server, publishes only to the selected Gateway, then verifies inference from that isolated Gateway with the exact primary model. The setup record remains staged until normal verified completion. Settings uses the same flow for an existing native Gateway. That Settings entry binds the existing Gateway ID and endpoint before opening AI setup. Its completion does not run WSL workspace finalization or rewrite existing permissions, sharing choices, or startup preferences. Native installation and recovery never create a WSL distro, change WSL networking, or run WSL configuration commands. Stop an existing owned runtime before repairing its files. Unconfirmed writes or external provider changes require reconciliation with the original Gateway, not an automatic overwrite.
Isolated Gateway console reads retry transient I/O and timeout failures twice,
including the initial cursor anchor before wizard.start. Polling retries use
the same cursor; initial reads never display historical instructions. A gap or
failure also shows persistent terminal
recovery outside the normal wizard-error controls, so continuing to another
question cannot hide lost OAuth guidance. Starting a new wizard resets this
warning. Explicit Restart gateway restarts the verified package service
even if it was already running before Companion attached; merely preparing a
wizard or disconnecting does not restart or stop that pre-existing service.
Historical package-aware proof (2026-09-16, package 0.0.0.1 ARM64): the original listener-job mismatch is resolved. Companion creates the launcher suspended, assigns its lifecycle job, retains its process handle and resumes it. A listener may belong to that job or be a verified live, same-user descendant of the package-identified launcher. Every ancestor handle is retained during inspection, creation times must be ordered, and TCP ownership is checked again before credential handoff. This is local process supervision, not MXC isolation or a defense against malicious code with the same user's process-access rights.
The disposable-profile proof reached authenticated hello-ok, received the
initial wizard.start note and cancelled without publishing a Gateway record.
It used production setup code to automatically approve only its own test device
through the package CLI, not security or provider prompts. For a fresh Companion
identity, setup verifies that the handshake request matches its device ID and
public key, approves that exact request in the dedicated profile, then reconnects
once. Listener ownership and local-profile configuration are checked before both
CLI calls. The token stays in the process environment, not command-line arguments.
There is no --latest approval or remote-record exemption. The profile-specific
terminal remains a recovery option, not a required onboarding step.
Pairing CLI calls have a two-minute total budget for packaged runtime startup and
the request. A failed terminal wizard response displays the Gateway's error detail
before its status. The installed Gateway's full optional tail previously failed
with PreparedModelCatalogConfigReplacedError after Optional apps. Shortened
setup deliberately ends before that tail and uses the validated handoff above.
It does not suppress that exception or repair the upstream full-wizard finalizer.
See the implementation results and limitations
for launch, shutdown, verification details and the pre-assignment crash window.
Install a local native gateway remains visible with Recommended while support
is checked. WSL and Connect to an existing gateway appear before the disabled
native choice until the capability check succeeds. A successful check enables native
and moves it to the first position. Unsupported or failed checks leave native disabled
in the last position with the support card and Windows Update recovery directly below
the choice list. The separate isolation warning and acknowledgment checkbox
remain removed; the general security notice and provider/onboarding consent
remain explicit. With an isolated-session Gateway package, the package provisions
and runs the agent account; the known legacy proof package retains its original
same-user runtime. The UI capability gate alone never proves isolation.
Native and WSL use the same focused AiSetupPage and two-choice AiReadyPage,
not separate normal provider/model wizards. The classic WizardPage is an explicit
compatibility option only when the required setup methods are unavailable.
WSL is always visible. It is first when native is unavailable and second after a
supported native choice, with Connect to an existing gateway between WSL and a
disabled native choice.
Companion checks current-user registration for the Store package
OpenClawFoundation.OpenClawGateway and publisher
CN=4BA40A7A-B719-4C40-BF91-84AF4F1136FC, package health, and the package-qualified
clawctl.exe and openclaw.exe aliases. It does not resolve an npm installation
from PATH. Native setup uses the same Windows capabilities and permission
selection as WSL, with native package installation consent on that same page.
Selecting Set up gateway starts native progress without WSL, Local AI or
Tailscale provisioning and without an additional review page.
A Store package is installed or refreshed automatically using
winget install --id 9NV70LV3D6XC --source msstore --silent --accept-package-agreements --accept-source-agreements --disable-interactivity;
unhealthy registration or unavailable aliases show an explicit repair error.
The fixed product is OpenClaw Gateway in Microsoft Store.
No MSIX version or download URL is pinned; Store selects the current compatible
release. Native setup checks for available Store updates before reusing a healthy Store package. Existing development profiles keep their package identity.
To explicitly refresh one, run
winget install --id 9NV70LV3D6XC --source msstore --accept-package-agreements --accept-source-agreements
WinGet reporting that no newer package is available is a successful no-op.
An unfinished draft saved against a different package family (for example, the
older development Gateway) offers Discard and set up again, just like a
runtime-contract change. Keeping the draft changes nothing. Confirming replaces
only its descriptor with a new profile for the installed package; old workspace
files, configuration and credentials are preserved. Published profiles cannot
be discarded through this recovery.
No local MSIX path or environment-variable configuration is required. To test a
Gateway built from openclaw/openclaw source instead, register it with
scripts\Build-NativeGatewayFromSource.ps1 -Patch <patch> and start Companion with
OPENCLAW_NATIVE_GATEWAY_DEV_PATCH=<patch>. Native setup then uses only
OpenClawFoundation.OpenClawGateway-<patch> and never falls back to the Store or WinGet.
The original OpenClaw.Gateway / OpenClaw Foundation development publisher pair
is still accepted for existing installations. If both identities are installed,
new setup reports duplicate registrations instead of guessing which to use. Existing
profiles resolve their original package family even when both packages are installed;
there is no implicit migration. Companion additionally checks the qualified
clawctl status --json integration kind and version before choosing a runtime.
An unversioned package already reporting a session is unsupported and requires
an MSIX update; it never falls back to same-user execution.
If the package reports a healthy Gateway but omits listener ownership because
Windows lacks process-sequence support, Gateway lifecycle remains available
but Companion will not send credentials. Update to Windows 11 build 26100.4770
or later before retrying; clawctl setup cannot add the missing OS API.
The capabilities-page disclosure explains that Set up gateway authorizes WinGet installation and
accepts the package and Store source agreements. Provider sign-in remains interactive.
Microsoft Store owns architecture/package selection, signature validation and
deployment. WinGet runs through the signed-in user's App Installer execution alias,
without a shell or elevation. Companion verifies actual package registration and aliases, then
automatically prepares the profile and opens Connect your AI.
Installation and verification share a cancellable 30-minute deadline by default.
Set OPENCLAW_SETUP_PACKAGE_ACQUISITION_TIMEOUT to override it in seconds
(1 through 2147483). Invalid values warn and keep the default.
Cancellation stops the WinGet request, but Windows may still finish an in-progress deployment.
Each packaged openclaw CLI call during native setup (configuration validation, node
capabilities, health, pairing) has a 4-minute deadline that includes packaged CLI startup. Set
OPENCLAW_SETUP_NATIVE_CLI_TIMEOUT to override it in seconds (1 through 2147483).
If WinGet reports stale Microsoft Store certificate pins (0x8A15005E), Companion
runs one current-user Repair-WinGetPackageManager -Force -Latest bootstrap and retries once.
The repair installs Microsoft's WinGet client module; it never bypasses certificate validation.
Other failures show explicit repair guidance and Retry setup. The normal
path has no separate install, availability-check or wizard-launch buttons.
An already installed healthy development/patch package skips installation. Store packages are checked for updates.
Retry checks registration again before invoking WinGet. Companion does not download Gateway packages directly,
change certificate trust, or uninstall packages on cancellation.
Progress reuses the WSL spinner/checkmark rows. Normal completion uses the same verified-model heading and single Chat action as WSL, without a native-only Gateway/capabilities summary. Gateway details and Windows permissions remain in their existing Connection and Permissions settings. AI readiness does not imply that a Windows node is paired or that command approvals have been granted.
The native path:
- Saves a credential-free setup draft and Companion device identity. For a
versioned isolated package,
clawctl setup --jsonmust report a ready session, thenclawctl companion prepare --port <preferred> --jsonuses the agent's default configuration and packaged Node.js. An existing agent port, token and provider settings are preserved; incompatible configuration fails explicitly. No host profile path is forwarded. The known legacy proof package alone retains a separate Companion-owned profile and same-user runtime. - Validates the active Gateway configuration and starts via the package's
gateway-servicelifecycle (or the legacy runtime). Before every credential handoff, including reconnects with a saved device identity, setup verifies the package-owned listener and its isolated-session process sequence against fresh Windows snapshots. The staged record is not made active in the registry. - Automatically pairs the setup's own Companion identity if required, then
opens the shared focused AI page. Authenticated method advertisements gate
discovery, provider authentication and model activation. Provider prompts stay
explicit; confirmed activation must pass exact primary-model verification.
The isolated path uses package-qualified
openclaw devices listandopenclaw devices approve <request-id>, which run as the agent user and read its config. Before each command, Companion checks that the effective port and token still match its setup record, then approves only the verified request. No host token or profile path is forwarded. No consent or provider answer is supplied automatically. Legacy console output is tailed from its dedicated profile. The isolated path uses upstream's authenticatedlogs.tailRPC after verifying the Gateway listener, then displays only root-loggerconsole.logmessages. It anchors at the current log size before provider setup (or classicwizard.start), polls bounded redacted batches, and reports skipped output or RPC failure with recovery-terminal guidance. It never tails WSL or a host profile for agent-side messages. Native console output and scoped terminal/restart/cancel recovery appear only for errors, skipped/unavailable console output or uncertain outcomes in the shared page/provider dialog. Healthy provider selection has no extra native controls. - The verified ready screen offers Open chat.
Choosing a destination rechecks the same Gateway, package
family and runtime contract, signing identity, agent, session and primary model.
After draining the operator, setup retains isolated stop ownership through
the explicit package restart. The legacy path first stops its own runtime
and restores its reload setting. Both check the selected
local/loopback/token configuration, run
config validate --json, and restart with owned-listener proof. Focused finalization then uses one authenticated operator connection forhealth(without an active probe) and exact primary model verification. Post-restart authorization, typed startup retries and health consume the existing admission window; restart and model verification retain their own existing bounds and the outer completion deadline. Neither automatic pairing nor credential recovery is allowed during finalization. A failed gate does not publish the staged record or permit mutation replay. - Keeps the verified isolated Gateway running, publishes the staged registry
record, then releases runtime ownership to the normal connection manager.
The legacy path stops its setup-owned runtime before publication.
An isolated finalization timeout or cancellation retains runtime ownership
until explicit setup disposal instead of stopping ongoing startup in a
finallyblock. Disposal still cleans up owned starts and preserves a pre-existing service. The selected destination uses the same protected restart receipt as WSL. The normal connection manager owns the native runtime after restart and supplies the authorized connection for another fresh verification before opening the selected page. This does not approve the separate Windows node role. Current Windows node permissions are preserved.
If the required AI setup methods are absent, the page explains the unsupported
contract and offers classic setup explicitly. That compatibility path retains
wizard.start with mode: "local" and installDaemon: false, its validated
optional-tail handoff and native configured-Gateway summary. It is not entered
for authentication errors, malformed responses or uncertain provider writes.
For the isolated package, clawctl gateway-service owns the Gateway process,
sign-in recovery and isolated session. Companion starts it through the package
when connecting and stops it only when this Companion runtime started it; an
already-running package service is left alone on detach. Legacy proof packages
retain Companion-owned same-user process supervision. Companion never calls
openclaw gateway install or registers a second service.
Cancelling setup, returning from the wizard, or closing setup stops only a
Gateway started by the setup runtime and closes its recovery terminal. Legacy
setup restores its reload setting. Cancel is not successful setup.
Restart gateway controls the selected runtime; Open terminal opens
clawctl pwsh in the agent for an isolated package, or the dedicated legacy
profile's shell, not a second onboarding TUI.
Its lifetime ends with setup or a restart. Configuration
already entered is retained in the agent's profile (or the legacy dedicated
profile) so it is not lost on retry. A
credential-free draft descriptor under gateways\native-setup-draft.json
resumes the same setup until successful publication. Only the legacy path has
a credential-free reload backup. Existing WSL distributions and remote
gateways are not replaced. Isolated setup reuses the agent account's default
OpenClaw configuration instead of touching the invoking user's .openclaw.
The native path does not enter the WSL
cleanup, Local AI installation, or WSL repair pipelines.
The legacy proof path was based on the packaging contract at
9a8cd4a.
The current source's isolated path instead requires the versioned
clawctl status --json integration, agent-side configuration and
gateway-service status --json listener attribution. MSIX registration or
the presence of IsolationProxy.exe alone is not sufficient.
The requirements below were recorded on 2026-09-16 for an earlier design. They are historical context, not the current lifecycle contract: the Gateway package now owns its isolated agent session, while Companion handles setup and verifies endpoint ownership. See Welcome for the current UI.
- Lifecycle owner (superseded proposal): Companion would have provisioned and supervised the MXC session. The implemented package instead provisions and records that session; Companion never creates a second one. See the verified MXC 0.8 contract and blockers.
- Distribution: Gateway packages are available as x64 MSIX, ARM64 MSIX, and an MSIX bundle. The future Store DLO is expected to point to the bundle, subject to confirmation when the link is available. Let Windows select the matching architecture from the bundle. The configured ARM64 development file is not a product-wide architecture restriction.
- Primary eligibility check: Windows version and enabled OS session
capabilities determine MXC native Gateway eligibility, not GPU or Local AI
eligibility. Evaluate this before recommending a local gateway path.
The shipped MXC 0.8
wxc-exec --probeexposesprobes.isolationSessionAvailable; the read-only local probe returnedtrue. Afalseresult conflates native API errors with lack of support, so a richer diagnostic contract is still needed. Read the OS build/revision separately if the probe does not expose them. A process-containment tier alone is not session support: require the session-specific capability result, not merely a high build number or the presence ofIsolationProxy.exe. - Recommendation order: Recommend the MXC native Gateway when the OS supports sessions and the Gateway session integration is available. If the OS is unsupported, present WSL first as the immediately available recommendation. Keep native Gateway visible as a disabled recommended option after the existing- Gateway choice, with Windows Update guidance and a capability recheck after updating. Do not automatically change the Windows update channel or enable preview features.
- Actionable failures: Distinguish an unsupported OS from a failed probe, disabled/unavailable session features, and a missing Gateway package/runtime. A probe error offers retry and diagnostics rather than asserting that an OS update is required. Meeting a version floor does not guarantee that a feature-gated OS API is enabled.
The implemented path must actually run the Gateway in the package's recorded isolated session. Do not relabel the historical ordinary-process proof as MXC, or recommend any MSIX as isolated based only on its registration.
The onboarding wizard installs a new app-owned local WSL gateway on Windows, connects an AI provider, and opens a selected native app page after live primary-model verification. It uses focused Gateway-hosted AI setup when supported and retains the classic OpenClaw onboard wizard for older gateways.
The shared Setup window starts at 720 x 820 DIPs and has a native presenter
minimum of 720 x 560 DIPs. SetupWindowSizing rounds those dimensions up to
physical pixels using the actual HWND DPI. SetupWindow reapplies the minimum
when its XamlRoot, monitor position or presenter changes and detaches the
subscriptions on close. DPI updates do not call Resize or reset the user's size.
The window remains movable, resizable and maximizable; page content scrolls
between its fixed header/footer at the minimum. This is a window constraint,
not a root-Grid minimum that would merely clip a smaller HWND.
The preferred minimum is not silently weakened for a smaller monitor. At 100% it is 720 x 560 physical pixels; at 150% it is 1080 x 840; at 200% it is 1440 x 1120. Actual monitor/work-area constraints remain Windows-owned.
Setup uses a 720-by-820 window with a scrolling body, centered vector mascot and wrapping heading. The 180-DIP mascot frame includes its motion/glow gutter; the title-bar mark is 24 DIPs. Theme-aware Mica/Fluent surfaces retain solid background and high-contrast fallbacks.
Capabilities, installation review and AI provider setup use native controls. The screen details below own their behavior and consent rules; the artwork section covers motion and asset packaging.
AiReadyPage is mounted only through the setup window's current verified
completion coordinator. Its "All set!" heading, graduation-cap celebration and
summary rows follow real primary-model verification, not discovery or browser
sign-in. Showing the page creates no pending handoff and performs no finalization.
The final screen mirrors CompletePage's success layout: rows with success
checks for the local Gateway, device pairing, the applied capability profile and
AI ready (the verified primary model), and one footer action, Open chat,
which opens Chat for the verified agent. There is no recommendation badge or
prompt implying multiple destinations, and no Return, Skip or Finish button.
Open chat is the final action. This removes the new
Channels and Skills setup destinations; ordinary Dashboard access from
Connection settings and the tray remains unchanged. The Chat action does not
sign in to channels, change channel configuration, or install skills.
Already-issued WhatsApp, Telegram, and Channels receipts remain accepted until
expiry and open the Gateway Dashboard's channels path. Retired Skills receipts
are rejected; legacy receipts do not add options to this screen.
Before restart, SetupWindow's SetupCompletionPreparation drains the AI page,
verifies the same Gateway, endpoint, agent, model, and main session, finalizes
Windows choices once, and publishes a restart preparation. After restart,
SetupNativeHandoffLauncher re-verifies that preparation and mounts the Ready
window. Choosing Chat then rechecks the captured Gateway, agent, and session
binding before opening native Chat; it does not repeat setup finalization.
The prior-page drain has its own 30-second deadline. Pre-restart verification has a separate deadline of one native connection budget plus model verification, eight minutes at the default 330-second connection and 150-second verification budgets. Finalization and restart publication use their owning operation and once-only protections, not those verification deadlines. Post-restart verification may start the selected owned Gateway and roll back that start on failure.
Preparation failures remain on the completion page with retry or return-to-AI guidance. Back to AI setup is available only inside the error message; returning invalidates the preparation and requires verification again. Post-restart connection failures retain the receipt only for explicit retry, while changed ownership consumes it. MCP-only/deferred routes do not claim verified AI.
A reported slow native cold start took about 136 seconds. Later reports on slow
ARM64 and x64 hosts reached a verified listener after about 165 to 210 seconds
(#1969), so the
former three-minute budget rolled back starts that were still progressing.
Companion uses a five-minute absolute startup budget from before the package start
request, with ten seconds for confirmation after a late acknowledgement, subject to
the caller deadline (at most 310 seconds for start/status), then still requires
fresh selected-port and process-sequence ownership proof. It never treats an
unhealthy/starting observation as ready, or retries the start command while
polling. A pre-existing starting service (for example after
clawctl gateway-service restart) is observed within the same startup budget
without taking start, stop or rollback ownership; it receives credentials only
after a fresh running attestation and the full listener checks. A listener that
appears before that attestation keeps the wait going but is not trusted, and a
momentarily unreadable (unknown) state is reported as unavailable inspection.
If the startup budget expires while the service is still starting, later reconnect
attempts read status once per backoff step instead of waiting another full budget,
until the state changes. Configuration is never repaired while the service is
starting. A pre-existing unhealthy service is not waited on; reconnect
observes it again after its normal capped backoff.
For a start Companion requested (or still owns), if a listener appears between a
pending status and the host snapshot, one immediate
status recheck may admit only a fresh running attestation. The full selected-port,
listener and process-sequence checks still run; another pending status or failed
attribution rejects that start.
The startup budget defaults to five minutes. Set OPENCLAW_NATIVE_GATEWAY_START_TIMEOUT
to whole seconds (30 to 3600) before starting Companion to change it; the published
connection phase and credential handoff budgets follow it. Only the published connection
phase keeps a 210-second floor for shorter values.
Staged native setup shares the existing 330-second default admission allowance
after successful native configuration validation through the first authenticated
operator hello. Configuration validation uses the native CLI timeout (four
minutes by default, overridable with OPENCLAW_SETUP_NATIVE_CLI_TIMEOUT) and
requires a confirmed zero-exit result; it does not consume the startup or
admission budget.
Start-command time, listener verification, challenge authorization, startup-sidecar
retry hints and pairing all consume that same remaining time. No reconnect or
credential recovery grants a fresh window. A current typed startup rejection
reports startup still pending at expiry; terminal authentication, protocol and
ownership failures do not retry. Caller cancellation remains cancellation.
An exhausted session needs new setup preparation rather than another connection retry.
This does not require the Gateway's broad /startupz sidecar readiness to finish
before an operator connection is attempted.
Focused finalization starts its admission budget after configuration validation
and the runtime-owned restart, preserving the existing startup allowance. It
shares the remainder through operator admission and authenticated health.
The health RPC also retains the configured native CLI
timeout as an upper bound; it does not receive a fresh startup window.
Health and exact-model verification must remain on the same authenticated
connection generation. The classic compatibility wizard retains its separate
gateway health --json --timeout check.
Failed focused finalization ends that admission operation, but cannot replay its mutations. An explicit Back/Close Local AI withdrawal can establish its own bounded connection instead of inheriting an exhausted finishing budget. An unavailable ownership inspection still blocks credentials and publication; it retains runtime ownership just like a readiness timeout, rather than being treated as proof of a foreign listener.
The health/startup contract was checked directly in Store package
2026.11.100.0 ARM64 on 2026-11-13. Its bundled OpenClaw 2026.11.1
dist/build-info.json identifies commit
4ffdd2047d192dd65554de3c8c46c0e0197c6e2a. The shipped CLI dispatches health
without probe parameters, honors the explicit RPC timeout, and the server emits
typed retryable UNAVAILABLE with reason startup-sidecars. This is installed
source evidence, not live delayed-start proof or a minimum-version claim.
The current package status contract does not expose attempt-bound startup-phase progress. Repeated unchanged status snapshots and unverified Gateway log lines do not extend a deadline. Progress-aware waiting needs a validated package signal associated with the owned launch attempt; until then the absolute startup ceiling and listener ownership checks remain authoritative.
On newer packages advertising integration.gatewayLaunch={version:1}, Companion
also correlates its launch before dispatch and conditionally stops only that
attempt, including after a lost start acknowledgement. An adopted launch grants
no cleanup ownership. A refused conditional stop never retries unconditionally.
Shipping isolated-session-v1 packages without that optional advertisement retain
their existing lifecycle behavior; malformed advertised support is an error,
not a legacy fallback. Listener/process-sequence proof is required independently
on both paths. See the native lifecycle contract.
When native setup fails after the package is installed, the setup page keeps the failed step, shows the typed failure (for a startup timeout: the phase, budget and last package status) and offers recovery actions:
- Collect Gateway diagnostics runs
clawctl collect-logs --jsonand reveals the package's redacted diagnostics ZIP. - Open terminal opens
clawctl pwshinside the isolated Gateway. - View setup log reveals
Logs\Setup\native-setup-<utc>.jsonlunder the Companion data folder. It records setup steps, sanitized package commands and the runtime's startup timeline, and the Debug page diagnostics bundle includes it.
The timeout guidance names the override variable. Retry setup reruns the full flow.
The published native connection borrow gets up to 330 seconds at the default startup budget for startup, authenticated handshake and authorization before exact-model verification. Preflight and final inspection also consume that outer budget; the confirmation allowance never extends it. Slow surrounding work can therefore cancel confirmation. Native credential reauthorization also has a bounded 330-second allowance instead of the unrelated five-second SSH/listener-check budget. Non-native authorization keeps its existing deadline. Caller cancellation, superseded attempts, record drift and connection error states still reject admission. Page drain, selection verification, runtime startup and published-owner handoff are distinct lifetimes.
SetupNativeCompletionTiming defines the published path's enforced phase ceilings
at the default startup budget:
330 seconds for the first borrow, 1,020 seconds to join already-admitted Local AI
recovery, 330 seconds for a fresh post-recovery borrow, 150 seconds for exact-model
verification (including the existing 120-second RPC and authorization), and
30 seconds for navigation. Their 1,860-second total bounds the execution window.
New preparation receipts also charge old-process teardown against this same
window, so acquisition receives only the remaining time, not a fresh 31 minutes.
A phase can fail earlier due to its underlying owner or caller cancellation;
unused phase time is not a guarantee that a different phase may overrun its ceiling.
Recovery waits never initiate or replay a provider mutation.
Timeouts retain a typed, finite phase (page drain, connection, Local AI recovery,
model verification, or native startup). The aggregate pre-publication verification
deadline uses neutral readiness guidance because it includes both connection and model
work; it does not incorrectly attribute a connection stall to model inference.
The chooser displays localized phase-specific
guidance and local diagnostics record only the phase/type, never raw package output,
model content or credentials.
Destination and preparation-v1 receipts retain five-minute unused-handle
admission. Their first acquisition atomically stores the execution start and
deadline under the existing file lock. New preparation-v2 receipts persist both
at issuance, before old-process teardown. Retries, reacquisition by another process
and app restarts use that same absolute deadline.
Expired, malformed, abandoned in-flight and legacy retry records lacking execution
provenance cannot grant a new window. Legacy unused records retain their original
five-minute admission deadline. No Gateway credential lifetime changes.
Fresh route/device/session proof and single-use consumption still fence navigation,
and deadline cancellation reaches the active navigation request before settlement.
Installed package limitation: package commit
133deeb
(MSIX 2026.9.700.0, payload 2026.9.7) cannot safely expose its pending start:
GatewayController
returns Starting after its 90-second listener wait;
Program.WriteGatewayStartResult
maps it to exit 1; and
ClawCtlJson.FromGateway
omits the Gateway object for that failed start. Only ok:false and a generic
cli_error with human text remain. Its subsequent unhealthy status supplies no
pending sandbox/process ownership proof. Companion intentionally rejects that
ambiguous failure and preserves rollback rather than parsing prose or accepting
arbitrary failures. The bounded polling change does not fix this package's
90-second failure path.
The successful pending-start fixtures describe conditional client behavior, not
an acknowledged pending-start contract supported by that installed package.
The packaging contract needs an explicit, versioned pending-start acknowledgement
with defined exit/ok semantics and stable session/launch ownership identity,
available on subsequent pending status checks and guarded stop operations.
That must distinguish this launch from another start, exited/replaced processes,
port changes and inspection failures. No guessed additional protocol fields are
accepted by Companion here.
A successful setup on payload 2026.9.4 followed by these failures on 2026.9.7 is a concrete version difference, not a controlled regression measurement. Package launcher timing, payload startup work and Companion's former combined 30-second selection deadline are separate contributors. The reported 22.5-second successful verification RPC plus authority subprocesses can exceed that former deadline; fixture tests reproduce that budget collision, but do not prove the exception shown by an installed UI whose original exception was not persisted.
The original verification retains the exact main session and a SHA256 binding over the normalized identity directory and the local device ID that signed the accepted connect request. A current-generation authenticated signing snapshot, not an optional server device-ID echo, supplies that identity. The standard Gateway hello schema does not declare such an echo. Current disk identity is validated only to detect rotation, never to relabel an already connected client; verified reconnects cannot generate a missing identity. Receipts contain the hash, not the identity path or credentials. Fresh clients must match those stable fields before model verification and finalization; their independent connection-generation counters need not match. Missing authority fields in earlier development receipts fail closed and require new verification. The persisted endpoint binding includes the effective SSH local forwarding endpoint, which is checked before a fresh connection is attempted.
Native setup offers the existing Launch OpenClaw at sign-in choice on PC capabilities, before package installation. Managed WSL keeps that choice on its Gateway setup review; Existing/Remote keep it on capabilities. Native finalization persists and applies the visible selection, including an explicit off choice. A failed application retains that selection for retry.
Isolated app hosts do not offer Windows startup registration. The host passes
that availability into setup, which hides the startup preference, keeps it off
even if an old isolated setting was true, and saves AutoStart=false before
native completion. Isolated and recovery completion do not invoke OS startup
registration. An ordinary explicit choice applies both enable and disable;
recovery preserves the saved preference. Registration failures remain visible
and retryable rather than being swallowed. AutoStartManager's isolation refusal
remains unchanged.
Setup requests schtasks /Create /HRESULT so completion can classify the
documented numeric HRESULT instead of localized error text. A completed
E_ACCESSDENIED (0x80070005) is a rejection; the existing policy may create a
Run-key fallback only after strict inspection confirms the task is absent.
An exact existing enabled task prevents duplication; a different or unknown
task refuses fallback. Timeouts, generic nonzero exits and unclassified failures
remain Unknown. No real non-elevated registration failure or universal failure
on ordinary installations is inferred from the controlled tests.
See Microsoft's schtasks create reference.
Native completion uses strict startup application: task removal must succeed when the task exists, unknown task state is an error, and Run-key failures are not swallowed. Existing best-effort callers retain their prior API. Classic completion instead acknowledges a startup-specific warning and continues the established restart path, so an optional startup failure cannot strand durable setup or masquerade as a failed application restart.
Strict task registration distinguishes acknowledged success, a request that did not start, and uncertain completion. An uncertain result cannot create a Run-key fallback. It may complete only if Task Scheduler confirms the exact enabled executable/action, principal, task path and logon trigger. A definite rejection with confirmed absence retains the legitimate Run-key fallback.
The trusted profile-local handoff retains exclusive leasing, five-minute unused
admission for destinations and legacy preparations, and a non-renewable bounded
execution deadline (including teardown for new preparations),
consumption on successful native presentation and explicit failure retry. New
ai-v3: opaque handles carry a typed native destination and exact verified
session in the protected record, not in public activation JSON. The experimental
ai-v2: browser-completion path is removed; those handles fail visibly and are
never reinterpreted as native receipts or ordinary Dashboard requests. The public
setup-dashboard activation route and profile-local storage name remain stable
for current native receipts. Ordinary Dashboard actions and headless setup are unchanged.
Failures after acquiring a receipt are settled before reporting: changed or
unreadable identity consumes it as Changed; an unavailable verification API or
malformed verification response retains explicit retry. Malformed stored
receipts, including oversized files rejected before acquisition, remain Invalid.
Acquisition distinguishes a busy exclusive lease from invalid input and unavailable
storage. A duplicate while a first launch owns the lease is ignored without a
failure notification, Connection navigation, or another queued launch. Storage
failures offer explicit Retry. That retry can admit an unstarted ready receipt
after pre-acquisition I/O failure or a settled retry receipt after a failed
presentation; it cannot replay an abandoned inflight receipt. Ordinary
activation of a retry receipt only offers recovery, never automatic execution.
A startup activation with a well-formed native handle bypasses the ordinary update prompt for that launch. Receipt validation still runs normally; handle shape is not verification authority. This prevents an unattended update prompt or accepted installer from expiring or skipping the selected destination.
Native post-setup children never forward to the shutting-down parent. They
acquire the instance mutex synchronously on the same thread, with a 60-second
wait per attempt followed by visible Retry/Cancel recovery. The unadmitted
handle is retained in a protected, profile-local setup-dashboard-handoff/restart.json
file, not logs or UI text. A newly owned ordinary launch can resume it; ordinary
secondary forwarding is unchanged. Busy or unavailable handoff attempts retain
the matching recovery record. Successful receipt consumption after page mounting,
or definitive invalid/changed rejection, clears only that matching record.
Retention does not extend receipt expiry or replace normal verification.
An invalid regular restart.json is rechecked and removed under its writer lease
before reporting the error once. A newer valid handle, other handoff files and
reparse paths are never removed by this recovery cleanup.
After restart, native launch re-verifies ownership before mounting Chat for new completion handoffs. Already-issued WhatsApp, Telegram, and Channels receipts remain supported until expiry and open the Gateway dashboard without starting authentication or changing channel configuration. Retired Skills receipts are rejected. Failed browser launches retain the handoff for explicit retry. Native Chat selects the verified session without changing the user's persistent chat-surface preference.
On first launch, the wizard appears only when there is no usable saved gateway connection. Users with existing gateways manage connections from the tray app's Connections tab. The local WSL setup affordance in Connections is shown only when setup has not already created an app-owned WSL gateway on this device.
The setup flow walks users through:
- Welcome and trust - Three feature rows and an inline device-trust notice
- Gateway - Capability-gated native Gateway recommendation (with WSL fallback), existing, remote, local MCP only, or deferred setup
- PC capabilities - Strict, Balanced (Recommended), Open, and inline Fine-tune; Node mode, local MCP and Ollama sharing stay independent. No Gateway-installation disclosure, Windows-access advisory panel, or probe runs here.
- Gateway setup - Managed WSL reviews installation and replacement consent; native Gateway checks its package and prepares a dedicated profile without WSL or Local AI installation.
- AI setup - Native Gateway, WSL and existing/remote gateways use focused AI setup and live model verification, followed by the same Chat-only completion. Native uses its setup-owned runtime until finalization; WSL workspace integration remains WSL-only.
- Completion - Both verified focused AI flows open native Chat. Already-issued WhatsApp, Telegram, and Channels receipts remain accepted until expiry and open the Gateway Dashboard's
channelspath; retired Skills receipts are rejected. Only the explicit classic compatibility fallback retains its setup-complete and connection handoff.
SetupWindow owns one SetupAccessDraft over the same SetupConfig for the
entire flow. The native connection contract separates verify-only Check from
Next, which revalidates and commits that same editor request. A successful
Next is the commit boundary: later Back/close preserves that committed choice;
cancelling before successful commit restores the prior active connection.
Existing/Remote then review capabilities and enter focused AI setup
using the committed registry. They never run WSL workspace finalization.
MCP-only/Deferred persist reviewed settings/startup and complete without AI or
WSL. MCP-only opens Companion Settings; deferred setup opens Connection settings.
Verified focused AI routes use the native chooser. AdvancedSetupRequested is only the explicit classic Settings fallback,
not the normal native route. Connection verification, credentials and commit
remain native host responsibilities. Progress indicators
come from OnboardingFlowPolicy, not a fixed six-page count. Local AI recovery
does not replay the introductory pages.
The injected ISetupNativeConnectionHost owns connection checks and commits.
The editor draft is not serialized into SetupConfig; see
native connection checks and cancellation
for the identity, drain and rollback contracts.
The legacy milestone and completion pages remain available for resume, classic wizard compatibility and errors. They are not gates in the new successful path.
After the install pipeline saves its Gateway, the typed Local AI host reconciles
that exact active record into the canonical registry before AI discovery. This
read-only handoff compares disk against the expected snapshot produced by the
owning cleanup/pairing/bootstrap-clear writes. It refuses intervening authority
edits, unrelated record changes, or invalid saved data instead of adopting a
freshly reread, unbound record.
The expected recovery reconnect may update LastConnected; newer canonical
timestamps are retained without rewriting the registry file or emitting events.
The runtime's initially unbound owner can bind once to this canonical record; an
already bound owner cannot switch to another Gateway.
Local AI use retains the selected Gateway ID with its model across reconnects and recovery returns. A different active Gateway is rejected before credential lookup, and again before verification/completion. Closing cancels and drains the actual runtime mutation and rollback before releasing the setup lock; only observations and transport cleanup have bounded deadlines. A failed start with confirmed terminal cleanup restores provider choices and Local AI repair. An uncertain publication retains exact-target verification only, without replaying the mutation.
GatewayAiSetupClient records intent from the explicit activation kind, never
from setupComplete. This provenance remains in the verification record;
the user's native destination choice, not that intent, determines the app page.
Only successful exact-model, main-role verification on the same authority and
connection generation produces a GatewayAiSetupCompletion. SetupWindow
checks the saved Gateway binding before and after workspace finalization.
SetupDashboardHandoffStore writes one atomic, credential-free pending record in
the current profile's data directory after verified completion. Restart and
activation carry only a random opaque handle, not serialized verification JSON.
The pending record binds the run, Gateway, endpoint, agent, model and intent.
A new completion supersedes the previous pending run. Only native ai-v3:
receipts can be issued or consumed.
SetupGatewaySessionBinding captures the exact record and resolved endpoint
before the temporary client is constructed. Registry revalidation before
credentials/connect, at handshake/reconnect, after connect and at request/route
boundaries can reject a changed Gateway, but cannot relabel the existing socket.
LastConnected bookkeeping does not change this binding; changes to Gateway ID,
endpoint or SSH intent do.
WindowManager.ShowNativeSetupAsync rechecks current Gateway, agent and
provider-qualified model observations after page readiness. A bare display model
ID is not treated as an exact provider route.
Ordinary Dashboard actions still use GatewayDashboardLauncher and the normal
credential resolver, with no completion receipt or automatic onboarding query.
Device/bootstrap tokens are never exported to browser URLs. Explicit error-dialog
retry remains available. Legacy chat, settings and connection restart
arguments remain supported.
The gated Inno-to-Store migration window reuses the wizard's visual design:
Mica backdrop, shared native vector OnboardingMascot, centered heading, themed content card, and persistent
footer actions. Its content scrolls independently so consent and recovery
actions remain available in smaller windows or with enlarged text.
The hero retains the shared 180-DIP frame and reduced-motion/theme behavior;
the small title-bar mascot is static and non-interactive. No legacy PNG artwork
or separate mascot implementation is used by this window.
Consent uses three short titled sections and a separate, non-dismissible warning.
Manual close and removal use step-specific headings and short instructions;
warnings stay in the same native InfoBar style as setup. Buttons retain the
wizard's 100-DIP minimum width, neutral left-hand dismissal, accent right-hand
primary action, and standard content/footer spacing. Recovery shortcuts are also
content-sized, and every action label wraps without ellipsis. The window uses
setup's 40,4,40,24 outer padding. Unlike setup's full-width footer, this
standalone window aligns its footer to the body's 560-DIP reading width. The title bar stays
"Move to the Store version"; retry/recovery states do not use setup step dots.
The window also sets the native OpenClaw icon for taskbar previews and the
window switcher; the custom title-bar image alone does not supply that icon.
The migration-capable Inno Settings page promotes this handoff with a
theme-aware recommended card that reuses the same card padding, typography,
accent badge, and primary-button styling as the rest of the app. The card
carries no decorative icon, so its text aligns with every other settings row,
and its action shares that single row. Its confirmation dialog
asks a question rather than repeating the button label, and states the handoff
grant and preserved data; detailed removal and finalization guidance stays in
the Store wizard, where the user can act on it.
This is a separate pre-start workflow, not a page in the setup pipeline.
StoreMigrationStartupGuard and StoreMigrationWorkflow retain migration
ownership; displaying the window does not construct SetupWindow, install a
gateway, or start normal app services. Consent, retry, and uninstall verification
are unchanged. The same visual workflow serves configured production Release
builds and explicit Debug previews. The first supported Inno release is pinned
to 2026.9.5.0, and MigrationProductionEnabled is checked in as true, so
non-Dev Release builds for win-x64 and win-arm64 carry the migration
surfaces. Enablement is gated at tag time, not by the checked-in default:
publication is blocked until that release's artifacts and acceptance are
verified, and the switch is set to false and retagged if acceptance fails.
See Release migration gates for the shared build contract and
the two-PR coordinated-release requirements.
StoreMigrationWindowProofTests mounts this production window with in-memory
operations only. It covers light/dark consent, busy/manual-close/removal and
unreadable-record recovery, plus work-area-height and small-window enlarged-text
layouts that scroll to the complete consent warning. With
OPENCLAW_VISUAL_TEST=1 and the existing OnboardingNativeProof environment
(OPENCLAW_UI_PROOF_DIR, OPENCLAW_UI_PROOF_FREEZE_DIR, and
OPENCLAW_UI_PROOF_MANIFEST_SHA256), it captures complete test-owned windows
against the reviewed source/build freeze. Run a fresh testhost for each theme,
setting OPENCLAW_UI_TEST_APP_THEME=Light or Dark before launch and selecting
matching theory rows with DisplayName!~Dark or DisplayName~Dark. The app theme
must be selected in the TestApp constructor; changing only the root theme after
window creation can leave Mica light beneath dark-theme text. Capture verifies
that app/content themes agree, as well as visible action/status
labels and mascot pixels, including the composed artwork rather than a
RenderTargetBitmap approximation. This is presentation proof, not real migration or installer
proof: it never runs production migration operations or opens Installed apps.
The page checks wxc-exec --probe asynchronously before recommending the first
Install a local native gateway card. It requires the reported
probes.isolationSessionAvailable boolean, not a process sandbox tier, build
comparison or IsolationProxy.exe file. On success the native card is enabled,
selected with the accent highlight and marked Recommended. An explicit
WSL or existing-gateway selection is not overridden by a late probe result.
Back navigation preserves those explicit choices even when native is supported.
The badge sits to the right of the title. Successful capability status appears
inside the card below its description, with a decorative green checkmark and a
screen-reader announcement. The description says Install and set up an OpenClaw
gateway on this device; it does not claim isolation based on a capability
probe alone. An older recognized proof package still runs same-user; a
non-proof package without the versioned isolation contract fails during
setup rather than pretending to be isolated.
If a resumed native setup profile's port has been taken by another process,
Retry selects a new port without replacing the profile, credentials or identity.
Unexpected launch/cleanup failures show an explicit failure and Retry action;
Companion never takes over or stops the conflicting process.
The WSL title is Install a local WSL gateway. Checking, unavailable and error
messages appear in a compact, bordered support card below the gateway choices,
outside the disabled native option so the Windows Update action stays usable.
The support card is hidden when native capability is available.
When capability is unavailable, Open Windows Update opens
ms-settings:windowsupdate. Guidance names the unavailable isolation-session
capability and explains that a newer Windows version alone does not guarantee
availability. It offers installing a local WSL gateway or connecting to an existing
gateway instead. For users who need to update Windows, it describes joining the Windows Insider
Program, selecting the Beta or Experimental channel, and choosing Windows 11, version
26H1 under Advanced options during enrollment. The guidance warns that
returning to Windows 11, version 25H2/26H2 requires a clean reinstall, as described
in Microsoft's Windows core version guidance.
After enrolling, users return to Settings > Windows Update, check for
updates, and may need to wait a few minutes for the update to appear. The copy
notes that feature availability can vary by device and tells users to reopen
the page to check support again, even if Windows is already up to date. It does
not promise a rollout or that updating fixes the capability. The Welcome page has no
Check again button. NativeGatewayEligibilityTextTests exercises the production
rich-text renderer, complete automation name, and repeated rich/plain transitions
on real WinUI TextBlock controls; the gallery also uses that renderer.
Feature rollout varies; a negative native API result is not proof
that the build alone is the cause. Probe failures or missing/invalid metadata
offer retry/Companion repair rather than misleading update advice. Windows Server
remains unsupported without invoking the native probe. No update-channel or
feature-policy changes are automatic.
The single-selection list always shows native first, WSL second and Connect to an existing gateway third. WSL is visible and selectable while native capability is being checked, when it succeeds, and when it fails or is unavailable. There is no Other gateway options expander. Page load starts WSL/Local AI discovery; choosing WSL retains the fresh readiness gate before Capabilities, then reviews replacement consent on the WSL setup page. Native package setup independently rechecks capability before configuration.
Choosing local Gateway setup runs read-only WSL viability and existing-config inspection before PC capabilities. Failures appear inline with a fresh-inspection retry, not a modal. Fresh installation has no redundant confirmation. A detected replacement is reviewed on the WSL setup page before Install; explicit consent is bound to the exact distro name, and unproven ownership still requires the engine's destructive confirmation. External saved Gateways stay untouched.
The gateway-choice scroll viewport owns the 560-DIP maximum width and stretches its list content. Keep the width constraint on the viewport, not on the nested ListView, so the choices share the header's center line as the window resizes. Back, Next, and the step indicator remain outside the scrolling area.
SetupInstallationProgress maps real pipeline events to prepare, install and
connect/check phases. Local AI recovery uses its own install label. Counts include
completed and skipped steps, not estimated percentages; only a running phase
spins. Unknown step IDs require an explicit phase mapping and test coverage.
Detailed activity is collapsed by default; actionable authorization and real
download progress remain visible outside it.
Installs and connects a new app-owned OpenClawGateway WSL instance from a clean WSL baseline. If the WSL platform is missing or its optional component is not initialized, setup requests administrator approval to install it, re-inspects readiness, and reports when a Windows restart is required. Setup does not export from or mutate an existing user Ubuntu distro; if WSL cannot create the named app-owned distro directly, setup fails with an actionable update message. Cleanup automatically unregisters a distro only when durable OpenClaw evidence is paired with exactly one readable current-user WSL registration whose canonical base path matches the expected managed install path. Automatic orphan-directory cleanup requires a marker bound to that exact path. An unproven same-named distro or leftover data directory is preserved unless the user explicitly confirms its permanent replacement in the setup UI or passes --confirm-destructive. When replacing an app-owned local gateway, the removal step is shown as part of progress and can be retried on failure.
The managed distro is locked down and is not intended to be a normal interactive Ubuntu profile. For editing openclaw.json as the openclaw user and using root for protected-file administration, see Managing the locked-down WSL gateway.
The draft updates setup capability flags and runtime Node* values in memory
only. Its exact profile order is System, Canvas, Screen, Camera, Location,
Browser, Tts, Stt. Strict (ReadOnly) enables Canvas and Screen; Balanced
(Standard) adds System, Tts and Stt; Open (Full) enables all eight. Only an
implicit bundled all-on placeholder defaults to Balanced at draft creation.
Explicit Open and custom choices survive
navigation. Device information is fixed, not a toggle. System controls
system.run and system.run.prepare, not file/clipboard access.
Profiles use vertical, full-width native single-selection rows with the system
selection indicator, selected background and keyboard behavior. Strict, Balanced
(Recommended) and Open appear without a redundant section heading. The adjacent
Fine-tune expander shows the selected-capability summary.
Gateway choices, the Balanced preset and the final Chat choice share the
RecommendedBadge control: a localized caption with an accent outline, 8 px
horizontal and 4 px vertical padding, and disabled-state brushes inherited from
the choice's enabled state. The Balanced label has no parenthetical suffix;
its accessible choice name still includes the recommendation.
Opening it only inspects existing flags; it does not select Custom. Editing any
flag shows a Custom capabilities badge with no preset falsely selected, even
if the flags later match a preset. Imported arbitrary flags have no invented base.
Explicit Custom intent and FineTuneExpanded live only in SetupAccessDraft and
survive page recreation. Selecting a preset reapplies exactly its eight flags
without changing disclosure state. The Toolkit SettingsExpander.Items contain
eight real SettingsCard rows; explanatory notes use ItemsFooter with a
16 px horizontal and 12 px vertical inset, keeping both paragraphs off the card
edges while preserving wrapping. Browser prerequisites remain in the Browser row
description.
Node mode, local MCP and Ollama sharing are independent of profiles. When both transports are off, profile/capability controls are disabled and dimmed without clearing choices; Fine-tune remains inspectable, with an explanation to enable either transport. Custom never bypasses these gates. Browser requires Node mode and a genuinely available Gateway, not the default loopback URL; a pending selection remains visible.
Onboarding does not probe Windows privacy settings or grant OS access. Remembered capture consent, execution approvals, sandbox grants, MCP tokens and voice configuration remain in native Companion Settings. Runtime screen capture uses monitor capture, not a guaranteed picker on each request.
Next routes directly to WSL review (managed), AI setup (committed existing/remote),
or asynchronous completion (MCP-only/deferred). Review Back returns to capabilities.
There is no ordinary permissions page or progress dot: the standard managed route
has seven stages, existing/remote five, MCP-only/deferred three. Headless
SkipPermissions is unchanged. The obsolete Windows-access preview and its
dedicated probing code have been removed; the inert gallery covers current
capabilities without probing Windows or opening Settings.
Local AI uses the existing managed Windows llama-server eligibility coordinator.
Unknown readiness and unsupported pinned recovery block installation only when
Local AI is required. Users may turn it off outside recovery. Model selection,
networking consent and the original wizard-skip preference survive Back/Next.
Consent authorizes installation to change global .wslconfig and stop all WSL
distributions once; the review itself never performs those actions.
Selected Tailscale requires a successful bounded Windows signed-in/MagicDNS
probe. WSL browser/auth-key sign-in is distinct from Windows sign-in and from the
separate, default-off identity-trust toggle. Auth keys remain session-only.
Serve is private tailnet access, not Funnel.
The WSL review shows its current installation blocker directly below the
centered heading, before optional choices. SetupAccessDraft.GetInstallRequirements
is the shared source for both CanInstall and this presentation, including
incomplete or stale inspection, exact-target replacement consent, Local AI,
networking consent and Tailscale readiness. When replacement is required, the
same page shows the full inspected consequences and an exact-distro checkbox near
the bottom, above the fixed footer. It starts unchecked and never installs or
navigates when changed. Install stays disabled while consent is outstanding.
Checking it enables Install only when all requirements are satisfied; other
requirements keep their specific recovery actions. Fresh installs and Local AI
recovery do not show replacement consent. The host rechecks CanInstall before progress.
A changed draft cannot turn a click on an already displayed review action into
installation. Users who want to keep an existing setup are directed back to the
existing-Gateway route, not encouraged to approve replacement.
Networking review returns to its caller: review to networking to review, or Local AI to networking to Local AI. Recovery mode, pinned model and explicit networking consent remain intact. Reviewing a requirement performs no WSL changes; installation remains the separate mutation boundary.
The focused client negotiates authenticated gateway method advertisements.
openclaw.setup.detect only presents available choices. Selecting a candidate,
provider login, local-provider preparation or manual key starts the corresponding
openclaw.setup.* operation. Detection never silently chooses or tests another
provider. Provider choices come from the gateway. Bundled brand aliases, bounded
public HTTPS metadata logos and native Fluent fallbacks supply their visual
identity without changing authentication. Metadata action labels are preserved.
See Provider artwork for trust boundaries and format differences.
Returning from a provider dialog preserves the selected provider, chooser scroll offset and original focus target. Restoration remains bound to its page generation and captured operation. Deferred focus/caret bring-into-view requests are intercepted inside the chooser before the outer scroll viewer handles them. That restoration scope ends on new pointer/keyboard input, focus departure, another provider operation or page close, so subsequent user scrolling is normal.
The grouped screen uses native WinUI SettingsCard commands and
SettingsExpander controls. Only this task page uses a compact, centered header
band with an 80-DIP mascot beside the wrapping title/status; earlier setup
pages retain their large centered heroes. Each provider has one native command
surface, not a selectable ListViewItem wrapped around another clickable card.
The page-local compact row style does not alter global Toolkit resources.
Gateway-supplied provider/model choices and the final next-step cards use
SetupActionCard, retaining the Toolkit card visuals while supplying a real
UI Automation Invoke provider. Native UIA invocation and ordinary clicks enter
the same guarded page action. Disabled or non-clickable choices cannot activate
setup. The pinned Toolkit peer advertises Invoke without implementing its
provider, so using that peer directly is not a supported automation path.
The API Keys entry and recommended setup-link cards use the same adapter.
Their existing actions, visibility, and consent requirements are unchanged.
Mounted behavioral tests also preserve the independent ownership boundaries: normal Gateway review hides the competing Local AI choice, changing the API provider selection performs no activation, and the verified completion page has no footer action that can bypass its coordinator. A completion failure exposes recovery inside the error bar; that action returns through the owning AI setup flow without publishing a destination. These checks exercise actual controls and protocol effects rather than matching XAML or method text.
- Local AI on this PC is a concise native choice row beside the detected Gateway choices, with actual GPU/model facts and its trailing action. It has no separate introductory heading or always-visible technical paragraph. Accessible help distinguishes managed Windows Local AI from NVIDIA's hosted API.
- Available on your Gateway presents server-returned candidates, recommended website links when needed, and unavailable discoveries.
- Set up a local model presents Gateway preparation choices before providers. The catalog and action labels come from Gateway metadata, not a Windows list of installed services. The fallback action is Connect / Set up.
- Connect an AI provider retains featured sign-in, a full API Keys row and auth-only More sign-in options. Auth kind determines the fallback Pair, Set up…, Configure… or Sign in action; metadata wins.
- Connect with an API key or token is the separate expanded form. The
API Keys command uses
FluentIconCatalog.Keyand opens the form without selecting or activating a provider. Its picker, PasswordBox and inline Connect are horizontal when the actual form width and current text scale allow, and stack otherwise. Empty keys cannot submit. The selected provider is revalidated at the explicit Connect boundary; secrets clear on submission and close. There is no duplicate page-footer Continue.
AiSetupPresentationModel suppresses a managed-local duplicate only when the
exact model reference and Gateway identity both match. Native card actions are
explicit; discovery and keyboard focus alone never start a provider. Enter/Space
use that same command, carrying its exact kind, identifier and model reference.
The inline API form is already visible when there are
no Gateway candidates or visible Local AI choice, without selecting its provider. Website links do not run
installers. Check again repeats discovery explicitly; a failed scan is not
an empty catalog. Native-conversation discovery is a visible, default-off opt-in
when the Gateway requests it. The current Boolean is sent only with an explicit
provider action; unchecked means false, never automatic permission. When the
Gateway does not request a preference, the parameter remains absent. Refreshing
presentation retains the user's current checkbox value.
Provider startup, noninteractive server progress, preparation, activation and
exact verification stay inline on Connect your AI, with the shared mascot,
visible status and a compact Cancel action whenever the operation can be
cancelled. They do not open a loading-only popup. The page-owned
ProviderSetupDialog opens for typed input, consent, acknowledgments, device
codes/browser sign-in instructions, or an explicit recovery decision. Device
codes and sign-in links remain visible while the Gateway polls for completion.
An input prompt stays open, disabled, while its answer is being submitted so
validation retries preserve the dialog and selection context. Submitted secrets
are cleared immediately. The page tracks answer submission separately from the
client's Uncertain protocol phase, so recovery does not expose a stale prompt.
Inline errors remain visible during loading. Cancel is available once the client
has allocated its owned wizard session ID, including while the start reply is
pending; cancellation still requires the Gateway's acknowledgement.
The page retains the operation lifetime and locks the existing choices even
while the popup is hidden. The client still owns protocol state; the dialog
never acquires another Gateway client or persistence store.
Confirmed rejection returns to the same cleared key field; confirmed cancellation
returns to usable choices. An uncertain outcome stays available for reconciliation
and is never replayed as another activation.
Server-owned client notes/actions still require Continue, typed inputs use Submit, and a client-owned device-code acknowledgment uses I've signed in. Gateway-owned progress has no answer button and is polled without an answer. Device codes remain selectable and have an explicit Copy action. Structured device-code prompts show the formatted code card, instructions and expiry instead of also repeating the Gateway's plain-text prompt. Prompts without structured device codes retain their messages, and errors remain visible separately. The fresh HTTPS URL from a user-started provider operation may open once; discovery, rerenders, reconnects and uncertain reconciliation never auto-open tabs. The manual sign-in link remains available, and opening a browser never counts as successful login.
GatewayAiSetupController retains the explicit preparation choice and catalog
preference, then automatically activates only its authoritative
preparedModelRef on the unchanged Gateway connection. Inline loading does not
introduce an extra page-level Activate button. Server download, plugin review
and promotion confirmations remain mandatory. Missing receipts, changed
connections or unsupported activation fail visibly without choosing another
model. If an uncertain preparation is later reconciled to an authoritative
prepared receipt, automatic continuation stays disarmed; an explicit
Activate model action in the same dialog can use that exact receipt without
replaying preparation. It cannot bypass a changed Gateway or generation.
This Gateway preparation path does not auto-install managed NVIDIA Local
AI or bypass its separate review/consent. A restart-required activation waits
up to 30 seconds for the existing connection's fresh same-authority handshake
before exact verification; timeout offers reconciliation without mutation replay.
This interaction comparison is pinned to
openclaw/openclaw@d69a5e74895cf64109eca0d3a172c17b74ddbe7b,
OnboardingAISetup.swift:1181-1212,1474-1506 and
OnboardingAISetupSheet.swift:52-57,127-137,183-212.
The compact Windows header and continuous dialog are intentional density/lifetime
improvements, not claims that Mac has identical geometry or never internally
reopens its sheet.
LocalAiOnboardingObservation observes independently of Gateway discovery and
fences cancellation, refresh and late results. SetupLocalAiHost reuses the
eligibility policy, canonical receipt/file inspection, runtime snapshot and
LocalAiSetupRouteResolver. Observation never calls runtime RefreshAsync:
that runtime API may publish or withdraw a Gateway route. Observation does not
install, migrate receipts, start inference, select a default or grant consent.
The row distinguishes checking, eligible but absent (Set up Local AI), installed/stopped (Start and use), healthy (Use this model), damaged (Repair Local AI), busy GPU, unknown facts, unsupported hardware and an unsupported Gateway. A loaded managed model's own GPU allocation is not treated as another workload. Installed, healthy, reachable and Gateway-verified are separate facts.
LocalAiOnboardingSnapshot.ShowLocalChoice hides only a confirmed unsupported
fresh device: no NVIDIA GPU, insufficient total GPU memory, or CUDA capability
below the runtime requirement. It uses the existing eligibility failure code,
not another hardware probe or a production test override. Unknown/checking
facts, busy GPUs, old drivers, missing runtime/catalog entries and unknown
models stay visible. Receipt or damaged-receipt evidence, a pinned installation
or retained runtime attention also keeps the row visible, without promoting its
action or changing repair/admission rules. Unsupported remote Gateway attention
is unchanged. Hiding the local row collapses its empty container, not independently
detected Gateway choices.
The layout comparison is pinned to
OnboardingAISetupView.swift at fef6b1290e412761888865da5b61ee1c0ce29586:
results at 191-254, candidate rows at 313-350, preparation at 440-480,
API Keys at 543-571, auth at 574-613 and manual entry at 616-674. Windows keeps
its managed local primary-model lifecycle and explicit consent, not Mac credential
reuse or utility-model semantics.
The inert native gallery now inventories 93 scenes in both themes (186 scene/theme states), including a distinct fresh-unsupported-hidden variant, installed unsupported attention, preparation before providers and the expanded manual form. The native proof inventory adds two mounted tests and the Working readiness case to the previous 108-case selection (111 expected when the same selection is used). These are source inventory counts, not claims of current rendered captures. Existing source-immutability, owned-input, DPI and capture guards remain required.
Set up and Repair enter the existing LocalAiSetupControl and networking review
inside this SetupWindow. Install and use is a separate consent boundary.
The host rechecks the same active, uniquely app-managed local Gateway and receipt
before selecting BuildLocalAiRecoverySteps, including on a first installation
with no receipt. These steps do not create/delete a distro, reinstall the Gateway,
mint tokens or pair devices. The existing global mirrored-networking warning
and explicit consent remain required. Back restores the prior configuration
draft; capabilities, route and startup preference are retained.
Start and Use recheck ownership, receipt/model identity, eligibility and canonical provider publication admission before calling the existing runtime. A Gateway switch during the read-only admission check is a rejected selection, restoring choices without starting the runtime. A target change after startup/publication remains uncertain and retains the exact-target reconciliation boundary. Publication preserves the recorded fallback and fails closed if the primary model or managed provider drifted outside that contract; health alone cannot overwrite a newer Gateway choice. A fresh setup-owned connection then verifies the exact returned model. An uncertain local action retries verification, not a hidden activation. Provider sessions must settle or confirm cancellation before local review. Closing drains page observations and the recovery pipeline before releasing the setup lock. Settings and headless entry points retain their existing contracts.
The pinned upstream contract is
openclaw/openclaw@fef6b1290e412761888865da5b61ee1c0ce29586.
The same setup schema blob (dbd8461f87f034b675b874313d2f401ac7c682c9)
is present in release v2026.9.6 at
eb377ac59e6c9fd6c7705028034812becf00271b.
- Schema lines 255-374:
optional
modelTarget: "utility"decorates the same choice kinds;setupModelandutilityModelare preserved alongsideconfiguredModel. - Role validation
(blob
6b8cc6e07ee6fb5367c7fd050fc4a53fd63bfc5b) requires exact role matching. Provider staging (blob9d93a352ed2342a695d9d189c4d1a8eefe7e016f) enforces it too. - Existing-model activation
(blob
b3abbf8dbf42b8a84d8fb06702eaba027edb2aca) checks exact model and role. - Utility route selection
(blob
666784e3cd5e8a689fbc287e692f5f13628b36ba) can use a utility route when no primary exists. - Verification result
(blob
1ce3a7737950f89798e655c7167e29bb72dbe535) includes that role.
Windows hides utility-only choices from the main-assistant list with a visible
explanation, rejects utility-marked activation/verification as main-assistant
success, and preserves absent-field behavior for older Gateways. Verify requests
send only the existing optional agentId, not modelRef or an invented
"primary" role. Full utility onboarding and a Gateway protocol upgrade are not
part of this change.
Interactive authentication and activation retain the shared wizard.next and
wizard.cancel contract, including sensitive fields, device codes, browser
actions and gateway-executed progress. A generic terminal wizard result or a
prepared model is not proof of working inference. Activation receipts, exact
model verification and restart reconciliation remain distinct.
An explicitly selected Local AI installation passes its resolved gateway model reference to verification after the installation pipeline succeeds. The UI does not guess that reference from a catalog ID. Cancellation or an uncertain reply does not replay a mutation. Insufficient operator scopes remain an explicit error, not a reason to fall back or use node credentials.
After verification, the native chooser finalizes Windows-node workspace guidance and the reviewed startup preference before restart. Dashboard management remains in Connection settings and the tray menu, not above Workspace chat. Windows capability consent remains in native Permissions, not in the web dashboard.
After OpenClaw onboard completes-or when the user explicitly skips it-local setup runs the installed gateway CLI's non-interactive baseline initializer against the final runtime workspace, then writes fixed Windows-node guidance into a setup-owned managed section of that workspace's AGENTS.md. The section is replaced idempotently between markers, preserves user-authored AGENTS.md content and file permissions outside those markers, and does not modify OpenClaw source files. This helps the initial companion-app OpenClaw session know to use the Windows node / nodes tool for Windows desktop, files, screenshots, camera, notifications, browser proxy, and Windows command tasks.
Renders server-defined setup steps via RPC (wizard.start / wizard.next). The gateway controls the flow - steps can be:
- Note - informational messages
- Confirm - yes/no decisions
- Text - free-form input (with PasswordBox for sensitive fields like API keys)
- Select - radio button choices (e.g., AI provider selection)
- Progress - loading indicator for background operations
If the gateway doesn't support the wizard protocol or is unreachable, this screen shows an "offline" message and can be skipped.
The wizard keeps recovery choices visible while setup steps are running so users can start the wizard again or skip it for now if an auth flow stalls. If the gateway restarts or the wizard connection is lost while setup is running, the same recovery choices are presented in the error state so the user is not trapped retrying a broken session.
Gateway-driven onboarding does not show a Back action. There is no dedicated wizard.back RPC. Gateways can instead provide in-band __back or back options, which protocol clients submit through wizard.next; Companion intentionally filters those options because its former local payload replay displayed stale state while the authoritative Gateway session remained on a later step. Users can restart onboard or skip and exit from More options instead.
Exact Gateway 2026.7.1 has a terminal compatibility path for an app-managed local WSL gateway. When the final model-check answer produces WebSocket close 1012 before the gateway can return done, setup retries the temporary NoListener state and the typed snapshot-changed race that can occur while the listener is restarting. Other unknown or conflicting endpoint ownership fails immediately, and no credential is sent until the managed endpoint is verified again. A retryable startup close 1013 remains inside the existing reconnect timeout. Setup completes only after a fresh authenticated hello-ok handshake. Other versions and steps keep the normal managed-local wizard replay behavior with the same bounded ownership wait; remote gateways and other disconnects do not enter this recovery path.
The headless setup engine also treats one terminal wizard payload as completion instead of failure. When the answers applied by the wizard restart the gateway, the gateway can tear down its own hosted wizard TUI and return a terminal payload whose error is exactly Error: TUI exited from signal SIGTERM. Setup accepts that result only when the payload is terminal and the request it just sent answered the authoritative final step, so the wizard is not cancelled after it already finished. The final step must be a plain acknowledgement note with no options whose id or title normalizes to done, and when the gateway supplies step position metadata it must also be the last step. An earlier SIGTERM, a progress poll, a replayed wizard session, any answerable step, any other step id or title, a non-terminal payload, and any other message (different signal, extra text, or different casing) all keep the wizard failure. Only surrounding whitespace is tolerated in the message. Reload-mode restoration, the one-shot managed restart, health verification, and provenance checks are unchanged and still fail closed.
When the gateway config wizard surfaces an error and the active gateway is an app-managed WSL distro, the error state also offers Open terminal and Restart gateway. The wizard does not parse or classify the gateway's error text; it leaves the message visible and selectable so the user can copy any command the gateway reports. The buttons reuse the shared GatewayTerminalLauncher and WslGatewayController (in OpenClaw.Connection, also used by the Connections tab). Restart re-enters the gateway config wizard (the provider/model onboarding step - not the whole V2 onboarding, and without re-installing the WSL distro) so fixes such as newly-installed tools are picked up on PATH. Because the gateway restart clears its wizard session, this resumes at the first config question rather than the exact step that failed. Detection is gated on GatewayRecord.SetupManagedDistroName, so it never appears for remote/SSH gateways.
Focused setup finishes through the two-choice native page. Startup is reviewed before completion and defaults on for a fresh, non-isolated setup. Recovery preserves that preference; isolated hosts keep it off. The classic completion page retains its summary and Open chat action. Errors retain diagnostics and recovery instead of showing success.
Onboarding uses the native vector OnboardingMascot control, adapted from
OpenClaw's Mac character at upstream commit
9afae26e080602bf1e330bfd88fcbd39a2bf22c0. Idle, curious, thinking, working,
happy, sad and celebrating poses reflect the current task. Working includes the
hard hat and hammer animation. Windows animation preferences select static
poses, and hidden/unloaded controls stop ticking. Navigation also respects the
Windows animation setting. Motion never adds a completion delay.
Provider artwork is bundled under Assets/Setup/ProviderIcons with its upstream
notices. Keep asset identity separate from the gateway-provided provider catalog.
Check light, dark and high-contrast rendering and the actual published
library-qualified paths, not only loose development assets.
The tray-hosted native connection editor is a main-window page. It supports a gateway address, a setup code or shared token, and optional SSH host, user and ports. SSH uses existing OpenSSH keys/configuration, not a separate key store. The browser-only profile route is not implemented through native credentials.
The connection editor shows the Gateway-stage progress indicator above a
separate row of wrapping Back, Cancel, Check and Next actions.
Connection results stay outside the scrollable form, above the navigation
actions, so a failed check and its retry guidance remain visible without
scrolling on shorter windows.
Both the Welcome existing-Gateway choice and Advanced existing/remote routes
use this editor. Its labels, accessible names and status messages use
Onboarding_NativeConnection_* resources in every supported locale.
Connection checking and cancellation copy is separate from the native
installer's package-check and WinGet cancellation messages.
Check connection authenticates with an isolated identity copy and optional temporary owned SSH listener, without saving a gateway or changing the active connection. Editing invalidates the displayed check result. Next checks the current draft again and transactionally commits before the PC capabilities page. Failed checks, editor cancellation and cancellation during Next leave or restore the previously active gateway. If rollback cannot be confirmed, setup shows an error and does not advance. After Next has succeeded, closing setup retains that explicitly committed gateway. Pairing-pending is not shown as a successful operator connection or as permission to enter AI setup.
The editor retains a temporary key for the same draft while gateway approval is pending. Successful bootstrap handoff tokens remain in memory until Next, allowing revalidation without reusing a consumed bootstrap code. Draft changes and editor close discard this staging state. No received token is written into the temporary key file during Check.
The onboarding wizard follows these security practices:
- Input validation: Setup codes limited to 2KB, decoded JSON validated, gateway URLs checked via
GatewayUrlHelper - URI scheme whitelists: Only
ms-settings:for permissions andhttp/httpsfor browser-launch links - Token protection: Query params stripped from all log output
- Gateway-owned pairing: Device approval uses the gateway CLI/API path so scope checks, token issuance, audit, and broadcasts stay centralized
- Error sanitization: Exception details logged but not shown to users
Gateway credentials are registry-backed. Setup codes and QR payloads create or update a GatewayRecord; bootstrap credentials live in GatewayRecord.BootstrapToken, long-lived manual tokens live in GatewayRecord.SharedGatewayToken, and post-pairing device tokens are saved in the per-gateway identity directory. SettingsManager may read legacy Token / BootstrapToken JSON fields for migration, but it does not write them back.
All user-visible strings use localization helpers with the Onboarding_* key namespace. Setup library pages use SetupLocalization; tray surfaces use LocalizationHelper. Supported languages are discovered from the Strings/<locale>/Resources.resw directories; the current locales are English, French, Dutch, Brazilian Portuguese, Chinese Simplified, and Chinese Traditional.
Translations are AI-generated following the repo convention. Technical terms (Gateway, Token, Node Mode) are kept in English across all locales.
See DEVELOPMENT.md for build instructions, environment variables, and testing workflow.
SettingsManager loads %APPDATA%\OpenClawTray\settings.json by default. Onboarding tests must not use new SettingsManager() without an isolated settings directory, because local user settings such as EnableNodeMode=true change setup behavior.
Use a temp settings directory for tests that construct SettingsManager, or set OPENCLAW_TRAY_DATA_DIR before the test process starts.
Real tray and setup proof launches must set all three isolation variables:
OPENCLAW_TRAY_DATA_DIR is the direct data folder;
OPENCLAW_TRAY_APPDATA_DIR and OPENCLAW_TRAY_LOCALAPPDATA_DIR are separate
roaming and local roots. The product may append OpenClawTray to those roots.
OPENCLAW_TRAY_LOCAL_DATA_DIR is a legacy direct-folder override, not a
replacement for the canonical local root.
Data directories alone do not isolate Windows registration. When the direct
data override is present, AppIdentity.IsIsolated suppresses Toolkit toast
activation subscription/unsubscription, toast display, and URI registration.
Startup mutations are explicitly refused. WSL keepalive lifecycle actions
require an explicitly managed gateway record, rather than adopting the normal
user's default distro. These guards do not authorize using an existing real
gateway or profile in a test. Use only owned disposable resources and compare
protected profile metadata and notification/COM, URI, and startup registration
fingerprints before and after native runs.
Setup images use ms-appx:///OpenClaw.SetupEngine.UI/Assets/Setup/... URIs.
Published installer and portable ZIP payloads must include that library-qualified
directory, not just the tray's loose Assets/Setup copies. The tray publish target
preserves both layouts; SetupAssetPublishTests executes that target against a
clean directory and checks every setup asset, including nested SVGs and notices.
| Path | Purpose |
|---|---|
src/OpenClaw.SetupEngine.UI/SetupWindow.xaml(.cs) |
Tray-hosted setup shell, run lock, preview routing, and page navigation |
src/OpenClaw.SetupEngine.UI/Pages/SecurityNoticePage.xaml(.cs) |
First-run device-trust warning before setup choices |
src/OpenClaw.SetupEngine.UI/Pages/WelcomePage.xaml(.cs) |
Native Gateway, WSL, and connect-existing choice with capability/readiness checks |
src/OpenClaw.SetupEngine.UI/Pages/AdvancedSetupPage.xaml(.cs) |
Connect-existing handoff to Connection settings |
src/OpenClaw.SetupEngine.UI/Pages/CapabilitiesPage.xaml(.cs) |
Shared capability profile and transport settings draft |
src/OpenClaw.SetupEngine.UI/Pages/ProgressPage.xaml(.cs) |
WSL gateway install progress and gateway-installed handoff |
src/OpenClaw.SetupEngine.UI/Pages/WizardPage.xaml(.cs) |
OpenClaw onboard provider/model/key wizard driven by gateway wizard.* frames |
src/OpenClaw.SetupEngine.UI/Pages/AiSetupPage.xaml(.cs) |
Focused provider choices, authentication, verification and bounded page-owned cleanup |
src/OpenClaw.SetupEngine/OnboardingFlowPolicy.cs |
Interactive stage list and installation subset; preserves the headless pipeline |
src/OpenClaw.SetupEngine/GatewayAiSetupClient.cs |
Typed route-bound discovery, explicit selection, activation and reconciliation |
src/OpenClaw.SetupEngine/GatewayAiSetupController.cs |
Bounded gateway-executed wizard progress polling |
src/OpenClaw.SetupEngine/SetupGatewaySession.cs |
Shared temporary setup operator session with registry identity and endpoint provenance |
src/OpenClaw.SetupEngine.UI/Controls/OnboardingMascot.cs |
Native vector control, animation preferences, theme updates and unload lifetime |
src/OpenClaw.SetupEngine/GatewayWizardRestartRecoveryPolicy.cs |
Exact terminal-restart classification and bounded restart provenance/reconnect retry policy |
src/OpenClaw.SetupEngine.UI/Pages/CompletePage.xaml(.cs) |
Success, failure, log/help, and startup preference summary |
src/OpenClaw.Connection/GatewayRegistry.cs |
Persistent gateway records and migration target |
src/OpenClaw.Connection/GatewayConnectionManager.cs |
Operator/node connection lifecycle used by onboarding |
src/OpenClaw.Tray.WinUI/Services/SetupExistingGatewayClassifier.cs |
Existing gateway classification for Welcome and startup gating |
Run the repository-required build, Shared and Tray suites, plus
OpenClaw.SetupEngine.Tests for the flow and AI protocol contracts.
AiReadyPageRenderingTests covers the Chat-only action and isolated startup.
ApprovedMock_FivePagesAndProviderPopup_LightAndDark provides an opt-in native
comparison without installation. Building fixtures alone is not rendered proof;
high contrast and Windows text scaling need authorized visible validation.
OnboardingAiPageTests mounts the production page with a scoped transport
double and checks explicit selection, masked input, conversation-discovery
consent, exact-model retry, uncertain replies, and cancellation before handoff.
OnboardingArtworkRenderingTests decodes the bundled SVGs through WinUI,
checks library-qualified URIs, and renders all static mascot moods in light and
dark themes. Set OPENCLAW_UI_PROOF_DIR to an isolated artifact directory to
save the current rendered scenes.
Mounted tests are not real-provider or gateway-to-node proof. Keep those
claims separate, run the required WSL/MXC validation path for setup/connect
changes, and report unavailable desktop or provider dependencies explicitly.
The real setup fixture uses separate data, roaming-root and local-root paths.
Its uninstall passes run-specific startup registry/task identities so teardown
cannot remove the normal Companion's startup registration.
The real Gateway proof also calls openclaw.setup.detect through the production
focused client, asserting advertised support, operator scope and typed discovery
without selecting a provider or starting a wizard. Provider-specific sign-in and
billing-dependent inference remain separate from that read-only contract proof.