Skip to content

docs: add Windows pnpm fallback for Corepack EPERM#94514

Open
africoding wants to merge 4 commits into
openclaw:mainfrom
africoding:docs/windows-pnpm-fallback
Open

docs: add Windows pnpm fallback for Corepack EPERM#94514
africoding wants to merge 4 commits into
openclaw:mainfrom
africoding:docs/windows-pnpm-fallback

Conversation

@africoding

@africoding africoding commented Jun 18, 2026 •
edited
Loading

Copy link
Copy Markdown

Summary

This PR adds a Windows-specific fallback note for Corepack EPERM errors during OpenClaw onboarding.

On some Windows environments, running corepack enable fails because Corepack cannot create the pnpm shim inside the protected C:\Program Files\nodejs directory.

This change documents npm install -g pnpm as a fallback path when Corepack fails.

Intended outcome

  • Prevent Windows onboarding from being blocked by Corepack permission errors.
  • Provide a reliable fallback path for pnpm installation.
  • Improve onboarding success for Windows contributors.

Out of scope

  • Runtime behavior changes.
  • Build system changes.
  • Dependency updates.
  • CI modifications.

Linked context

Closes #

Related #

No maintainer request.

Real behavior proof

Behavior addressed: Windows Corepack EPERM failure during OpenClaw onboarding. corepack enable failed when attempting to create the pnpm shim in C:\Program Files\nodejs.

Real environment tested: Windows 10, Git Bash, Node.js v24.16.0, pnpm v11.2.2.

Exact steps or command run after this patch:

corepack enable

Output:

Internal Error: EPERM: operation not permitted, open 'C:\Program Files\nodejs\pnpm.CMD'

Fallback:

npm install -g pnpm
pnpm -v

Output:

changed 1 package in 5s
11.2.2

OpenClaw repository validation:

pnpm install

Output excerpt:

Scope: all 155 workspace projects
Lockfile is up to date
Packages: +1207
...
Done in 3m 43.7s using pnpm v11.2.2

Evidence after fix: After using the documented fallback (npm install -g pnpm), pnpm installed successfully and pnpm install completed successfully in the OpenClaw repository, including dependency installation, preinstall hooks, postinstall hooks, and prepare scripts.

Observed result after fix: The Windows Corepack EPERM issue no longer blocked repository setup. The fallback path allowed successful pnpm installation and successful OpenClaw workspace installation.

What was not tested: Windows 11, administrator-elevated Corepack installation, and alternative Node.js versions.

Proof limitations or environment constraints: This PR changes documentation only. Validation was performed by reproducing the Windows Corepack EPERM failure and verifying that the documented fallback successfully completed OpenClaw repository setup.

Tests and validation

Commands executed:

corepack enable
npm install -g pnpm
pnpm -v
pnpm install

No automated tests were added because this is a documentation-only change.

Risk checklist

Did user-visible behavior change? Yes

Did config, environment, or migration behavior change? No

Did security, auth, secrets, network, or tool execution behavior change? No

Highest-risk area: Documentation accuracy.

How is that risk mitigated? The documented fallback was reproduced and validated on a real Windows 10 environment.

Current review state

Next action: Maintainer review.

Waiting on: Real behavior proof validation and reviewer feedback.

Bot or reviewer comments addressed: Added real Windows 10 reproduction steps, terminal output, and successful OpenClaw repository setup evidence.

@openclaw-barnacle openclaw-barnacle Bot added docs Improvements or additions to documentation size: XS triage: low-signal-docs Candidate: docs-only change looks low signal; maintainer review needed. triage: needs-real-behavior-proof Candidate: external PR needs after-fix proof from a real setup. labels Jun 18, 2026
@BradGroux BradGroux mentioned this pull request Jun 18, 2026
Draft
@clawsweeper

clawsweeper Bot commented Jun 18, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Codex review: needs maintainer review before merge. Reviewed July 25, 2026, 4:28 AM ET / 08:28 UTC.

ClawSweeper review

What this changes

This PR adds a Windows source-setup note recommending npm install -g [email protected] when corepack enable cannot create the pnpm shim because of an EPERM error.

Merge readiness

⚠️ Ready for maintainer review - 1 item remains

Keep this PR open for ordinary maintainer review. The scoped change is a plausible, documentation-only recovery path and the contributor supplied a real Windows setup transcript, but the branch is behind main and the exact current pnpm pin and surrounding setup guidance need a final current-main confirmation before merge.

Priority: P3
Reviewed head: defdae2e7a2120a42670ea88e769bea45b366315

Review scores

Measure Result What it means
Overall readiness 🐚 platinum hermit (4/6) A focused documentation patch with relevant real-environment context; a final current-main pin and branch refresh check is the remaining confidence reducer.
Proof confidence 🌊 off-meta tidepool Not applicable: Real behavior proof is not required because this PR only changes files under docs/.
Patch quality 🐚 platinum hermit (4/6) No actionable review findings were identified.

Verification

Check Result Evidence
Real behavior Not applicable Not applicable: Real behavior proof is not required because this PR only changes files under docs/.
Evidence reviewed 3 items Scoped documentation patch: The proposed branch changes only the Windows fallback note in the source setup guide and pins the fallback command to pnpm 11.15.1.
Supplied real setup evidence: The PR body records a Windows 10 Corepack EPERM reproduction followed by a successful global pnpm installation and successful OpenClaw workspace install; this is relevant after-fix evidence for a documentation-only change.
Prior review continuity: The earlier placement finding was addressed by moving the note from getting-started into source setup; the latest review context identified only current-pin confirmation and branch refresh as remaining review work.
Findings None None.
Security None None.

How this fits together

The source-setup documentation tells contributors how to prepare Node and pnpm before installing the OpenClaw workspace. This note sits on the recovery path between a failed Corepack shim installation and a usable pnpm command, after which dependency installation can proceed.

flowchart LR
  A[Windows contributor] --> B[Corepack enable]
  B --> C{Shim creation succeeds?}
  C -- Yes --> D[pnpm available]
  C -- EPERM --> E[Source setup fallback]
  E --> D
  D --> F[Workspace dependency install]
Loading

Before merge

  • Resolve merge risk (P1) - The branch is behind current main; before merge, confirm that [email protected] is still the repository-pinned version and that no newer setup guidance supersedes this recovery note.
Agent review details

Security

None.

PR surface

Docs +6. Total +6 across 1 file.

View PR surface stats
Area Files Added Removed Net
Source 0 0 0 0
Tests 0 0 0 0
Docs 1 6 0 +6
Config 0 0 0 0
Generated 0 0 0 0
Other 0 0 0 0
Total 1 6 0 +6

Review metrics

None.

Merge-risk options

Maintainer options:

  1. Decide the mitigation before merge
    Keep the concise fallback in source setup if the current package-manager pin still matches it, then refresh the branch against main so the published guidance remains accurate.
  2. Pause or close
    Do not merge this PR until maintainers decide whether the risk is worth taking.

Technical review

Best possible solution:

Keep the concise fallback in source setup if the current package-manager pin still matches it, then refresh the branch against main so the published guidance remains accurate.

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

Not applicable as a current-main code reproduction: this PR changes documentation only. The contributor supplied a concrete Windows 10 reproduction of the Corepack EPERM path and a successful fallback setup transcript.

Is this the best way to solve the issue?

Unclear pending current-main confirmation of the package-manager pin. Moving the note into source setup is the appropriate narrow documentation layer, but the exact version and wording should match current repository guidance before merge.

AGENTS.md: found and applied where relevant.

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

Labels

Label changes:

  • add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit. Replaced prior rating: 🦐 gold shrimp.
  • remove rating: 🦐 gold shrimp: Current PR rating is rating: 🐚 platinum hermit, so this older rating label is no longer current.

Label justifications:

  • P3: This is a narrowly scoped documentation improvement for a recoverable contributor setup problem.
  • rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit. Replaced prior rating: 🦐 gold shrimp.
  • status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: Real behavior proof is not required because this PR only changes files under docs/.

Evidence

What I checked:

  • Scoped documentation patch: The proposed branch changes only the Windows fallback note in the source setup guide and pins the fallback command to pnpm 11.15.1. Public docs: docs/start/setup.md. (docs/start/setup.md:185, defdae2e7a21)
  • Supplied real setup evidence: The PR body records a Windows 10 Corepack EPERM reproduction followed by a successful global pnpm installation and successful OpenClaw workspace install; this is relevant after-fix evidence for a documentation-only change. (defdae2e7a21)
  • Prior review continuity: The earlier placement finding was addressed by moving the note from getting-started into source setup; the latest review context identified only current-pin confirmation and branch refresh as remaining review work. Public docs: docs/start/setup.md. (docs/start/setup.md:185, a8ae9f001161)

Likely related people:

  • OpenClaw documentation ownership: Available review context establishes the affected surface as the maintained source-setup guide, but it does not provide sufficient local history evidence to attribute a specific current-main documentation owner safely. (role: likely follow-up owner; confidence: low; files: docs/start/setup.md)

Rank-up moves

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

  • Rebase or refresh against current main and verify that the documented pnpm version still matches the repository pin.

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 (3 earlier review cycles)
  • reviewed 2026-06-26T21:22:20.022Z sha 39b1656 :: needs changes before merge. :: [P2] Move the pnpm fallback to source setup
  • reviewed 2026-07-20T20:59:35.262Z sha 0fb5c71 :: needs maintainer review before merge. :: none
  • reviewed 2026-07-21T07:24:02.630Z sha a8ae9f0 :: needs maintainer review before merge. :: none

@clawsweeper clawsweeper Bot added rating: 🦐 gold shrimp Decent PR readiness signal, but merge confidence is limited. status: ⏳ waiting on author ClawSweeper has contributor-facing work open and is waiting for author action. P3 Low-priority cleanup, docs, polish, ergonomics, or speculative work. merge-risk: 🚨 compatibility 🚨 May break existing users, config, migrations, defaults, or upgrade paths. labels Jun 18, 2026
@openclaw-barnacle openclaw-barnacle Bot added proof: supplied External PR includes structured after-fix real behavior proof. and removed triage: needs-real-behavior-proof Candidate: external PR needs after-fix proof from a real setup. labels Jun 19, 2026
@africoding

africoding commented Jun 22, 2026

Copy link
Copy Markdown
Author

Thanks for the review and feedback.

The Real Behavior Proof section has been updated with a Windows 10 reproduction and successful OpenClaw repository setup validation using the documented fallback path.

Regarding the suggestion to move the workaround from docs/start/getting-started.md to source setup or troubleshooting documentation, I'm happy to make that change if maintainers agree that the current location is not the appropriate layer for this guidance.

Could a maintainer advise whether the preferred next step is:

  1. Keep the fallback note in docs/start/getting-started.md, or
  2. Move it to source setup / Windows troubleshooting documentation and submit an updated patch?

Thank you.

@clawsweeper clawsweeper Bot added status: 🛠️ actively grinding The PR author has acted after the latest ClawSweeper review and work remains. status: ⏳ waiting on author ClawSweeper has contributor-facing work open and is waiting for author action. and removed status: ⏳ waiting on author ClawSweeper has contributor-facing work open and is waiting for author action. status: 🛠️ actively grinding The PR author has acted after the latest ClawSweeper review and work remains. labels Jun 26, 2026
@clawsweeper clawsweeper Bot added rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR. and removed rating: 🦐 gold shrimp Decent PR readiness signal, but merge confidence is limited. status: ⏳ waiting on author ClawSweeper has contributor-facing work open and is waiting for author action. merge-risk: 🚨 compatibility 🚨 May break existing users, config, migrations, defaults, or upgrade paths. labels Jul 21, 2026
@africoding

africoding commented Jul 21, 2026

Copy link
Copy Markdown
Author

@clawsweeper re-review

Moved the Windows Corepack EPERM workaround from docs/start/getting-started.md to docs/start/setup.md and aligned the fallback with the repository's pinned pnpm version ([email protected]).

@clawsweeper

clawsweeper Bot commented Jul 21, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

@clawsweeper clawsweeper Bot added rating: 🦐 gold shrimp Decent PR readiness signal, but merge confidence is limited. and removed rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. labels Jul 23, 2026
@africoding

africoding commented Jul 25, 2026

Copy link
Copy Markdown
Author

Updated the pnpm version in the Windows fallback note from [email protected] to [email protected] to match the current packageManager pin in package.json on main. This addresses the P1 flagged in the last ClawSweeper review.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

docs Improvements or additions to documentation P3 Low-priority cleanup, docs, polish, ergonomics, or speculative work. proof: supplied External PR includes structured after-fix real behavior proof. rating: 🦐 gold shrimp Decent PR readiness signal, but merge confidence is limited. size: XS status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR. triage: low-signal-docs Candidate: docs-only change looks low signal; maintainer review needed.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@africoding