PR #52846: fix: keep whatsapp and acpx bundled, show install hint for missing channel plugins [AI-assisted]

• Repository: openclaw/openclaw
• Author: armanddp
• State: closed | merged: False
• Link: https://github.com/openclaw/openclaw/pull/52846

Description (problem / solution / changelog)

Problem

Upgrading from 2026.3.13 to 2026.3.22 silently breaks WhatsApp and ACPX. Both were added to optionalBundledClusters but:

• Neither has a published npm package (@openclaw/whatsapp, @openclaw/acpx return 404)
• The ClawHub [email protected] package is broken (missing openclaw.extensions metadata)
• The validation warning says "stale config entry ignored; remove it from plugins config" — the opposite of what users should do

6 of 13 optional bundled plugins are completely unavailable on 2026.3.22 (not bundled, not on npm): whatsapp, acpx, googlechat, diffs, memory-lancedb, ui.

Fix

Single commit with three targeted changes to ease the transition to channels-as-plugins:

1. Keep whatsapp and acpx in default builds (scripts/lib/optional-bundled-clusters.mjs)

Remove whatsapp and acpx from the optional list. Both are core functionality — WhatsApp is a primary messaging channel (bundled since day one) and ACPX is the ACP/Codex runtime. Once their npm packages are published and stable, they can move back to optional with proper migration guidance.

2. Include WhatsApp runtime API entries in the extension build (extensions/whatsapp/package.json)

The WhatsApp plugin uses a lazy boundary pattern that resolves light-runtime-api, runtime-api, and other modules at runtime. These were not listed in openclaw.extensions, so tsdown never compiled them into dist/extensions/whatsapp/. Without this, tarball installs crash with:

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

3. Show install hint for configured-but-missing channel plugins (src/config/validation.ts)

When a missing plugin matches a known channel ID with active configuration, show an actionable install command. This covers both plugins.entries and plugins.allow paths.

Before:

plugin not found: whatsapp (stale config entry ignored; remove it from plugins config)

After:

plugin not installed: whatsapp — channel is configured but the plugin is not bundled
in this build. Install it with: openclaw plugins install whatsapp

Changes

Testing

• Unit tests: pnpm vitest run src/config/config.plugin-validation.test.ts — 16/16 pass
• Extension tests: pnpm test:extension whatsapp — 297/305 pass (8 pre-existing failures in login.test.ts timer mocks, unrelated to this change)
• Build from source: pnpm build → verified dist/extensions/whatsapp/ includes light-runtime-api.js, runtime-api.js, etc.
• Tarball install: npm pack → npm install -g openclaw-2026.3.23.tgz → gateway restart → WhatsApp connected and processing messages (not a symlink — real tarball install)
• Fully tested end-to-end on macOS arm64

Review feedback addressed

• Hoisted KNOWN_CHANNEL_ID_SET to module scope (greptile P2)
• Added expect(res.ok).toBe(true) assertion (greptile P2)
• Install hint fires for plugins.allow entries too, not just plugins.entries (codex P1)
• Extracted isConfiguredChannel() helper (codex P1)

AI-assisted

Fixes #52838

Changed files

• .gitignore (modified, +1/-0)
• pnpm-lock.yaml (modified, +3/-0)
• scripts/copy-bundled-plugin-metadata.mjs (modified, +28/-0)
• scripts/lib/optional-bundled-clusters.mjs (modified, +7/-2)
• src/config/config.plugin-validation.test.ts (modified, +39/-0)
• src/config/validation.ts (modified, +22/-0)