fix: keep native addons available during agent-initiated commands

[anna-dingler]

What Problem This Solves

Fixes: native OpenClaw modules such as Koffi become unavailable when Copilot invokes openclaw from within an isolated agent turn.

User Impact

User impact: agent-initiated openclaw commands retain the staged native dependency redirect used by the foreground and gateway processes without replacing agent-owned Node.js options.

Why This Change Was Made

OpenClaw creates its own %OPENCLAW_STATE_DIR%\tmp\agent-cli\openclaw.cmd and prepends it for agent exec. That runtime shim reconstructs the current Node.js invocation from process.execArgv, so a preload delivered only through ambient NODE_OPTIONS is absent from the reconstructed command.

The launcher now places the native redirect on Node's real runtime argument vector before packaged app\openclaw.mjs. Upstream OpenClaw preserves ordinary --import runtime flags when it reconstructs its agent-visible CLI. Once loaded, the redirect appends itself to the agent account's NODE_OPTIONS for ordinary child Node.js processes, preserving existing values as data. Foreground and detached gateway launches use the same argument ordering and continue holding the staged root for their lifetimes.

Evidence

Head SHA: 99fa6a407bc3afaaff02e3bfea529920cec588c3

Observed VM reproduction against prior PR artifact:

• package 0.1.586.1
• packaging commit eb200fb2a50532223c125a5b2e674a3b35da730d
• payload commit 3a9d69db306cd7f081e06254cb89c4bcc14a7107
• direct launch worked, but an agent-invoked openclaw doctor still reported the native Koffi module missing

Passed locally on the corrected head:

• Release build of OpenClaw.SessionProtocol
• Release build of OpenClaw.SessionHost
• Release build of OpenClaw.Launcher
• scripts\Test-DocReferences.ps1 (0 findings)
• git diff --check

Regression coverage verifies:

• foreground Node ordering is --import <file-url> app\openclaw.mjs <unchanged upstream args>
• detached gateway launches use the same runtime prefix
• launches without staged natives retain the original entrypoint-first shape
• the runtime preload URL remains percent encoded
• agent-owned NODE_OPTIONS, including quoted paths containing &, is never expanded by the packaging batch shim

Not completed locally:

• scripts\Test-DotNetQuality.ps1
• the full xUnit suite
• scripts\Test-NativeAotCli.Tests.ps1

This development machine's .NET 10.0.401 MSBuild project-reference graph exits with code 1 without a project diagnostic. CI is the authoritative full validation lane. No package registration, isolated session, or user state was modified locally.

Successful VM Validation

Validated the test-signed x64 MSIX from workflow run 35660440161:

• package 0.1.599.1
• packaging head 99fa6a407bc3afaaff02e3bfea529920cec588c3
• real Copilot agent turn invoked openclaw doctor
• command completed with exit code 0 and no errors; the native Koffi failure did not recur

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

ClawSweeper review complete

ClawSweeper finished reviewing this revision. The review result is being finalized.

View the workflow run.

[clawsweeper]

Codex review: blocked before merge. Reviewed September 21, 2026, 6:44 PM ET / 22:44 UTC (Revision 5).

ClawSweeper review

What this changes

The Windows launcher carries native-addon redirection through Node startup arguments and command shims while preserving agent-owned Node options.

Merge readiness

⛔ Blocked before merge - 2 items remain

This remains a useful fix beyond current main. Earlier correctness findings are resolved, and the new VM evidence supports the central agent-command fix; compatibility validation remains incomplete.

Priority: P2
Reviewed head: 99fa6a407bc3afaaff02e3bfea529920cec588c3

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	A focused repair with resolved earlier findings, positive VM evidence, and passing CI; remaining compatibility coverage prevents an unconditional landing recommendation.
Proof confidence	🐚 platinum hermit (4/6) ✨ media proof bonus	Sufficient (screenshot): The pinned x64 VM report and inspected screenshot show a real Copilot turn invoking openclaw doctor successfully after the launcher-preload change. This supports the central fix; it does not resolve the separate fresh-session and upgrade compatibility gap.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Verified	Sufficient (screenshot): The pinned x64 VM report and inspected screenshot show a real Copilot turn invoking openclaw doctor successfully after the launcher-preload change. This supports the central fix; it does not resolve the separate fresh-session and upgrade compatibility gap.
Evidence reviewed	10 items	Introduced change and merge ownership: Reviewed the pinned main-to-head delta. The test merge has the exact main parent followed by the exact PR head; its Program.cs changes preserve the same introduced launch and shell changes. Current main still needs this fix: Main delivers the preload through NodeOptionsSuffix and its preload does not propagate itself into child NODE_OPTIONS. The merged native-staging work at #75 supplies the foundation, but does not implement this agent-command correction. The latest release is v2026.9.4-msix.3. Affirmative upstream dependency: The changed runtime-argument helper explicitly depends on upstream OpenClaw reconstructing its agent CLI from Node runtime arguments. The workflow and release policy pin that application to 3a9d69db306cd7f081e06254cb89c4bcc14a7107.
Findings	None	None.
Security	None	None.

How this fits together

The Windows package launches OpenClaw inside an isolated agent account, where native dependencies must load from staged copies. Its launcher and shell shim supply the preload that redirects module resolution to those copies.

flowchart LR
  A[Foreground or gateway launch] --> B[Node startup arguments]
  C[Agent shell command shim] --> B
  B --> D[Native dependency preload]
  D --> E[Staged native packages]
  B --> F[OpenClaw agent command reconstruction]
  F --> D
  D --> G[Child Node environment]

Loading

Before merge

• Resolve merge risk (P1) - Fresh-session and existing-install compatibility remain unverified for the preload cutover. In particular, the shell now restores native redirection only through its OpenClaw shim; existing direct Node scripts may lose that inherited behavior, and the doctor screenshot does not establish preservation of custom NODE_OPTIONS or upgrade behavior.
• Complete next step (P2) - Record focused Windows fresh-session and upgrade results covering custom NODE_OPTIONS, shell commands, and child Node native loading; confirm affected foreground, gateway, and dashboard launches still work.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Production and test delta	Production +106/-47; tests +206/-30	Production growth supports runtime argument propagation and the shell shim, with most net growth in regression coverage.

Merge-risk options

Maintainer options:

1. Close the compatibility evidence gap (recommended)
   Record fresh-session and upgrade results for inherited Node options and shell/child native loading, preserving existing behavior wherever those checks expose a regression.

Technical review

Best possible solution:

Keep the runtime-argument fix while preserving supported shell and child-process behavior, backed by focused fresh-session and upgrade evidence.

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

Yes, source establishes why an environment-only preload is absent from upstream's reconstructed runtime arguments, and the PR records the corresponding VM failure. This review did not execute a current-main reproduction.

Is this the best way to solve the issue?

Yes for the central defect: supplying the existing preload through runtime arguments matches the pinned upstream contract. Shell inheritance and upgrade compatibility still need the bounded validation described above.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning medium; reviewed against 288521d5fcc9.

Labels

Label changes:

• add proof: sufficient: Contributor real behavior proof is sufficient. The pinned x64 VM report and inspected screenshot show a real Copilot turn invoking openclaw doctor successfully after the launcher-preload change. This supports the central fix; it does not resolve the separate fresh-session and upgrade compatibility gap.
• add proof: 📸 screenshot: Contributor real behavior proof includes screenshot evidence. The pinned x64 VM report and inspected screenshot show a real Copilot turn invoking openclaw doctor successfully after the launcher-preload change. This supports the central fix; it does not resolve the separate fresh-session and upgrade compatibility gap.

Label justifications:

• P2: This fixes a bounded Windows agent-command failure with positive VM evidence.
• merge-risk: 🚨 compatibility: Changing preload inheritance and the interactive shell environment needs fresh-session and upgrade validation beyond the demonstrated doctor command.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (screenshot): The pinned x64 VM report and inspected screenshot show a real Copilot turn invoking openclaw doctor successfully after the launcher-preload change. This supports the central fix; it does not resolve the separate fresh-session and upgrade compatibility gap.
• proof: sufficient: Contributor real behavior proof is sufficient. The pinned x64 VM report and inspected screenshot show a real Copilot turn invoking openclaw doctor successfully after the launcher-preload change. This supports the central fix; it does not resolve the separate fresh-session and upgrade compatibility gap.
• proof: 📸 screenshot: Contributor real behavior proof includes screenshot evidence. The pinned x64 VM report and inspected screenshot show a real Copilot turn invoking openclaw doctor successfully after the launcher-preload change. This supports the central fix; it does not resolve the separate fresh-session and upgrade compatibility gap.

Evidence

What I checked:

• Introduced change and merge ownership: Reviewed the pinned main-to-head delta. The test merge has the exact main parent followed by the exact PR head; its Program.cs changes preserve the same introduced launch and shell changes. (src/OpenClaw.Launcher/Program.cs:329, 99fa6a407bc3)
• Current main still needs this fix: Main delivers the preload through NodeOptionsSuffix and its preload does not propagate itself into child NODE_OPTIONS. The merged native-staging work at fix: load packaged native addons from the isolated session #75 supplies the foundation, but does not implement this agent-command correction. The latest release is v2026.9.4-msix.3. (src/OpenClaw.Launcher/node/native-redirect.mjs:24, 288521d5fcc9)
• Affirmative upstream dependency: The changed runtime-argument helper explicitly depends on upstream OpenClaw reconstructing its agent CLI from Node runtime arguments. The workflow and release policy pin that application to 3a9d69db306cd7f081e06254cb89c4bcc14a7107. (src/OpenClaw.Launcher/OpenClawRuntimeEnvironment.cs:157, 99fa6a407bc3)
• Pinned upstream contract verified: filterOpenClawChildExecArgv preserves ordinary --import arguments, and resolveCurrentOpenClawCliInvocation incorporates process.execArgv. The adjacent CLI-shim owner renders that invocation into the agent-visible command. (src/infra/openclaw-cli-invocation.ts:33, 3a9d69db306c)
• Positive Windows VM evidence: Inspected the prepared screenshot at https://github.com/user-attachments/assets/a07fe5e4-330d-4d50-92bb-3320c1015f09. It shows the requested agent-run openclaw doctor and a reported exit code 0 without errors. The captured PR body identifies test-signed x64 package 0.1.599.1 and this exact head, contrasting the earlier Koffi failure. The image shows the agent's result summary rather than expanded process diagnostics. (99fa6a407bc3)
• Earlier findings resolved: The batch shim no longer expands NODE_OPTIONS, and its regression test includes a quoted path containing an ampersand. The dashboard caller now supplies the preload before openclaw.mjs. The prior fresh-session/upgrade rank-up remains only partially addressed by the new doctor evidence. (src/OpenClaw.SessionHost/SessionToolInstaller.cs:21, 99fa6a407bc3)

Likely related people:

• Anna Koenig: Raw commit 8215c34 adds src/OpenClaw.Launcher/node/native-redirect.mjs:43 relative to its recorded parents. This identifies author metadata, not feature responsibility or a PR merger. (role: source-line author; confidence: high; commits: 8215c346a531; files: src/OpenClaw.Launcher/node/native-redirect.mjs)
• unknown: The claimed source-line change could not be verified from bounded local history. (role: source history unknown; confidence: low)

Rank-up moves

Optional improvements that raise the rating; they are not merge blockers.

• Record redacted fresh-session and upgrade results showing existing NODE_OPTIONS and native access survive affected shell and child-process flows.

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
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.

Workflow

• 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.

History

Review history (4 earlier review cycles)

• reviewed 2026-09-21T18:30:06.151Z sha 50b4db5 :: blocked before merge. :: [P1] Preserve quoted NODE_OPTIONS without batch reinterpretation
• reviewed 2026-09-21T18:53:13.267Z sha df556d7 :: blocked before merge. :: none
• reviewed 2026-09-21T21:58:10.503Z sha ef3a1c1 :: blocked before merge. :: [P1] [P1] Migrate the dashboard caller with the preload helper
• reviewed 2026-09-21T22:06:19.668Z sha 99fa6a4 :: blocked before merge. :: none

[anna-dingler]

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event exact_review_queue).
Result: when the review finishes, ClawSweeper will create the durable review comment if needed or update the existing comment in place.

[anna-dingler]

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event exact_review_queue).
Result: when the review finishes, ClawSweeper will create the durable review comment if needed or update the existing comment in place.