[v2026.3.23] WhatsApp bundled runtime sidecars are still missing after global npm upgrade, causing gateway failures (missing light-runtime-api)

Summary

After upgrading a global macOS install from OpenClaw 2026.3.22 to OpenClaw 2026.3.23, the gateway still failed for WhatsApp with:

WhatsApp plugin runtime is unavailable: missing light-runtime-api for plugin 'whatsapp'

This contradicts the v2026.3.23 release note that says bundled plugin runtime sidecars such as WhatsApp light-runtime-api.js are shipped in the npm package again:

• Release notes: v2026.3.23
• Relevant line from the release notes:
  • "ship bundled plugin runtime sidecars like WhatsApp light-runtime-api.js ..."

Environment

• Host OS: macOS 26.3.1 arm64
• Node: v25.6.1
• Install method: global npm install under ~/.npm-global
• Previous version: OpenClaw 2026.3.22
• Upgraded to: OpenClaw 2026.3.23 (ccfeecb)

Actual behavior

Gateway request handling and the WhatsApp health monitor fail with:

Error: WhatsApp plugin runtime is unavailable: missing light-runtime-api for plugin 'whatsapp'

Observed log lines:

2026-03-24T02:39:39.242-07:00 [health-monitor] [whatsapp:default] health-monitor: restart failed: Error: WhatsApp plugin runtime is unavailable: missing light-runtime-api for plugin 'whatsapp'
2026-03-24T02:40:20.089-07:00 [gateway] request handler failed: Error: WhatsApp plugin runtime is unavailable: missing light-runtime-api for plugin 'whatsapp'

Expected behavior

Per the v2026.3.23 release notes, the global npm install should include the bundled WhatsApp runtime sidecars, and the gateway should not fail on missing:

• dist/extensions/whatsapp/light-runtime-api.js
• dist/extensions/whatsapp/runtime-api.js

Reproduction

I reproduced this on March 24, 2026 by upgrading an existing global install:

npm install -g openclaw@2026.3.23
openclaw gateway restart
openclaw gateway health

Then inspect the installed WhatsApp extension directory:

ls -la ~/.npm-global/lib/node_modules/openclaw/dist/extensions/whatsapp

On this machine the directory contained only:

index.js
openclaw.plugin.json
package.json
setup-entry.js

The expected sidecars were missing:

• light-runtime-api.js
• runtime-api.js

Additional evidence

1. The runtime boundary explicitly requires these files

The installed runtime boundary resolves:

• light-runtime-api
• runtime-api

and throws if either is missing.

This is visible in the built file:

• dist/runtime-whatsapp-boundary-*.js

The logic is effectively:

resolveWhatsAppRuntimeModulePath(..., "light-runtime-api")
resolveWhatsAppRuntimeModulePath(..., "runtime-api")
throw new Error("missing light-runtime-api for plugin 'whatsapp'")

2. The source tag contains the sidecar source files

In the v2026.3.23 source tree, these files do exist:

• extensions/whatsapp/light-runtime-api.ts
• extensions/whatsapp/runtime-api.ts

3. The build entry list appears to omit them

In the same source tag, extensions/whatsapp/package.json lists only:

"extensions": [
  "./index.ts"
]

with setupEntry set separately to ./setup-entry.ts.

The bundled plugin entry collector uses openclaw.extensions plus setupEntry to decide what gets emitted into dist/extensions/<plugin>/.

That means:

• index.ts is emitted
• setup-entry.ts is emitted
• light-runtime-api.ts is not emitted
• runtime-api.ts is not emitted

This matches the broken installed package layout I observed.

Local workaround that restored the gateway

I was able to restore WhatsApp locally by:

1. Cloning the v2026.3.23 source
2. Editing extensions/whatsapp/package.json to include:

"extensions": [
  "./index.ts",
  "./light-runtime-api.ts",
  "./runtime-api.ts"
]

3. Running the normal dist build
4. Overlaying the rebuilt dist/ onto the global install
5. Restarting the gateway

After that:

openclaw gateway health
OK
WhatsApp: linked

and:

openclaw status --deep
Channels
WhatsApp ON OK linked

This strongly suggests the regression is in the build/package entry list, not in WhatsApp config or device state.

Impact

• WhatsApp is registered as a built-in/bundled channel again in 2026.3.23
• but the required runtime sidecars are missing from the installed dist
• so gateway request handling and health monitoring fail at runtime
• users upgrading specifically to pick up the WhatsApp sidecar fix can still end up blocked

Suggested fix

Ensure v2026.3.23+ bundled builds include the WhatsApp sidecar entrypoints in the emitted dist artifacts:

• extensions/whatsapp/light-runtime-api.ts
• extensions/whatsapp/runtime-api.ts

The likely minimal fix is to add those files to the WhatsApp plugin build entries so they are emitted under:

• dist/extensions/whatsapp/light-runtime-api.js
• dist/extensions/whatsapp/runtime-api.js

Related release-note item

• v2026.3.23 release notes
• Relevant fix entry:
  • bundled plugin runtime sidecars like WhatsApp light-runtime-api.js should ship in npm again

Optional maintainer checks

If helpful, maintainers may want to verify all of the following in a clean global install:

npm install -g openclaw@2026.3.23
ls dist/extensions/whatsapp
openclaw gateway health
openclaw status --deep

and confirm that dist/extensions/whatsapp/ contains:

• index.js
• setup-entry.js
• light-runtime-api.js
• runtime-api.js