PR #63000: fix(plugins): normalize Windows ESM import paths #62980

• Repository: openclaw/openclaw
• Author: jepson-liu
• State: closed | merged: False
• Link: https://github.com/openclaw/openclaw/pull/63000

Description (problem / solution / changelog)

Summary

• Problem: On Windows, OpenClaw onboarding/setup flows can crash with ERR_UNSUPPORTED_ESM_URL_SCHEME when plugin loader paths like C:\... are passed through the ESM loader, which interprets c: as an unsupported URL scheme.
• Why it matters: This breaks initial onboarding and configuration for Windows users, preventing them from installing and configuring models/providers successfully.
• What changed: Centralized a helper to normalize Windows absolute paths into file:// URLs and applied it to plugin loader Jiti bases and specifiers used by the setup and doctor contract registries.
• What did NOT change (scope boundary): No behavior changes to plugin discovery, activation rules, config schema validation, or non-Windows platforms; only the way module paths are passed into the loader was adjusted.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations (plugin loading/setup)
• API / contracts (plugin loader behavior)
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Fixes #62980

User-visible / Behavior Changes

• Windows users should no longer see Error [ERR_UNSUPPORTED_ESM_URL_SCHEME]: ... Received protocol 'c:' when running onboarding or plugin-related configuration flows.
• Behavior on non-Windows platforms is unchanged; paths are left as-is.

Security Impact (required)

• New permissions/capabilities? (Yes/No)
  No
• Secrets/tokens handling changed? (Yes/No)
  No
• New/changed network calls? (Yes/No)
  No
• Command/tool execution surface changed? (Yes/No)
  No
• Data access scope changed? (Yes/No)
  No
• If any Yes, explain risk + mitigation:
  N/A

Repro + Verification

Environment

• OS: Windows 10 (issue reporter), Linux dev environment for this fix
• Runtime/container: Node.js 22+ (as per repo baseline)
• Model/provider: Not required to trigger the loader bug
• Integration/channel: Plugin loader and setup/doctor plugin registries
• Relevant config (redacted): Any config that exercises plugin setup APIs or doctor contracts on Windows

Steps (original repro from issue)

1. On Windows PowerShell, install and run OpenClaw onboarding:

   powershell -c "irm https://openclaw.ai/install.ps1 | iex"

2. Configure a model/provider via onboarding so that plugin setup code runs.

Expected

• Onboarding and configuration complete without crashes.
• No ERR_UNSUPPORTED_ESM_URL_SCHEME from the Node ESM loader.

Actual (before this fix)

• On Windows, onboarding/setup can fail with:

  Error [ERR_UNSUPPORTED_ESM_URL_SCHEME]: Only URLs with a scheme in:
  file, data, and node are supported by the default ESM loader.
  On Windows, absolute paths must be valid file:// URLs.
  Received protocol 'c:'

Verification (after this fix)

Locally, on Linux (cannot fully exercise Windows ESM behavior, but we verify the loader wiring and tests that simulate win32):

• Targeted tests:

  pnpm test src/plugins/setup-registry.test.ts src/plugins/doctor-contract-registry.test.ts

  Both files now pass, including the cases that:

  • Force process.platform === "win32".
  • Assert that createJiti(...) is called with file://... URLs rather than raw paths for setup/contract modules.

• TypeScript + repo checks via the pre-commit hook:

  • pnpm tsgo (run inside scripts/committer)
  • pnpm check (run by scripts/committer)

On a real Windows machine, the expected manual verification is:

1. Upgrade to a build containing this fix.
2. Re-run onboarding / plugin configuration steps.
3. Confirm that ERR_UNSUPPORTED_ESM_URL_SCHEME no longer appears in logs or CLI output.

What Changed

• src/plugins/sdk-alias.ts

  • Added toSafeImportPath(specifier: string) as a shared helper that:
    • On win32, converts absolute paths (including drive-letter paths like C:\...) to file:// URLs.
    • Leaves file:// URLs and non-absolute specifiers unchanged.
  • Kept behavior on non-Windows platforms as a no-op.

• src/plugins/loader.ts

  • Switched from a local toSafeImportPath implementation to the shared helper in sdk-alias.ts, so that all plugin loader paths normalize imports consistently.

• src/plugins/setup-registry.ts

  • Updated the internal getJiti(modulePath) helper to:
    • Use toSafeImportPath(modulePath) when constructing the Jiti base.
  • When loading setup-api modules, now:
    • Use the original setupSource for alias resolution and cache keys.
    • Pass toSafeImportPath(setupSource) as the actual import specifier to Jiti.
  • This ensures Windows absolute paths are always normalized to file:// URLs before hitting ESM.

• src/plugins/doctor-contract-registry.ts

  • Applied the same pattern as setup-registry:
    • Normalize the Jiti base with toSafeImportPath(modulePath).
    • Normalize the contract module specifier with toSafeImportPath(contractSource).

• src/plugins/setup-registry.test.ts

  • Adjusted expectations to match the new behavior:
    • In the Windows-specific test, assert that createJiti is called with file://... URLs (using pathToFileURL(...).href), not with raw filesystem paths.

• src/plugins/doctor-contract-registry.test.ts

  • Same as above for the doctor contract path:
    • Ensure that on simulated win32, the Jiti base is a file:// URL.

Tests

• pnpm test src/plugins/setup-registry.test.ts src/plugins/doctor-contract-registry.test.ts
• pnpm tsgo

All of the above passed locally.

Checklist

• Changes are limited to the plugin loader + setup/doctor registry surfaces and related tests.
• No secrets, tokens, or user-specific data added to code or tests.
• Behavior on non-Windows platforms is unchanged.
• Tests added/updated to cover the Windows path normalization and prevent regressions.

Changed files

• src/plugins/doctor-contract-registry.test.ts (modified, +4/-1)
• src/plugins/doctor-contract-registry.ts (modified, +5/-2)
• src/plugins/loader.ts (modified, +1/-26)
• src/plugins/sdk-alias.ts (modified, +26/-0)
• src/plugins/setup-registry.test.ts (modified, +4/-1)
• src/plugins/setup-registry.ts (modified, +9/-4)