diff --git a/CHANGELOG.md b/CHANGELOG.md index 8008842f777..46dabf1ac67 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,7 @@ Docs: https://docs.openclaw.ai ### Changes +- Docs/iMessage: deprecate BlueBubbles for new OpenClaw setups, document the upstream server-release rationale, and point new iMessage deployments toward the native `imsg` path while keeping BlueBubbles as a supported legacy fallback. - Plugins/install: add `npm-pack:` installs so local npm pack artifacts run through the same managed npm-root install, lockfile verification, dependency scan, and install-record path as registry npm plugins. - Plugin skills/Windows: publish plugin-provided skill directories as junctions on Windows so standard users without Developer Mode can register plugin skills without symlink EPERM failures. Fixes #77958. (#77971) Thanks @hclsys and @jarro. - MS Teams: surface blocked Bot Framework egress by logging JWKS fetch network failures and adding a Bot Connector send hint for transport-level reply failures. Fixes #77674. (#78081) Thanks @Beandon13. diff --git a/docs/channels/bluebubbles.md b/docs/channels/bluebubbles.md index 8868901ce40..cfb7a155979 100644 --- a/docs/channels/bluebubbles.md +++ b/docs/channels/bluebubbles.md @@ -1,5 +1,5 @@ --- -summary: "iMessage via BlueBubbles macOS server (REST send/receive, typing, reactions, pairing, advanced actions)." +summary: "Legacy iMessage support via the BlueBubbles macOS server (REST send/receive, typing, reactions, pairing, advanced actions)." read_when: - Setting up BlueBubbles channel - Troubleshooting webhook pairing @@ -8,7 +8,13 @@ title: "BlueBubbles" sidebarTitle: "BlueBubbles" --- -Status: bundled plugin that talks to the BlueBubbles macOS server over HTTP. **Recommended for iMessage integration** due to its richer API and easier setup compared to the legacy imsg channel. +Status: bundled legacy plugin that talks to the BlueBubbles macOS server over HTTP. Existing BlueBubbles setups continue to work, but new OpenClaw iMessage deployments should prefer the native [iMessage](/channels/imessage) plugin when its requirements fit your host. + + +BlueBubbles is deprecated for new OpenClaw setups. + +The upstream BlueBubbles ecosystem is still active, but OpenClaw depends on the BlueBubbles macOS server API. As of May 6, 2026, the official [`bluebubbles-server`](https://github.com/BlueBubblesApp/bluebubbles-server) development branch last changed on [January 22, 2026](https://github.com/BlueBubblesApp/bluebubbles-server/commit/88a4921bbd5a8111f1e9582b83715cf877171037), and the latest server release ([`v1.9.9`](https://github.com/BlueBubblesApp/bluebubbles-server/releases/tag/v1.9.9)) was published on May 16, 2025. The client app and helper repositories have newer activity, so this is not an abandonment claim; the deprecation is about reducing OpenClaw's dependency on an external HTTP server, webhooks, and private-API compatibility surface when the native `imsg` path keeps the integration on a local stdio contract. + Current OpenClaw releases bundle BlueBubbles, so normal packaged builds do not need a separate `openclaw plugins install` step. @@ -17,6 +23,7 @@ Current OpenClaw releases bundle BlueBubbles, so normal packaged builds do not n ## Overview - Runs on macOS via the BlueBubbles helper app ([bluebubbles.app](https://bluebubbles.app)). +- Legacy fallback for installations that already rely on BlueBubbles channel IDs, webhook state, group targets, cron delivery, or workspace routing. - Recommended/tested: macOS Sequoia (15). macOS Tahoe (26) works; edit is currently broken on Tahoe, and group icon updates may report success but not sync. - OpenClaw talks to it through its REST API (`GET /api/v1/ping`, `POST /message/text`, `POST /chat/:id/*`). - Incoming messages arrive via webhooks; outgoing replies, typing indicators, read receipts, and tapbacks are REST calls. diff --git a/docs/channels/imessage.md b/docs/channels/imessage.md index 2591e21cf01..081887bb792 100644 --- a/docs/channels/imessage.md +++ b/docs/channels/imessage.md @@ -1,22 +1,20 @@ --- -summary: "Legacy iMessage support via imsg (JSON-RPC over stdio). New setups should use BlueBubbles." +summary: "Native iMessage support via imsg (JSON-RPC over stdio). Preferred for new OpenClaw iMessage setups when host requirements fit." read_when: - Setting up iMessage support - Debugging iMessage send/receive title: "iMessage" --- - -For new iMessage deployments, use BlueBubbles. + +For new OpenClaw iMessage deployments, start here when you can run `imsg` on a signed-in macOS Messages host. BlueBubbles remains available as a legacy fallback for existing setups that depend on its HTTP server, webhooks, or richer private-API actions. + -The `imsg` integration is legacy and may be removed in a future release. - - -Status: legacy external CLI integration. Gateway spawns `imsg rpc` and communicates over JSON-RPC on stdio (no separate daemon/port). +Status: native external CLI integration. Gateway spawns `imsg rpc` and communicates over JSON-RPC on stdio (no separate daemon/port). - - Preferred iMessage path for new setups. + + Keep using it for existing BlueBubbles-backed routing; avoid it for new setups when imsg fits. iMessage DMs default to pairing mode. diff --git a/docs/channels/index.md b/docs/channels/index.md index 76265dd6c85..9857c2fb2cd 100644 --- a/docs/channels/index.md +++ b/docs/channels/index.md @@ -21,11 +21,11 @@ Text is supported everywhere; media and reactions vary by channel. ## Supported channels -- [BlueBubbles](/channels/bluebubbles) - **Recommended for iMessage**; uses the BlueBubbles macOS server REST API with full feature support (bundled plugin; edit, unsend, effects, reactions, group management - edit currently broken on macOS 26 Tahoe). +- [BlueBubbles](/channels/bluebubbles) - Legacy iMessage bridge via the BlueBubbles macOS server REST API; deprecated for new OpenClaw setups but still supported for existing configs and richer private-API actions. - [Discord](/channels/discord) - Discord Bot API + Gateway; supports servers, channels, and DMs. - [Feishu](/channels/feishu) - Feishu/Lark bot via WebSocket (bundled plugin). - [Google Chat](/channels/googlechat) - Google Chat API app via HTTP webhook (downloadable plugin). -- [iMessage (legacy)](/channels/imessage) - Legacy macOS integration via imsg CLI (deprecated, use BlueBubbles for new setups). +- [iMessage](/channels/imessage) - Native macOS integration via the imsg CLI; preferred for new OpenClaw iMessage setups when host permissions and Messages access fit. - [IRC](/channels/irc) - Classic IRC servers; channels + DMs with pairing/allowlist controls. - [LINE](/channels/line) - LINE Messaging API bot (downloadable plugin). - [Matrix](/channels/matrix) - Matrix protocol (downloadable plugin). diff --git a/docs/channels/pairing.md b/docs/channels/pairing.md index d7f515a536c..040a995aadb 100644 --- a/docs/channels/pairing.md +++ b/docs/channels/pairing.md @@ -208,7 +208,7 @@ Stored under `~/.openclaw/devices/`: - Telegram: [Telegram](/channels/telegram) - WhatsApp: [WhatsApp](/channels/whatsapp) - Signal: [Signal](/channels/signal) - - BlueBubbles (iMessage): [BlueBubbles](/channels/bluebubbles) - - iMessage (legacy): [iMessage](/channels/imessage) + - iMessage: [iMessage](/channels/imessage) + - BlueBubbles (legacy iMessage bridge): [BlueBubbles](/channels/bluebubbles) - Discord: [Discord](/channels/discord) - Slack: [Slack](/channels/slack) diff --git a/docs/concepts/features.md b/docs/concepts/features.md index d8d6ec9005f..701f9122bdc 100644 --- a/docs/concepts/features.md +++ b/docs/concepts/features.md @@ -32,8 +32,8 @@ title: "Features" **Channels:** -- Built-in channels include Discord, Google Chat, iMessage (legacy), IRC, Signal, Slack, Telegram, WebChat, and WhatsApp -- Bundled plugin channels include BlueBubbles for iMessage, Feishu, LINE, Matrix, Mattermost, Microsoft Teams, Nextcloud Talk, Nostr, QQ Bot, Synology Chat, Tlon, Twitch, Zalo, and Zalo Personal +- Built-in channels include Discord, Google Chat, iMessage, IRC, Signal, Slack, Telegram, WebChat, and WhatsApp +- Bundled plugin channels include BlueBubbles as a legacy iMessage bridge, Feishu, LINE, Matrix, Mattermost, Microsoft Teams, Nextcloud Talk, Nostr, QQ Bot, Synology Chat, Tlon, Twitch, Zalo, and Zalo Personal - Optional separately installed channel plugins include Voice Call and third-party packages such as WeChat - Third-party channel plugins can extend the Gateway further, such as WeChat - Group chat support with mention-based activation diff --git a/docs/gateway/config-channels.md b/docs/gateway/config-channels.md index 7778709056c..cf29c7f2529 100644 --- a/docs/gateway/config-channels.md +++ b/docs/gateway/config-channels.md @@ -575,7 +575,7 @@ When Mattermost native commands are enabled: ### BlueBubbles -BlueBubbles is the recommended iMessage path (plugin-backed, configured under `channels.bluebubbles`). +BlueBubbles is the legacy iMessage bridge (plugin-backed, configured under `channels.bluebubbles`). Existing setups remain supported, but new OpenClaw iMessage deployments should prefer `channels.imessage` when `imsg` can run on the Messages host. ```json5 { @@ -593,11 +593,11 @@ BlueBubbles is the recommended iMessage path (plugin-backed, configured under `c - Core key paths covered here: `channels.bluebubbles`, `channels.bluebubbles.dmPolicy`. - Optional `channels.bluebubbles.defaultAccount` overrides default account selection when it matches a configured account id. - Top-level `bindings[]` entries with `type: "acp"` can bind BlueBubbles conversations to persistent ACP sessions. Use a BlueBubbles handle or target string (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) in `match.peer.id`. Shared field semantics: [ACP Agents](/tools/acp-agents#persistent-channel-bindings). -- Full BlueBubbles channel configuration is documented in [BlueBubbles](/channels/bluebubbles). +- Full BlueBubbles channel configuration and deprecation rationale are documented in [BlueBubbles](/channels/bluebubbles). ### iMessage -OpenClaw spawns `imsg rpc` (JSON-RPC over stdio). No daemon or port required. +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. ```json5 { diff --git a/docs/reference/rpc.md b/docs/reference/rpc.md index 3382c443d10..348d4a319fb 100644 --- a/docs/reference/rpc.md +++ b/docs/reference/rpc.md @@ -1,5 +1,5 @@ --- -summary: "RPC adapters for external CLIs (signal-cli, legacy imsg) and gateway patterns" +summary: "RPC adapters for external CLIs (signal-cli, imsg) and gateway patterns" read_when: - Adding or changing external CLI integrations - Debugging RPC adapters (signal-cli, imsg) diff --git a/docs/start/docs-directory.md b/docs/start/docs-directory.md index 6195ee8725f..26433a9f9a1 100644 --- a/docs/start/docs-directory.md +++ b/docs/start/docs-directory.md @@ -39,9 +39,9 @@ For a complete map of the docs, see [Docs hubs](/start/hubs). - [Telegram](/channels/telegram) - [Discord](/channels/discord) - [Mattermost](/channels/mattermost) -- [BlueBubbles (iMessage)](/channels/bluebubbles) +- [BlueBubbles (legacy iMessage bridge)](/channels/bluebubbles) - [QQ Bot](/channels/qqbot) -- [iMessage (legacy)](/channels/imessage) +- [iMessage](/channels/imessage) - [Groups](/channels/groups) - [WhatsApp group messages](/channels/group-messages) - [Media images](/nodes/images) diff --git a/docs/start/hubs.md b/docs/start/hubs.md index 2f6d21f3162..6b291aeafe7 100644 --- a/docs/start/hubs.md +++ b/docs/start/hubs.md @@ -73,9 +73,9 @@ Use these hubs to discover every page, including deep dives and reference docs t - [Discord](/channels/discord) - [Mattermost](/channels/mattermost) - [Signal](/channels/signal) -- [BlueBubbles (iMessage)](/channels/bluebubbles) +- [BlueBubbles (legacy iMessage bridge)](/channels/bluebubbles) - [QQ Bot](/channels/qqbot) -- [iMessage (legacy)](/channels/imessage) +- [iMessage](/channels/imessage) - [Location parsing](/channels/location) - [WebChat](/web/webchat) - [Webhooks](/automation/cron-jobs#webhooks) diff --git a/skills/bluebubbles/SKILL.md b/skills/bluebubbles/SKILL.md index 946c76629e2..1bb9a90e5e4 100644 --- a/skills/bluebubbles/SKILL.md +++ b/skills/bluebubbles/SKILL.md @@ -8,7 +8,7 @@ metadata: { "openclaw": { "emoji": "🫧", "requires": { "config": ["channels.bl ## Overview -BlueBubbles is OpenClaw’s recommended iMessage integration. Use the `message` tool with `channel: "bluebubbles"` to send messages and manage iMessage conversations: send texts and attachments, react (tapbacks), edit/unsend, reply in threads, and manage group participants/names/icons. +BlueBubbles is OpenClaw's legacy iMessage bridge. Use the `message` tool with `channel: "bluebubbles"` for existing BlueBubbles-backed conversations that need attachments, tapbacks, edit/unsend, replies, or group management. ## Inputs to collect