BlueBubbles - iMessage 现代方案

BlueBubbles 是一个开源的 iMessage 桥接服务器，运行在 macOS 设备上，通过 REST API 和 WebSocket 提供对 iMessage 的编程访问。它是 OpenClaw 推荐的 iMessage 集成方案，替代旧版直接读取 iMessage 数据库的方式。

为什么选择 BlueBubbles

特性	旧版 iMessage 集成	BlueBubbles
安装复杂度	高（需修改 TCC 权限）	低（标准应用安装）
API 接口	无，直接读取 SQLite	完整 REST API + WebSocket
稳定性	系统更新可能导致失效	独立应用，更新稳定
消息推送	轮询数据库	Webhook 实时推送
社区支持	无	活跃的开源社区

前置要求

• 一台持续运行的 Mac（macOS 11 Big Sur+）
• Mac 上已登录 iMessage（Apple ID）
• OpenClaw Gateway（网关）已安装并运行

接入步骤

第一步：安装 BlueBubbles Server

1. 从 BlueBubbles 官网 下载 macOS Server 应用
2. 打开应用并完成初始化向导
3. 授予必要权限：Full Disk Access（完整磁盘访问）和 Accessibility（辅助功能）

Homebrew 安装

brew install --cask bluebubbles

手动安装

# 从 GitHub Releases 下载最新版本
# https://github.com/BlueBubblesApp/bluebubbles-server/releases

第二步：配置 BlueBubbles Server

1. 启动 BlueBubbles Server 应用
2. 设置连接密码（Server Password）
3. 配置 Proxy Service（代理服务）— 可选择 Ngrok、Cloudflare 或 Dynamic DNS
4. 记录服务器地址和密码

本地连接

如果 OpenClaw Gateway 与 Mac 在同一网络中，可以直接使用本地地址（如 http://192.168.1.100:1234），无需配置 Proxy Service。

第三步：配置 Webhook

在 BlueBubbles Server 设置中：

1. 进入 API & Webhooks 标签
2. 添加 Webhook URL：https://your-gateway/bluebubbles/webhook
3. 勾选需要的事件类型：New Message、Updated Message、Typing Indicator

第四步：配置 OpenClaw

{
  channels: {
    bluebubbles: {
      enabled: true,
      serverUrl: "http://localhost:1234",        // BlueBubbles Server 地址
      password: "YOUR_SERVER_PASSWORD",           // Server 密码
      dmPolicy: "pairing"                        // DM Policy（私信策略）
    }
  }
}

也可以通过 Environment Variable（环境变量）设置：

export BLUEBUBBLES_SERVER_URL="http://localhost:1234"
export BLUEBUBBLES_PASSWORD="your-password"

第五步：重启 Gateway 并配对

openclaw gateway restart

通过 iMessage 向 Mac 上登录的手机号或 Apple ID 发送消息，获取 Pairing Code（配对码）后批准：

openclaw pairing approve bluebubbles <pairing-code>

消息类型支持

BlueBubbles 支持 iMessage 的大部分消息类型：

消息类型	支持状态
Text（文本）	✅ 完全支持
Image（图片）	✅ 完全支持
Attachment（附件）	✅ 完全支持
Tapback（回应）	✅ 支持
Group Chat（群聊）	✅ 支持
Read Receipt（已读回执）	✅ 支持
Typing Indicator（输入指示器）	✅ 支持

群聊支持

{
  channels: {
    bluebubbles: {
      groups: {
        allowAll: false,
        allowGroups: ["group-guid-xxx"],       // 允许的群聊 GUID
        requireMention: false                   // iMessage 群聊无 @ 功能
      }
    }
  }
}

群聊 GUID

群聊 GUID 在 Gateway 日志中显示，或通过 BlueBubbles API 查询：

curl http://localhost:1234/api/v1/chat?password=YOUR_PASSWORD

DM Policy（私信策略）

策略	说明
pairing	用户需先获取 Pairing Code（配对码）验证
allowlist	仅允许指定手机号/Apple ID 私聊
open	所有人均可私聊（谨慎使用）

从旧版 iMessage 集成迁移

如果你之前使用旧版 imessage 渠道，迁移步骤如下：

1. 安装 BlueBubbles Server 并配置
2. 将 OpenClaw 配置中的 channels.imessage 替换为 channels.bluebubbles
3. 重新进行 Pairing（配对），已有对话的用户需重新验证

# 禁用旧版
openclaw config set channels.imessage.enabled false --json

# 启用 BlueBubbles
openclaw config set channels.bluebubbles.enabled true --json

常见问题

无法收到新消息

1. 确认 BlueBubbles Server 正在运行且 iMessage 已登录
2. 确认 Webhook URL 可达
3. 检查 BlueBubbles Server 日志中是否有错误

Mac 休眠导致断线

确保 Mac 不进入休眠状态：

# 防止休眠（macOS）
sudo pmset -a disablesleep 1

或在 System Settings > Energy 中关闭自动休眠。

消息发送失败

1. 确认 Mac 上的 iMessage 正常工作（手动发送测试）
2. 检查 BlueBubbles Server 的 Full Disk Access 权限
3. 确认 Apple ID 未被锁定或要求二次验证

🇨🇳 中国用户须知

BlueBubbles 需要一台持续运行的 macOS 设备作为服务端，这是使用 iMessage 集成的基本前提。

设备要求：需要一台 Mac mini 或其他 macOS 设备 24/7 运行。Mac mini 是最经济的选择。

Apple ID：中国大陆 Apple ID 完全支持 iMessage，无需代理即可使用。

适用场景：已有 Apple 设备的团队、面向 iPhone 用户的客服场景、需要通过 iMessage 触达用户的业务。

成本考虑：除 Mac 硬件外，BlueBubbles Server 完全免费开源。如需远程访问，Ngrok 免费方案可满足基本需求。