feat(integrations): surface the WSL2 mirrored-networking step for OpenClaw

[joelst]

Flint already ships the fix for this. The problem is finding it.

The gap

Settings → Network → WSL clients is complete and good: it detects WSL presence, version, and NAT-vs-mirrored mode, offers Enable mirrored networking in one click, writes .wslconfig with a backup, prompts the WSL restart, and documents the manual NAT fallback. Backed by sidecar/wsl-config.js and wsl-config.test.ts.

But the pointer to it lived in the OpenClaw card's limitations array, which renders only after clicking "Show limitations & docs" — collapsed by default. So the real path was:

copy snippet → connection refused → think to expand a disclosure panel → read bullet 1 of 4 → navigate to another tab

WSL2's default NAT mode gives the VM its own loopback, so a client inside WSL cannot reach Flint on 127.0.0.1 even though the identical URL works from Windows. That is the most likely first-run failure for OpenClaw on Windows, and RELEASE_ROADMAP.md names OpenClaw compatibility as the headline next milestone while RELEASE_0.7.0.md requires shipping "one verified client recipe."

The change

Data-only edit to the integrations catalog — no component or runtime changes:

• Card description now names the WSL2 requirement and where the one-click setup lives, visible without expanding anything.
• Limitations entry reduced to the manual NAT alternative, so the card does not say it twice.

USER_GUIDE.md gains a WSL clients row in the network table, a subsection on why loopback fails under NAT, and a troubleshooting row for "WSL client cannot connect (works from Windows)."

Deliberately not in this PR

A button on the card that navigates straight to the setting. That means touching +page.svelte (444 KB, @ts-nocheck, untested per BACKLOG.md), and a button landing on Settings without scrolling to the WSL section is a half-feature. It belongs with the existing "Verified recipes for OpenClaw, Cline, Continue" backlog item.

Drive-by

The guide's troubleshooting table still said SmartScreen warnings are "expected with self-signed builds until release certs" — the same stale claim fixed in the README in #116. Windows installers carry a public-trust Authenticode signature; corrected to note that a new publisher identity can still draw a SmartScreen prompt until it accumulates reputation.

Verification

• npm test — 1100/1100
• npm run check — 0 errors (1 pre-existing a11y warning in +page.svelte:8446, untouched here)
• npm run verify:markdown-links — 135 links across 29 files
• Changeset uses empty frontmatter: this ships in 0.7.0, whose version is already set, so it must not bump

Note for the release

This changes shipped code, so the draft's artifacts (built from afdc9a4) go stale and 0.7.0 needs a re-signed rebuild. The workflow passes releaseBody: "See CHANGELOG for details." to tauri-action, which will likely overwrite the concise release notes on the draft — they need re-applying after the rebuild.

[Copilot]

🟡 Changes recommended

Clarify the WSL setup flow and NAT wording, and update the contradictory in-app SmartScreen guidance.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Improves OpenClaw WSL2 networking discoverability and documents setup, NAT fallback, and SmartScreen guidance.

Changes:

• Updates the OpenClaw integration card.
• Adds WSL networking and troubleshooting guidance.
• Adds a non-version-bumping 0.7.0 changeset.

File summaries

File	Summary
src/lib/integrations.ts	Updates OpenClaw guidance; moderate issue: “one-click setup” overstates the actual flow (1 vote).
docs/USER_GUIDE.md	Adds WSL documentation; nit on qualifying NAT guidance (3 votes) and moderate issue requiring the in-app SmartScreen text to be updated (1 vote).
.changeset/openclaw-wsl-discoverability.md	Records the release note without a version bump; no findings.

Review details

Suppressed comments (2)

docs/USER_GUIDE.md:128

• This fixes the guide's SmartScreen explanation, but the in-app Help troubleshooting item at src/routes/+page.svelte:8293 still says Windows installers are self-signed and that release certificates are not yet used. Users following Help will therefore receive contradictory, obsolete guidance; update that user-facing copy in the same change.

| Windows SmartScreen warning | Installers are signed with a public-trust certificate, but a new publisher identity can still show a SmartScreen prompt until it accumulates reputation. Choose **More info → Run anyway**. |

src/lib/integrations.ts:410

• The visible card copy calls this a one-click setup, but on a fresh Settings view wslStatus is null and the only action shown is Check WSL; the enable button appears only after that probe, and enabling still requires confirmation plus a WSL restart. Please describe this as a guided setup or mention those steps so the card matches the actual flow.

      'Agentic coding tool. OpenClaw natively supports OpenAI-compatible local endpoints — point it at Flint directly per its "local models" gateway docs. No translation proxy required for the standard path. Running OpenClaw inside WSL2? Turn on mirrored networking first — Settings → Network → WSL clients does it in one click. WSL\'s default NAT mode gives the VM its own loopback, so the snippet below cannot reach Flint on 127.0.0.1 until you do.',

• Files reviewed: 3/3 changed files
• Comments generated: 1
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🟡 Changes recommended

The guidance contains contradictory networking claims, omits compatibility constraints, and recommends bypassing SmartScreen without verification.

Get a fresh assessment by requesting another Copilot review.

Review details

Suppressed comments (1)

docs/USER_GUIDE.md:91

• The new NAT fallback below makes both claims in this table too absolute: mirrored networking is not required to reach Flint when the manual host-address route is used, and the client URL is not always loopback in that mode. Qualify these rows so the summary agrees with the detailed instructions.

| **WSL clients** (Settings → Network) | One-click **mirrored networking** lets tools running inside WSL2 use the usual loopback URL; NAT users can follow the manual setup below. |

• Files reviewed: 3/3 changed files
• Comments generated: 3
• Review effort level: Balanced

[Copilot]

🟡 Changes recommended

The guide contains a broken manual-setup reference and does not identify the expected Authenticode publisher.

Get a fresh assessment by requesting another Copilot review.

Review details

• Files reviewed: 3/3 changed files
• Comments generated: 2
• Review effort level: Balanced

[Copilot]

🔵 Needs a closer look

The guide directs unsupported Windows/WSL versions to a mirrored-networking button that the UI does not render.

Review details

Suppressed comments (2)

Previously missed (1) — in code that hasn't changed since the last review.

docs/USER_GUIDE.md:99

• This says the panel always offers the one-click action, but the UI only renders that button when mirroredSupported is true; on Windows older than 11 22H2 or WSL older than 2.0, users only get the manual NAT instructions. Qualify the button by those requirements so the guide matches the actual fallback behavior.

This issue also appears on line 127 of the same file.

docs/USER_GUIDE.md:127

• The troubleshooting action can be absent on unsupported Windows/WSL versions, leaving affected users with no applicable instruction. Include the same version qualification and point unsupported systems to the manual NAT setup shown by the panel.

| WSL client cannot connect (works from Windows) | WSL2 NAT mode cannot reach `127.0.0.1` on the host. **Settings → Network → WSL clients → Enable mirrored networking**, then restart WSL. |

• Files reviewed: 3/3 changed files
• Comments generated: 0 new
• Review effort level: Balanced