Packaged gateway fails to start: suspected agent-user execute permission issue with Koffi native dependency

[xlinush]

Summary

The packaged OpenClaw gateway fails to start inside its isolated agent session with a reported Koffi module-loading / "module not found" error. Anna and Linus both reproduced the failure after updating the bundled OpenClaw version.

Primary hypothesis: the isolated agent user's security context can read the packaged JavaScript but lacks the permissions required to load/execute Koffi's native binaries, or a native library they depend on, from the installed MSIX package.

This is a suspected cause, not yet confirmed. A module-loading error alone does not distinguish denied access from a missing binary, a missing dependent DLL, or an architecture mismatch.

Affected scenario

• Windows MSIX installation with isolated agent sessions enabled/required.
• Current bundled OpenClaw: v2026.9.4, commit 3a9d69db306cd7f081e06254cb89c4bcc14a7107.
• Koffi 3.1.6 is declared as a direct runtime dependency in that release and in v2026.8.1/v2026.8.2. It was first reported to ship as a direct dependency in stable v2026.8.1.
• The application runs directly from the immutable MSIX package; the bundled Node.js runtime is provisioned separately for the agent session.

Reproduction

On an affected Windows machine:

1. Install the session-enabled MSIX containing the newer OpenClaw payload.
2. Run clawctl setup to provision the isolated agent session and runtime.
3. Run clawctl gateway-service start.
4. Observe that the gateway does not start successfully and its diagnostics report a Koffi loading / module-not-found error.

Expected: the gateway starts under the isolated agent user and can load its required native dependencies without weakening session isolation.

Actual: gateway startup fails while loading Koffi. The exact failing binary path and underlying Windows loader error still need to be captured.

Investigation needed

• Capture the full Koffi error, native binary path, and Windows loader/access failure under the actual agent-user token.
• Verify that the architecture-correct Koffi binary and its dependent DLLs are present in the installed package.
• Check effective read/execute access and relevant package/session restrictions for that user, rather than relying on whether loading succeeds as the interactive user.
• Add an isolated-session startup/native-module regression check; a successful package build alone does not exercise this runtime permission boundary.

Any fix should preserve isolation and avoid broadly granting write or execute access without identifying the specific blocked resource.

Current direction

Investigate and implement a real, isolation-preserving fix for native dependency loading in the packaged gateway, rather than work around the failure by packaging an older Koffi-free OpenClaw release.

Continue the investigation and repair work Anna put together in #75, which stages native-bearing dependency packages in the isolated agent's LocalState and redirects native package resolution. Treat that PR as a repair candidate to review and refine, not as an already accepted or fully validated fix.

Before resolving this issue, confirm the underlying loader/access failure and validate the resulting fix in installed packages, including fresh installs, state-preserving in-place upgrades, and both x64 and ARM64. Preserve the isolated-session boundary and the immutable packaged application outside the narrowly scoped native-dependency staging.

The compatibility-build draft #76 has been closed. Its results remain useful diagnostic history, but the downgrade/older-release direction is not being pursued as the fix. Keep this issue open until installed gateway recovery is demonstrated.

Compatibility experiment (closed)

A compatibility build packages OpenClaw v2026.7.33, commit b60a4e9fa97cddf1869a1866d879b3051783cf12, while retaining the current launcher and isolated-session changes. Its dependency manifest/lockfile and generated packages contain no Koffi dependency.

• Closed compatibility PR: fix: build MSIX packages with older OpenClaw releases #76. It addressed older-release build-identity metadata; it did not fix the native-module loading problem.
• Compatibility CI run successfully produced test-signed x64 and ARM64 MSIXs.
• Successful installed gateway startup with those packages has not yet been verified.

Simply reverting the previous upstream pin would select v2026.8.2, which still declares Koffi; that is not a Koffi-free comparison.

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed September 18, 2026, 5:11 PM ET / 21:11 UTC.

Summary
The startup failure remains unresolved on main and the latest release. The existing repair candidate has useful installed x64 evidence, but has not merged or demonstrated ARM64 and state-preserving upgrade recovery. The collaborator-authored issue should remain open.

Reproducibility: A concrete installed-Windows reproduction path exists: setup the isolated session, then start the gateway. Current source and reported native-loader diagnostics support it, but this review did not independently execute that path or establish the precise loader failure.

Ways to help us reproduce this

• Add a screenshot or short recording showing the behavior.
• Add expected vs actual behavior.

Next step
Review and resolve #75, then verify installed recovery before closing; a separate automated repair would duplicate active work.

Review details

Best possible solution:

Qualify narrowly scoped native-dependency staging through the existing repair, preserve immutable application execution and isolation, and expose setup recovery through a visible Doctor or Fix action.

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

A concrete installed-Windows reproduction path exists: setup the isolated session, then start the gateway. Current source and reported native-loader diagnostics support it, but this review did not independently execute that path or establish the precise loader failure.

Is this the best way to solve the issue?

Yes, refining the existing isolation-preserving repair is the best supported direction; downgrading the bundled runtime would avoid the trigger without repairing native loading.

AGENTS.md: not found in the target repository.

Remaining risk / open question:

• The exact failing installed binary, Windows loader result, and agent-token context still need durable diagnostic evidence.
• The demonstrated repair predates later branch changes and does not cover ARM64 or state-preserving in-place upgrades.

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

Label changes

Label justifications:

• P0: The installed gateway cannot complete first startup, and recovery currently requires technical investigation.
• impact:crash-loop: Native dependency loading prevents the gateway process from becoming available.
• impact:ux-release-blocker: The packaged first-run path is blocked without an established in-product recovery.

Evidence reviewed

What I checked:

• Current gateway launch boundary: GatewayRuntime supplies the packaged application directory and agent Node executable; SessionGatewayClient launches openclaw.mjs from that directory. Current source contains no agentNativeRoot or native-redirect implementation. (src/OpenClaw.Launcher/Gateway/SessionGatewayClient.cs:110, a99bb66d2162)
• Known packaged executable restriction: The helper stager explicitly documents that isolated agent identities cannot execute binaries directly from another package's WindowsApps directory. This supports the reported mechanism, although helper staging alone does not establish the exact Koffi loader failure. (src/OpenClaw.Launcher/Session/SessionHelperStager.cs:9, a99bb66d2162)
• Existing repair and corroboration: fix: load packaged native addons from the isolated session #75 remains an open, unmerged draft at a6a849b. Its captured body reports direct native loading returning Access is denied and successful loading after copying the same bytes. ChazGo independently comments that they encountered the issue. (a6a849b970be)
• Installed repair evidence inspected: Inspected all three prepared screenshots linked by the repair PR. They show gateway status listening, a connected TUI with entered text, and a Control UI user message; they do not visibly prove an assistant response. The captured body attributes the clean x64 installation to 9696a50 and explicitly excludes later repair revisions, ARM64, and in-place upgrades.
• Current release remains affected baseline: The latest release is v2026.9.4-msix.2, targeting the inspected main commit and published September 18, 2026. release-policy.json still pins OpenClaw v2026.9.4; no merged native-staging repair was established. (release-policy.json:3, a99bb66d2162)
• Related work does not resolve this failure: The captured discussion identifies fix: build MSIX packages with older OpenClaw releases #76 as a closed, unmerged compatibility experiment without installed startup validation. The verified merged improve: harden native library loading #18 restricts launcher kernel32 P/Invoke probing and adjusts marshalling; it does not address agent-side Koffi loading.

Likely related people:

• paulcam206: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)
• anna-dingler: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

[ChazGo]

@xlinush this is fixed now that #75 is merged, right?