docs: add Crabbox Windows validation skill

[RomneyDa]

Summary

• add a repository-local Crabbox skill for remote Windows-node validation
• port the native Windows, WSL2, static SSH, desktop proof, diagnostics, reporting, and cleanup guidance that applies here
• add safe native-Windows-controller setup for Azure auth, config discovery, target-specific sync, PowerShell --script-stdin, and opt-in private networking
• omit OpenClaw-monorepo-only workflows and all organization-specific cloud, VPN, certificate, vault, account, resource, address, and cost data

Port scope

The primary source is openclaw/openclaw:.agents/skills/crabbox/SKILL.md. This port is intentionally smaller and uses the Windows node repository contracts: build.ps1, the shared/tray tests, targeted CLI and MXC gates, isolated WinUI launch, and local MCP proof.

A private local setup guide was reviewed only for generic Windows-controller behavior. Its duplicate Downloads copies were byte-identical; neither file nor any private identifier or credential-bearing setup was added to this repository. Candidate claims were checked against the current sibling Crabbox docs and implementation before inclusion.

Validation

• python3 /Users/dallin/.codex/skills/.system/skill-creator/scripts/quick_validate.py .agents/skills/crabbox — passed on 0edaea4d5eebd3025391331829ff171908c7ff05
• git diff --check — passed
• sensitive-literal scan of the follow-up diff — no GUID, address, email, private-key marker, or populated secret field found
• .agents/skills/autoreview/scripts/autoreview --mode local — initially found the Windows PowerShell 5.1 native-pipeline encoding hazard; fixed by forcing UTF-8 for --script-stdin, restoring caller encoding, and preserving the exit code
• final .agents/skills/autoreview/scripts/autoreview --mode local — clean, no accepted/actionable findings
• current-head GitHub CI — in progress

Required native closeout is Not verified / blocked from this macOS checkout:

• Azure acquisition previously failed before a lease was created because Azure CLI/subscription auth was unavailable.
• AWS acquisition previously failed before a lease was created because no broker session or raw EC2 credentials were available. No raw cloud credentials were requested or supplied.
• Consequently ./build.ps1, dotnet test ./tests/OpenClaw.Shared.Tests/OpenClaw.Shared.Tests.csproj --no-restore, and dotnet test ./tests/OpenClaw.Tray.Tests/OpenClaw.Tray.Tests.csproj --no-restore were not run in Crabbox.
• No lease id or cleanup action exists because both providers failed before acquisition.

Real behavior proof

This PR changes agent-facing instructions only; it does not change product UI, MCP commands, or runtime behavior.

The native-Windows-controller follow-up was verified against the current Crabbox CLI/docs/source:

• crabbox azure login supports active Azure CLI subscription detection and persistent location setup
• crabbox config path discovers the platform-specific user config without dumping its contents
• native Windows targets use local tar and archive transfer, so WSL is not required for native validation
• POSIX/WSL2 targets use rsync; a Windows controller prefers WSL rsync when wsl.exe exists and otherwise falls back to native rsync
• PowerShell 5.1 --script-stdin now explicitly uses UTF-8 and restores the prior output encoding
• private Azure addressing is only recommended after an operator confirms an approved VPN/VNet route already exists

The earlier source-blind forward test remains evidence for the core lease, native validation, isolated UI/MCP proof, provider-bound cleanup, and WSL2 boundary flow. No private setup-guide content is reproduced in this PR.

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed July 14, 2026, 9:05 AM ET / 13:05 UTC.

Summary
Adds a 404-line repository-local Crabbox skill covering remote native-Windows and WSL2 validation, cloud or SSH setup, proof collection, diagnostics, reporting, and lease cleanup.

Reproducibility: not applicable. This PR adds an agent-facing validation workflow rather than fixing a reproducible product bug.

Review metrics: 3 noteworthy metrics.

• Instruction surface: 1 file, 404 lines added. The diff is focused, but its size creates meaningful ongoing operational-workflow ownership and drift cost.
• Runtime surface: 0 product or workflow files changed. The patch cannot directly regress shipped application code, dependencies, or GitHub Actions.
• Automated checks: 11 successful, 2 expected skips. The supplied current-head check set is green, while live cloud-host execution remains the distinct proof gap.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🌊 off-meta tidepool
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:

• Confirm the long-term ownership boundary for the repository-local skill.
• [P2] If keeping it local, add canonical provenance, drift guidance, and a redacted native-Windows lease transcript.

Risk before merge

• [P1] The current head has source-level checks and green CI but no live native-Windows Crabbox lease run, so provider acquisition, target sync, command execution, artifact collection, and cleanup remain unproven together.
• [P1] A large repository-local port can drift from the canonical shared Crabbox workflow unless maintainers explicitly accept ownership and establish provenance or synchronization guidance.

Maintainer options:

1. Prove and govern the local skill (recommended)
   Before merge, add a redacted current-head native-Windows Crabbox transcript and state how the port will remain aligned with its canonical source.
2. Accept source-only validation
   Merge the member-authored instructions while accepting that the first live provider run may reveal acquisition, synchronization, or cleanup corrections.
3. Replace with a thin overlay
   Pause this branch and retain only repository-specific Windows commands while consuming the shared skill for generic provider and lease behavior.

Next step before merge

• [P2] A maintainer should decide the shared-versus-local skill ownership boundary and whether live native-Windows proof is required before merge; there is no narrow automated code repair to queue.

Maintainer decision needed

• Question: Should this repository permanently own the full Windows-specific Crabbox skill, or rely on the canonical shared Crabbox skill with a smaller repository-specific validation overlay?
• Rationale: Both approaches are technically viable, but selecting the durable ownership boundary and accepting its synchronization cost requires maintainer intent.
• Likely owner: shanselman — The available history most strongly connects this person to Windows build, CI, and validation-policy decisions.
• Options:
  • Own the local skill (recommended): Merge the repository-local workflow after recording canonical provenance, an update policy, and current-head native-Windows proof.
  • Use a thin overlay: Keep the shared Crabbox skill canonical and place only Windows-node commands and repository-specific proof requirements in the existing local validation guidance.

Security
Cleared: The skill adds operational cloud and SSH guidance, but the reviewed change contains no concrete credential exposure, permission broadening, dependency execution, or weakened security boundary.

Review details

Best possible solution:

Keep a Windows-node-specific Crabbox skill only if maintainers want zero-setup repository ownership; if retained, document its canonical source and drift policy and capture a redacted current-head native-Windows lease transcript covering acquisition, synchronization, required tests, proof collection, and cleanup.

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

Not applicable; this PR adds an agent-facing validation workflow rather than fixing a reproducible product bug.

Is this the best way to solve the issue?

Unclear. The Windows-specific workflow is coherent and focused, but maintainers must choose whether the maintainable ownership boundary is a large repository-local skill or a thin overlay on the canonical shared workflow.

AGENTS.md: found and applied where relevant.

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

Label changes

Label changes:

• add merge-risk: 🚨 automation: The skill directs cloud acquisition, repository synchronization, remote PowerShell execution, proof capture, and lease cleanup that ordinary green CI does not exercise end to end.

Label justifications:

• P3: This is low-risk agent workflow and validation documentation with no shipped runtime behavior change.
• merge-risk: 🚨 automation: The skill directs cloud acquisition, repository synchronization, remote PowerShell execution, proof capture, and lease cleanup that ordinary green CI does not exercise end to end.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: The contributor is a repository member and the patch changes only agent instructions; source checks and green CI are useful evidence, while a live native-Windows transcript remains a merge-risk reducer rather than an external-contributor proof gate.

Evidence reviewed

What I checked:

• Focused skill-only diff: The PR adds one agent-instruction file and does not modify product runtime, dependencies, persisted state, or GitHub workflows. (.agents/skills/crabbox/SKILL.md:1, 0edaea4d5eeb)
• Repository validation policy applies: The repository policy routes agent-facing instruction changes through proof-validation guidance and requires Windows build, shared-test, and tray-test coverage; the supplied current-head GitHub checks are green, while the PR transparently records that a live Crabbox lease was unavailable. (AGENTS.md:1, 77c42440376e)
• Canonical shared workflow exists: The shared agent-skills guidance identifies Crabbox as a canonical operational skill and treats downstream vendoring of large workflows as an intentional zero-setup ownership choice requiring provenance and drift management. (.agents/skills/crabbox/SKILL.md:8, 0edaea4d5eeb)
• Re-review continuity: Earlier ClawSweeper cycles found no actionable patch defects; subsequent commits focused on authentication clarity, validation hardening, PowerShell encoding safety, and native-Windows controller setup. (.agents/skills/crabbox/SKILL.md:1, 0edaea4d5eeb)
• Security-conscious scope: The PR reports a sensitive-literal scan, excludes private identifiers and credential-bearing setup, avoids dumping configuration contents, and makes private-network use conditional on operator confirmation. (.agents/skills/crabbox/SKILL.md:1, 0edaea4d5eeb)

Likely related people:

• shanselman: Repository history and the review timeline connect this person to Windows build, CI, and validation-policy work, making them the strongest available routing candidate. (role: recent build and CI area contributor; confidence: medium; files: AGENTS.md, .github/workflows/ci.yml, build.ps1)
• AlexAlves87: The existing review timeline routes this Windows validation change to this contributor, with adjacent repository work on Windows application behavior. (role: adjacent Windows repository contributor; confidence: low; files: src/OpenClaw.Tray.WinUI)

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.

Review history (2 earlier review cycles)

• reviewed 2026-07-13T21:55:32.877Z sha c24e6b8 :: needs maintainer review before merge. :: none
• reviewed 2026-07-13T22:02:44.871Z sha c24e6b8 :: needs maintainer review before merge. :: none