Summary

Clarify the difference between disabling the BlueBubbles channel and disabling the BlueBubbles plugin, and document a safe local loopback-only runtime configuration.

Problem to solve

Users trying to keep Apple Messages / BlueBubbles under tight control can reasonably believe they have disabled BlueBubbles when they set channels.bluebubbles.enabled=false, but startup behavior can still treat BlueBubbles as configured and auto-enable the plugin unless plugin disablement is also explicit. Current behavior and documentation do not make the two disablement layers clear enough, and the safe local runtime posture is not obvious.

Proposed solution

Document, in one place, the difference between:

• channels.bluebubbles.enabled=false
• plugins.entries.bluebubbles.enabled=false

and explain which layer controls what.

Also add a documented safe local runtime example for users who want:

• gateway.mode=local
• gateway.bind=loopback
• gateway.auth.mode=token
• channels.bluebubbles.enabled=false
• plugins.entries.bluebubbles.enabled=false

Please also document whether startup may:

• rewrite config
• add/update meta
• auto-enable plugins
• infer that a channel is “configured” based on extra keys even when enabled=false

Alternatives considered

Workarounds were possible locally by trial and error:

• explicitly disabling the plugin as well as the channel
• hardening auth manually
• validating behavior by repeated shell launches

However, these are weaker because they depend on operator discovery instead of clear product guidance. Without docs, users can end up in a runtime posture different from what they intended.

Impact

Affected users/systems/channels:

• Users running local macOS OpenClaw runtimes
• Users integrating BlueBubbles / Apple Messages
• Users who want a read-only or non-mutating local runtime posture

Severity:

• Medium usability / safety-posture issue

Frequency:

• Likely whenever users attempt a local BlueBubbles-disabled setup and assume channel disablement alone is sufficient

Consequence:

• Confusion about whether BlueBubbles is actually disabled
• Extra manual investigation and repeated testing
• Risk of ending up with a runtime posture different from what the operator intended
• Slower onboarding for local controlled deployments

Evidence/examples

Observed locally:

• channels.bluebubbles.enabled=false was present
• startup still treated BlueBubbles as configured
• plugin auto-enable behavior was surprising unless plugins.entries.bluebubbles.enabled=false was also set explicitly
• a safer steady-state required:
  • loopback-only runtime
  • token auth
  • BlueBubbles disabled at both channel and plugin layers

A separate bug report was filed for the runtime/context behavior. This feature request is specifically about documentation and safe setup clarity.

Additional information

Requested outcome:

A user should be able to read the docs and confidently answer:

• “Have I actually disabled BlueBubbles?”
• “Do I also need to disable the plugin?”
• “How do I keep my local runtime loopback-only and authenticated?”
• “What config can startup mutate on launch?”

This is related to a bug report, but it is also a docs / usability gap on its own. Even if the runtime behavior is fixed later, clearer docs and a safe local example would still help prevent confusion and accidental unsafe posture.