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)

PR #52913: fix(release): preserve shipped channel surfaces in npm tar

• Repository: openclaw/openclaw
• Author: ngutman
• State: closed | merged: True
• Link: https://github.com/openclaw/openclaw/pull/52913

Description (problem / solution / changelog)

Summary

Describe the problem and fix in 2–5 bullets:

• Problem: 2026.3.22 stripped previously shipped optional bundled extension metadata and dist/control-ui from the npm tarball, which left upgraded packaged installs with missing channel discovery and missing UI assets.
• Why it matters: upgraded users could hit Unknown channel: whatsapp, lose auto-install discovery for install-on-demand channels, and end up with missing Control UI assets after upgrade.
• What changed: ship the official channel catalog fallback, keep previously shipped optional bundled upgrade surfaces in npm release artifacts by default, require dist/control-ui/index.html plus optional bundled extension manifests in release-check, and make release:check build Control UI before validating the pack.
• What did NOT change (scope boundary): this does not publish @openclaw/whatsapp, does not change plugin install semantics beyond restoring discovery and shipped upgrade surfaces, and does not force optional bundles for lanes that explicitly opt out with OPENCLAW_INCLUDE_OPTIONAL_BUNDLED=0.

Change Type (select all)

• Bug fix
• Feature
• Refactor
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes #
• Related #52838

User-visible / Behavior Changes

• Packaged installs keep dist/control-ui and the previously shipped optional bundled extension metadata needed for upgrade continuity.
• Official install-on-demand channels remain discoverable in packaged installs even when their runtime is not bundled.
• No operator-facing config changes are required for the normal release lane.

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:

Repro + Verification

Environment

• OS: macOS
• Runtime/container: local build + clean npm pack install
• Model/provider: n/a
• Integration/channel (if any): WhatsApp / Control UI
• Relevant config (redacted): clean OPENCLAW_STATE_DIR for packaged-install repro

Steps

1. Install [email protected] into a clean temporary directory.
2. Run openclaw channels add --channel whatsapp or inspect the packaged tarball contents.
3. Observe that WhatsApp metadata and dist/control-ui are missing from the shipped artifact.

Expected

• Previously shipped upgrade surfaces remain present in the npm tarball, and official install-on-demand channels stay discoverable.

Actual

• Clean packaged installs lost WhatsApp discoverability and the tarball omitted Control UI assets.

Evidence

Attach at least one:

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Human Verification (required)

What you personally verified (not just CI), and how:

• Verified scenarios:
  • pnpm check
  • pnpm build
  • pnpm test -- test/official-channel-catalog.test.ts
  • pnpm test -- src/channels/plugins/plugins-core.test.ts
  • pnpm test -- src/plugins/copy-bundled-plugin-metadata.test.ts
  • pnpm test -- test/release-check.test.ts
  • node scripts/stage-bundled-plugin-runtime-deps.mjs
  • pnpm ui:build
  • node --import tsx scripts/release-check.ts
  • npm pack --dry-run --json --ignore-scripts includes dist/channel-catalog.json, dist/control-ui/index.html, and the optional bundled extension manifests for acpx, diagnostics-otel, diffs, googlechat, matrix, memory-lancedb, msteams, nostr, tlon, twitch, whatsapp, and zalouser
• Edge cases checked:
  • shipped official catalog entries load when bundled metadata is absent
  • bundled metadata-backed channel entries still preserve pluginId
  • default packaging now keeps the prior shipped optional-bundle upgrade surface
  • explicit OPENCLAW_INCLUDE_OPTIONAL_BUNDLED=0 still disables optional bundles for size-sensitive lanes
  • release-check fails when required shipped paths are missing
• What you did not verify:
  • publishing/installing the actual @openclaw/whatsapp package
  • the full top-level pnpm release:check wrapper is still blocked earlier by existing config baseline drift on current main; the pack-validation portion was run directly and passed

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

If a bot review conversation is addressed by this PR, resolve that conversation yourself. Do not leave bot review conversation cleanup for maintainers.

Compatibility / Migration

• Backward compatible? (Yes/No) Yes
• Config/env changes? (Yes/No) No
• Migration needed? (Yes/No) No
• If yes, exact upgrade steps:

Failure Recovery (if this breaks)

• How to disable/revert this change quickly: revert 2f1f4100ec, or set OPENCLAW_INCLUDE_OPTIONAL_BUNDLED=0 on a size-sensitive packaging lane that must opt out explicitly
• Files/config to restore: scripts/lib/optional-bundled-clusters.mjs, scripts/release-check.ts, package.json
• Known bad symptoms reviewers should watch for: packaged installs missing dist/control-ui/index.html, missing optional bundled extension manifests, or pack size growing materially beyond the new 176 MiB budget

Risks and Mitigations

List only real risks for this PR. Add/remove entries as needed. If none, write None.

• Risk: restoring the shipped upgrade surface increases npm pack size.
  • Mitigation: the budget is raised only to 176 MiB, while remaining well below the 2026.3.12 213.6 MiB regression guardrail, and release-check still enforces the budget.
• Risk: some size-sensitive packaging lanes may still want the old stripped behavior.
  • Mitigation: those lanes can opt out explicitly with OPENCLAW_INCLUDE_OPTIONAL_BUNDLED=0.

Changed files

• package.json (modified, +1/-1)
• scripts/copy-bundled-plugin-metadata.d.mts (modified, +5/-1)
• scripts/lib/bundled-plugin-build-entries.d.mts (added, +19/-0)
• scripts/lib/bundled-plugin-build-entries.d.ts (added, +19/-0)
• scripts/lib/optional-bundled-clusters.mjs (modified, +3/-1)
• scripts/release-check.ts (modified, +16/-3)
• scripts/runtime-postbuild.mjs (modified, +2/-0)
• scripts/write-official-channel-catalog.d.mts (added, +19/-0)
• scripts/write-official-channel-catalog.mjs (added, +104/-0)
• src/channels/plugins/catalog.ts (modified, +52/-6)
• src/channels/plugins/plugins-core.test.ts (modified, +40/-0)
• src/plugins/copy-bundled-plugin-metadata.test.ts (modified, +10/-10)
• test/official-channel-catalog.test.ts (added, +146/-0)
• test/release-check.test.ts (modified, +47/-1)