docs(channels/bluebubbles): document channel-vs-plugin disablement and safe loopback config (#54607)

lonexreb · lonexreb · commit 4cbb6e0de767 · 2026-05-05T13:12:25.000-05:00
The two BlueBubbles disablement layers (channels.bluebubbles.enabled
vs plugins.entries.bluebubbles.enabled) are independent. Operators
running tight-control postures regularly assume the channel-level off
also disables the plugin, then hit auto-enable surprises and config
rewrites at startup.

Add a 'Disabling BlueBubbles' section to docs/channels/bluebubbles.md
that:
  - shows the two layers as a comparison table with concrete effects
  - names when each is the right posture
  - ships a copy-pasteable safe local loopback-only example combining
    gateway.mode=local + bind=loopback + token auth + both layers off
  - notes which startup behaviors (meta block writes) are still
    allowed and which (auto-enable on explicit enabled: false) are not

Docs-only change. Mintlify-compatible Note block matches the style
already used elsewhere in this file.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -10,6 +10,7 @@ Docs: https://docs.openclaw.ai
 
 ### Changes
 
+- Docs/channels/bluebubbles: document the two independent BlueBubbles disablement layers and ship a copy-pasteable safe local loopback-only configuration. Refs #54607. Thanks @lonexreb.
 - Docker/Gateway: harden the gateway container by dropping `NET_RAW` and `NET_ADMIN` capabilities and enabling `no-new-privileges` in the bundled `docker-compose.yml`. Thanks @VintageAyu.
 - Telegram: accept plugin-owned numeric forum-topic targets in the agent message tool and keep reply-dispatch provider chunks behind a real stable runtime alias during in-place package updates. Fixes #77137. Thanks @richardmqq.
 - Channels/WhatsApp: support explicit WhatsApp Channel/Newsletter `@newsletter` outbound message targets with channel session metadata instead of DM routing. Fixes #13417; carries forward the narrow outbound target idea from #13424. Thanks @vincentkoc and @agentz-manfred.
diff --git a/docs/channels/bluebubbles.md b/docs/channels/bluebubbles.md
@@ -588,6 +588,48 @@ Related global options:
 - `agents.list[].groupChat.mentionPatterns` (or `messages.groupChat.mentionPatterns`).
 - `messages.responsePrefix`.
 
+## Disabling BlueBubbles
+
+OpenClaw has two independent disablement layers. Setting one does **not** automatically set the other, and operators who want BlueBubbles fully off should configure both.
+
+| Layer               | Key                                          | Effect                                                                                                                                                                                                                                                                           |
+| ------------------- | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Channel disablement | `channels.bluebubbles.enabled: false`        | Hard opt-out from inbound webhook routing, outbound delivery, channel auto-enable, and bundled-channel setup discovery. The plugin row may still appear in `openclaw plugins list` (it is bundled), but the channel does not register handlers and is treated as explicitly off. |
+| Plugin disablement  | `plugins.entries.bluebubbles.enabled: false` | Keeps the bundled plugin from registering at all. No webhook handler, no auto-enable on startup, no setup probes.                                                                                                                                                                |
+
+Either layer alone is sufficient to keep BlueBubbles routing and setup discovery off. Setting both is the belt-and-suspenders configuration when an operator wants the bundled plugin module itself to stay un-registered as well — useful in tight-control deployments that audit plugin registration counts at startup.
+
+A safe local loopback-only configuration that keeps BlueBubbles fully off looks like this:
+
+```json5
+{
+  gateway: {
+    mode: "local",
+    bind: "loopback",
+    auth: {
+      mode: "token",
+      // OpenClaw generates and persists a token on first start when token
+      // auth has no token. To pin a known value (recommended for scripted
+      // setups, CI, and operators who want config to be the source of
+      // truth), set it explicitly:
+      token: "<paste-or-generate-with-openclaw-auth-token-rotate>",
+    },
+  },
+  channels: {
+    bluebubbles: { enabled: false },
+  },
+  plugins: {
+    entries: {
+      bluebubbles: { enabled: false },
+    },
+  },
+}
+```
+
+<Note>
+  Startup may add a `meta` block to your `openclaw.json` (`lastTouchedVersion`, `lastTouchedAt`) when other config-mutating operations run. If `gateway.auth.mode: "token"` has no `gateway.auth.token`, OpenClaw also generates a token on first start and persists it back to the same file — that one extra write is the trade-off for omitting the token. Auto-enable for BlueBubbles itself never fires when `channels.bluebubbles.enabled` is explicitly `false`; auto-enable only fires for channels that look configured (e.g. a `serverUrl` and `password` present without an explicit `enabled: false`).
+</Note>
+
 ## Addressing / delivery targets
 
 Prefer `chat_guid` for stable routing:
