Implement guided onboarding/setup wizard with contextual error recovery

[shanselman]

Problem

There's no guided onboarding flow for new users or when authentication fails. The current experience:

1. User installs the app → Welcome dialog says "Open Settings" → they see a Gateway URL and Token field with no guidance on where to get these values
2. If the token is wrong → "Connection failed" (now improved in fix: surface gateway error messages in Settings test connection #54 to show the actual error, but still no guidance on what to do)
3. If Node Mode is enabled → device appears as "Waiting for approval" in the tray menu, but there's no explanation of what the user needs to do on the gateway host
4. There's no way to re-trigger the Welcome/setup flow after dismissing it

Proposed onboarding flow

Trigger conditions

• First launch (no settings.json exists) → auto-start onboarding
• Test connection fails in Settings → offer "Need help setting up?" link/button
• Tray menu → add a "Setup Guide..." menu item (always available)
• Deep link: openclaw://setup → opens the onboarding flow

Step 1: Gateway connection

• Ask for Gateway URL with a hint: "This is the address of your OpenClaw gateway (usually ws://your-mac-ip:18789)"
• "Find on network" button that scans common ports? (stretch goal)
• Test connection inline with clear success/failure feedback
• If it fails, show the actual gateway error (already implemented in fix: surface gateway error messages in Settings test connection #54) and suggest fixes:
  • "Unable to connect" → "Make sure your gateway is running and the URL is correct"
  • "origin not allowed" → "Add this machine's address to gateway.controlUi.allowedOrigins on your gateway"
  • "token mismatch" → "The token doesn't match. Find your token with openclaw config show on your gateway host"

Step 2: Token

• Ask for the gateway token
• Explain where to find it: "On your gateway host, run openclaw config show and copy the gateway.remote.token value"
• Test connection with both URL + token before proceeding
• On success → save settings and connect

Step 3: Node Mode (optional)

• Toggle to enable Node Mode
• If enabled, explain the pairing flow:
  • "Your device ID is: a0afe9ec..." (with copy button)
  • "On your gateway host, run:"

  • openclaw devices list     # find your device
    openclaw devices approve <device-id>
    

  • Show a spinner/polling state: "Waiting for approval..."
  • When approved → toast notification: "🎉 Node paired! Your Windows machine is now connected."

Step 4: Done

• Summary: "✅ Connected to gateway at 192.168.1.254"
• Show channels status
• "Open Dashboard" / "Done" buttons

Re-triggering onboarding

• Settings window: Add "Run Setup Guide..." button
• Tray menu: Add "Setup Guide..." item (between Settings and Exit)
• Deep link: openclaw://setup
• On auth failure: Show a banner/button in the tray menu: "⚠️ Not connected — Run Setup"

Additional improvements

• The WelcomeDialog should be reworked into a multi-step wizard (or replaced with a new SetupWizard window)
• Settings "Test" button failure should offer contextual help based on the error type
• Node pairing should send a toast when approved
• Consider storing "setup complete" flag so we don't re-show on every launch

Related issues

• fix: surface gateway error messages in Settings test connection #54 (merged) — gateway errors now surfaced in test connection
• bug: aggressive retry loop on authentication failures triggers gateway rate limiter #198 — aggressive retry on auth failures