[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M698QFXW9PDK8YZ467MBW5P1":3,"skill-same:01M698QFXW9PDK8YZ467MBW5P1":70},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":22,"publishedAt":42,"linkOnly":43,"markdownContent":44,"markdownBody":45,"frontMatter":46,"refName":47,"commitSha":48,"skillDirectory":49,"forksCount":50,"repositoryHtmlUrl":51,"repositoryHomepageUrl":52,"ownerHtmlUrl":53,"ownerBlogUrl":52,"ownerDescription":54,"updatedAt":55,"install":56,"resources":69},"01M698QFXW9PDK8YZ467MBW5P1","openclaw-debugging",null,"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.","openclaw\u002Fopenclaw-windows-node","openclaw","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F252820863?v=4","01M698P3FSAZ6B4R928ZF19KPT","01M698Q6SND6RHZDPP8ZM0NSP7",2198,"MIT","https:\u002F\u002Fgithub.com\u002Fopenclaw\u002Fopenclaw-windows-node\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fopenclaw-debugging\u002FSKILL.md",[17],{"categoryNo":18,"categoryName":19,"taxonomyType":20,"taxonomyTypeDesc":21},"01JBSEEDCAT000000000000030","开发工程师","PROFESSION","适用职业",[9,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41],"debugging","openclaw debugging","setup","proof","connection","boundary","debug","system","windows","gateway","path","companion","node","run","permissions","capabilities","code","updates","failing","2026-11-10 10:12:30",false,"---\nname: openclaw-debugging\ndescription: 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.\n---\n\n# OpenClaw Windows Debugging\n\nUse this skill to debug OpenClaw Companion and the Windows node. Start from the\nreported behavior, identify the first failing boundary, and collect the narrowest\nevidence that distinguishes setup, configuration, transport, product code,\nWindows permission, packaging, and runtime failures.\n\nThis skill does not authorize installing software, changing shared runtimes,\nresetting pairing, approving requests, invoking sensitive capabilities, or\nediting user configuration. Obtain the required authority first. Never print or\nshare Gateway tokens, setup codes, MCP tokens, device identities, private keys,\nraw settings, screenshots, recordings, camera data, microphone data, or chat\npayloads.\n\n## Read first\n\n- [Architecture ownership](..\u002F..\u002F..\u002Fdocs\u002FARCHITECTURE.md) for the affected owner.\n- [Connection architecture](..\u002F..\u002F..\u002Fdocs\u002FCONNECTION_ARCHITECTURE.md) for\n  credentials, pairing, reconnect, and node state.\n- [Local MCP](..\u002Fwindows-app-mcp\u002FSKILL.md) for same-machine discovery and\n  invocation.\n- [winnode](..\u002Fwinnode\u002FSKILL.md) for exact command arguments and output shapes.\n- [Windows node testing](..\u002F..\u002F..\u002Fdocs\u002FWINDOWS_NODE_TESTING.md) for capability,\n  permission, and `system.run` behavior.\n- [Setup engine](..\u002F..\u002F..\u002Fdocs\u002FSETUP_ENGINE_REDESIGN.md) and\n  [onboarding](..\u002F..\u002F..\u002Fdocs\u002FONBOARDING_WIZARD.md) for WSL and native Gateway\n  setup.\n- [Proof selection](..\u002Fopenclaw-proof-validation\u002FSKILL.md) before runtime or UI\n  claims.\n\nDo not preload unrelated guides. Follow the owner named by the first failing\nboundary.\n\n## Default loop\n\n1. Record the exact repository HEAD, dirty files, app build, runtime identity,\n   selected profile, Gateway kind, and repro command or UI route.\n2. State one suspected boundary before changing code.\n3. Collect the narrowest signal from that boundary.\n4. Reproduce without switching profile, app build, Gateway, transport, command,\n   or permission state unless that variable is the test.\n5. Classify the failure as environment\u002Fsetup, configuration\u002Fpermission,\n   transport\u002Fpairing, product code, packaging\u002Fupdate, or unproven.\n6. Patch the owner of the first incorrect behavior, not the next layer that\n   reports it.\n7. Rerun the exact failing probe, then add the required broader validation.\n\nAn exit code alone is not proof. Check that the intended tests executed, that\nthe selected command appeared in `tools\u002Flist`, that the app under test came\nfrom the expected HEAD, and that UI evidence shows the asserted state.\n\n## Choose the boundary\n\n| Symptom | First evidence | Boundary interpretation |\n|---|---|---|\n| App will not start, exits, or opens the wrong instance | `openclaw-tray.log`, `crash.log`, `run.marker`, activation arguments, runtime identity | Startup, single-instance, activation, migration admission, or crash handling |\n| Setup fails before Companion is usable | Latest setup JSONL and matching journal, failed step, command exit\u002Ftimeout, rollback result | Setup pipeline or host prerequisite, not automatically a product runtime defect |\n| WSL Gateway is installed but unavailable | WSL service status and journal as user `openclaw`, then Windows reachability | Gateway service\u002Fruntime or Windows-to-WSL reachability |\n| Native Gateway is installed but unavailable | Setup page status, **Collect Gateway diagnostics**, **View setup log**, or `clawctl gateway-service status` | Package service, isolated session, listener ownership, or native runtime readiness |\n| Companion is disconnected or pairing is pending | `app.connection.status`, `app.connection.gateways`, pending approvals, connection event timeline | Registry, credential, protocol, operator, node, or approval state |\n| Local MCP is unavailable | Selected profile, `mcp-token.txt` existence, listener state, `winnode --list-tools` | Local MCP startup\u002Fauthentication, not Gateway pairing |\n| Command is absent | Live `tools\u002Flist`, capability settings, disabled commands, Gateway allowlist | Registration or gating before invocation |\n| Command is listed but fails | Exact `winnode` request, tool error, tray log entry, native permission state | Capability implementation or Windows runtime permission |\n| Local MCP works but remote use fails | Same command through Gateway `node.invoke`, node pairing\u002Ftrust, allowlist | Gateway transport or policy; local MCP is only supporting evidence |\n| `system.run` fails | `system.which`, `system.run.prepare`, approval snapshot, MXC diagnostics, exact argv\u002Fcwd | Binding, approval, policy, containment, execution, or cleanup |\n| Update check behaves unexpectedly | Build identity, package state, update status, tray log | Store\u002FDev\u002FDebug intentional skip, release updater, or optional dependency |\n| Installer or migration fails | Exact artifact\u002Fidentity, installer source checks, migration receipts and runtime logs | Packaging\u002Fmigration; unit or source checks do not prove installed behavior |\n| UI state is wrong but snapshots look correct | Current-head native UI evidence on the selected profile | Presentation or lifecycle; MCP snapshots do not prove pixels |\n\nStop at the first boundary whose actual result differs from its contract. Do not\nreset settings, delete state, re-pair, restart an unowned Gateway, or swap to a\ndifferent transport to make the symptom disappear.\n\n## Establish the exact runtime\n\nBefore branch-specific, proof-specific, or runtime-specific debugging:\n\n```powershell\ngit branch --show-current\ngit rev-parse HEAD\ngit --no-pager status --short\n```\n\nRecord:\n\n- Companion build configuration and architecture.\n- Release or Dev identity.\n- Packaged MSIX, unpackaged Inno\u002Fportable, fixture, or source-built app.\n- Selected profile and any `OPENCLAW_TRAY_*` overrides.\n- WSL, Store native Gateway, development native Gateway patch, remote Gateway,\n  or synthetic fixture.\n- Local MCP or Gateway node transport.\n\n`OPENCLAW_TRAY_DATA_DIR` is a direct isolated profile. It controls settings,\nlogs, crash state, MCP token, run marker, identities, and the isolated mutex.\n`OPENCLAW_STATE_DIR` in the app process separately overrides the exec-approvals\nlocation, so record it before claiming approval isolation. Keep the same profile\nin the app and every `winnode` command. Release and Dev profiles are distinct.\nPackaged apps can use Windows redirected storage, so use the running app's\nDiagnostics page or resolved profile rather than guessing a package-family path.\n\nIsolated and fixture instances intentionally suppress Windows toasts, skip\nstartup update checks, and do not register URI schemes. Use a non-isolated,\nauthorized identity for visible toast or capture-indicator proof. Do not invoke\n`screen.snapshot`, `camera.snap`, or `location.get` in an isolated or fixture\ninstance because sensor access can continue after the suppressed indicator.\nUse the tray-log suppression entry only to debug the non-sensitive notification\npath, not as sensitive-capture proof.\n\nThe fixture Gateway is deterministic app and UI evidence. It is not real WSL\nsetup, pairing, provider, node invocation, sensor, notification, or MXC proof.\n\n## Use the repository diagnostics\n\n### Start with WinApp for native Windows failures\n\nCheck `winapp --version` and the relevant `--help` or `--cli-schema`.\nUse the [WinApp workflow](..\u002F..\u002F..\u002Fdocs\u002FWINAPP_CLI.md) before inventing native\ndiagnostic tooling: `run --debug-output --symbols` for an authorized crash\nrepro, `perf` for WinUI layout\u002FGC\u002Fprocess-cost evidence, `ui` for mounted\ncontrol state, and `devtools` for live XAML properties and binding diagnostics.\nPrefer project-scoped `find-api` and Reactor-aware `find-ui` to guessed APIs.\n\nThese are first-choice aids, not permission to launch, inject, capture private\nstate, replace a running app or register its package. Keep the same owned\nruntime\u002Fprofile and preserve exact binary\u002Fconfiguration identity. A successful\nattachment is not useful trace coverage; a layout trace is not GPU\u002FDefender\nattribution; a Sandbox run is not MXC or real Gateway proof. Retain the sanitized\nbundle below, and never publish raw dumps\u002FETL as if they were sanitized logs.\n\n### Preferred sanitized bundle\n\nOpen **Settings > Diagnostics**, then use **Create diagnostics bundle**. Review\nthe preview before copying or saving it. The bundle includes bounded, sanitized:\n\n- support and debug summaries\n- connection event timeline\n- `openclaw-tray.log` and `openclaw-tray.log.old` tails\n- `Logs\\diagnostics.jsonl` tail\n- `crash.log` tail\n- latest setup JSONL tails\n\nIt excludes raw settings, Gateway records, MCP tokens, device identities,\nscreenshots, recordings, chat payloads, camera data, and microphone data.\n**Open diagnostics folder** opens the selected profile's structured diagnostics\ndirectory. For a non-isolated Release identity, `openclaw:\u002F\u002Fdiagnostics` opens\nthat registered app's folder. Dev uses `openclaw-dev:\u002F\u002Fdiagnostics`; isolated\ninstances do not register either scheme.\n\n### File locations\n\nFor the normal unpackaged Release identity:\n\n| Evidence | Default location |\n|---|---|\n| Tray log | `%LOCALAPPDATA%\\OpenClawTray\\openclaw-tray.log` |\n| Tray archive | `%LOCALAPPDATA%\\OpenClawTray\\openclaw-tray.log.old` |\n| Crash log | `%LOCALAPPDATA%\\OpenClawTray\\crash.log` |\n| Structured events | `%LOCALAPPDATA%\\OpenClawTray\\Logs\\diagnostics.jsonl` |\n| Setup logs | `%APPDATA%\\OpenClawTray\\Logs\\Setup\\setup-engine-*.jsonl` |\n| Setup journal | Beside its setup log as `*.journal.jsonl` |\n| Native setup log | `%APPDATA%\\OpenClawTray\\Logs\\Setup\\native-setup-*.jsonl` |\n\nDev uses `OpenClawTray-Dev`. An isolated run puts these artifacts under the\nselected direct profile. For packaged storage, resolve the active profile\nthrough the app instead of hard-coding the Windows package publisher suffix.\n\nSet `OPENCLAW_TRAY_TRACE=1` only for a bounded reproduction that needs verbose\nGateway protocol traces. Restart the selected app with the same profile and\nunset the variable afterward. Trace is not a replacement for\n`app.connection.status` or a real invocation.\n\n## Distinguish setup failures from product defects\n\nFor a developer build-host failure, check prerequisites without installing\nanything:\n\n```powershell\n.\\scripts\\setup-dev.ps1 -CheckOnly\n```\n\nThis checks repository build prerequisites such as Git, .NET, Node, Windows SDK,\nWebView2, and the build script's prerequisite contract. It does not prove WSL2,\nGateway, MXC, Store, packaged permission, or desktop proof readiness.\n\nFor a product setup failure, start from the failed setup JSONL step. A missing\nWindows capability, Store access, WSL feature, or runtime prerequisite remains\nan environment\u002Fsetup failure until the supported setup path handles it\nincorrectly. Preserve the exact prerequisite result and setup step.\n\nFor WSL setup, correlate:\n\n1. `setup-engine-*.jsonl` `step.started`, `cmd.start`, `cmd.done`,\n   `step.completed`, and `step.exception` records.\n2. The matching `.journal.jsonl` start, completion, and rollback records.\n3. Whether the original command timed out. A timeout is an unknown outcome and\n   must not be rewritten as a clean failure.\n4. The first failed step and any later rollback failure separately.\n\nInspect the managed distro without mutating it:\n\n```powershell\nwsl.exe --list --verbose\nwsl.exe -d OpenClawGateway --user openclaw -- bash -lc \"systemctl --user status openclaw-gateway.service --no-pager || true\"\nwsl.exe -d OpenClawGateway --user openclaw -- bash -lc \"journalctl --user-unit openclaw-gateway.service --no-pager -n 80 || true\"\n```\n\nUse the actual distro name for Dev or custom setup. Do not run the user-service\nchecks as root, edit the VHD, or inspect the full Gateway configuration. See\n[WSL Gateway administration](..\u002F..\u002F..\u002Fdocs\u002FWSL_GATEWAY_ADMIN.md).\n\nNative Gateway setup writes `native-setup-*.jsonl`. Isolated native Gateway\nconsole output is obtained through its authenticated `logs.tail` setup path,\nnot an invented host log file. Store package acquisition failures, unavailable\naliases, package registration ambiguity, and unsupported Windows capability are\nsetup\u002Fadmission evidence. They are not proof that later Companion runtime code\nis defective.\n\nFor an installed native Gateway that cannot start, prefer the setup page's\n**Collect Gateway diagnostics** and **View setup log** actions. The former runs\n`clawctl collect-logs --json` and creates a redacted ZIP under package-owned\nstate; review it before sharing. `clawctl gateway-service status` is the\nread-only lifecycle probe named by startup timeout guidance.\n\n## Connection, pairing, and node flow\n\nUse local MCP diagnostics before changing connection code:\n\n```powershell\n$env:OPENCLAW_TRAY_DATA_DIR = '\u003Cselected-profile>'\nRemove-Item Env:\\OPENCLAW_MCP_TOKEN -ErrorAction SilentlyContinue\n$mcpUrl = '\u003Cselected-loopback-mcp-url>'\nwinnode --mcp-url $mcpUrl --list-tools\nwinnode --mcp-url $mcpUrl --command app.connection.status --params '{}'\nwinnode --mcp-url $mcpUrl --command app.connection.gateways --params '{}'\nwinnode --mcp-url $mcpUrl --command app.connection.pendingApprovals --params '{}'\n```\n\nUse the endpoint printed by the same selected app or fixture. Profile selection\ndoes not select the MCP port, and an inherited `OPENCLAW_MCP_TOKEN` overrides\nthe profile token. Repeat the profile, token clearing, and explicit URL in each\nfresh agent shell. Follow the canonical\n[client binding procedure](..\u002Fwindows-app-mcp\u002FSKILL.md#start-an-isolated-development-app).\n\n`app.connection.status` is the primary read-only projection. Preserve:\n\n- active Gateway and effective mode\n- operator and node state\n- credential source and credential-resolution status\n- accepted and supported protocol versions\n- MCP enabled\u002Frunning\u002Ferror state\n- browser proxy caveat\n- pending actions and retry hint\n- recent connection diagnostic events\n\n`app.connection.gateways` returns credential-presence booleans, never token\nvalues. A device identity load failure is not permission to replace the key.\nDevice token precedence must not be downgraded to shared or bootstrap token.\nProtocol mismatch is not fixed by repeated reconnects.\n\nPairing approval tools and reconnect tools mutate live state. Use them only when\nthat exact action is authorized, with a request ID read from the same selected\nGateway:\n\n- `app.connection.approveDevicePairing`\n- `app.connection.rejectDevicePairing`\n- `app.connection.approveNodePairing`\n- `app.connection.rejectNodePairing`\n- `app.connection.reconnect`\n- `app.connection.reconnectNode`\n\nLocal MCP connection diagnostics do not prove remote `node.invoke`. When the\nbug is Gateway-mediated, reproduce the same command through the active Gateway\nafter pairing, trust, and allowlist state are known.\n\n## Local MCP and capability discovery\n\nKeep local MCP and Gateway node mode distinct:\n\n```powershell\n$env:OPENCLAW_TRAY_DATA_DIR = '\u003Cselected-profile>'\nRemove-Item Env:\\OPENCLAW_MCP_TOKEN -ErrorAction SilentlyContinue\n$mcpUrl = '\u003Cselected-loopback-mcp-url>'\nwinnode --mcp-url $mcpUrl --list-tools\nwinnode --mcp-url $mcpUrl --command app.status --params '{}'\nwinnode --mcp-url $mcpUrl --command app.connection.status --params '{}'\n```\n\nA refused selected endpoint means that tray MCP server is not listening. Port\n8765 is only the default. Do not reinstall `winnode`. Confirm **Permissions >\nIntegrations > Local MCP Server**, the profile, endpoint, and token-file\ncreation. Never print the token or put it on a command line.\n\nIf discovery succeeds but a command is absent, inspect live capability settings\nand `NodeCapabilityGating` before editing the static catalog. `browser.proxy` is\nintentionally absent until a Gateway client, shared token, enabled bridge, and\nverified browser-control endpoint are all present.\n\n## Native Windows capability probes\n\nRun only probes whose side effects and permission prompts are authorized. Start\nwith discovery and status-shaped commands. Use the same explicit profile and\nMCP URL binding established above; exact schemas remain in\n[winnode](..\u002Fwinnode\u002FSKILL.md).\n\n```powershell\nwinnode --mcp-url $mcpUrl --list-tools\nwinnode --mcp-url $mcpUrl --command camera.list --params '{}'\nwinnode --mcp-url $mcpUrl --command stt.status --params '{}'\nwinnode --mcp-url $mcpUrl --command tts.status --params '{}'\nwinnode --mcp-url $mcpUrl --command system.which --params '{\"bins\":[\"git\",\"powershell\"]}'\n```\n\nSensitive capture results contain screen images, camera images, locations, or\nmicrophone transcripts. Do not let them print into the agent transcript. For an\nauthorized non-isolated Release or Dev identity, bind `winnode` to that exact\napp and redirect each complete payload to a separate private artifact:\n\n```powershell\n$screenArtifact = '\u003Cauthorized-private-screen-result.json>'\nwinnode --mcp-url $mcpUrl --command screen.snapshot --params '{\"format\":\"png\",\"maxWidth\":1280}' > $screenArtifact\n\n$cameraArtifact = '\u003Cauthorized-private-camera-result.json>'\nwinnode --mcp-url $mcpUrl --command camera.snap --params '{\"format\":\"jpeg\",\"maxWidth\":1280}' > $cameraArtifact\n\n$sttArtifact = '\u003Cauthorized-private-stt-result.json>'\nwinnode --mcp-url $mcpUrl --command stt.transcribe --params '{\"maxDurationMs\":5000,\"language\":\"auto\"}' > $sttArtifact\n```\n\nCheck `$LASTEXITCODE` after each call. Do not read or publish raw base64,\nlocation, or transcript content unless that exact inspection and destination\nare authorized. Report only the bounded non-sensitive metadata needed for the\ndebug claim. Use the exact command schemas in [winnode](..\u002Fwinnode\u002FSKILL.md).\n\nNon-capture presentation probes can remain inline when authorized:\n\n```powershell\nwinnode --mcp-url $mcpUrl --command tts.speak --params '{\"text\":\"OpenClaw diagnostic probe\"}'\nwinnode --mcp-url $mcpUrl --command system.notify --params '{\"body\":\"OpenClaw diagnostic probe\",\"sound\":false}'\n```\n\nInterpret results by boundary:\n\n- Absence from `tools\u002Flist` usually means a disabled capability or registration\n  gate, not a Windows API failure.\n- Screen, camera, and location require remembered app consent and a visible\n  per-use indication before sensor access.\n- Camera failures that report blocked access require Windows camera access for\n  desktop apps. Packaged and unpackaged identities can have different Windows\n  permission state.\n- Microphone capture and camera clips with audio need the relevant Windows\n  microphone permission and an available input device.\n- TTS status separates configuration\u002Freadiness from playback.\n- Notification proof requires a visible toast from the tested app identity.\n  A successful return without visible presentation is incomplete UI proof.\n  Isolated and fixture identities suppress Windows toasts by design and cannot\n  provide visible notification or sensitive capture proof.\n- Base64 payload success proves the capability return, not image\u002Faudio quality.\n  Inspect authorized artifacts without publishing sensitive content.\n\nFor packaged permission bugs, record package identity, architecture, app version,\nWindows version, the exact privacy setting, and whether the same build behaves\ndifferently unpackaged. Do not treat a permission denial as a code regression\nuntil identity and OS permission state are established.\n\n## `system.run` and MXC\n\nStart with non-executing boundaries:\n\n```powershell\nwinnode --mcp-url $mcpUrl --command system.which --params '{\"bins\":[\"cmd\",\"powershell\",\"git\"]}'\nwinnode --mcp-url $mcpUrl --command system.run.prepare --params '{\"command\":[\"cmd.exe\",\"\u002Fd\",\"\u002Fs\",\"\u002Fc\",\"echo diagnostic\"],\"rawCommand\":\"echo diagnostic\"}'\n```\n\nPreserve canonical argv, `rawCommand`, cwd, timeout, selected profile, approval\npolicy, and the exact tool error. Do not convert a rejected string command into\nanother shell shape after approval. A non-empty custom environment is rejected.\nAn omitted cwd uses owned scratch; an explicit cwd must be granted.\n\n`system.execApprovals.get` is not a read-only filesystem probe. It can migrate a\nlegacy file or create the default approvals file when missing, and the app's\n`OPENCLAW_STATE_DIR` can redirect that write outside\n`OPENCLAW_TRAY_DATA_DIR`. Invoke it only when that exact policy-file mutation is\nauthorized, then verify the returned path belongs to the intended profile.\n\nClassify the first failure:\n\n1. command binding or argument validation\n2. live System tools permission\n3. approval policy or stale approval snapshot\n4. MXC availability\u002Fprobe\n5. folder, cwd, executable, or protected-path admission\n6. native spawn, output drain, timeout, cancellation, or cleanup\n\nOn supported Windows, SDK load, probe, policy, or spawn failures block. They do\nnot fall back to uncontained execution. Positive unsupported-Windows\ncompatibility is a separate explicit result.\n\nLocal MCP proves the local capability path only. For Gateway-mediated behavior,\nalso use the same safe command through the active node. Run the CLI where the\nselected Gateway is authenticated, obtain the node ID from that same Gateway,\nand pass it explicitly:\n\n```powershell\nopenclaw nodes list --json\nopenclaw nodes invoke --node '\u003Cselected-windows-node-id>' --command system.which --params '{\"bins\":[\"git\"]}'\n```\n\nMXC, `system.run`, exec approvals, or Windows node execution changes require:\n\n```powershell\n.\\scripts\\validate-mxc-e2e.ps1\n```\n\nThe script sets its own E2E gates and fails if MXC proof skips. `-AllowSkip`\ndocuments a host limitation only; it is not merge validation. This provisions a\nfresh WSL Gateway and mutates runtime state, so run it only with explicit\nauthorization. Otherwise report the gate as blocked.\n\n## Update, installer, and packaged-app boundaries\n\nUpdate behavior depends on identity:\n\n- Packaged builds are treated as Microsoft Store-managed and intentionally skip\n  the release updater.\n- Dev and Debug builds intentionally skip release-channel checks.\n- Isolated profiles and `OPENCLAW_SKIP_UPDATE_CHECK=1` skip the startup check.\n- Production unpackaged Release uses the optional updater.\n- An authenticated Gateway on extended-stable can suppress an ordinary\n  Companion update.\n- An optional updater dependency load failure disables automatic checks for that\n  process, logs a warning, and leaves the app usable.\n\nCapture the update status from the Diagnostics support context and the matching\ntray-log lines before changing updater code. Do not diagnose an intentional\nskip as a failed network check. Do not use a Debug build to prove release\ndownload or install behavior.\n\nFor source-level updater or installer changes, use focused checks:\n\n```powershell\ndotnet test .\\tests\\OpenClaw.Tray.Tests\\OpenClaw.Tray.Tests.csproj --filter \"FullyQualifiedName~UpdateBackendLoaderTests|FullyQualifiedName~UpdateCheckPipelineTests\"\n.\\scripts\\run-proof-tests.ps1 -Project 'tests\\OpenClaw.Tray.Tests\\OpenClaw.Tray.Tests.csproj' -Filter 'FullyQualifiedName~InstallerIssAssertionTests' -ResultName 'installer-source'\n```\n\nInstaller source checks do not prove install, upgrade, uninstall, Store\nmigration, package registration, startup task, protocol activation, or Windows\npermission behavior. Those claims require the matching disposable-machine proof\npool and exact signed artifacts. Never test destructive migration or uninstall\nagainst a shared machine without explicit authority and the repository's\nuninstall\u002Fmigration workflow.\n\n## End-to-end repro and proof routes\n\nChoose the smallest route that crosses the failing boundary:\n\n| Boundary | Supported route | What it proves |\n|---|---|---|\n| Pure helper, projection, or policy | Focused owning test project and filter | Managed contract only |\n| App UI with deterministic Gateway data | Build the exact app, then `.\\scripts\\test-gateway-fixture.ps1 -AppPath '\u003Cbuilt-app.exe>'` | Real app, Gateway client, MCP, and selected native UI against synthetic data |\n| Local MCP command | `winnode --list-tools`, then `winnode --command ...` | Selected app's local dispatch and capability |\n| Raw MCP protocol | Authenticated `initialize`, `tools\u002Flist`, `tools\u002Fcall` against the selected loopback endpoint | HTTP\u002FJSON-RPC\u002Fauth\u002Fcancellation shape |\n| WSL setup, pairing, reconnect | The `windows-wsl-gateway-e2e` proof pool's exact `run-gateway-product-path` command | Real product WSL Gateway path |\n| Safe Gateway-to-node invocation | `FullSetup_SafeNodeInvocation_RoutesThroughRealGateway` | Real setup, pairing, node registration, and `system.which` invoke |\n| MXC or `system.run` | `.\\scripts\\validate-mxc-e2e.ps1` | Required real Gateway and MXC proof on a capable host |\n| Native screen\u002Fcamera\u002Faudio\u002Fnotification | Current-head app, exact `winnode` call, visible\u002Finspected result, then Gateway invoke when relevant | Native Windows behavior for the tested identity |\n| Installer\u002Fupdate\u002Fpackage behavior | Focused source checks plus applicable disposable-machine proof pool | Installed identity and lifecycle only when the runtime proof ran |\n\nExample real WSL setup\u002Fconnect lane:\n\n```powershell\n$env:OPENCLAW_RUN_E2E = '1'\n$env:OPENCLAW_RUN_OLLAMA_E2E = '1'\n.\\scripts\\run-proof-tests.ps1 `\n  -Project 'tests\\OpenClaw.E2ETests\\OpenClaw.E2ETests.csproj' `\n  -Filter 'FullyQualifiedName~OpenClaw.E2ETests.Setup.SetupAndConnectTests' `\n  -ResultName 'gateway-setup-connect' `\n  -RuntimeIdentifier win-x64\n```\n\nUse `win-arm64` on native ARM64. The selected cases must execute with no skipped\nrequired proof. This proof pool provisions a WSL Gateway, mutates runtime state,\nand requires maintainer approval. If that authority is unavailable, report the\nproof gate as blocked rather than running a partial command.\n\n## Validation after a fix\n\nEvery code change still requires the repository closeout:\n\n```powershell\n$env:OPENCLAW_REPO_ROOT = (Get-Location).Path\n.\\build.ps1\ndotnet test .\\tests\\OpenClaw.Shared.Tests\\OpenClaw.Shared.Tests.csproj --no-restore\ndotnet test .\\tests\\OpenClaw.Tray.Tests\\OpenClaw.Tray.Tests.csproj --no-restore\n```\n\nAdd the focused owner test and the end-to-end route selected above. In a fresh\nworktree, build a test project first or omit `--no-restore` once so a successful\nno-op is not mistaken for executed tests.\n\nFor this skill or other prose-only debugging guidance:\n\n```powershell\n.\\scripts\\validate-docs.ps1\n.\\scripts\\validate-agent-skills.ps1\n.\\scripts\\test-agent-skills-validator.ps1\ngit diff --check\n```\n\nDo not launch the app or mutate a Gateway solely to validate prose.\n\n## Handoff\n\nReport:\n\n- boundary tested\n- exact app\u002FGateway\u002Fprofile\u002FHEAD\n- exact redacted command or UI route\n- observed log, diagnostic, tool, or visible signal\n- classification: setup\u002Fenvironment, configuration\u002Fpermission,\n  transport\u002Fpairing, product code, packaging\u002Fupdate, or blocked\n- owner and fix location\n- focused validation and end-to-end proof\n- unproven boundaries and why\n\nKeep validation confidence, source-review confidence, and runtime\u002FUI proof\nconfidence separate.\n\n## Source and maintenance\n\nWindows-owned adaptation of the MIT-licensed OpenClaw\n[debugging skill](https:\u002F\u002Fgithub.com\u002Fopenclaw\u002Fopenclaw\u002Fblob\u002F0969d13b34cb8dc3279eac337b0c4fc589abe204\u002F.agents\u002Fskills\u002Fopenclaw-debugging\u002FSKILL.md).\nThis is not a synchronized copy. The Windows repository owns its diagnostics,\ncommands, setup paths, packaging behavior, native permissions, and proof\nrequirements.\n","# OpenClaw Windows Debugging\n\nUse this skill to debug OpenClaw Companion and the Windows node. Start from the\nreported behavior, identify the first failing boundary, and collect the narrowest\nevidence that distinguishes setup, configuration, transport, product code,\nWindows permission, packaging, and runtime failures.\n\nThis skill does not authorize installing software, changing shared runtimes,\nresetting pairing, approving requests, invoking sensitive capabilities, or\nediting user configuration. Obtain the required authority first. Never print or\nshare Gateway tokens, setup codes, MCP tokens, device identities, private keys,\nraw settings, screenshots, recordings, camera data, microphone data, or chat\npayloads.\n\n## Read first\n\n- [Architecture ownership](..\u002F..\u002F..\u002Fdocs\u002FARCHITECTURE.md) for the affected owner.\n- [Connection architecture](..\u002F..\u002F..\u002Fdocs\u002FCONNECTION_ARCHITECTURE.md) for\n  credentials, pairing, reconnect, and node state.\n- [Local MCP](..\u002Fwindows-app-mcp\u002FSKILL.md) for same-machine discovery and\n  invocation.\n- [winnode](..\u002Fwinnode\u002FSKILL.md) for exact command arguments and output shapes.\n- [Windows node testing](..\u002F..\u002F..\u002Fdocs\u002FWINDOWS_NODE_TESTING.md) for capability,\n  permission, and `system.run` behavior.\n- [Setup engine](..\u002F..\u002F..\u002Fdocs\u002FSETUP_ENGINE_REDESIGN.md) and\n  [onboarding](..\u002F..\u002F..\u002Fdocs\u002FONBOARDING_WIZARD.md) for WSL and native Gateway\n  setup.\n- [Proof selection](..\u002Fopenclaw-proof-validation\u002FSKILL.md) before runtime or UI\n  claims.\n\nDo not preload unrelated guides. Follow the owner named by the first failing\nboundary.\n\n## Default loop\n\n1. Record the exact repository HEAD, dirty files, app build, runtime identity,\n   selected profile, Gateway kind, and repro command or UI route.\n2. State one suspected boundary before changing code.\n3. Collect the narrowest signal from that boundary.\n4. Reproduce without switching profile, app build, Gateway, transport, command,\n   or permission state unless that variable is the test.\n5. Classify the failure as environment\u002Fsetup, configuration\u002Fpermission,\n   transport\u002Fpairing, product code, packaging\u002Fupdate, or unproven.\n6. Patch the owner of the first incorrect behavior, not the next layer that\n   reports it.\n7. Rerun the exact failing probe, then add the required broader validation.\n\nAn exit code alone is not proof. Check that the intended tests executed, that\nthe selected command appeared in `tools\u002Flist`, that the app under test came\nfrom the expected HEAD, and that UI evidence shows the asserted state.\n\n## Choose the boundary\n\n| Symptom | First evidence | Boundary interpretation |\n|---|---|---|\n| App will not start, exits, or opens the wrong instance | `openclaw-tray.log`, `crash.log`, `run.marker`, activation arguments, runtime identity | Startup, single-instance, activation, migration admission, or crash handling |\n| Setup fails before Companion is usable | Latest setup JSONL and matching journal, failed step, command exit\u002Ftimeout, rollback result | Setup pipeline or host prerequisite, not automatically a product runtime defect |\n| WSL Gateway is installed but unavailable | WSL service status and journal as user `openclaw`, then Windows reachability | Gateway service\u002Fruntime or Windows-to-WSL reachability |\n| Native Gateway is installed but unavailable | Setup page status, **Collect Gateway diagnostics**, **View setup log**, or `clawctl gateway-service status` | Package service, isolated session, listener ownership, or native runtime readiness |\n| Companion is disconnected or pairing is pending | `app.connection.status`, `app.connection.gateways`, pending approvals, connection event timeline | Registry, credential, protocol, operator, node, or approval state |\n| Local MCP is unavailable | Selected profile, `mcp-token.txt` existence, listener state, `winnode --list-tools` | Local MCP startup\u002Fauthentication, not Gateway pairing |\n| Command is absent | Live `tools\u002Flist`, capability settings, disabled commands, Gateway allowlist | Registration or gating before invocation |\n| Command is listed but fails | Exact `winnode` request, tool error, tray log entry, native permission state | Capability implementation or Windows runtime permission |\n| Local MCP works but remote use fails | Same command through Gateway `node.invoke`, node pairing\u002Ftrust, allowlist | Gateway transport or policy; local MCP is only supporting evidence |\n| `system.run` fails | `system.which`, `system.run.prepare`, approval snapshot, MXC diagnostics, exact argv\u002Fcwd | Binding, approval, policy, containment, execution, or cleanup |\n| Update check behaves unexpectedly | Build identity, package state, update status, tray log | Store\u002FDev\u002FDebug intentional skip, release updater, or optional dependency |\n| Installer or migration fails | Exact artifact\u002Fidentity, installer source checks, migration receipts and runtime logs | Packaging\u002Fmigration; unit or source checks do not prove installed behavior |\n| UI state is wrong but snapshots look correct | Current-head native UI evidence on the selected profile | Presentation or lifecycle; MCP snapshots do not prove pixels |\n\nStop at the first boundary whose actual result differs from its contract. Do not\nreset settings, delete state, re-pair, restart an unowned Gateway, or swap to a\ndifferent transport to make the symptom disappear.\n\n## Establish the exact runtime\n\nBefore branch-specific, proof-specific, or runtime-specific debugging:\n\n```powershell\ngit branch --show-current\ngit rev-parse HEAD\ngit --no-pager status --short\n```\n\nRecord:\n\n- Companion build configuration and architecture.\n- Release or Dev identity.\n- Packaged MSIX, unpackaged Inno\u002Fportable, fixture, or source-built app.\n- Selected profile and any `OPENCLAW_TRAY_*` overrides.\n- WSL, Store native Gateway, development native Gateway patch, remote Gateway,\n  or synthetic fixture.\n- Local MCP or Gateway node transport.\n\n`OPENCLAW_TRAY_DATA_DIR` is a direct isolated profile. It controls settings,\nlogs, crash state, MCP token, run marker, identities, and the isolated mutex.\n`OPENCLAW_STATE_DIR` in the app process separately overrides the exec-approvals\nlocation, so record it before claiming approval isolation. Keep the same profile\nin the app and every `winnode` command. Release and Dev profiles are distinct.\nPackaged apps can use Windows redirected storage, so use the running app's\nDiagnostics page or resolved profile rather than guessing a package-family path.\n\nIsolated and fixture instances intentionally suppress Windows toasts, skip\nstartup update checks, and do not register URI schemes. Use a non-isolated,\nauthorized identity for visible toast or capture-indicator proof. Do not invoke\n`screen.snapshot`, `camera.snap`, or `location.get` in an isolated or fixture\ninstance because sensor access can continue after the suppressed indicator.\nUse the tray-log suppression entry only to debug the non-sensitive notification\npath, not as sensitive-capture proof.\n\nThe fixture Gateway is deterministic app and UI evidence. It is not real WSL\nsetup, pairing, provider, node invocation, sensor, notification, or MXC proof.\n\n## Use the repository diagnostics\n\n### Start with WinApp for native Windows failures\n\nCheck `winapp --version` and the relevant `--help` or `--cli-schema`.\nUse the [WinApp workflow](..\u002F..\u002F..\u002Fdocs\u002FWINAPP_CLI.md) before inventing native\ndiagnostic tooling: `run --debug-output --symbols` for an authorized crash\nrepro, `perf` for WinUI layout\u002FGC\u002Fprocess-cost evidence, `ui` for mounted\ncontrol state, and `devtools` for live XAML properties and binding diagnostics.\nPrefer project-scoped `find-api` and Reactor-aware `find-ui` to guessed APIs.\n\nThese are first-choice aids, not permission to launch, inject, capture private\nstate, replace a running app or register its package. Keep the same owned\nruntime\u002Fprofile and preserve exact binary\u002Fconfiguration identity. A successful\nattachment is not useful trace coverage; a layout trace is not GPU\u002FDefender\nattribution; a Sandbox run is not MXC or real Gateway proof. Retain the sanitized\nbundle below, and never publish raw dumps\u002FETL as if they were sanitized logs.\n\n### Preferred sanitized bundle\n\nOpen **Settings > Diagnostics**, then use **Create diagnostics bundle**. Review\nthe preview before copying or saving it. The bundle includes bounded, sanitized:\n\n- support and debug summaries\n- connection event timeline\n- `openclaw-tray.log` and `openclaw-tray.log.old` tails\n- `Logs\\diagnostics.jsonl` tail\n- `crash.log` tail\n- latest setup JSONL tails\n\nIt excludes raw settings, Gateway records, MCP tokens, device identities,\nscreenshots, recordings, chat payloads, camera data, and microphone data.\n**Open diagnostics folder** opens the selected profile's structured diagnostics\ndirectory. For a non-isolated Release identity, `openclaw:\u002F\u002Fdiagnostics` opens\nthat registered app's folder. Dev uses `openclaw-dev:\u002F\u002Fdiagnostics`; isolated\ninstances do not register either scheme.\n\n### File locations\n\nFor the normal unpackaged Release identity:\n\n| Evidence | Default location |\n|---|---|\n| Tray log | `%LOCALAPPDATA%\\OpenClawTray\\openclaw-tray.log` |\n| Tray archive | `%LOCALAPPDATA%\\OpenClawTray\\openclaw-tray.log.old` |\n| Crash log | `%LOCALAPPDATA%\\OpenClawTray\\crash.log` |\n| Structured events | `%LOCALAPPDATA%\\OpenClawTray\\Logs\\diagnostics.jsonl` |\n| Setup logs | `%APPDATA%\\OpenClawTray\\Logs\\Setup\\setup-engine-*.jsonl` |\n| Setup journal | Beside its setup log as `*.journal.jsonl` |\n| Native setup log | `%APPDATA%\\OpenClawTray\\Logs\\Setup\\native-setup-*.jsonl` |\n\nDev uses `OpenClawTray-Dev`. An isolated run puts these artifacts under the\nselected direct profile. For packaged storage, resolve the active profile\nthrough the app instead of hard-coding the Windows package publisher suffix.\n\nSet `OPENCLAW_TRAY_TRACE=1` only for a bounded reproduction that needs verbose\nGateway protocol traces. Restart the selected app with the same profile and\nunset the variable afterward. Trace is not a replacement for\n`app.connection.status` or a real invocation.\n\n## Distinguish setup failures from product defects\n\nFor a developer build-host failure, check prerequisites without installing\nanything:\n\n```powershell\n.\\scripts\\setup-dev.ps1 -CheckOnly\n```\n\nThis checks repository build prerequisites such as Git, .NET, Node, Windows SDK,\nWebView2, and the build script's prerequisite contract. It does not prove WSL2,\nGateway, MXC, Store, packaged permission, or desktop proof readiness.\n\nFor a product setup failure, start from the failed setup JSONL step. A missing\nWindows capability, Store access, WSL feature, or runtime prerequisite remains\nan environment\u002Fsetup failure until the supported setup path handles it\nincorrectly. Preserve the exact prerequisite result and setup step.\n\nFor WSL setup, correlate:\n\n1. `setup-engine-*.jsonl` `step.started`, `cmd.start`, `cmd.done`,\n   `step.completed`, and `step.exception` records.\n2. The matching `.journal.jsonl` start, completion, and rollback records.\n3. Whether the original command timed out. A timeout is an unknown outcome and\n   must not be rewritten as a clean failure.\n4. The first failed step and any later rollback failure separately.\n\nInspect the managed distro without mutating it:\n\n```powershell\nwsl.exe --list --verbose\nwsl.exe -d OpenClawGateway --user openclaw -- bash -lc \"systemctl --user status openclaw-gateway.service --no-pager || true\"\nwsl.exe -d OpenClawGateway --user openclaw -- bash -lc \"journalctl --user-unit openclaw-gateway.service --no-pager -n 80 || true\"\n```\n\nUse the actual distro name for Dev or custom setup. Do not run the user-service\nchecks as root, edit the VHD, or inspect the full Gateway configuration. See\n[WSL Gateway administration](..\u002F..\u002F..\u002Fdocs\u002FWSL_GATEWAY_ADMIN.md).\n\nNative Gateway setup writes `native-setup-*.jsonl`. Isolated native Gateway\nconsole output is obtained through its authenticated `logs.tail` setup path,\nnot an invented host log file. Store package acquisition failures, unavailable\naliases, package registration ambiguity, and unsupported Windows capability are\nsetup\u002Fadmission evidence. They are not proof that later Companion runtime code\nis defective.\n\nFor an installed native Gateway that cannot start, prefer the setup page's\n**Collect Gateway diagnostics** and **View setup log** actions. The former runs\n`clawctl collect-logs --json` and creates a redacted ZIP under package-owned\nstate; review it before sharing. `clawctl gateway-service status` is the\nread-only lifecycle probe named by startup timeout guidance.\n\n## Connection, pairing, and node flow\n\nUse local MCP diagnostics before changing connection code:\n\n```powershell\n$env:OPENCLAW_TRAY_DATA_DIR = '\u003Cselected-profile>'\nRemove-Item Env:\\OPENCLAW_MCP_TOKEN -ErrorAction SilentlyContinue\n$mcpUrl = '\u003Cselected-loopback-mcp-url>'\nwinnode --mcp-url $mcpUrl --list-tools\nwinnode --mcp-url $mcpUrl --command app.connection.status --params '{}'\nwinnode --mcp-url $mcpUrl --command app.connection.gateways --params '{}'\nwinnode --mcp-url $mcpUrl --command app.connection.pendingApprovals --params '{}'\n```\n\nUse the endpoint printed by the same selected app or fixture. Profile selection\ndoes not select the MCP port, and an inherited `OPENCLAW_MCP_TOKEN` overrides\nthe profile token. Repeat the profile, token clearing, and explicit URL in each\nfresh agent shell. Follow the canonical\n[client binding procedure](..\u002Fwindows-app-mcp\u002FSKILL.md#start-an-isolated-development-app).\n\n`app.connection.status` is the primary read-only projection. Preserve:\n\n- active Gateway and effective mode\n- operator and node state\n- credential source and credential-resolution status\n- accepted and supported protocol versions\n- MCP enabled\u002Frunning\u002Ferror state\n- browser proxy caveat\n- pending actions and retry hint\n- recent connection diagnostic events\n\n`app.connection.gateways` returns credential-presence booleans, never token\nvalues. A device identity load failure is not permission to replace the key.\nDevice token precedence must not be downgraded to shared or bootstrap token.\nProtocol mismatch is not fixed by repeated reconnects.\n\nPairing approval tools and reconnect tools mutate live state. Use them only when\nthat exact action is authorized, with a request ID read from the same selected\nGateway:\n\n- `app.connection.approveDevicePairing`\n- `app.connection.rejectDevicePairing`\n- `app.connection.approveNodePairing`\n- `app.connection.rejectNodePairing`\n- `app.connection.reconnect`\n- `app.connection.reconnectNode`\n\nLocal MCP connection diagnostics do not prove remote `node.invoke`. When the\nbug is Gateway-mediated, reproduce the same command through the active Gateway\nafter pairing, trust, and allowlist state are known.\n\n## Local MCP and capability discovery\n\nKeep local MCP and Gateway node mode distinct:\n\n```powershell\n$env:OPENCLAW_TRAY_DATA_DIR = '\u003Cselected-profile>'\nRemove-Item Env:\\OPENCLAW_MCP_TOKEN -ErrorAction SilentlyContinue\n$mcpUrl = '\u003Cselected-loopback-mcp-url>'\nwinnode --mcp-url $mcpUrl --list-tools\nwinnode --mcp-url $mcpUrl --command app.status --params '{}'\nwinnode --mcp-url $mcpUrl --command app.connection.status --params '{}'\n```\n\nA refused selected endpoint means that tray MCP server is not listening. Port\n8765 is only the default. Do not reinstall `winnode`. Confirm **Permissions >\nIntegrations > Local MCP Server**, the profile, endpoint, and token-file\ncreation. Never print the token or put it on a command line.\n\nIf discovery succeeds but a command is absent, inspect live capability settings\nand `NodeCapabilityGating` before editing the static catalog. `browser.proxy` is\nintentionally absent until a Gateway client, shared token, enabled bridge, and\nverified browser-control endpoint are all present.\n\n## Native Windows capability probes\n\nRun only probes whose side effects and permission prompts are authorized. Start\nwith discovery and status-shaped commands. Use the same explicit profile and\nMCP URL binding established above; exact schemas remain in\n[winnode](..\u002Fwinnode\u002FSKILL.md).\n\n```powershell\nwinnode --mcp-url $mcpUrl --list-tools\nwinnode --mcp-url $mcpUrl --command camera.list --params '{}'\nwinnode --mcp-url $mcpUrl --command stt.status --params '{}'\nwinnode --mcp-url $mcpUrl --command tts.status --params '{}'\nwinnode --mcp-url $mcpUrl --command system.which --params '{\"bins\":[\"git\",\"powershell\"]}'\n```\n\nSensitive capture results contain screen images, camera images, locations, or\nmicrophone transcripts. Do not let them print into the agent transcript. For an\nauthorized non-isolated Release or Dev identity, bind `winnode` to that exact\napp and redirect each complete payload to a separate private artifact:\n\n```powershell\n$screenArtifact = '\u003Cauthorized-private-screen-result.json>'\nwinnode --mcp-url $mcpUrl --command screen.snapshot --params '{\"format\":\"png\",\"maxWidth\":1280}' > $screenArtifact\n\n$cameraArtifact = '\u003Cauthorized-private-camera-result.json>'\nwinnode --mcp-url $mcpUrl --command camera.snap --params '{\"format\":\"jpeg\",\"maxWidth\":1280}' > $cameraArtifact\n\n$sttArtifact = '\u003Cauthorized-private-stt-result.json>'\nwinnode --mcp-url $mcpUrl --command stt.transcribe --params '{\"maxDurationMs\":5000,\"language\":\"auto\"}' > $sttArtifact\n```\n\nCheck `$LASTEXITCODE` after each call. Do not read or publish raw base64,\nlocation, or transcript content unless that exact inspection and destination\nare authorized. Report only the bounded non-sensitive metadata needed for the\ndebug claim. Use the exact command schemas in [winnode](..\u002Fwinnode\u002FSKILL.md).\n\nNon-capture presentation probes can remain inline when authorized:\n\n```powershell\nwinnode --mcp-url $mcpUrl --command tts.speak --params '{\"text\":\"OpenClaw diagnostic probe\"}'\nwinnode --mcp-url $mcpUrl --command system.notify --params '{\"body\":\"OpenClaw diagnostic probe\",\"sound\":false}'\n```\n\nInterpret results by boundary:\n\n- Absence from `tools\u002Flist` usually means a disabled capability or registration\n  gate, not a Windows API failure.\n- Screen, camera, and location require remembered app consent and a visible\n  per-use indication before sensor access.\n- Camera failures that report blocked access require Windows camera access for\n  desktop apps. Packaged and unpackaged identities can have different Windows\n  permission state.\n- Microphone capture and camera clips with audio need the relevant Windows\n  microphone permission and an available input device.\n- TTS status separates configuration\u002Freadiness from playback.\n- Notification proof requires a visible toast from the tested app identity.\n  A successful return without visible presentation is incomplete UI proof.\n  Isolated and fixture identities suppress Windows toasts by design and cannot\n  provide visible notification or sensitive capture proof.\n- Base64 payload success proves the capability return, not image\u002Faudio quality.\n  Inspect authorized artifacts without publishing sensitive content.\n\nFor packaged permission bugs, record package identity, architecture, app version,\nWindows version, the exact privacy setting, and whether the same build behaves\ndifferently unpackaged. Do not treat a permission denial as a code regression\nuntil identity and OS permission state are established.\n\n## `system.run` and MXC\n\nStart with non-executing boundaries:\n\n```powershell\nwinnode --mcp-url $mcpUrl --command system.which --params '{\"bins\":[\"cmd\",\"powershell\",\"git\"]}'\nwinnode --mcp-url $mcpUrl --command system.run.prepare --params '{\"command\":[\"cmd.exe\",\"\u002Fd\",\"\u002Fs\",\"\u002Fc\",\"echo diagnostic\"],\"rawCommand\":\"echo diagnostic\"}'\n```\n\nPreserve canonical argv, `rawCommand`, cwd, timeout, selected profile, approval\npolicy, and the exact tool error. Do not convert a rejected string command into\nanother shell shape after approval. A non-empty custom environment is rejected.\nAn omitted cwd uses owned scratch; an explicit cwd must be granted.\n\n`system.execApprovals.get` is not a read-only filesystem probe. It can migrate a\nlegacy file or create the default approvals file when missing, and the app's\n`OPENCLAW_STATE_DIR` can redirect that write outside\n`OPENCLAW_TRAY_DATA_DIR`. Invoke it only when that exact policy-file mutation is\nauthorized, then verify the returned path belongs to the intended profile.\n\nClassify the first failure:\n\n1. command binding or argument validation\n2. live System tools permission\n3. approval policy or stale approval snapshot\n4. MXC availability\u002Fprobe\n5. folder, cwd, executable, or protected-path admission\n6. native spawn, output drain, timeout, cancellation, or cleanup\n\nOn supported Windows, SDK load, probe, policy, or spawn failures block. They do\nnot fall back to uncontained execution. Positive unsupported-Windows\ncompatibility is a separate explicit result.\n\nLocal MCP proves the local capability path only. For Gateway-mediated behavior,\nalso use the same safe command through the active node. Run the CLI where the\nselected Gateway is authenticated, obtain the node ID from that same Gateway,\nand pass it explicitly:\n\n```powershell\nopenclaw nodes list --json\nopenclaw nodes invoke --node '\u003Cselected-windows-node-id>' --command system.which --params '{\"bins\":[\"git\"]}'\n```\n\nMXC, `system.run`, exec approvals, or Windows node execution changes require:\n\n```powershell\n.\\scripts\\validate-mxc-e2e.ps1\n```\n\nThe script sets its own E2E gates and fails if MXC proof skips. `-AllowSkip`\ndocuments a host limitation only; it is not merge validation. This provisions a\nfresh WSL Gateway and mutates runtime state, so run it only with explicit\nauthorization. Otherwise report the gate as blocked.\n\n## Update, installer, and packaged-app boundaries\n\nUpdate behavior depends on identity:\n\n- Packaged builds are treated as Microsoft Store-managed and intentionally skip\n  the release updater.\n- Dev and Debug builds intentionally skip release-channel checks.\n- Isolated profiles and `OPENCLAW_SKIP_UPDATE_CHECK=1` skip the startup check.\n- Production unpackaged Release uses the optional updater.\n- An authenticated Gateway on extended-stable can suppress an ordinary\n  Companion update.\n- An optional updater dependency load failure disables automatic checks for that\n  process, logs a warning, and leaves the app usable.\n\nCapture the update status from the Diagnostics support context and the matching\ntray-log lines before changing updater code. Do not diagnose an intentional\nskip as a failed network check. Do not use a Debug build to prove release\ndownload or install behavior.\n\nFor source-level updater or installer changes, use focused checks:\n\n```powershell\ndotnet test .\\tests\\OpenClaw.Tray.Tests\\OpenClaw.Tray.Tests.csproj --filter \"FullyQualifiedName~UpdateBackendLoaderTests|FullyQualifiedName~UpdateCheckPipelineTests\"\n.\\scripts\\run-proof-tests.ps1 -Project 'tests\\OpenClaw.Tray.Tests\\OpenClaw.Tray.Tests.csproj' -Filter 'FullyQualifiedName~InstallerIssAssertionTests' -ResultName 'installer-source'\n```\n\nInstaller source checks do not prove install, upgrade, uninstall, Store\nmigration, package registration, startup task, protocol activation, or Windows\npermission behavior. Those claims require the matching disposable-machine proof\npool and exact signed artifacts. Never test destructive migration or uninstall\nagainst a shared machine without explicit authority and the repository's\nuninstall\u002Fmigration workflow.\n\n## End-to-end repro and proof routes\n\nChoose the smallest route that crosses the failing boundary:\n\n| Boundary | Supported route | What it proves |\n|---|---|---|\n| Pure helper, projection, or policy | Focused owning test project and filter | Managed contract only |\n| App UI with deterministic Gateway data | Build the exact app, then `.\\scripts\\test-gateway-fixture.ps1 -AppPath '\u003Cbuilt-app.exe>'` | Real app, Gateway client, MCP, and selected native UI against synthetic data |\n| Local MCP command | `winnode --list-tools`, then `winnode --command ...` | Selected app's local dispatch and capability |\n| Raw MCP protocol | Authenticated `initialize`, `tools\u002Flist`, `tools\u002Fcall` against the selected loopback endpoint | HTTP\u002FJSON-RPC\u002Fauth\u002Fcancellation shape |\n| WSL setup, pairing, reconnect | The `windows-wsl-gateway-e2e` proof pool's exact `run-gateway-product-path` command | Real product WSL Gateway path |\n| Safe Gateway-to-node invocation | `FullSetup_SafeNodeInvocation_RoutesThroughRealGateway` | Real setup, pairing, node registration, and `system.which` invoke |\n| MXC or `system.run` | `.\\scripts\\validate-mxc-e2e.ps1` | Required real Gateway and MXC proof on a capable host |\n| Native screen\u002Fcamera\u002Faudio\u002Fnotification | Current-head app, exact `winnode` call, visible\u002Finspected result, then Gateway invoke when relevant | Native Windows behavior for the tested identity |\n| Installer\u002Fupdate\u002Fpackage behavior | Focused source checks plus applicable disposable-machine proof pool | Installed identity and lifecycle only when the runtime proof ran |\n\nExample real WSL setup\u002Fconnect lane:\n\n```powershell\n$env:OPENCLAW_RUN_E2E = '1'\n$env:OPENCLAW_RUN_OLLAMA_E2E = '1'\n.\\scripts\\run-proof-tests.ps1 `\n  -Project 'tests\\OpenClaw.E2ETests\\OpenClaw.E2ETests.csproj' `\n  -Filter 'FullyQualifiedName~OpenClaw.E2ETests.Setup.SetupAndConnectTests' `\n  -ResultName 'gateway-setup-connect' `\n  -RuntimeIdentifier win-x64\n```\n\nUse `win-arm64` on native ARM64. The selected cases must execute with no skipped\nrequired proof. This proof pool provisions a WSL Gateway, mutates runtime state,\nand requires maintainer approval. If that authority is unavailable, report the\nproof gate as blocked rather than running a partial command.\n\n## Validation after a fix\n\nEvery code change still requires the repository closeout:\n\n```powershell\n$env:OPENCLAW_REPO_ROOT = (Get-Location).Path\n.\\build.ps1\ndotnet test .\\tests\\OpenClaw.Shared.Tests\\OpenClaw.Shared.Tests.csproj --no-restore\ndotnet test .\\tests\\OpenClaw.Tray.Tests\\OpenClaw.Tray.Tests.csproj --no-restore\n```\n\nAdd the focused owner test and the end-to-end route selected above. In a fresh\nworktree, build a test project first or omit `--no-restore` once so a successful\nno-op is not mistaken for executed tests.\n\nFor this skill or other prose-only debugging guidance:\n\n```powershell\n.\\scripts\\validate-docs.ps1\n.\\scripts\\validate-agent-skills.ps1\n.\\scripts\\test-agent-skills-validator.ps1\ngit diff --check\n```\n\nDo not launch the app or mutate a Gateway solely to validate prose.\n\n## Handoff\n\nReport:\n\n- boundary tested\n- exact app\u002FGateway\u002Fprofile\u002FHEAD\n- exact redacted command or UI route\n- observed log, diagnostic, tool, or visible signal\n- classification: setup\u002Fenvironment, configuration\u002Fpermission,\n  transport\u002Fpairing, product code, packaging\u002Fupdate, or blocked\n- owner and fix location\n- focused validation and end-to-end proof\n- unproven boundaries and why\n\nKeep validation confidence, source-review confidence, and runtime\u002FUI proof\nconfidence separate.\n\n## Source and maintenance\n\nWindows-owned adaptation of the MIT-licensed OpenClaw\n[debugging skill](https:\u002F\u002Fgithub.com\u002Fopenclaw\u002Fopenclaw\u002Fblob\u002F0969d13b34cb8dc3279eac337b0c4fc589abe204\u002F.agents\u002Fskills\u002Fopenclaw-debugging\u002FSKILL.md).\nThis is not a synchronized copy. The Windows repository owns its diagnostics,\ncommands, setup paths, packaging behavior, native permissions, and proof\nrequirements.\n",{"name":5,"description":7},"main","a6ff6a164b20835bd5d77200c9134578dd7ce0c6",".agents\u002Fskills\u002Fopenclaw-debugging",349,"https:\u002F\u002Fgithub.com\u002Fopenclaw\u002Fopenclaw-windows-node","https:\u002F\u002Fopenclaw.ai","https:\u002F\u002Fgithub.com\u002Fopenclaw","Your personal, open source AI assistant.","2026-11-14 18:13:49",{"source":8,"skillName":5,"commands":57,"prompt":67,"zipAvailable":68},[58,61,64],{"tool":59,"command":60},"npx","npx skills add openclaw\u002Fopenclaw-windows-node --skill openclaw-debugging",{"tool":62,"command":63},"bunx","bunx skills add openclaw\u002Fopenclaw-windows-node --skill openclaw-debugging",{"tool":65,"command":66},"pnpm","pnpm dlx skills add openclaw\u002Fopenclaw-windows-node --skill openclaw-debugging","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fopenclaw\u002Fopenclaw-windows-node\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fopenclaw-debugging\u002FSKILL.md",true,[],[71,95,112,130,151,171],{"skillNo":72,"name":73,"nameZh":6,"description":74,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":75,"categories":76,"keywords":77,"publishedAt":42},"01M6KZCXK5PCYWWW5FCVDYPAXK","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.","https:\u002F\u002Fgithub.com\u002Fopenclaw\u002Fopenclaw-windows-node\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fretrigger-flaky-ci\u002FSKILL.md",[],[78,79,80,81,41,82,83,84,85,86,87,88,89,90,91,92,93,94],"retrigger flaky ci","ci","changes","when","rerun","use","triage","only","decide","request","active","pull request","pr","unrelated","branch","with","pull",{"skillNo":96,"name":97,"nameZh":6,"description":98,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":99,"categories":100,"keywords":101,"publishedAt":42},"01M698QMQN5TQES4R7ZPTYAZF5","technical-documentation","Write, review, or restructure Windows node documentation and agent instructions using current source, task-focused explanations, and explicit fact preservation.","https:\u002F\u002Fgithub.com\u002Fopenclaw\u002Fopenclaw-windows-node\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Ftechnical-documentation\u002FSKILL.md",[],[102,103,104,105,35,31,106,107,108,109,110,111],"technical documentation","technical","documentation","agent instructions","source","preservation","write","instructions","review","task",{"skillNo":113,"name":114,"nameZh":6,"description":115,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":116,"categories":117,"keywords":118,"publishedAt":42},"01M698QKPXJ8ZG34MYHPPCAT4T","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.","https:\u002F\u002Fgithub.com\u002Fopenclaw\u002Fopenclaw-windows-node\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fpr-simplify\u002FSKILL.md",[],[119,90,120,121,122,26,123,35,124,81,83,125,126,127,128,31,129],"pr simplify","simplify","preparation","contracts","implementation","change","fix","complete","remove","slop","platform",{"skillNo":131,"name":132,"nameZh":6,"description":133,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":134,"categories":135,"keywords":141,"publishedAt":42},"01M698QJEA384YPM8R9CPZ1YFD","openclaw-testing","Choose proportional OpenClaw Windows node tests, builds, packaging checks, and runtime proof, then diagnose failures without weakening required gates.","https:\u002F\u002Fgithub.com\u002Fopenclaw\u002Fopenclaw-windows-node\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fopenclaw-testing\u002FSKILL.md",[136],{"categoryNo":137,"categoryName":138,"taxonomyType":139,"taxonomyTypeDesc":140},"01JBSEEDCAT000000000000008","测试与质量","SCENARIO","使用场景",[142,9,143,144,26,35,145,146,147,148,149,150,31],"testing","openclaw testing","gates","runtime proof","tests","choose","packaging","runtime","diagnose",{"skillNo":152,"name":153,"nameZh":6,"description":154,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":155,"categories":156,"keywords":160,"publishedAt":42},"01M698QH7JVVA09769ER9P2TKY","openclaw-proof-validation","Plan and collect OpenClaw Windows validation\u002Fproof: tests, rubber-duck review, UI evidence, MCP output, and gateway runtime proof.","https:\u002F\u002Fgithub.com\u002Fopenclaw\u002Fopenclaw-windows-node\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fopenclaw-proof-validation\u002FSKILL.md",[157],{"categoryNo":158,"categoryName":159,"taxonomyType":139,"taxonomyTypeDesc":140},"01JBSEEDCAT000000000000023","Skill与智能体开发",[161,9,162,26,31,32,163,164,165,166,167,168,169,110,145,146,170,149],"openclaw proof validation","validation","MCP","evidence","duck","ui","ui evidence","plan","output","collect",{"skillNo":172,"name":173,"nameZh":6,"description":174,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":175,"categories":176,"keywords":178,"publishedAt":42},"01M698QEPAAXVVCFQCZMEWMW6H","native-gateway-from-source","Run side-by-side named Gateway patches as the default for local and future cloud native-Gateway E2E on capable Windows clients. Build from npm latest, a published packaging release with -GatewayChannel Packaged, or explicit sources; select the patch with OPENCLAW_NATIVE_GATEWAY_DEV_PATCH and remove only owned instances.","https:\u002F\u002Fgithub.com\u002Fopenclaw\u002Fopenclaw-windows-node\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fnative-gateway-from-source\u002FSKILL.md",[177],{"categoryNo":137,"categoryName":138,"taxonomyType":139,"taxonomyTypeDesc":140},[179,106,180,32,181,93,182,183,184,85,185,186,148,187,127,188,189,190,31,191,9],"native gateway from source","native","default","patch","cloud native","e2e","dev","local","select","for","as","sources","instances"]