Gateway commands mix Linux vs Windows semantics + path confusion

[samanthamsong]

Problem: Gateway commands mix Linux vs Windows semantics and there is path confusion between the WSL and Windows sides. (Related to but distinct from #901, which tracks WSL Gateway <-> Tray version lock-step.)

Impact: Platform/infra - confusing, error-prone command surface across WSL/Windows.

Epic: should ladder up to #834 (S1 - Local gateway golden path).

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed July 1, 2026, 4:53 PM ET / 20:53 UTC.

Summary
Keep open: current main still exposes WSL/Linux gateway-control commands alongside Windows-host node command execution, and no merged current-main or release change defines the cross-boundary path and shell contract.

Reproducibility: no. high-confidence live reproduction yet. Source inspection gives a medium-confidence reproduction of the mixed command domains, but the issue lacks a concrete failing command, cwd, log, or screenshot and this read-only review did not run a Windows gateway path.

Ways to help us reproduce this

• Add expected vs actual behavior.

Next step
Maintainers need to choose the intended WSL-vs-Windows command and path contract before automation changes docs, UI, tests, or command behavior.

Review details

Best possible solution:

Define an explicit contract for local WSL gateway administration versus Windows node execution, then update the relevant UI, diagnostics, docs, and tests so each command names where it runs and which path format it expects.

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

No high-confidence live reproduction yet. Source inspection gives a medium-confidence reproduction of the mixed command domains, but the issue lacks a concrete failing command, cwd, log, or screenshot and this read-only review did not run a Windows gateway path.

Is this the best way to solve the issue?

Unclear until maintainers choose the intended contract. Current main has primitives and partial docs, but the narrow maintainable solution needs a product decision on whether to document, diagnose, translate paths, or change command behavior.

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

• The report does not include a concrete failing command, cwd, UI path, or log, so source inspection shows the mixed domains but not the exact user-facing failure mode.
• A fix may be docs-only, diagnostics/UI copy, path translation, or command API behavior; those options have different compatibility and operator-training implications.
• The adjacent version lock-step issue at Keep the local WSL OpenClawGateway version in lock-step with the Windows Tray app #901 does not settle this issue's path and shell semantics contract.

Codex review notes: model internal, reasoning high; reviewed against 8b857ecbb1f5.

Label changes

Label justifications:

• P2: The issue affects local gateway command usability and maintainer-visible platform behavior, but there is no crash, data loss, security bypass, or confirmed urgent live regression.
• impact:other: The concrete impact is platform/infra confusion across WSL and Windows command boundaries, which does not fit the specific owned impact labels.

Evidence reviewed

What I checked:

• Repository policy read and applied: AGENTS.md was read fully; its gateway, MCP, Windows-node, setup, and proof guidance makes this a product/architecture contract review rather than a narrow stale cleanup close. (AGENTS.md:31, 8b857ecbb1f5)
• WSL gateway control uses Linux-side command execution: WslGatewayController builds gateway start/stop/restart as bash -lc with a Linux PATH prefix and openclaw gateway inside the managed WSL distro. (src/OpenClaw.Connection/WslGatewayController.cs:32, 8b857ecbb1f5)
• WSL runner explicitly shells through wsl.exe: WslCommandRunner invokes wsl.exe, and RunInDistroAsync prepends -d <name> --, confirming this command surface runs on the WSL side. (src/OpenClaw.Connection/WslCommandRunner.cs:57, 4166e0fd63f8)
• Windows node system.run is documented as Windows-host execution: The MCP command description says system.run executes on the Windows node host with cwd and Windows-node shell semantics, which is distinct from WSL gateway administration. (src/OpenClaw.Shared/Mcp/McpToolBridge.cs:189, 4166e0fd63f8)
• Host runner uses Windows process working directory and shells: LocalCommandRunner maps requests to cmd.exe, pwsh.exe, or Windows PowerShell and applies request.Cwd as ProcessStartInfo.WorkingDirectory. (src/OpenClaw.Shared/LocalCommandRunner.cs:237, 4166e0fd63f8)
• Docs partially explain the split but do not define a full contract: WSL admin docs tell users to run gateway/config commands as the Linux openclaw user, use root via wsl.exe --user root, and avoid editing through Windows WSL shares. (docs/WSL_GATEWAY_ADMIN.md:3, 4166e0fd63f8)

Likely related people:

• shanselman: Current blame for the WSL gateway control builder, WSL command runner, MCP system.run description, and LocalCommandRunner points at the v0.6.12 source snapshot, and the current main docs refresh also came through this area. (role: recent source/docs contributor; confidence: high; commits: 4166e0fd63f8, 8b857ecbb1f5, e772b5e6e90c; files: src/OpenClaw.Connection/WslGatewayController.cs, src/OpenClaw.Connection/WslCommandRunner.cs, src/OpenClaw.Shared/LocalCommandRunner.cs)
• bkudiess: Commit history shows work on WSL gateway dependency recovery and the shared WSL command/terminal/controller helpers that are central to the Linux-side command surface. (role: WSL gateway helper contributor; confidence: medium; commits: 1e6951331f1c; files: src/OpenClaw.Connection/WslCommandRunner.cs, src/OpenClaw.Connection/WslGatewayController.cs, src/OpenClaw.Connection/GatewayTerminalLauncher.cs)
• ranjeshj: History ties the out-of-process SetupEngine redesign to the local gateway setup and WSL command path that this issue depends on. (role: local WSL setup owner; confidence: medium; commits: cefce3952ab1; files: src/OpenClaw.SetupEngine/CommandRunner.cs, src/OpenClaw.SetupEngine/SetupSteps.cs, src/OpenClaw.Connection/GatewayConnectionManager.cs)
• indierawk2k2: GitHub PR history and commit metadata show Windows node gateway metadata and WSL keepalive work adjacent to how node commands are exposed through the gateway. (role: Windows node adjacent contributor; confidence: low; commits: ffb59394e88b; files: src/OpenClaw.Tray.WinUI/Services/NodeService.cs, src/OpenClaw.Shared/WindowsNodeClient.cs, docs/gateway-node-integration.md)

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.