build(whatsapp): externalize whatsapp plugin

steipete · steipete · commit 85f9276624fc · 2026-05-13T11:21:17.000+01:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -53,7 +53,7 @@ Docs: https://docs.openclaw.ai
 - Scrub streamable MCP redirect headers [AI]. (#80906) Thanks @pgondhi987.
 - fix(memory-wiki): require admin scope for ingest [AI]. (#80897) Thanks @pgondhi987.
 - memory-wiki: require write scope for Obsidian search [AI]. (#80904) Thanks @pgondhi987.
-- WhatsApp/install: allow Baileys' pinned libsignal git subdependency under pnpm 11 so source installs and local checks can complete.
+- WhatsApp: externalize the channel as a ClawHub/npm plugin outside the core npm runtime bundle, and bump Baileys to `7.0.0-rc11` so libsignal resolves from the registry instead of a GitHub tarball.
 - Build: skip copied metadata for bundled plugins that are excluded from build entries, preventing update/status rebuilds from advertising missing QQ Bot runtime files. (#80925)
 - Control UI/sessions: nest subagent sessions under their parent session in the session picker dropdown using a visual `└─ ` prefix, making the parent-child relationship clear. Fixes #77628. (#78623) Thanks @chinar-amrutkar.
 - fix(config): reject auto-managed meta.lastTouched\* paths in config set/unset (#80856). Thanks @ai-hpc
diff --git a/docs/channels/index.md b/docs/channels/index.md
@@ -16,8 +16,8 @@ Text is supported everywhere; media and reactions vary by channel.
 - Slack multi-person DMs route as group chats, so group policy, mention
   behavior, and group-session rules apply to MPIM conversations.
 - WhatsApp setup is install-on-demand: onboarding can show the setup flow before
-  the plugin package is installed, and the Gateway loads the WhatsApp runtime
-  only when the channel is actually active.
+  the plugin package is installed, and the Gateway loads the external
+  ClawHub/npm plugin only when the channel is actually active.
 
 ## Supported channels
 
diff --git a/docs/channels/whatsapp.md b/docs/channels/whatsapp.md
@@ -14,27 +14,19 @@ Status: production-ready via WhatsApp Web (Baileys). Gateway owns linked session
 - `openclaw channels login --channel whatsapp` also offers the install flow when
   the plugin is not present yet.
 - Dev channel + git checkout: defaults to the local plugin path.
-- Stable/Beta: uses the npm package `@openclaw/whatsapp` on the current official
-  release tag.
+- Stable/Beta: installs the official `@openclaw/whatsapp` plugin from ClawHub
+  first, with npm as the fallback.
+- The WhatsApp runtime is distributed outside the core OpenClaw npm package
+  because its Baileys dependency chain uses GPL-licensed `libsignal`.
 
 Manual install stays available:
 
 ```bash
-openclaw plugins install @openclaw/whatsapp
+openclaw plugins install clawhub:@openclaw/whatsapp
 ```
 
-Use the bare package to follow the current official release tag. Pin an exact
-version only when you need a reproducible install.
-
-On Windows, the WhatsApp plugin needs Git on `PATH` during npm install because
-one of its Baileys/libsignal dependencies is fetched from a git URL. Install
-Git for Windows, then restart the shell and rerun the install:
-
-```powershell
-winget install --id Git.Git -e
-```
-
-Portable Git also works if its `bin` directory is on `PATH`.
+Use the bare npm package (`@openclaw/whatsapp`) only when you need the registry
+fallback. Pin an exact version only when you need a reproducible install.
 
 <CardGroup cols={3}>
   <Card title="Pairing" icon="link" href="/channels/pairing">
diff --git a/docs/plugins/plugin-inventory.md b/docs/plugins/plugin-inventory.md
@@ -166,7 +166,7 @@ uninstall, and publishing commands.
 | [tlon](/plugins/reference/tlon)                                     | Adds the Tlon channel surface for sending and receiving OpenClaw messages.            | `@openclaw/tlon`<br />npm; ClawHub                                                               | channels: tlon; contracts: tools; skills                                     |
 | [twitch](/plugins/reference/twitch)                                 | Adds the Twitch channel surface for sending and receiving OpenClaw messages.          | `@openclaw/twitch`<br />npm; ClawHub                                                             | channels: twitch                                                             |
 | [voice-call](/plugins/reference/voice-call)                         | Adds agent-callable tools.                                                            | `@openclaw/voice-call`<br />npm; ClawHub                                                         | contracts: tools                                                             |
-| [whatsapp](/plugins/reference/whatsapp)                             | Adds the WhatsApp channel surface for sending and receiving OpenClaw messages.        | `@openclaw/whatsapp`<br />npm; ClawHub                                                           | channels: whatsapp                                                           |
+| [whatsapp](/plugins/reference/whatsapp)                             | Adds the WhatsApp channel surface for sending and receiving OpenClaw messages.        | `@openclaw/whatsapp`<br />ClawHub: `clawhub:@openclaw/whatsapp`; npm                             | channels: whatsapp                                                           |
 | [zalo](/plugins/reference/zalo)                                     | Adds the Zalo channel surface for sending and receiving OpenClaw messages.            | `@openclaw/zalo`<br />npm; ClawHub                                                               | channels: zalo                                                               |
 | [zalouser](/plugins/reference/zalouser)                             | Adds the Zalo Personal channel surface for sending and receiving OpenClaw messages.   | `@openclaw/zalouser`<br />npm; ClawHub                                                           | channels: zalouser; contracts: tools                                         |
 
diff --git a/docs/plugins/reference.md b/docs/plugins/reference.md
@@ -128,7 +128,7 @@ pnpm plugins:inventory:gen
 | [vydra](/plugins/reference/vydra)                                   | Adds Vydra model provider support to OpenClaw.                                                                                                                       | `@openclaw/vydra-provider`<br />included in OpenClaw                                             | providers: vydra; contracts: imageGenerationProviders, speechProviders, videoGenerationProviders                                                                                                                                                                 |
 | [web-readability](/plugins/reference/web-readability)               | Extract readable article content from local HTML web fetch responses.                                                                                                | `@openclaw/web-readability-plugin`<br />included in OpenClaw                                     | contracts: webContentExtractors                                                                                                                                                                                                                                  |
 | [webhooks](/plugins/reference/webhooks)                             | Authenticated inbound webhooks that bind external automation to OpenClaw TaskFlows.                                                                                  | `@openclaw/webhooks`<br />included in OpenClaw                                                   | plugin                                                                                                                                                                                                                                                           |
-| [whatsapp](/plugins/reference/whatsapp)                             | Adds the WhatsApp channel surface for sending and receiving OpenClaw messages.                                                                                       | `@openclaw/whatsapp`<br />npm; ClawHub                                                           | channels: whatsapp                                                                                                                                                                                                                                               |
+| [whatsapp](/plugins/reference/whatsapp)                             | Adds the WhatsApp channel surface for sending and receiving OpenClaw messages.                                                                                       | `@openclaw/whatsapp`<br />ClawHub: `clawhub:@openclaw/whatsapp`; npm                             | channels: whatsapp                                                                                                                                                                                                                                               |
 | [xai](/plugins/reference/xai)                                       | Adds xAI model provider support to OpenClaw.                                                                                                                         | `@openclaw/xai-plugin`<br />included in OpenClaw                                                 | providers: xai; contracts: imageGenerationProviders, mediaUnderstandingProviders, realtimeTranscriptionProviders, speechProviders, tools, videoGenerationProviders, webSearchProviders                                                                           |
 | [xiaomi](/plugins/reference/xiaomi)                                 | Adds Xiaomi model provider support to OpenClaw.                                                                                                                      | `@openclaw/xiaomi-provider`<br />included in OpenClaw                                            | providers: xiaomi; contracts: speechProviders                                                                                                                                                                                                                    |
 | [zai](/plugins/reference/zai)                                       | Adds Z.AI model provider support to OpenClaw.                                                                                                                        | `@openclaw/zai-provider`<br />included in OpenClaw                                               | providers: zai; contracts: mediaUnderstandingProviders                                                                                                                                                                                                           |
diff --git a/docs/plugins/reference/whatsapp.md b/docs/plugins/reference/whatsapp.md
@@ -12,22 +12,12 @@ Adds the WhatsApp channel surface for sending and receiving OpenClaw messages.
 ## Distribution
 
 - Package: `@openclaw/whatsapp`
-- Install route: npm; ClawHub
+- Install route: ClawHub: `clawhub:@openclaw/whatsapp`; npm
 
 ## Surface
 
 channels: whatsapp
 
-## Windows install note
-
-On Windows, the WhatsApp plugin needs Git on `PATH` during npm install because one of its Baileys/libsignal dependencies is fetched from a git URL. Install Git for Windows, then restart the shell and rerun the install:
-
-```powershell
-winget install --id Git.Git -e
-```
-
-Portable Git also works if its `bin` directory is on `PATH`.
-
 ## Related docs
 
 - [whatsapp](/channels/whatsapp)
diff --git a/extensions/whatsapp/package.json b/extensions/whatsapp/package.json
@@ -8,7 +8,7 @@
   },
   "type": "module",
   "dependencies": {
-    "baileys": "7.0.0-rc10",
+    "baileys": "7.0.0-rc11",
     "https-proxy-agent": "9.0.0",
     "jimp": "1.6.1",
     "typebox": "1.1.38",
@@ -56,8 +56,9 @@
       ]
     },
     "install": {
+      "clawhubSpec": "clawhub:@openclaw/whatsapp",
       "npmSpec": "@openclaw/whatsapp",
-      "defaultChoice": "npm",
+      "defaultChoice": "clawhub",
       "minHostVersion": ">=2026.4.25"
     },
     "compat": {
diff --git a/patches/baileys@7.0.0-rc11.patch b/patches/baileys@7.0.0-rc11.patch
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
@@ -12,7 +12,9 @@ minimumReleaseAgeExclude:
   - "@agentclientprotocol/sdk"
   - "axios"
   - "basic-ftp"
+  - "baileys@7.0.0-rc11"
   - "hono"
+  - "libsignal@6.0.0"
   - "openclaw"
   - "protobufjs"
   - "vite"
@@ -71,7 +73,6 @@ allowBuilds:
   "@tloncorp/api": true
   "@tloncorp/tlon-skill": true
   baileys: true
-  "@whiskeysockets/libsignal-node": true
   authenticate-pam: true
   "@discordjs/opus": false
   esbuild: true
@@ -92,5 +93,5 @@ peerDependencyRules:
     "prism-media>opusscript": "^0.0.8 || ^0.1.1"
 
 patchedDependencies:
-  "baileys@7.0.0-rc10": "patches/baileys@7.0.0-rc10.patch"
+  "baileys@7.0.0-rc11": "patches/baileys@7.0.0-rc11.patch"
   "@agentclientprotocol/claude-agent-acp@0.33.1": "patches/@agentclientprotocol__claude-agent-acp@0.33.1.patch"
diff --git a/scripts/generate-plugin-inventory-doc.mjs b/scripts/generate-plugin-inventory-doc.mjs
@@ -28,20 +28,7 @@ const PLUGIN_DOC_ALIASES = new Map([
   ["tavily", "/tools/tavily"],
   ["tokenjuice", "/tools/tokenjuice"],
 ]);
-const PLUGIN_REFERENCE_EXTRA_SECTIONS = new Map([
-  [
-    "whatsapp",
-    `## Windows install note
-
-On Windows, the WhatsApp plugin needs Git on \`PATH\` during npm install because one of its Baileys/libsignal dependencies is fetched from a git URL. Install Git for Windows, then restart the shell and rerun the install:
-
-\`\`\`powershell
-winget install --id Git.Git -e
-\`\`\`
-
-Portable Git also works if its \`bin\` directory is on \`PATH\`.`,
-  ],
-]);
+const PLUGIN_REFERENCE_EXTRA_SECTIONS = new Map([]);
 
 function readJson(relativePath) {
   return JSON.parse(fs.readFileSync(path.join(ROOT, relativePath), "utf8"));
diff --git a/scripts/lib/bundled-plugin-build-entries.mjs b/scripts/lib/bundled-plugin-build-entries.mjs
@@ -9,7 +9,7 @@ import { shouldBuildBundledCluster } from "./optional-bundled-clusters.mjs";
 
 const TOP_LEVEL_PUBLIC_SURFACE_EXTENSIONS = new Set([".ts", ".js", ".mts", ".cts", ".mjs", ".cjs"]);
 export const NON_PACKAGED_BUNDLED_PLUGIN_DIRS = new Set(["qa-channel", "qa-lab", "qa-matrix"]);
-const EXCLUDED_CORE_BUNDLED_PLUGIN_DIRS = new Set(["qqbot"]);
+const EXCLUDED_CORE_BUNDLED_PLUGIN_DIRS = new Set(["qqbot", "whatsapp"]);
 const toPosixPath = (value) => value.replaceAll("\\", "/");
 
 function readBundledPluginPackageJson(packageJsonPath) {
diff --git a/scripts/lib/official-external-channel-catalog.json b/scripts/lib/official-external-channel-catalog.json
@@ -475,8 +475,9 @@
           "systemImage": "message"
         },
         "install": {
+          "clawhubSpec": "clawhub:@openclaw/whatsapp",
           "npmSpec": "@openclaw/whatsapp",
-          "defaultChoice": "npm",
+          "defaultChoice": "clawhub",
           "minHostVersion": ">=2026.4.25"
         }
       }
diff --git a/src/plugins/copy-bundled-plugin-metadata.test.ts b/src/plugins/copy-bundled-plugin-metadata.test.ts
@@ -414,15 +414,15 @@ describe("copyBundledPluginMetadata", () => {
       expectedExists: false,
     },
     {
-      name: "still bundles previously released optional plugins without the opt-in env",
+      name: "removes externalized optional plugin metadata from the core dist",
       pluginId: "whatsapp",
       packageName: "@openclaw/whatsapp",
       packageOpenClaw: {
         extensions: ["./index.ts"],
         install: { npmSpec: "@openclaw/whatsapp" },
       },
       env: {},
-      expectedExists: true,
+      expectedExists: false,
     },
   ] as const)("$name", ({ pluginId, packageName, packageOpenClaw, env, expectedExists }) => {
     const repoRoot = makeRepoRoot(`openclaw-bundled-plugin-${pluginId}-`);
diff --git a/src/plugins/official-external-plugin-repair-hints.test.ts b/src/plugins/official-external-plugin-repair-hints.test.ts
diff --git a/test/official-channel-catalog.test.ts b/test/official-channel-catalog.test.ts
diff --git a/test/scripts/bundled-plugin-build-entries.test.ts b/test/scripts/bundled-plugin-build-entries.test.ts
diff --git a/test/scripts/postinstall-bundled-plugins.test.ts b/test/scripts/postinstall-bundled-plugins.test.ts
