fix: diagnose Windows LAN Gateway firewall blocks by joshavant · Pull Request #98666 · openclaw/openclaw

joshavant · 2026-07-01T14:25:13Z

What Problem This Solves

Windows users can bind the Gateway to LAN, see a valid local loopback probe and LAN Control UI URL, and still have other devices blocked by Windows Firewall. The old status/setup paths either missed that distinction or risked spending too much time on firewall inspection in critical user flows.

Why This Change Was Made

This moves Windows Firewall inspection out of critical flows. Fast gateway status/probe no longer runs PowerShell or netsh, and setup/configure only print static Windows LAN firewall guidance.

Deep gateway status remains the diagnostic path. On Windows LAN bindings, openclaw gateway status --deep runs one bounded read-only PowerShell probe that inspects active profiles, local rules, and managed ActiveStore rules so GPO/MDM allow rules are not misreported as blocked.

User Impact

Windows LAN users get faster setup/configure/status flows and still have an explicit deep diagnostic when LAN clients cannot reach the advertised Gateway URL. The warning points users toward an inbound TCP allow rule, a managed firewall rule, loopback, Tailscale, or SSH tunneling as appropriate.

AI-assisted: implemented with Codex.

Evidence

pnpm test src/infra/windows-gateway-firewall-diagnostics.test.ts src/commands/gateway-status.test.ts src/cli/daemon-cli/status.gather.test.ts src/wizard/setup.finalize.test.ts src/commands/configure.wizard.test.ts -- --reporter=verbose
node scripts/run-oxlint.mjs --tsconfig config/tsconfig/oxlint.core.json ...changed files...
pnpm tsgo:core
pnpm tsgo:test:src
git diff --check
$autoreview: clean after addressing accepted findings around managed-rule preservation and quick-probe port matching.
Live E2E on local Parallels Windows 11, LAN Gateway config on port 28991:
- Fast openclaw gateway status --json --timeout 3000: completed with no gateway.windowsFirewall block.
- Fast openclaw gateway probe --json --port 28991 --timeout 3000: emitted no firewall warnings; failed only when no Gateway was listening.
- Foreground LAN Gateway run plus fast openclaw gateway status --json --timeout 5000 --token ...: RPC OK, Gateway version reported, no gateway.windowsFirewall block.
- Foreground LAN Gateway run plus openclaw gateway status --deep --json --timeout 5000 --token ...: RPC OK and emitted gateway.windowsFirewall.code = "windows_firewall_program_scoped_rule_unverified" instead of windows_firewall_inspection_failed.

joshavant · 2026-07-01T14:42:44Z

@clawsweeper re-review

clawsweeper · 2026-07-01T14:42:47Z

🦞🧹
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.

clawsweeper · 2026-07-01T14:54:29Z

Codex review: needs maintainer review before merge. Reviewed July 1, 2026, 5:23 PM ET / 21:23 UTC.

Summary
The PR adds read-only Windows Firewall diagnostics for deep local LAN Gateway status, static Windows LAN firewall guidance in setup/configure/docs, and focused regression tests.

PR surface: Source +1074, Tests +927, Docs +4. Total +2005 across 13 files.

Reproducibility: yes. for review purposes: current main lacks the diagnostic path, and the PR body gives a concrete Parallels Windows 11 before/after path for the blocked LAN URL case. I did not rerun that live Windows setup in this read-only review.

Review metrics: 1 noteworthy metric.

Windows subprocess diagnostic: 1 bounded quick PowerShell inspection added to deep local LAN status. This is the one new runtime availability cost maintainers should consciously accept before merge.

Stored data model
Persistent data-model change detected: serialized state: src/infra/windows-gateway-firewall-diagnostics.test.ts. Confirm migration or upgrade compatibility proof before merge.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🦞 diamond lobster
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] Merging this intentionally adds bounded native Windows PowerShell firewall inspection to deep local LAN Gateway status, so maintainers should accept the CLI responsiveness and availability tradeoff.
[P1] The PR has strong Parallels Windows proof, but source review and CI cannot fully settle every managed Windows Firewall, GPO, or MDM policy variant the diagnostic classifies.

Maintainer options:

Accept Bounded Windows Inspection (recommended)
A maintainer can accept the added deep-status latency because the inspection is local-only, timeout-bounded, read-only, and backed by Windows before/after proof.
Ask For More Managed-Policy Proof
Maintainers can hold the PR until another Windows firewall, Group Policy, or MDM environment confirms the warning classifications if the Parallels proof is not enough.
Narrow The Diagnostic Budget
Maintainers can request a smaller timeout or more explicit diagnostic budget before merge if five seconds is too expensive for deep status.

Next step before merge

[P2] The protected maintainer label and explicit availability-risk acceptance make this a human maintainer merge decision rather than an automated repair job.

Security
Cleared: The diff adds bounded read-only local Windows inspection and warning output without dependency, workflow, secret-handling, permission, or firewall-policy mutation changes.

Review details

Best possible solution:

Land the diagnostic only if maintainers accept bounded Windows PowerShell inspection in deep local LAN status; otherwise narrow the diagnostic budget before merge.

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

Yes for review purposes: current main lacks the diagnostic path, and the PR body gives a concrete Parallels Windows 11 before/after path for the blocked LAN URL case. I did not rerun that live Windows setup in this read-only review.

Is this the best way to solve the issue?

Yes, with maintainer acceptance: the latest head keeps active inspection in deep local LAN status and uses static setup/configure guidance for critical flows. The remaining question is whether maintainers accept the bounded Windows subprocess cost.

AGENTS.md: found and applied where relevant.

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

Label changes

Label justifications:

P2: This is a bounded Gateway CLI diagnostics fix with limited blast radius and no emergency data-loss, security-bypass, or crash signal.
merge-risk: 🚨 availability: The diff adds native Windows subprocess inspection to user-facing deep status, which can affect CLI responsiveness even when normal tests pass.
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 (live_output): The PR body includes after-fix Parallels Windows 11 live command output showing fast status/probe avoid firewall warnings and deep status emits the expected Windows firewall diagnostic.
proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes after-fix Parallels Windows 11 live command output showing fast status/probe avoid firewall warnings and deep status emits the expected Windows firewall diagnostic.

Evidence reviewed

PR surface:

Source +1074, Tests +927, Docs +4. Total +2005 across 13 files.

View PR surface stats

Area	Files	Added	Removed	Net
Source	6	1076	2	+1074
Tests	6	927	0	+927
Docs	1	4	0	+4
Config	0	0	0	0
Generated	0	0	0	0
Other	0	0	0	0
Total	13	2007	2	+2005

What I checked:

Repository policy: Full root AGENTS.md and docs/AGENTS.md were read; protected-label handling, CLI compatibility, docs guidance, and availability-risk review policy shaped the keep-open verdict. (AGENTS.md:1, e79865569c50)
Live PR metadata: Live GitHub metadata shows the PR is open, mergeable but unstable, and carries the protected maintainer label plus proof: sufficient and merge-risk: availability labels. (37ade9866ca5)
Current main gap: Current main has no inspectWindowsGatewayFirewall, windowsFirewall, Get-NetFirewall, LocalFirewallRules, or windows_firewall diagnostic path under src or docs. (e79865569c50)
Deep-status gate: The PR head calls inspectWindowsGatewayFirewall only for Windows LAN bindings and, from daemon status, only when deep local Gateway status is requested. (src/cli/daemon-cli/status.gather.ts:607, 37ade9866ca5)
Diagnostic implementation: The new diagnostic returns not_applicable outside win32 LAN binds and bounds the quick PowerShell diagnostic path with a timeout. (src/infra/windows-gateway-firewall-diagnostics.ts:815, 37ade9866ca5)
Static setup guidance: Setup/configure guidance is static and platform-gated, so critical flows do not run firewall inspection. (src/infra/windows-gateway-firewall-diagnostics.ts:1017, 37ade9866ca5)

Likely related people:

joshavant: Recent merged Gateway/Control UI and SecretRef diagnostic work touched the same LAN setup/status surface, and this PR branch is also authored by this account. (role: recent adjacent owner; confidence: high; commits: ba5244c18996, a2cb81199e22; files: src/cli/daemon-cli/status.gather.ts, src/commands/configure.wizard.ts, src/wizard/setup.finalize.ts)
vincentkoc: Recent merged gateway status diagnostic and command/output work touched the same command surface extended by this PR. (role: gateway status diagnostics contributor; confidence: medium; commits: 08ce17c33ddb, 71ce525c6922; files: src/commands/gateway-status.ts, src/commands/gateway-status/output.ts, src/commands/gateway-status.test.ts)
steipete: Recent history shows repeated gateway status, configure wizard, terminal output, and docs work around the same CLI and Control UI surfaces. (role: recent area contributor; confidence: medium; commits: 09df56ee1f26, 118060157d21, 8946648ace20; files: src/commands/gateway-status.ts, src/commands/gateway-status/output.ts, src/commands/configure.wizard.ts)
brokemac79: Recent daemon status diagnostic work added local status advisory behavior near the status.gather.ts area this PR extends. (role: daemon status diagnostics contributor; confidence: medium; commits: 72e40833bac7; files: src/cli/daemon-cli/status.gather.ts)

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.

joshavant · 2026-07-01T15:01:20Z

@clawsweeper re-review

* Diagnose Windows LAN Gateway firewall blocks * Fix Windows firewall diagnostic lint * fix: gate gateway firewall diagnostics to local targets * fix: keep firewall inspection off critical flows

Diagnose Windows LAN Gateway firewall blocks

a00be96

openclaw-barnacle Bot added docs Improvements or additions to documentation cli CLI command changes commands Command implementations size: XL maintainer Maintainer-authored PR labels Jul 1, 2026

Fix Windows firewall diagnostic lint

35fb32f

fix: gate gateway firewall diagnostics to local targets

c061710

fix: keep firewall inspection off critical flows

37ade98

joshavant merged commit eb417fa into main Jul 1, 2026
99 of 101 checks passed

joshavant deleted the codex/windows-gateway-firewall-diagnostics branch July 1, 2026 21:24

github-actions Bot mentioned this pull request Jul 1, 2026

📡 Upstream Digest — 2026-07-01 23:04 UTC curtismercier/openclaw-mods#1185

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

fix: diagnose Windows LAN Gateway firewall blocks#98666

fix: diagnose Windows LAN Gateway firewall blocks#98666
joshavant merged 4 commits into
mainfrom
codex/windows-gateway-firewall-diagnostics

joshavant commented Jul 1, 2026 •

edited

Loading

Uh oh!

joshavant commented Jul 1, 2026

Uh oh!

clawsweeper Bot commented Jul 1, 2026 •

edited

Loading

Uh oh!

clawsweeper Bot commented Jul 1, 2026 •

edited

Loading

Uh oh!

joshavant commented Jul 1, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Uh oh!

Conversation

joshavant commented Jul 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What Problem This Solves

Why This Change Was Made

User Impact

Evidence

Uh oh!

joshavant commented Jul 1, 2026

Uh oh!

clawsweeper Bot commented Jul 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

clawsweeper Bot commented Jul 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

joshavant commented Jul 1, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

joshavant commented Jul 1, 2026 •

edited

Loading

clawsweeper Bot commented Jul 1, 2026 •

edited

Loading

clawsweeper Bot commented Jul 1, 2026 •

edited

Loading