Improve remote gateway setup and connection error recovery

[bkudiess]

Summary

• Problem: Remote gateway setup in Connection settings did not explain cleartext token risk, SSH tunnel/trusted-proxy options, or which recovery path applies when auth/transport fails. The earlier "Remote gateway setup help" used the same Expander chrome as the functional "Use SSH tunnel" input section, so guidance read like another form field.
• Why it matters: Remote users need actionable setup and repair guidance before sending credentials over the network or retrying with stale/insufficient credentials — and help content should be visually distinct from inputs.
• What changed: Added shared URL/error classifiers; ConnectionPage setup guidance; a cleartext/TLS/SSH transport-security InfoBar that reliably refreshes when the URL changes; recovery copy for token drift, scope mismatch, TLS, tunnel, pairing/auth, and rate-limited states; setup-code SSH persistence. The setup help is now a lightweight info link that opens a TeachingTip (guidance popup) instead of an Expander, so it is clearly distinct from the SSH tunnel input section.
• What did NOT change (scope boundary): No new gateway protocol, node capability, credential precedence, TLS fingerprint pinning, persisted password storage, or MCP server behavior.

Change Type (select all)

• Bug fix
• Feature
• Refactor
• Docs / instructions
• Tests / validation
• Security hardening
• Chore / infra

Scope (select all touched areas)

• Tray / WinUI UX
• Windows node capability
• Local MCP / winnode
• Gateway / connection / pairing
• Setup / onboarding
• Permissions / privacy / security
• Tests / CI / docs

Linked Issue/PR

• Closes #
• Related #
• Related to a bug or regression

Validation

• ./build.ps1
  • Passed: all projects built successfully (Shared, Cli, WinNodeCli, SetupEngine, WinUI).
• dotnet test .\tests\OpenClaw.Tray.Tests\OpenClaw.Tray.Tests.csproj
  • Passed: 1215 passed / 0 skipped / 1215 total.
• dotnet test .\tests\OpenClaw.Shared.Tests\OpenClaw.Shared.Tests.csproj
  • Passed: 2566 passed / 31 skipped / 2597 total (one integration test flaked on first run, passed on rerun).
• dotnet test .\tests\OpenClaw.Connection.Tests\OpenClaw.Connection.Tests.csproj
  • Passed: 374 passed / 0 skipped / 374 total (includes the new setup-code SSH-persistence test).
• Focused proof tests:
  • ... OpenClaw.Shared.Tests --filter "FullyQualifiedName~Classifier" → 78 passed / 0 skipped.
  • ... OpenClaw.Connection.Tests --filter "FullyQualifiedName~SetupCodeFlowTests" → 15 passed / 0 skipped.

Real behavior proof

• Environment tested: Windows ARM64 isolated tray profile from worktree bkudiess-stunning-funicular, branch bkudiess-remote-gateway-parity (Connection → Add gateway → Direct).
• Exact steps run:
  • Launched the rebuilt isolated tray app, opened Connection → Add gateway → Direct.
  • Clicked the "How do I connect to a remote gateway?" link to open the TeachingTip.
  • Typed ws://gateway.example.com:18789 (cleartext warning), then wss://gateway.example.com:18789 (TLS green) to confirm the InfoBar updates when severity changes.
  • Ran the focused classifier and setup-code tests below.

Evidence after fix — captured live from the running tray app:

1. Setup help is now a link (ⓘ "How do I connect to a remote gateway?"), visually distinct from the "Use SSH tunnel (optional)" input expander below it.

2. The help link opens a TeachingTip — a read-only guidance popup (Direct/TLS, SSH tunnel, trusted proxy/Tailscale, auth) — not an input form.

3. A remote ws:// URL shows the yellow "Unencrypted connection" InfoBar (token would be sent in cleartext).

4. Switching to wss:// flips the InfoBar to green "Encrypted (TLS)" — confirming the refresh fix.

Test evidence:

• Classifier proof: Passed! - Failed: 0, Passed: 78, Skipped: 0, Total: 78.

• Setup-code proof: Passed! - Failed: 0, Passed: 15, Skipped: 0, Total: 15.

• MCP server logs: Not applicable — this PR does not modify the local MCP server, MCP transport, node capabilities, winnode, or MCP tool schemas. No MCP-server log is produced by this UI-only path.

• Not verified / blocked: No live gateway. Recovery-state copy (token drift / scope / rate-limit) is covered by unit/focused tests because reproducing those real gateway states requires a configured gateway fixture.

Security Impact (required)

• New permissions/capabilities? (No)
• Secrets/tokens handling changed? (Yes)
• New/changed network calls? (No)
• Command/tool execution surface changed? (No)
• Data access scope changed? (No)
• If any Yes, explain risk + mitigation:
  • Setup guidance warns before a remote cleartext ws:// would send a token unencrypted.
  • Setup-code SSH tunnel config is persisted when supplied, so the saved connection matches the encrypted-transport advice shown to the user.
  • Token drift/scope/auth recovery copy routes users to re-pair or replace credentials instead of repeated retries.
  • TLS copy says protection applies when the certificate validates; this does not add TLS fingerprint pinning.

Compatibility / Migration

• Backward compatible? (Yes)
• Config/env changes? (No)
• Migration needed? (No)
• If yes, exact upgrade steps: N/A

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only conversations that still need reviewer or maintainer judgment.

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed June 26, 2026, 2:47 PM ET / 18:47 UTC.

Summary
The PR adds shared gateway URL/error classifiers, WinUI remote setup TeachingTip and transport-security advice, recovery copy, setup-code SSH tunnel persistence, localized strings, and classifier/setup-code tests.

Reproducibility: not applicable. as a PR implementing setup UX and recovery improvements rather than a standalone bug report. Source inspection plus inspected tray screenshots cover the visible Direct setup behavior; live recovery-state reproduction was not provided.

Review metrics: 2 noteworthy metrics.

• Changed surface: 16 files, +1377/-58. The PR spans shared classifiers, connection manager API, WinUI setup UX, locale resources, and tests, so maintainers should review both code behavior and user-facing copy.
• Localized security copy: 5 locale files changed. Remote credential and transport guidance must stay consistent across all supported locales before merge.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🦞 diamond lobster ✨ media proof bonus
Patch quality: 🐚 platinum hermit
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

• none.

Risk before merge

• [P1] The PR intentionally changes credential transport guidance; CI cannot prove the conditional trusted-proxy/Tailscale copy is appropriate for every deployment topology.
• [P1] Recovery-state copy for token drift, scope mismatch, TLS, and rate limiting is covered by classifiers/tests rather than a live configured gateway fixture.

Maintainer options:

1. Accept the current security-copy scope (recommended)
   Land with the current screenshots, classifier tests, and green checks if maintainers agree the conditional trusted-proxy/Tailscale wording is the intended remote-gateway guidance.
2. Ask for live gateway recovery proof
   Require a redacted live gateway fixture demonstration for token drift, scope mismatch, TLS, and rate-limited recovery states before merge.
3. Narrow the trusted-proxy wording
   If maintainers do not want the app to bless plain ws:// behind private overlays, revise that copy to recommend TLS or managed SSH only.

Next step before merge

• No ClawSweeper repair is queued; the remaining action is maintainer review of the security-sensitive setup guidance and proof scope.

Security
Cleared: Cleared: current head removes the unsupported Basic-auth guidance and does not add new network calls, credential precedence, or secret storage beyond persisting the selected SSH tunnel config on the gateway record.

Review details

Best possible solution:

Land the bounded setup/recovery UX improvements if maintainers accept the credential-transport copy and keep credential persistence owned by GatewayRegistry and GatewayConnectionManager.

Do we have a high-confidence way to reproduce the issue?

Not applicable as a PR implementing setup UX and recovery improvements rather than a standalone bug report. Source inspection plus inspected tray screenshots cover the visible Direct setup behavior; live recovery-state reproduction was not provided.

Is this the best way to solve the issue?

Yes. The current approach keeps connection lifecycle and credential persistence in the existing GatewayConnectionManager/GatewayRegistry boundary, removes the earlier unsupported Basic-auth copy, and adds focused shared classifier coverage.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 1c377cb64b65.

Label changes

Label changes:

• add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🦞 diamond lobster and patch quality is 🐚 platinum hermit.
• add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (screenshot): The PR body includes inspected after-fix screenshots from a rebuilt tray app showing the help link, TeachingTip, cleartext warning, and TLS refresh behavior.
• remove rating: 🦐 gold shrimp: Current PR rating is rating: 🐚 platinum hermit, so this older rating label is no longer current.
• remove status: ⏳ waiting on author: Current PR status label is status: 👀 ready for maintainer look.

Label justifications:

• P2: This is a normal-priority setup and security-guidance improvement with limited blast radius.
• merge-risk: 🚨 security-boundary: The diff changes user guidance around when remote gateway tokens are protected or exposed in transit.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🦞 diamond lobster and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (screenshot): The PR body includes inspected after-fix screenshots from a rebuilt tray app showing the help link, TeachingTip, cleartext warning, and TLS refresh behavior.
• proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes inspected after-fix screenshots from a rebuilt tray app showing the help link, TeachingTip, cleartext warning, and TLS refresh behavior.
• proof: 📸 screenshot: Contributor real behavior proof includes screenshot evidence. The PR body includes inspected after-fix screenshots from a rebuilt tray app showing the help link, TeachingTip, cleartext warning, and TLS refresh behavior.

Evidence reviewed

What I checked:

• AGENTS policy applied: AGENTS.md was read fully; its connection/pairing guidance applies because this PR changes gateway setup, credential-adjacent copy, GatewayConnectionManager, and tray UX. (AGENTS.md:1, 1c377cb64b65)
• Architecture boundary: Connection architecture docs identify GatewayConnectionManager as the connection lifecycle owner and GatewayRegistry as the gateway record/credential persistence boundary, matching the PR's implementation surface. (docs/CONNECTION_ARCHITECTURE.md:17, 1c377cb64b65)
• Unsupported Basic-auth copy removed: PR head now tells users to paste a shared token or leave it blank for setup-code pairing, and the TeachingTip Auth text no longer advertises user-info/password-in-URL credentials. (src/OpenClaw.Tray.WinUI/Pages/ConnectionPage.xaml:954, d0017621bc9d)
• Transport advice refresh path: PR head classifies Direct, TLS, and SSH tunnel topologies and forces the InfoBar closed when severity changes so the cleartext/TLS warning repaints correctly. (src/OpenClaw.Tray.WinUI/Pages/ConnectionPage.xaml.cs:1703, d0017621bc9d)
• Setup-code SSH persistence: ApplySetupCodeAsync now accepts an optional SshTunnelConfig and stores it on the GatewayRecord while preserving existing shared/bootstrap token behavior. (src/OpenClaw.Connection/GatewayConnectionManager.cs:521, d0017621bc9d)
• Regression coverage: The PR adds a setup-code test that asserts an SSH tunnel config is persisted on the active gateway record, plus shared classifier tests for URL/error classification. (tests/OpenClaw.Connection.Tests/SetupCodeFlowTests.cs:106, d0017621bc9d)

Likely related people:

• ranjeshj: GitHub commit metadata and local history show ranjeshj authored or merged recent ConnectionPage and connection architecture work, including the bkudiess tray UX stack and shared-token Direct setup changes. (role: connection architecture and tray UX area contributor; confidence: high; commits: 429be9ba9368, ed126f2aac6d, ffeff39c16c5; files: src/OpenClaw.Tray.WinUI/Pages/ConnectionPage.xaml.cs, src/OpenClaw.Tray.WinUI/Pages/ConnectionPage.xaml, src/OpenClaw.Connection/GatewayConnectionManager.cs)
• vincentkoc: Recent merged history touches ConnectionPage, ConnectionPagePlan, and GatewayConnectionManager for pairing reconnect and startup state adjacent to this PR's recovery-copy changes. (role: recent connection recovery contributor; confidence: medium; commits: 260fb90c6dc7; files: src/OpenClaw.Tray.WinUI/Pages/ConnectionPage.xaml.cs, src/OpenClaw.Tray.WinUI/Pages/ConnectionPagePlan.cs, src/OpenClaw.Connection/GatewayConnectionManager.cs)
• bkudiess: Current-main history includes prior ConnectionPage polish commits in the affected UI surface that match this PR author's GitHub identity, beyond only opening the current PR. (role: Connection page feature-history contributor; confidence: medium; commits: 9c9f70565076, d3d008206e4a, 6544d03ec219; files: src/OpenClaw.Tray.WinUI/Pages/ConnectionPage.xaml.cs, src/OpenClaw.Tray.WinUI/Pages/ConnectionPage.xaml, src/OpenClaw.Tray.WinUI/Pages/ConnectionPagePlan.cs)

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

[bkudiess]

Thanks @clawsweeper — addressed the blocking finding (option 1).

Removed the unsupported Basic-auth / user:password@ guidance from all three locations you flagged:

• ConnectionPage.xaml Direct auth hint (was line ~955) → now: "Paste a shared gateway token, or leave it blank to pair with a setup code."
• ConnectionPage.xaml TeachingTip Auth text (was line ~1022) → now: "Paste a shared token, or leave it blank and pair with a setup code. Re-pairing also upgrades this device's scopes."
• All 5 locale resources (ConnectionPage_TokenOrPasswordHint.Text and ConnectionPage_RemoteSetupHelpAuth.Text) updated to match.

Shared-token, setup-code pairing, TLS, and SSH guidance are unchanged. No credential storage, precedence, protocol, or MCP behavior was added — this was copy-only.

Validation re-run: ./build.ps1 OK; Tray.Tests 1215/0 (localization all-or-none passes); Connection.Tests 374/0; Shared.Tests 2566/0. Screenshots in the PR body re-captured from a rebuilt tray app showing the corrected hint and TeachingTip text.

Head is now d001762.