openclaw-proof-validation
Plan and collect OpenClaw Windows validation/proof: tests, rubber-duck review, UI evidence, MCP output, and gateway runtime proof.
- License 许可
- MIT
- 最近更新
- 2026-11-14
- Stars
- ★ 2.2k
- Forks
- 349
01 前言 Front Matter
- name
- openclaw-proof-validation
- description
- Plan and collect OpenClaw Windows validation/proof: tests, rubber-duck review, UI evidence, MCP output, and gateway runtime proof.
02 资源文件 1
- 参考文档PARALLELS.md3.4 KB
03 SKILL.md 正文
OpenClaw Proof and Validation
Use for changes that affect tray UX, Settings, onboarding, chat/canvas, Command Center, Windows node capabilities, local MCP, gateway connection/pairing, permissions, diagnostics, or agent-facing instructions.
If the validation host is macOS, read PARALLELS.md for the optional local Parallels Windows VM workflow.
Rules
- Required automated/focused tests are mandatory. Do not ask to skip them.
- Prefer isolated tray data so proof does not mutate
%APPDATA%\OpenClawTray. - Computer-use is usually a batched closeout proof pass, not a continuous dev-loop tool. Mid-development use is fine when explicitly requested or needed to unblock work; ask first whether to run it or provide manual screenshot/output steps.
- Local MCP is part of every Windows node command contract: command discovery and invocation must work through
winnodeor raw MCP JSON-RPC. - Rubber-duck review is required before PR publication for non-trivial UI/MCP/node-command/setup/pairing/security/permissions/diagnostics work; it is also useful mid-development when extra design/testing validation is requested.
- Report blockers explicitly. Do not turn missing UI, MCP, gateway, camera, screen, or permission proof into success-shaped wording.
Required validation
First follow execution-target routing: app-only proof defaults to the isolated fixture Gateway; native-Gateway E2E defaults to named side-by-side patches on an authorized, capable Windows client host, locally or in future cloud lanes. Use separate VMs for OS/clean-image isolation or unavailable host capabilities, not one VM per Gateway. Preserve required real MXC/WSL proof and explicit authority for existing shared Gateways.
Select the changed contract before running checks. Use the
read-only validation plan
to distinguish hosted lanes, mandatory local code-change closeout, and custom
proof candidates. A candidate is neither scheduled nor executed proof.
Ordinary prose-only changes need documentation/skill checks, not native runtime
tests. Shipped winnode command-reference changes retain CLI/core checks.
$env:OPENCLAW_REPO_ROOT = (Get-Location).Path
.\build.ps1
dotnet test .\tests\OpenClaw.Shared.Tests\OpenClaw.Shared.Tests.csproj --no-restore
dotnet test .\tests\OpenClaw.Tray.Tests\OpenClaw.Tray.Tests.csproj --no-restore
Fresh worktrees may need a first run without --no-restore, or a project build first, so tests do not no-op before bin\ exists.
Check actual report/execution counts, not only the exit code. Custom proof must
not contain skipped selected cases. Ordinary CI skips remain a separate policy,
not proof that the skipped behavior works.
For winnode, command descriptions, or new/renamed node commands, also run:
dotnet test .\tests\OpenClaw.WinNode.Cli.Tests\OpenClaw.WinNode.Cli.Tests.csproj --no-restore
Proof checklist
Select the runtime and its authority
Ordinary prose validation does not need an app. For supported deterministic app
exploration, prefer the fixture workflow
with an explicit current-build executable on an authorized Windows desktop.
It uses synthetic Gateway data, isolated profiles and a dedicated MCP port,
with owned-process cleanup. Sensitive node capabilities, automatic repair and
voice are disabled. It is not an OS sandbox, node-command proof, or real
Gateway pairing/provider proof. An interactive ready result is not a passed
scenario.
For live app proof outside that fixture, select the Gateway before launching.
For an isolated build that needs a real native Gateway, the default is the
task-owned build and named-patch workflow:
build Companion in its own worktree, prepare a uniquely named Gateway patch in
a task-owned work root, and launch with that patch and separate app data.
The launcher's shared npm-latest / packaged defaults are not per-test
instances; -Isolated alone does not create a unique Gateway.
The local launcher has these distinct effects:
| Option | Actual boundary |
|---|---|
-Isolated / -DataDir |
Selects separate profile data, not an OS sandbox or permission to change machine runtimes. -Isolated uses a stable worktree/branch directory, not a fresh profile on every run. |
| Default Gateway (no explicit selection) | Builds/registers an npm-latest development native Gateway, or reuses an existing patch selected by OPENCLAW_NATIVE_GATEWAY_DEV_PATCH without rebuilding. |
-GatewayChannel Latest |
Builds/registers an npm-latest development native Gateway. Conflicts with a nonblank OPENCLAW_NATIVE_GATEWAY_DEV_PATCH; clear that variable before selecting an explicit channel. |
-GatewayChannel Packaged |
Builds/registers a development Gateway from a published packaging release, not the installed Store runtime. Like Latest, conflicts with a nonblank OPENCLAW_NATIVE_GATEWAY_DEV_PATCH. |
-UseStoreGateway |
Skips development Gateway packaging and selects the installed Store Gateway. It does not make the launched app read-only. |
-NoBuild |
Skips only the Companion build. Requires existing output with matching identity/configuration/RID; Gateway preparation can still run. |
-DryRun |
Returns before Gateway packaging and app launch, but after the optional Companion build and profile-directory creation. Not a read-only planner, even with -NoBuild. |
Local implementation authority does not authorize Gateway registration, installs,
or shared-runtime changes. Use the
native Gateway skill only with the
needed authority. Do not execute the launcher to discover its parameters;
inspect its PowerShell AST for read-only command checks. There is no
-AllowNonMain switch.
For example, only when use of the installed Store Gateway and a live app launch are authorized:
.\run-app-local.ps1 -Isolated -UseStoreGateway
Expect the launcher to print the selected profile, Gateway, output path and process identity. Record the actual build/runtime identity; isolation alone is not evidence that the binary matches the current source.
Collect the selected proof
Use the WinApp CLI guide proactively when choosing native evidence: UIA state plus visible capture, stowed-exception diagnostics, DevTools inspection, bounded WinUI ETW, or owned Sandbox app runs. Discover the installed version and command schema instead of assuming those tools are absent. Preserve the runtime-selection rules above and the host's computer-use policy; WinApp does not bypass consent or substitute for existing proof pools. Record trace coverage and capture completeness, not just a successful command. For clean artifact/installer proof, consult the sandbox-mcp versus WinApp decision table. Preserve missing-prerequisite findings, label explicitly provisioned runs, and inspect reports/screenshots rather than equating a startup PASS with acceptance. The two tools must not compete for the same guest's lifecycle.
| Surface | Proof to collect |
|---|---|
| UI / WinUI | On an authorized isolated desktop, use the runtime selected above, exercise the changed path with computer-use or developer-provided screenshots/output, and include visible evidence or blocker. If the developer captures manually, provide exact steps and confirm screenshot/artifact links resolve after an authorized PR body update. |
| Local MCP | Enable Local MCP Server, run winnode --list-tools, then invoke the changed command with winnode --command <name> --params '<json-object>'. |
| Raw MCP HTTP | For protocol/server-shape changes, paste JSON-RPC tools/list and tools/call responses from http://127.0.0.1:8765/. |
| Gateway path | When relevant and available, prove openclaw nodes invoke --command <name> --params '<json-object>'; otherwise state the gateway blocker. |
| Rubber-duck | Inspect the current host's advertised tools/roles. When task advertises rubber-duck, use it for a bounded independent implementation/proof-plan review. Otherwise use an advertised independent review role and name the actual tool/role and limits; if none exists, report independent review blocked. Direct self-review is not independent review. Verify findings before changing code. |
For shared source-review mode, base, P0-P3 scope and fallback requirements, use the autoreview entrypoint. Host tool availability does not establish model access or a completed review. Keep source review separate from live UI, MCP and Gateway proof.
When local MCP proof is refused
Connection refused on http://127.0.0.1:8765/ means the tray MCP server is not running. Do not reinstall winnode. Write PascalCase settings.json with EnableMcpServer true and EnableNodeMode false, launch the tray with OPENCLAW_TRAY_DATA_DIR and OPENCLAW_SKIP_UPDATE_CHECK=1, and pass that same data directory to winnode. StartupSetupState.RequiresSetup stays false when MCP is already enabled, so the first-run wizard does not block. An isolated data directory uses its own mutex. Wait until mcp-token.txt exists and the port accepts a connection.
browser.proxy stays off tools/list until the app has a gateway client, a non-empty shared gateway token, and a verified browser endpoint. Unknown tool: browser.proxy is that rule. A refused port is not successful discovery. The review can accept a concrete gateway-availability blocker. It does not accept the refused port as the browser.proxy call.
When the review asks for the production HTTP client, drive that client against a real socket. HttpClient.Timeout does not cancel a body read that starts after HttpCompletionOption.ResponseHeadersRead.
For isolated tray runs, copy the data directory printed by run-app-local.ps1 -Isolated and set it before MCP proof commands:
$env:OPENCLAW_TRAY_DATA_DIR = '<isolated-data-dir-from-run-app-local>'
Raw token lookup:
$tokenPath = if ($env:OPENCLAW_TRAY_DATA_DIR) {
Join-Path $env:OPENCLAW_TRAY_DATA_DIR 'mcp-token.txt'
} else {
Join-Path $env:APPDATA 'OpenClawTray\mcp-token.txt'
}
$token = Get-Content $tokenPath -Raw
New Windows node command checklist
- Register the command in the same
INodeCapabilitypath used by the gateway node. - Add/update
McpToolBridge.CommandDescriptions. - Update
.agents/skills/winnode/SKILL.mdwith input shape, output shape, side effects, permissions, and examples. - Add/update capability, MCP bridge,
winnode, and UI/gateway tests as applicable. - Prove discovery and invocation with
winnodeor raw MCP JSON-RPC. - Prove the gateway path when the behavior is gateway-mediated and a gateway is available.
PR proof package
This section owns evidence requirements and their limits. Use Windows PR preparation to assemble that evidence into the current PR template and report readiness without assuming publication authority.
Before publishing or updating a PR, collect:
## Validationwith exact commands and pass/fail counts.## Real behavior proofwith current-head after-change evidence that directly shows the changed behavior: copied live output, screenshot/video, developer-provided screenshot, copied UI diagnostics,winnode, raw MCP JSON-RPC, gateway invoke output, redacted runtime log, or linked artifact. For UI changes, prefer screenshots/video of the active changed state, not only adjacent or empty UI.- PR body proof must stay in sync with current behavior: remove stale screenshots/claims after design changes and verify embedded image/artifact links resolve.
- Rubber-duck notes for non-trivial UI/MCP-sensitive work, or why skipped.
Not verified / blockednotes for focused proof or unavailable dependencies.
For inventory-bound filtered tests, use local execution evidence validation. The summary checks source/report/artifact correspondence; it does not replace native freeze/binary verification, visible UI inspection, or live Gateway proof, and it never marks a whole pool complete.
04 同仓库更多 Skills
network-handoff
Use before generating, changing, or reviewing networking, IPC, or cross-process handoffs, including requests, retries, deadlines, reconnect, process launch, configuration apply, cancellation, and cleanup. Establish confirmation, identity, authority, reconciliation, and producer compatibility before implementation.
retrigger-flaky-ci
Triage failed CI on a pull request or the active branch, decide whether the failures come from its changes, and rerun only failures that are unrelated. Use when asked to retrigger, rerun, or kick CI on a PR with failing checks.
technical-documentation
Write, review, or restructure Windows node documentation and agent instructions using current source, task-focused explanations, and explicit fact preservation.
pr-simplify
Simplify your own Windows-node change to its smallest complete fix while preserving distinct regressions, platform contracts, and required proof. Use after implementation before PR preparation, after large repairs, or when asked to shrink a change or remove slop.
openclaw-testing
Choose proportional OpenClaw Windows node tests, builds, packaging checks, and runtime proof, then diagnose failures without weakening required gates.
openclaw-debugging
Debug OpenClaw Windows Companion, setup, Gateway connection, node capabilities, packaged permissions, updates, installers, and system.run by selecting the failing boundary and proof path before changing code.