OpenClaw 接入 BlueBubbles：iMessage 现代化接入方案完整配置

BlueBubbles 是 OpenClaw 推荐的 iMessage 接入方案，通过 macOS 上的 REST API 服务器提供更丰富的功能，取代了遗留的 imsg 集成。

BlueBubbles 的优势#

相比遗留的 imsg 集成：

• 支持编辑消息、撤回消息
• 支持回复线程
• 支持消息特效
• 支持群组管理（改名、更换图标）
• 支持 Tapback 反应
• 支持打字指示和已读回执
• 更稳定的 REST API，无需 JSON-RPC 通信

前置条件#

• macOS 设备（Sequoia 15 已验证，Tahoe 26 可用但部分功能受限）
• 已登录 iMessage 的 Apple ID
• BlueBubbles macOS 服务器应用（bluebubbles.app）

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

1. 访问 bluebubbles.app/install 下载并安装
2. 在 BlueBubbles 设置中：
   • 启用 Web API
   • 设置 API 密码（务必设置！）
   • 记录服务器 URL（通常是 http://192.168.1.x:1234）

第二步：配置 OpenClaw#

{
  "channels": {
    "bluebubbles": {
      "enabled": true,
      "serverUrl": "http://192.168.1.100:1234",
      "password": "your-password",
      "webhookPath": "/bluebubbles-webhook"
    }
  }
}

也可以运行向导：

openclaw onboard  # 选择 BlueBubbles

第三步：配置 BlueBubbles Webhook#

在 BlueBubbles 服务器设置中，将 Webhook URL 指向 OpenClaw Gateway：

安全说明：始终设置 webhook password，OpenClaw 会强制验证所有 Webhook 请求中的密码。

第四步：启动并配对#

openclaw gateway
openclaw pairing list bluebubbles
openclaw pairing approve bluebubbles CODE

访问控制配置#

DM 访问#

{
  "channels": {
    "bluebubbles": {
      "dmPolicy": "pairing",
      "allowFrom": ["+8613800138000", "someone@example.com"]
    }
  }
}

allowFrom 接受手机号（E.164 格式）或 Apple ID 邮箱。

群组访问#

{
  "channels": {
    "bluebubbles": {
      "groupPolicy": "allowlist",
      "groupAllowFrom": ["+8613800138000"]
    }
  }
}

@提及限制#

{
  "channels": {
    "bluebubbles": {
      "groups": {
        "*": { "requireMention": true }
      }
    }
  }
}

高级功能#

打字指示和已读回执#

{
  "channels": {
    "bluebubbles": {
      "typingIndicators": true,
      "readReceipts": true
    }
  }
}

流式消息分块#

{
  "channels": {
    "bluebubbles": {
      "streaming": {
        "blockStreaming": false,
        "chunkMinBytes": 100
      }
    }
  }
}

保持 Messages.app 活跃（VM/无头服务器）#

在 VM 或无头 macOS 服务器上，Messages.app 可能进入「空闲」状态导致消息停止接收。用 AppleScript + LaunchAgent 每 5 分钟触碰一次：

第一步：创建 ~/Scripts/poke-messages.scpt：

try
  tell application "Messages"
    if not running then
      launch
    end if
    set _chatCount to (count of chats)
  end tell
on error
end try

第二步：创建 LaunchAgent ~/Library/LaunchAgents/com.user.poke-messages.plist 设置每 5 分钟（300 秒）运行一次上面的脚本。

常见问题#

Webhook 收不到消息？ 检查密码是否正确，URL 中的 ?password= 参数要与 OpenClaw 配置中的 password 一致。

macOS Tahoe 上编辑消息无效？ 这是已知问题，BlueBubbles 在 Tahoe 上部分功能受限，团队正在修复中。

群组图标更新不生效？ 在 Tahoe 上 API 调用返回成功，但图标可能不同步——这是 Tahoe 的兼容性问题。

原文：BlueBubbles - OpenClaw | 来源：OpenClaw 官方文档