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, 4:45 PM ET / 20:45 UTC.

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

Reproducibility: not applicable. this is a PR implementing setup UX and recovery improvements, not a standalone bug report. Source inspection and screenshots cover the visible Direct setup behavior; live gateway recovery states were not reproduced.

Review metrics: 2 noteworthy metrics.

• Changed surface: 17 files, +1403/-58. The PR spans shared classifiers, connection manager API, WinUI setup UX, locale resources, and tests, so maintainers should review both behavior and copy.
• Localized security copy: 5 locale files changed. Credential and transport guidance must stay consistent across supported languages 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 user guidance for when remote gateway tokens are protected in transit; CI cannot prove that the trusted-proxy/Tailscale wording 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 Current Security Copy Scope (recommended)
   Land with the current screenshots and classifier tests if maintainers agree that TLS, managed SSH, and trusted private overlays are the intended remote-gateway guidance.
2. Require Live Gateway Recovery Proof
   Ask for a redacted live gateway fixture demonstration for token drift, scope mismatch, TLS failure, and rate-limit recovery states before merge.
3. Narrow Trusted-Proxy Wording
   Revise the help copy to recommend TLS or managed SSH only if maintainers do not want the app to endorse cleartext ws URLs over private overlay networks.

Next step before merge

• No ClawSweeper repair is queued because the remaining action is maintainer judgment on security-sensitive setup guidance and proof scope, not a narrow code defect.

Security
Cleared: No concrete security or supply-chain defect was found; the remaining security-boundary question is maintainer acceptance of the remote credential-transport guidance.

Review details

Best possible solution:

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

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

Not applicable: this is a PR implementing setup UX and recovery improvements, not a standalone bug report. Source inspection and screenshots cover the visible Direct setup behavior; live gateway recovery states were not reproduced.

Is this the best way to solve the issue?

Yes, with maintainer acceptance. The implementation keeps connection lifecycle and credential persistence in the existing GatewayConnectionManager/GatewayRegistry boundary and adds focused classifier and setup-code coverage.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 37bdd3837709.

Label changes

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 credentials are encrypted 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:

• Repository policy read and 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, 37bdd3837709)
• Connection ownership boundary: Connection architecture docs identify GatewayConnectionManager as the connection lifecycle owner and GatewayRegistry as the gateway record and credential persistence boundary, which matches the PR's implementation surface. (docs/CONNECTION_ARCHITECTURE.md:17, 37bdd3837709)
• Setup-code SSH persistence: PR head changes ApplySetupCodeAsync to accept an optional SshTunnelConfig and stores it on the GatewayRecord while preserving the existing shared/bootstrap token behavior. (src/OpenClaw.Connection/GatewayConnectionManager.cs:521, e228f4b8fffa)
• Setup-code UI path passes tunnel config: The latest PR head builds the add-form SSH tunnel config and passes it into ApplySetupCodeAsync from the setup-code flow. (src/OpenClaw.Tray.WinUI/Pages/ConnectionPage.xaml.cs:2745, e228f4b8fffa)
• Remote setup security copy: The PR head shows the new Direct auth hint, TeachingTip, TLS/SSH/trusted-proxy guidance, and no user-info/password-in-URL guidance in this setup help surface. (src/OpenClaw.Tray.WinUI/Pages/ConnectionPage.xaml:954, e228f4b8fffa)
• Classifier and persistence tests: The PR adds focused classifier tests plus a setup-code test asserting that an SSH tunnel config is persisted on the active gateway record. (tests/OpenClaw.Connection.Tests/SetupCodeFlowTests.cs:106, e228f4b8fffa)

Likely related people:

• ranjeshj: Recent merged history includes connection/pairing hardening and the merged tray UX stack that touched ConnectionPage and GatewayConnectionManager. (role: connection architecture and tray UX area contributor; confidence: high; commits: ea36b12f9e4c, 429be9ba9368, ed126f2aac6d; files: src/OpenClaw.Connection/GatewayConnectionManager.cs, src/OpenClaw.Tray.WinUI/Pages/ConnectionPage.xaml.cs, src/OpenClaw.Tray.WinUI/Pages/ConnectionPage.xaml)
• vincentkoc: Recent current-main history touches pairing reconnect and startup state adjacent to the recovery-copy and credential-source behavior in this PR. (role: recent connection recovery contributor; confidence: medium; commits: 260fb90c6dc7, ee8fd4ef4ff0, 64b650cb3313; files: src/OpenClaw.Connection/GatewayConnectionManager.cs, src/OpenClaw.Tray.WinUI/Pages/ConnectionPagePlan.cs)
• bkudiess: Current-main commit history includes prior ConnectionPage rebuild and polish commits by this contributor, so they are relevant beyond opening this PR. (role: Connection page feature-history contributor; confidence: high; commits: 672aadc33fe0, 6544d03ec219, d3d008206e4a; files: src/OpenClaw.Tray.WinUI/Pages/ConnectionPage.xaml.cs, src/OpenClaw.Tray.WinUI/Pages/ConnectionPage.xaml, src/OpenClaw.Tray.WinUI/Pages/ConnectionPagePlan.cs)
• anagnorisis2peripeteia: Recent current-main work added per-gateway browser-control endpoint override support and hardened shared-token routing for split and remote gateway topologies. (role: adjacent remote topology/security contributor; confidence: medium; commits: a2e2773bb935; files: src/OpenClaw.Connection/GatewayRecord.cs, src/OpenClaw.Tray.WinUI/Services/NodeService.cs, tests/OpenClaw.Tray.Tests/BrowserProxyEndpointScopingTests.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.