Surface accurate node mode and MCP-only states

[bkudiess]

Summary

• Problem: Node/MCP settings could present misleading state: MCP-only could look disabled, and one credentialed MCP-only startup path did not start the local MCP server after a successful operator startup connect.
• Why it matters: Users need truthful UI for whether capabilities are being served locally. MCP-only mode must not silently start a gateway node, and it must still start local MCP when an operator connection exists.
• What changed: Added explicit MCP-only and node-starting UI states, surfaced MCP startup errors, kept local MCP-served controls actionable while keeping gateway-only browser proxy disabled in MCP-only mode, and separated gateway-node startup gating from local NodeService/MCP initialization.
• What did NOT change: No credential precedence changes, no MCP token model changes, no new node capability commands, and no broader exec approval policy changes.

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
  Result: all projects built successfully.
• dotnet test ./tests/OpenClaw.Shared.Tests/OpenClaw.Shared.Tests.csproj --no-restore
  Result: 2513 passed, 31 skipped, 0 failed.
• dotnet test ./tests/OpenClaw.Connection.Tests/OpenClaw.Connection.Tests.csproj --no-restore
  Result: 373 passed, 0 failed.
• dotnet test ./tests/OpenClaw.Tray.Tests/OpenClaw.Tray.Tests.csproj --no-restore --filter "FullyQualifiedName~NodeModeUiStateTests|FullyQualifiedName~NodeCapabilityGatingTests|FullyQualifiedName~LocalizationValidationTests"
  Result: 49 passed, 0 failed.
• dotnet test ./tests/OpenClaw.Tray.Tests/OpenClaw.Tray.Tests.csproj --no-restore
  Result: local full-suite run currently hits unrelated AssistantBridgeServiceTests.StartListenServiceAsync_KillsTimedOutBackendCommand timing failure; that test passes when run isolated. Branch-affected Tray tests and localization validation pass.

Real behavior proof

Screenshot: Connection page MCP-only state with active operator gateway

Screenshot: Permissions page MCP-only state

Mixed operator-connected startup proof

Raw proof file: https://raw.githubusercontent.com/bkudiess/openclaw-windows-node/proof/pr-827-node-ui/mixed-startup-proof.md

Settings: EnableMcpServer=true, EnableNodeMode=false.
Profile: copied active local gateway profile with operator credential; secrets redacted.

[INFO] Connecting to last successful gateway during startup: ws://<gateway> (identity.DeviceToken)
[INFO] gateway connected, waiting for challenge...
[INFO]   role=operator, clientId=cli, mode=cli
[INFO] [HANDSHAKE] Received hello-ok!
[INFO] [MCP] HTTP server listening on http://<host>:8765/
[INFO] Started MCP-only node service without gateway connection
[INFO] [App] Skipping local NodeService auto-connect because node mode is disabled

MCP server proof artifact

Raw proof file: https://raw.githubusercontent.com/bkudiess/openclaw-windows-node/proof/pr-827-node-ui/mcp-proof.md

GET /:
OpenClaw MCP server. POST JSON-RPC to http://127.0.0.1:8765/

tools/list:
- total tools: 44
- selected tools: system.notify, system.which, canvas.present, screen.snapshot, camera.list, location.get, device.info

tools/call device.info:
{"systemName":"Windows","appVersion":"0.6.4-bkudiess-node-mode-ui-enablement.1","locale":"en-US"}

MCP server logs:
[INFO] Starting Windows Node in MCP-only mode (no gateway)
[INFO] Capabilities registered: system, canvas, screen, camera, location, device (6 caps)
[INFO] [MCP] HTTP server listening on http://<host>:8765/
[INFO] Started MCP-only node service without gateway connection
[DEBUG] [MCP] tools/call device.info

Security Impact (required)

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? No
• Command/tool execution surface changed? No
• Data access scope changed? No
• If any Yes, explain risk + mitigation: N/A. This PR changes UI/status/gating around existing node and MCP surfaces; it does not add commands, broaden network exposure, or change credential/token handling.

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.

Addressed ClawSweeper findings:

• Local MCP now starts after successful operator startup connects when EnableMcpServer=true and EnableNodeMode=false.
• Browser proxy toggle remains disabled in MCP-only mode because browser proxy requires a gateway node client.
• MCP startup errors are surfaced even when EnableNodeMode=true and the gateway node role is connected.

[clawsweeper]

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

Summary
The PR separates gateway-node startup gating from local MCP startup, adds MCP-only/connecting/error UI states on Connection and Permissions pages, updates localization, and adds tray tests.

Reproducibility: yes. Source inspection gives a high-confidence path: current docs define independent Node/MCP modes, while current main uses the combined ShouldInitializeNodeService predicate for gateway-node startup and collapses node-off/MCP-on to Off in the Connection plan.

Review metrics: 3 noteworthy metrics.

• Diff scope: 13 files, +567/-69. The patch spans startup gating, WinUI state rendering, localization, and tests, so runtime and UI validation both matter before merge.
• Real proof artifacts: 2 screenshots, 2 raw proof logs. The proof covers the visible MCP-only UI states plus live MCP startup and tool-call behavior.
• Merge-ref checks: 1 E2E shard failed. The failing setup-connect shard is merge-relevant because this PR changes startup and connection behavior, even though the observed timeout is in the MXC proof path.

Merge readiness
Overall: 🦐 gold shrimp
Proof: 🦞 diamond lobster ✨ media proof bonus
Patch quality: 🐚 platinum hermit
Result: needs maintainer review before merge.

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

Rank-up moves:

• [P2] Resolve the setup-connect MXC timeout or have a maintainer explicitly mark it unrelated to this PR before merge.

Risk before merge

• [P1] The patch changes node/MCP lifecycle gating, so an incorrect merge could leave local MCP unavailable, start an unintended gateway node, or misreport capability availability at startup.
• [P2] The setup-connect E2E shard failed on the merge ref with an MXC denied-write timeout; the failure is not a line-level defect in this diff, but maintainers should decide whether it is unrelated before landing an availability-sensitive change.
• [P1] The PR body reports the required full local Tray test run hit an unrelated timing failure, so branch-affected tests are covered but the repository-required full tray validation was not clean in the contributor’s local run.

Maintainer options:

1. Clear setup-connect before merge (recommended)
   Wait for the setup-connect E2E shard to pass, or document why the MXC denied-write timeout is unrelated to this node/MCP startup change before landing.
2. Accept the runtime proof
   Maintainers can merge based on the inspected screenshots and raw MCP/startup logs while explicitly owning the remaining setup-connect check risk.
3. Pause for an independent Windows smoke
   Keep the PR open until a maintainer repeats the Connection, Permissions, and mixed operator-connected MCP-only startup paths on a clean Windows tray setup.

Next step before merge

• [P2] Maintainers need to decide whether the failing setup-connect E2E result is unrelated or must be cleared before merging this availability-sensitive startup change.

Security
Cleared: No concrete security or supply-chain regression was found; the diff does not add dependencies, credential handling, capability commands, or new network exposure.

Review details

Best possible solution:

Land after maintainers either clear the setup-connect failure or explicitly accept it as unrelated, preserving the documented independent Node/MCP mode matrix and the supplied runtime proof.

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

Yes. Source inspection gives a high-confidence path: current docs define independent Node/MCP modes, while current main uses the combined ShouldInitializeNodeService predicate for gateway-node startup and collapses node-off/MCP-on to Off in the Connection plan.

Is this the best way to solve the issue?

Mostly yes. Separating gateway-node enablement from local MCP lifecycle matches the documented mode matrix; the remaining blocker is validation and maintainer acceptance, not a known code defect in the patch.

AGENTS.md: found and applied where relevant.

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

Label changes

Label justifications:

• P1: The PR targets a broken node/MCP workflow where local capabilities can be unavailable or misrepresented after startup.
• merge-risk: 🚨 availability: The diff changes node/MCP lifecycle gating, and an incorrect merge could leave local MCP or gateway node mode unavailable.
• rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; 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 (linked_artifact): The PR body includes after-fix screenshots plus raw startup and MCP logs showing the changed UI and live MCP-only behavior with secrets redacted.
• proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes after-fix screenshots plus raw startup and MCP logs showing the changed UI and live MCP-only behavior with secrets redacted.

Evidence reviewed

Acceptance criteria:

• [P1] ./build.ps1.
• [P1] dotnet test ./tests/OpenClaw.Shared.Tests/OpenClaw.Shared.Tests.csproj --no-restore.
• [P1] dotnet test ./tests/OpenClaw.Tray.Tests/OpenClaw.Tray.Tests.csproj --no-restore.
• [P1] dotnet test ./tests/OpenClaw.E2ETests/OpenClaw.E2ETests.csproj --no-restore --filter "FullyQualifiedNameOpenClaw.E2ETests.Setup.SetupAndConnectTests|FullyQualifiedNameOpenClaw.E2ETests.Setup.MxcSetupAndConnectTests" -r win-x64.

What I checked:

• Repository policy applied: AGENTS.md was read fully; its connection/MCP guidance applies because this PR changes connection, node, MCP, and tray UX behavior. (AGENTS.md:36, 1c377cb64b65)
• Documented mode contract: Current docs define EnableNodeMode and EnableMcpServer as independent, with EnableMcpServer=true and EnableNodeMode=false meaning local MCP server only with no gateway required. (docs/CONNECTION_ARCHITECTURE.md:185, 1c377cb64b65)
• Current-main startup mismatch: Current main passes ShouldInitializeNodeService as the gateway connection manager node predicate, and that predicate includes EnableMcpServer, so MCP-only settings can satisfy gateway-node startup gating. (src/OpenClaw.Tray.WinUI/App.xaml.cs:647, 1c377cb64b65)
• Current-main UI mismatch: Current main maps every EnableNodeMode=false case to NodeCardState.Off, so MCP-only mode is not represented as its own Connection-page node state. (src/OpenClaw.Tray.WinUI/Pages/ConnectionPagePlan.cs:601, 1c377cb64b65)
• PR startup split: At the PR head, GatewayConnectionManager receives IsGatewayNodeEnabled, node-only startup is gated only by EnableNodeMode, and credentialed operator startup starts local MCP when gateway node mode is off. (src/OpenClaw.Tray.WinUI/App.xaml.cs:649, fe6758eaef70)
• PR UI and test coverage: At the PR head, ConnectionPagePlan declares OffMcpOnly and OnNodeConnecting, maps node-off/MCP-on to OffMcpOnly, and source-level tray tests pin the new gating and UI status contracts. (src/OpenClaw.Tray.WinUI/Pages/ConnectionPagePlan.cs:85, fe6758eaef70)

Likely related people:

• codemonkeychris: Introduced local MCP HTTP server mode and the independent EnableNodeMode/EnableMcpServer contract that this PR preserves. (role: original MCP mode contributor; confidence: high; commits: a3d884f4c4ba; files: docs/MCP_MODE.md, src/OpenClaw.Tray.WinUI/App.xaml.cs, src/OpenClaw.Tray.WinUI/Services/NodeService.cs)
• shanselman: Restored the MCP-only startup path in App.xaml.cs, which is directly adjacent to the startup behavior changed here. (role: MCP-only startup contributor; confidence: high; commits: 49bc64708d2a; files: src/OpenClaw.Tray.WinUI/App.xaml.cs)
• ranjeshj: Authored connection architecture and MCP runtime-toggle work, plus recent tray UX stack changes touching Connection and Permissions surfaces. (role: connection and tray UX area contributor; confidence: high; commits: 5c49c5a820df, d7d7661ac28c, 429be9ba9368; files: src/OpenClaw.Tray.WinUI/App.xaml.cs, src/OpenClaw.Tray.WinUI/Pages/ConnectionPage.xaml.cs, src/OpenClaw.Tray.WinUI/Pages/PermissionsPage.xaml.cs)
• vincentkoc: Recent merged node reconnect/startup state work touched the same App and Connection-page state surfaces. (role: recent startup and connection-state contributor; confidence: medium; commits: 260fb90c6dc7; files: src/OpenClaw.Tray.WinUI/App.xaml.cs, src/OpenClaw.Tray.WinUI/Pages/ConnectionPage.xaml.cs, src/OpenClaw.Tray.WinUI/Pages/ConnectionPagePlan.cs)
• bkudiess: Beyond this PR, recent merged history includes adjacent tray permissions and capability readiness/status work. (role: recent tray permissions and capability contributor; confidence: medium; commits: ff5cafb52f52; files: src/OpenClaw.Tray.WinUI/Pages/PermissionsPage.xaml.cs, src/OpenClaw.Tray.WinUI/Services/NodeService.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]

@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: the existing ClawSweeper review comment will be edited in place when the review finishes.

[bkudiess]

@clawsweeper re-review

[bkudiess]

@clawsweeper re-review

[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: the existing ClawSweeper review comment will be edited in place when the review finishes.

[bkudiess]

@clawsweeper re-review