通过BlueBubbles让OpenClaw接入iMessage

为什么选择 BlueBubbles

如果你之前使用过 OpenClaw 的原生 iMessage 集成（基于 AppleScript 桥接），你可能已经注意到它存在不少限制：轮询延迟、无法发送富媒体、对 macOS 系统更新敏感等。从 OpenClaw 最新版本开始，旧版 iMessage 集成已被正式弃用，官方推荐使用 BlueBubbles 作为连接 iMessage 的替代方案。

BlueBubbles 是一个开源项目，它在 macOS 上运行一个服务器，通过 REST API 暴露 iMessage 的完整功能。OpenClaw 通过这套 API 与 iMessage 交互，相比旧方案有以下显著优势：

• REST API 架构：稳定可靠，不再依赖脆弱的 AppleScript 桥接
• 完整功能支持：收发文本、图片、附件、Tapback 反应等
• 实时消息推送：通过 WebSocket 实现即时通知，告别轮询延迟
• 原生集成：OpenClaw 内置了 BlueBubbles 频道支持，无需额外插件
• 活跃维护：BlueBubbles 社区活跃，持续跟进 macOS 更新

前置条件

在开始之前，请确认以下准备工作：

与旧版方案不同，OpenClaw 本身不需要运行在 macOS 上。你可以在 Linux VPS 上运行 OpenClaw，同时让一台 Mac mini 作为 BlueBubbles 服务器。这种分离架构更加灵活。

第一步：安装和配置 BlueBubbles 服务器

1.1 下载 BlueBubbles

前往 BlueBubbles 官方网站下载 macOS 服务器应用，或者通过 Homebrew 安装：

brew install --cask bluebubbles

1.2 初始化设置

首次启动 BlueBubbles 后，按照向导完成基础配置：

1. 授予 BlueBubbles 完全磁盘访问权限（系统设置 → 隐私与安全性 → 完全磁盘访问权限）
2. 确保 Messages.app 已登录你的 Apple ID
3. 在 BlueBubbles 中配置服务器密码（稍后需要填入 OpenClaw 配置）

1.3 获取 REST API 地址

BlueBubbles 启动后，会在状态栏显示服务器的本地地址，通常是：

http://localhost:1234

如果 OpenClaw 运行在另一台机器上，你需要确保这个端口可以被远程访问。可以通过以下方式实现：

• 局域网直连：确保两台机器在同一网络，使用 Mac 的局域网 IP
• 反向代理：使用 Nginx 或 Cloudflare Tunnel 暴露 API
• BlueBubbles 内置的 Ngrok/动态 DNS 功能

第二步：配置 OpenClaw 连接 BlueBubbles

2.1 添加频道

运行以下命令添加 BlueBubbles 频道：

openclaw channel add bluebubbles

向导会引导你填写 BlueBubbles 服务器地址和密码。

2.2 手动编辑配置

你也可以直接编辑 ~/.config/openclaw/openclaw.json5：

{
  channels: {
    bluebubbles: {
      enabled: true,

      // BlueBubbles 服务器地址
      serverUrl: "http://192.168.1.100:1234",

      // BlueBubbles 服务器密码
      password: "your-server-password",

      // 安全配置
      security: {
        allowedIdentifiers: [
          "+8613800138000",
          "[email protected]"
        ],
        groupChatEnabled: false,
        allowUnknown: false
      },

      // 触发配置
      trigger: {
        autoReply: true,
        keywords: [],
        groupTrigger: "keyword",
        groupKeywords: ["@AI", "/ask"]
      },

      // 消息配置
      message: {
        maxLength: 10000,
        sendTypingIndicator: true,
        sendReadReceipts: true,
        supportAttachments: true
      }
    }
  }
}

2.3 启动并验证

openclaw restart

# 查看 BlueBubbles 频道日志
openclaw logs -f --component channel:bluebubbles

连接成功后你会看到：

[INFO] [channel:bluebubbles] BlueBubbles 连接已建立
[INFO] [channel:bluebubbles] 服务器版本: 1.x.x
[INFO] [channel:bluebubbles] WebSocket 已连接，等待实时消息...
[INFO] [channel:bluebubbles] 允许的联系人: 2 个

从旧版 iMessage 集成迁移

如果你之前使用的是旧版 AppleScript 方案，迁移步骤很简单：

1. 停止 OpenClaw 服务：openclaw stop
2. 在配置文件中将 channels.imessage.enabled 设为 false
3. 按照上述步骤配置 BlueBubbles 频道
4. 重新启动：openclaw up

旧版 imessage 频道的配置可以保留在配置文件中，只要确保 enabled 为 false 即可。OpenClaw 在启动时如果检测到旧版 iMessage 频道仍处于启用状态，会输出弃用警告并建议你切换到 BlueBubbles。

消息类型支持对比

BlueBubbles 方案相比旧版有了大幅提升：

常见问题排查

无法连接到 BlueBubbles 服务器

# 测试网络连通性
curl http://192.168.1.100:1234/api/v1/server/info -H "Authorization: Bearer your-password"

如果返回服务器信息 JSON，说明网络和认证都没问题。否则检查防火墙设置和密码是否正确。

Mac 休眠导致断连

作为服务器的 Mac 不能进入休眠状态。在系统设置中关闭自动休眠：

系统设置 → 节能 → 防止自动进入休眠

对于 Mac mini，建议接上显示器或使用 HDMI 欺骗器，避免系统因无显示器而降低性能。

BlueBubbles 更新后连接异常

BlueBubbles 更新可能会更改 API 行为。遇到此情况时，确保 OpenClaw 也更新到最新版本：

openclaw update
openclaw restart

总结

BlueBubbles 是 OpenClaw 官方推荐的 iMessage 连接方案，完全取代了已弃用的旧版 AppleScript 集成。它通过 REST API 和 WebSocket 提供稳定、功能完整的 iMessage 接入体验。关键要点：

• 务必迁移：旧版 iMessage 集成已弃用，未来版本可能移除
• 架构灵活：OpenClaw 和 BlueBubbles 服务器可以分开部署
• 功能完整：支持图片、附件、Tapback、已读回执等完整特性
• 设置白名单：和所有频道一样，建议配置联系人白名单保护隐私和 API 额度
• Mac 常开：确保运行 BlueBubbles 的 Mac 不会休眠或关机