docs(imessage): document bluebubbles deprecation

vincentkoc · vincentkoc · commit 0fca66549794 · 2026-05-07T13:12:00.000-07:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -16,7 +16,6 @@ Docs: https://docs.openclaw.ai
 - Discord/voice: make `openclaw channels capabilities --channel discord --target channel:<id>` and `channels status --probe` audit voice-channel permissions, including auto-join targets, so missing Connect/Speak/Read Message History permissions show up before `/vc join`.
 - Channels CLI: make `openclaw channels list` channel-only — drop the `Auth providers (OAuth + API keys)` block (use `openclaw models auth list`), drop the per-provider usage/quota fetch and the `--no-usage` flag (use `openclaw status` or `openclaw models list`), add `--all` to surface bundled-unconfigured, catalog-not-installed, and catalog-installed-but-unconfigured channels, and render explicit `installed` / `configured` / `enabled` tags per row plus an `origin` + `installed` field in JSON. Fixes WeCom-class catalog channels disappearing from `--all` when installed on disk but not yet configured. (#78456) Thanks @sliverp.
 - CLI/cron: add computed `status` field to `cron list --json` and `cron show <id> --json` output, mirroring the human-readable status column (disabled/running/ok/error/skipped/idle) so external tooling can determine job state without re-deriving it from raw state fields. (#78701) Thanks @aweiker.
-- Channels/iMessage: remove the bundled BlueBubbles channel surface and docs, make `imsg` the supported iMessage setup path, and report non-macOS default `imsg` configs with remote-Mac wrapper guidance.
 - Discord/voice: make voice capture less choppy by extending the default post-speech silence grace to 2.5s, add `voice.captureSilenceGraceMs` for noisy Discord sessions, and tighten the spoken-output prompt around live STT fragments. Thanks @vincentkoc.
 - Discord/streaming: default Discord replies to progress draft previews so tool/work activity appears in one edited Discord message unless `channels.discord.streaming.mode` is set to `off`.
 - OpenAI: support `openai/chat-latest` as an explicit direct API-key model override for trying the moving ChatGPT Instant API alias without changing the stable default model.
@@ -147,6 +146,10 @@ Docs: https://docs.openclaw.ai
 - Config/Nix: keep startup-derived plugin enablement, gateway auth tokens, control UI origins, and owner-display secrets runtime-only instead of rewriting `openclaw.json`; in Nix mode, config writers, mutating `openclaw update`, plugin lifecycle mutators, and doctor repair/token-generation now refuse with agent-first nix-openclaw guidance. (#78047) Thanks @joshp123.
 - Agents/context engine: invalidate cached assembled context views when source history shrinks or assembly fails, preventing stale pre-reset history from being reused. Fixes #77968. (#78163) Thanks @brokemac79 and @ChrisBot2026.
 
+### Breaking
+
+- Channels/iMessage: remove the bundled BlueBubbles channel surface and deprecate BlueBubbles-backed iMessage setup in OpenClaw. Existing `channels.bluebubbles` configs must migrate to `channels.imessage` using `imsg` on a signed-in Mac or an SSH wrapper, and non-macOS default `imsg` configs now report remote-Mac wrapper guidance.
+
 ### Fixes
 
 - Docs/Docker: document a local Compose override for Docker Desktop DNS failures in the shared-network `openclaw-cli` sidecar, keeping the default compose setup hardened while unblocking `openclaw plugins install` when users opt in. Fixes #79018. Thanks @Jason-Vaughan.
diff --git a/docs/channels/imessage.md b/docs/channels/imessage.md
@@ -10,6 +10,10 @@ title: "iMessage"
 For OpenClaw iMessage deployments, use `imsg` on a signed-in macOS Messages host. If your Gateway runs on Linux or Windows, point `channels.imessage.cliPath` at an SSH wrapper that runs `imsg` on the Mac.
 </Note>
 
+<Warning>
+BlueBubbles is deprecated and no longer ships as a bundled OpenClaw channel. Migrate `channels.bluebubbles` configs to `channels.imessage`; OpenClaw now supports iMessage through `imsg` only. If you still need a BlueBubbles-backed bridge, publish or install it as a third-party plugin outside core.
+</Warning>
+
 Status: native external CLI integration. Gateway spawns `imsg rpc` and communicates over JSON-RPC on stdio (no separate daemon/port).
 
 <CardGroup cols={3}>
diff --git a/docs/docs.json b/docs/docs.json
@@ -52,6 +52,10 @@
     ]
   },
   "redirects": [
+    {
+      "source": "/channels/bluebubbles",
+      "destination": "/channels/imessage"
+    },
     {
       "source": "/install/migrating-matrix",
       "destination": "/channels/matrix-migration"
diff --git a/docs/gateway/config-channels.md b/docs/gateway/config-channels.md
@@ -585,6 +585,8 @@ When Mattermost native commands are enabled:
 
 OpenClaw spawns `imsg rpc` (JSON-RPC over stdio). No daemon or port required. This is the preferred path for new OpenClaw iMessage setups when the host can grant Messages database and Automation permissions.
 
+BlueBubbles is deprecated and no longer ships as a bundled OpenClaw channel. Migrate `channels.bluebubbles` configs to `channels.imessage`; third-party BlueBubbles bridges belong outside core.
+
 If the Gateway is not running on the signed-in Messages Mac, keep `channels.imessage.enabled=true` and set `channels.imessage.cliPath` to an SSH wrapper that runs `imsg "$@"` on that Mac. The default local `imsg` path is macOS-only.
 
 ```json5
diff --git a/scripts/github/barnacle-auto-response.mjs b/scripts/github/barnacle-auto-response.mjs
@@ -60,6 +60,13 @@ const rules = [
     close: true,
     message: thirdPartyExtensionMessage,
   },
+  {
+    label: "r: bluebubbles",
+    close: true,
+    commentTriggers: ["bluebubbles", "blue bubbles"],
+    message:
+      "BlueBubbles is deprecated and no longer ships as a bundled OpenClaw channel. Use iMessage via `imsg` instead: https://docs.openclaw.ai/channels/imessage. If this needs to stay BlueBubbles-backed, publish it as a third-party plugin on ClawHub instead of adding it back to core.",
+  },
   {
     label: "r: moltbook",
     close: true,
@@ -104,6 +111,10 @@ export const managedLabelSpecs = {
     color: "5319E7",
     description: "Auto-close: third-party plugins/capabilities belong on ClawHub.",
   },
+  "r: bluebubbles": {
+    color: "D93F0B",
+    description: "Auto-close: BlueBubbles is deprecated; use iMessage via imsg or ClawHub.",
+  },
   "r: moltbook": {
     color: "B60205",
     description: "Auto-close and lock: Moltbook is off-topic for OpenClaw.",
diff --git a/test/scripts/barnacle-auto-response.test.ts b/test/scripts/barnacle-auto-response.test.ts
@@ -230,6 +230,7 @@ describe("barnacle-auto-response", () => {
     expect(managedLabelSpecs["r: support"].description).toContain("support requests");
     expect(managedLabelSpecs["r: false-positive"].description).toContain("false positive");
     expect(managedLabelSpecs["r: third-party-extension"].description).toContain("ClawHub");
+    expect(managedLabelSpecs["r: bluebubbles"].description).toContain("deprecated");
     expect(managedLabelSpecs["r: too-many-prs"].description).toContain("twenty active PRs");
     expect(managedLabelSpecs[PROOF_SUPPLIED_LABEL].color).toBe("C2E0C6");
     expect(managedLabelSpecs[PROOF_SUFFICIENT_LABEL].color).toBe("0E8A16");
@@ -817,6 +818,29 @@ describe("barnacle-auto-response", () => {
     expect(calls.update).toContainEqual(expect.objectContaining({ state: "closed" }));
   });
 
+  it("closes manually labeled BlueBubbles requests with imsg migration guidance", async () => {
+    const { calls, github } = barnacleGithub([]);
+
+    await runBarnacleAutoResponse({
+      github,
+      context: barnacleIssueContext({}, ["r: bluebubbles"], {
+        action: "labeled",
+        label: { name: "r: bluebubbles" },
+        sender: { login: "maintainer", type: "User" },
+      }),
+      core: {
+        info: () => undefined,
+      },
+    });
+
+    expect(calls.createComment).toContainEqual(
+      expect.objectContaining({
+        body: expect.stringContaining("/channels/imessage"),
+      }),
+    );
+    expect(calls.update).toContainEqual(expect.objectContaining({ state: "closed" }));
+  });
+
   it("keeps bot-applied candidate labels passive", async () => {
     const { calls, github } = barnacleGithub([file("extensions/example/openclaw.plugin.json")]);
 

Original file line number	Diff line number	Diff line change
`@@ -52,6 +52,10 @@`
`52`	`52`	`]`
`53`	`53`	`},`
`54`	`54`	`"redirects": [`
	`55`	`+ {`
	`56`	`+ "source": "/channels/bluebubbles",`
	`57`	`+ "destination": "/channels/imessage"`
	`58`	`+ },`
`55`	`59`	`{`
`56`	`60`	`"source": "/install/migrating-matrix",`
`57`	`61`	`"destination": "/channels/matrix-migration"`