feat(connection): enforce gateway protocol compatibility

[bkudiess]

Related: #1105

Note

This was developed as the next layer over #1105 and rebased onto main after #1105 merged.

What Problem This Solves

Resolves a problem where an incompatible Gateway could be treated as a generic connection failure or continue far enough to break Windows-node behavior without telling the operator which component needed updating.

Why This Change Was Made

The Windows operator and node clients now share the documented Gateway protocol v3-v4 range and validate the minimal hello-ok shape before publishing connection success or persisting handshake tokens. Successful hello values at or above the supported floor remain forward-compatible because hello-ok.protocol is the Gateway's current constant, while structured mismatch responses drive too-old/too-new recovery. Structured compatibility state drives diagnostics, MCP, telemetry, and directional Connection-page recovery without changing setup, WSL lifecycle, or Gateway package selection.

User Impact

Supported v3-v4 Gateways connect normally. Gateways below that range show Gateway update required. Newer Gateways that reject the offered range show Windows app update required. Deterministic protocol mismatches do not reconnect indefinitely, but the operator retains explicit Connect and Disconnect recovery controls after updating software.

Gateway package version and wire protocol remain separate diagnostics.

Evidence

Gateway update required

Windows app update required

Both screenshots are from the source-identical proof build represented by final commit 9f558495cd8a4323f86b54391e6e9209eb0a4231, use unique isolated roaming and local-data roots, and render a loopback fake Gateway with no real credentials.

Live isolated winnode --command app.connection.status --params '{}' proof:

{
  "schemaVersion": 2,
  "effectiveMode": "LocalMcpOnly",
  "gateway": { "packageVersion": null },
  "protocol": {
    "selectedProtocol": null,
    "currentProtocol": 4,
    "minimumSupportedProtocol": 3,
    "maximumSupportedProtocol": 4,
    "compatibility": "gateway_too_new",
    "source": "operator",
    "gatewayExpectedProtocol": 5,
    "gatewayMinimumProtocol": 3,
    "retryable": false
  },
  "mcp": { "enabled": true, "running": true, "error": null }
}

gateway.packageVersion is intentionally null because the incompatible hello is rejected before Gateway self-information is published.

Live OTLP collector proof

Exact current-head commit 9f558495cd8a4323f86b54391e6e9209eb0a4231 exported to a test-owned loopback collector at http://127.0.0.1:54946 using OTLP HTTP/protobuf. Six requests were decoded with the official ExportTraceServiceRequest, ExportMetricsServiceRequest, and ExportLogsServiceRequest schemas.

Affected trace:

{
  "name": "openclaw.connection.operator.connect",
  "status": "STATUS_CODE_ERROR",
  "eventPayloadCount": 0,
  "attributes": {
    "openclaw.connection.role": "operator",
    "openclaw.connection.operation": "connect",
    "openclaw.source": "gateway_connection",
    "openclaw.outcome": "failure",
    "openclaw.protocol.client": 4,
    "openclaw.protocol.gateway": "newer",
    "openclaw.protocol.compatibility": "gateway_too_new",
    "openclaw.error.category": "protocolmismatch"
  }
}

Affected metric:

{
  "name": "openclaw.connection.attempt.duration",
  "type": "histogram",
  "unit": "ms",
  "count": 1,
  "attributes": {
    "openclaw.connection.role": "operator",
    "openclaw.connection.operation": "connect",
    "openclaw.outcome": "failure",
    "openclaw.protocol.client": 4,
    "openclaw.protocol.gateway": "newer",
    "openclaw.protocol.compatibility": "gateway_too_new",
    "openclaw.error.category": "protocolmismatch"
  }
}

Logs were also decoded. By design they contain only finite connection event and role-state fields and do not carry protocol tags.

Privacy inspection found no collector/Gateway URL, Gateway/device/pairing ID, credential/token, raw error message/frame, Gateway package version, or user content in exported application attributes. Standard pre-existing OTLP resource metadata such as tray service.version, process ID, service instance ID, and SDK identity was redacted from this proof. Sanitized collector artifact SHA-256: be52c76d229480f4d71db57840ada22f2107a112454872a1a0e5196df5a41737.

Change Type

• Bug fix
• Feature
• Refactor
• Docs or instructions
• Tests or validation
• Security hardening
• Chore or infrastructure

Scope

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

Validation

• $env:OPENCLAW_REPO_ROOT = (Get-Location).Path; .\build.ps1: 5/5 projects and 46 docs succeeded, 0 warnings/errors
• Shared: 3,690 passed, 32 skipped, 0 failed
• Tray: 2,260 passed, 0 failed
• Connection: 593 passed, 0 failed
• WinNode CLI: 127 passed, 0 failed
• Aggregate local closeout: 6,670 passed, 32 skipped, 0 failed
• Focused compatibility: Shared 19, Connection manager/state machine 224, Tray 21, CLI drift 2
• Default localization: 22 passed
• Strict localization: only two pre-existing untouched hard-coded strings remain:
  • SettingsPage.xaml: OpenClaw Windows Companion
  • HubWindow.xaml: Disconnected
• GitHub CI on the exact final head:
  • full test job passed, including Tray integration and Accessibility
  • setup-connect, revocation-recovery, and network-recovery E2E shards passed
  • x64 and ARM64 packaging builds passed
  • all required checks are green

Review:

• Independent Opus and Codex adversarial reviews found the documented v3 compatibility cutoff, forward-compatible hello semantics, node transport closure, stale MCP selected protocol, recovery controls, accepted-protocol state propagation, event ordering, localization, documentation, and automatic-reconnect issues; all accepted findings were fixed with focused regressions.
• Final actual-head review at 9f558495:
  • GPT-5.3 Codex: 97/100, no Critical/High/Medium findings
  • Claude Opus 5: 96/100, no Critical/High/Medium findings
  • Independent Claude Sonnet 5 code review: 93/100, no Critical/High/Medium findings
  • Average: 95.3/100
• Repository-aware rubber-duck review found no actionable defects after all fixes.
• Bundled autoreview failed closed before model invocation because the bundle, including binary screenshots, exceeded its 180 KB limit.

Real Behavior Proof

• Environment tested: Windows, isolated local data, loopback fake Gateway, isolated Local MCP, loopback OTLP collector
• PR head or commit tested: 9f558495cd8a4323f86b54391e6e9209eb0a4231
• Exact steps:
  • launch current-head Companion with unique OPENCLAW_TRAY_DATA_DIR and OPENCLAW_TRAY_LOCALAPPDATA_DIR
  • connect to test-owned loopback mismatch Gateway
  • inspect Connection page through UI Automation
  • run winnode --list-tools and winnode --command app.connection.status --params '{}'
  • export OTLP HTTP/protobuf to a test-owned collector and decode traces, metrics, and logs
• Observed result:
  • expected protocol v2 produces Gateway-update guidance
  • expected protocol v5 produces Windows-app-update guidance
  • both mismatch states retain explicit Connect and Disconnect without automatic reconnect
  • MCP reports current/min/max v4/v3/v4, role source, expected protocol, null selected protocol during mismatch, and non-retryable compatibility
  • OTLP trace and attempt-duration metric carry the finite protocol/error attributes shown above
• Screenshot or artifact links verified? Yes
• Not verified or blocked:
  • no real Gateway or WSL path was exercised for this protocol/UX layer
  • the earliest proof attempt omitted local-data isolation and stopped stale shared keepalive PID 36632; it was reported immediately, never restarted or touched afterward, and its transient screenshot was discarded. All retained proof used fresh isolated roaming and local-data roots.

Security Impact

• New permissions or capabilities? No
• Secrets or tokens handling changed? No
• New or changed network calls? No
• Command or tool execution surface changed? No
• Data access scope changed? No
• If any answer is Yes, explain the risk and mitigation: N/A

The change fails closed before token persistence or connected state when the Gateway rejects the offered protocol range.

Compatibility and Migration

• Backward compatible? Yes; preserves the documented protocol v3-v4 range and adds explicit handling outside it
• Config or environment changes? No
• Migration needed? No
• If yes, list the exact upgrade steps: N/A

Review Conversations

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

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed August 9, 2026, 10:50 AM ET / 14:50 UTC.

ClawSweeper review

What this changes

Adds Gateway wire-protocol validation and exposes incompatible-Gateway recovery through connection state, WinUI, local MCP diagnostics, telemetry, documentation, and regression tests.

Merge readiness

⚠️ Ready for maintainer review - 3 items remain

This PR remains necessary: current main advertises the v3-v4 range but accepts a hello-ok by type without validating its protocol value. The proposed boundary and recovery paths are coherent, proof is substantial, and a maintainer should decide whether to land this cross-cutting compatibility policy.

Priority: P1
Reviewed head: 9f558495cd8a4323f86b54391e6e9209eb0a4231
Owner decision: Required. See Decision needed.

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	A well-evidenced compatibility implementation with broad but cohesive scope and no supported line-level correctness finding.
Proof confidence	🦞 diamond lobster (5/6) ✨ media proof bonus	Sufficient (screenshot): Prepared current-head screenshots visibly show both update-directed Connection-page states, and the PR body includes after-fix local MCP and loopback collector output from isolated data roots.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Verified	Sufficient (screenshot): Prepared current-head screenshots visibly show both update-directed Connection-page states, and the PR body includes after-fix local MCP and loopback collector output from isolated data roots.
Evidence reviewed	5 items	Current main lacks handshake protocol validation: Both clients advertise protocol range 3 through 4, while the operator response path recognizes hello-ok by type before publishing success and persisted handshake state. This establishes the remaining gap addressed by the PR. Documented compatibility boundary: Current documentation says Windows advertises minProtocol 3 and maxProtocol 4, and that current main only records hello-ok.protocol for diagnostics rather than branching on it. Current-head proof artifacts: Prepared screenshots visibly show both directional recovery states, including retained Connect and Disconnect controls. The PR body also supplies source-head local MCP status output and loopback collector output for the same behavior.
Findings	None	None.
Security	None	None.

How this fits together

The operator and Windows-node clients connect to a Gateway through the shared connection manager. Handshake results become connection state, then drive reconnection behavior, the Connection page, local MCP diagnostics, and opt-in telemetry.

flowchart LR
A[Gateway handshake response] --> B[Operator and node clients]
B --> C[Protocol range validation]
C --> D[Connection state manager]
D --> E[Reconnect policy]
D --> F[Connection page recovery]
D --> G[Local MCP diagnostics]
D --> H[Opt-in telemetry]

Loading

Decision needed

Question	Recommendation
Should the documented v3-v4 range become the enforced terminal runtime boundary for both managed and remote Gateway connections?	Confirm the v3-v4 boundary and land: Merge the PR with the documented policy that incompatible handshakes stop automatic retries and direct the operator to update the affected side.

Why: The implementation changes failure and retry behavior for existing remote Gateways, which is a support-policy decision beyond ordinary code correctness.

Before merge

• Resolve merge risk (P1) - Merging turns malformed or out-of-range handshakes into terminal non-retrying states, so a supported-range decision directly affects existing remote Gateway recovery.
• Resolve merge risk (P1) - The change crosses operator and node lifecycle, UI, MCP, and telemetry. The loopback proof is strong, but no real Gateway or WSL route was exercised for this exact mismatch behavior.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Cross-cutting surface	43 files, +2,627 / -72 lines	The compatibility policy reaches both clients, connection state, WinUI, MCP, telemetry, docs, and focused regressions.

Merge-risk options

Maintainer options:

1. Confirm and land the documented boundary (recommended)
   Accept v3-v4 as the supported Gateway contract and merge the explicit mismatch recovery behavior.
2. Add real-Gateway upgrade proof first
   Pause merge until a real supported Gateway confirms that normal connection and recovery remain intact around this terminal mismatch policy.

Technical review

Best possible solution:

Keep one shared v3-v4 contract, reject incompatible handshakes before connected state or token persistence, and retain clear manual recovery controls with compatibility-safe local MCP diagnostics.

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

Yes, source reproducible: current main advertises v3-v4 but does not validate the successful handshake protocol before publishing connection success. This read-only review did not execute the loopback reproduction.

Is this the best way to solve the issue?

Yes, conditional on maintainer confirmation of the v3-v4 support policy. A shared contract and sanitized compatibility state avoid divergent operator and node handling.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 582a44713860.

Labels

Label justifications:

• P1: This changes connection and recovery behavior for operator and Windows-node workflows.
• merge-risk: 🚨 compatibility: Existing remote Gateways outside the documented range now receive a terminal update path rather than generic failure handling.
• merge-risk: 🚨 availability: Protocol mismatch intentionally suppresses automatic reconnect for both connection roles.
• 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): Prepared current-head screenshots visibly show both update-directed Connection-page states, and the PR body includes after-fix local MCP and loopback collector output from isolated data roots.
• proof: sufficient: Contributor real behavior proof is sufficient. Prepared current-head screenshots visibly show both update-directed Connection-page states, and the PR body includes after-fix local MCP and loopback collector output from isolated data roots.
• proof: 📸 screenshot: Contributor real behavior proof includes screenshot evidence. Prepared current-head screenshots visibly show both update-directed Connection-page states, and the PR body includes after-fix local MCP and loopback collector output from isolated data roots.

Evidence

What I checked:

• Current main lacks handshake protocol validation: Both clients advertise protocol range 3 through 4, while the operator response path recognizes hello-ok by type before publishing success and persisted handshake state. This establishes the remaining gap addressed by the PR. (src/OpenClaw.Shared/OpenClawGatewayClient.cs:1792, 582a44713860)
• Documented compatibility boundary: Current documentation says Windows advertises minProtocol 3 and maxProtocol 4, and that current main only records hello-ok.protocol for diagnostics rather than branching on it. (docs/CONNECTION_PROTOCOL_RESEARCH.md:79, 582a44713860)
• Current-head proof artifacts: Prepared screenshots visibly show both directional recovery states, including retained Connect and Disconnect controls. The PR body also supplies source-head local MCP status output and loopback collector output for the same behavior. (docs/proof/gateway-compatibility/gateway-too-new.png, 9f558495cd8a)
• Related merged policy work: feat(setup): enforce validated protocol-v4 Gateway releases #1105 established the exact protocol-v4 Gateway release policy; this PR adds the distinct runtime handshake and recovery layer. (docs/CONNECTION_PROTOCOL_RESEARCH.md:71, e295df266c72)
• Recent connection-area ownership: Recent current-main history shows Barbara Kudiess authored the gateway recovery hardening that touches both gateway clients and the connection manager. (src/OpenClaw.Connection/GatewayConnectionManager.cs:1, 603886a81d34)

Likely related people:

• Barbara Kudiess: Authored current-main gateway recovery and credential-handoff work across the affected gateway client and connection-manager paths. (role: recent connection-area contributor; confidence: high; commits: 603886a81d34, bc210e048aa9, c04c5fb06238; files: src/OpenClaw.Shared/OpenClawGatewayClient.cs, src/OpenClaw.Connection/GatewayConnectionManager.cs)
• Scott Hanselman: Authored current-main managed Gateway release and restart hardening adjacent to the documented protocol-v4 support policy. (role: recent adjacent contributor; confidence: medium; commits: 01faa6419b42; files: src/OpenClaw.Shared/OpenClawGatewayClient.cs, src/OpenClaw.Connection/GatewayConnectionManager.cs)
• RomneyDa: Authored the merged Gateway release-policy PR that establishes the protocol-v4 setup context this runtime compatibility layer builds on. (role: introduced release-policy context; confidence: medium; commits: e295df266c72; files: docs/CONNECTION_PROTOCOL_RESEARCH.md)

Rank-up moves

Optional improvements that raise the rating; they are not merge blockers.

• Obtain maintainer confirmation that the v3-v4 boundary is the intended remote-Gateway support policy.

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
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.

Workflow

• 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.

History

Review history (19 earlier review cycles; latest 8 shown)

• reviewed 2026-08-09T01:47:30.517Z sha 9f55849 :: found issues before merge. :: [P2] Capture current-head collector proof for protocol telemetry
• reviewed 2026-08-09T02:17:32.993Z sha 9f55849 :: needs maintainer review before merge. :: none
• reviewed 2026-08-09T03:16:15.842Z sha 9f55849 :: needs maintainer review before merge. :: none
• reviewed 2026-08-09T04:09:47.247Z sha 9f55849 :: needs maintainer review before merge. :: none
• reviewed 2026-08-09T06:55:51.390Z sha 6b6b875 :: needs maintainer review before merge. :: none
• reviewed 2026-08-09T08:46:01.978Z sha 9f55849 :: needs maintainer review before merge. :: none
• reviewed 2026-08-09T10:20:42.283Z sha 9f55849 :: needs maintainer review before merge. :: none
• reviewed 2026-08-09T11:59:10.755Z sha 9f55849 :: needs maintainer review before merge. :: none

[bkudiess]

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: when the review finishes, ClawSweeper will create the durable review comment if needed or update the existing comment in place.

Re-review progress:

• State: Complete
• Detail: A newer review tuple already exists; this stale result was superseded.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/31290093545
• Updated: 2026-08-09T02:19:39.314Z

[bkudiess]

@clawsweeper re-review