OpenClaw

OpenClaw BlueBubbles 渠道

即时通讯
中等

通过 BlueBubbles REST API 将 OpenClaw 连接到 iMessage。此集成将您的 Mac 变为 iMessage 网关——安装 BlueBubbles 服务端应用，启用 Web API，您的 AI 助手即可收发 iMessage 消息、tapback 表情回应和媒体附件。BlueBubbles 是推荐的 iMessage 渠道，取代了旧版 imsg CLI 方案。

快速信息
难度中等
分类即时通讯
支持功能数4 / 6

BlueBubbles 支持的功能

文本消息

支持

媒体与文件

支持

消息反应

支持

消息线程

不支持

语音消息

不支持

群聊

支持

BlueBubbles 前置条件

  • 运行 macOS High Sierra (10.13) 或更高版本的 Mac（推荐 Ventura 13+ 以获得完整功能；Tahoe 26 有部分限制）
  • 已安装 BlueBubbles 服务端应用（从 bluebubbles.app 下载）
  • 在 BlueBubbles 配置中启用 Web API 并设置密码
  • OpenClaw Gateway 已运行并配置

BlueBubbles 快速设置

1

在 Mac 上安装 BlueBubbles 服务端

从 bluebubbles.app/install 下载并安装 BlueBubbles 服务端应用。启动应用，使用 Apple ID 登录，并完成初始设置。确保 iMessage 在该 Mac 上正常工作。

2

启用 Web API

在 BlueBubbles 服务端设置中，启用 Web/REST API 并设置一个强密码。记下服务器 URL（例如 http://localhost:1234）——您将在 OpenClaw 配置中使用它。

3

添加 BlueBubbles 渠道配置

运行 'openclaw onboard' 并选择 BlueBubbles，或手动将渠道配置添加到 ~/.openclaw/openclaw.json，填入 serverUrl 和 password。如需要可配置 webhookPath。

4

配置 Webhook 并测试

将 BlueBubbles Webhook 指向您的 Gateway：https://your-gateway-host:3000/bluebubbles-webhook?password=<password>。启动 Gateway 并发送一条测试 iMessage 以验证连接。如使用 pairing 策略，通过 'openclaw pairing approve bluebubbles <code>' 审批发送者。

BlueBubbles 配置示例

config.json
{
  "channels": {
    "bluebubbles": {
      "enabled": true,
      "serverUrl": "http://localhost:1234",
      "password": "YOUR_BLUEBUBBLES_PASSWORD",
      "webhookPath": "/bluebubbles-webhook",
      "dmPolicy": "pairing"
    }
  }
}

BlueBubbles 深入了解

架构概览

OpenClaw 通过运行在 Mac 上的 BlueBubbles 服务端应用连接 iMessage。BlueBubbles 暴露 REST API，Gateway 通过该 API 发送消息、表情回应和管理聊天。传入消息通过 Webhook 投递——BlueBubbles 将新消息事件推送到 Gateway 的 Webhook 端点。 架构流程为：iMessage 到达 Mac → BlueBubbles 服务端 → Webhook 推送到 Gateway → OpenClaw 使用 AI 处理 → REST API 回调 BlueBubbles → iMessage 发送。 此方案需要一台保持在线的 Mac（物理机或虚拟机），因为 iMessage 是 Apple 专有服务。Mac 充当 Apple 消息生态和 OpenClaw 助手之间的桥梁。
专用的 Mac Mini 或 macOS 虚拟机是运行 BlueBubbles 作为持久 iMessage 网关的理想选择。
BlueBubbles 支持 Private API 以实现高级功能（如 tapback 表情回应、消息编辑和撤回）——请确保在 BlueBubbles 设置中启用。

BlueBubbles 服务端设置

设置 BlueBubbles 需要在 Mac 上安装服务端应用： 1. 从 bluebubbles.app/install 下载 BlueBubbles 并启动应用。 2. 使用 Apple ID 登录，确保 iMessage 在该 Mac 上正常工作。 3. 在 BlueBubbles 设置中启用 Web/REST API。 4. 设置一个强 API 密码——此密码用于验证所有 API 请求和 Webhook 投递。 5. 记下应用中显示的服务器 URL（默认：http://localhost:1234）。 6. 可选：启用 Private API 以获得高级功能（表情回应、编辑、撤回）。 服务端必须保持运行，iMessage 桥接才能工作。建议配置 BlueBubbles 开机自启以确保可靠性。
webhook URL
# Gateway 的 Webhook URL 格式
https://your-gateway-host:3000/bluebubbles-webhook?password=YOUR_PASSWORD
请妥善保管 BlueBubbles API 密码。如果在网络上暴露服务器，请在 BlueBubbles 上启用 HTTPS 并使用防火墙规则限制访问。同主机反向代理会绕过密码认证——需添加代理级别认证并配置 gateway.trustedProxies。

私聊策略

私聊（DM）策略控制谁可以通过 iMessage 与您的 AI 助手互动。OpenClaw 支持四种策略： • pairing（默认）——未知发送者会收到限时配对码（1 小时后过期）。通过 'openclaw pairing approve bluebubbles <CODE>' 审批或拒绝。审批后即可自由聊天。 • allowlist——仅 allowFrom 列表中的电话号码和邮箱地址可以发消息。其他人会被静默忽略。电话号码支持 E.164 格式。 • open——任何人发消息都会收到回复。请谨慎使用。 • disabled——完全关闭私聊处理。
openclaw.json
{
  "channels": {
    "bluebubbles": {
      "dmPolicy": "allowlist",
      "allowFrom": ["+15551234567", "user@example.com"]
    }
  }
}
allowFrom 字段同时接受电话号码（E.164 格式，如 +15551234567）和邮箱地址，用于 iMessage 路由。

群聊管理

OpenClaw 通过 BlueBubbles 支持 iMessage 群聊，提供灵活的访问控制： • groupPolicy 控制谁可以在群聊中触发机器人： - open——任何群成员都可以互动 - allowlist——仅 groupAllowFrom 列表中的地址可以触发 - disabled（默认）——忽略群消息 • 提及触发——当 requireMention 为 true（群聊默认）时，机器人仅在被提及时回复。提及模式在 agents.list[].groupChat.mentionPatterns 中配置。 • 按群配置——使用 groups 对象为特定群聊设置不同的 requireMention 规则。
openclaw.json
{
  "channels": {
    "bluebubbles": {
      "groupPolicy": "allowlist",
      "groupAllowFrom": ["+15551234567"],
      "groups": {
        "iMessage;+;chat123456": {
          "requireMention": false
        }
      }
    }
  }
}

iMessage 操作与特效

BlueBubbles 通过 Private API 暴露丰富的 iMessage 原生操作。每个操作可单独开关： • reactions——发送和接收 tapback 表情回应（喜爱、点赞、踩、大笑、强调、疑问） • edit——修改已发送消息（需 macOS 13+；macOS Tahoe 上目前不可用） • unsend——撤回已发送消息（macOS 13+） • reply——通过 GUID 引用消息实现会话线程 • sendWithEffect——发送带气泡特效的消息（猛击、响亮、温柔、隐形墨水等） • sendAttachment——发送媒体文件和语音备忘录（语音使用 MP3/CAF 格式；BlueBubbles 自动处理 MP3→CAF 转换） 群组管理操作： • renameGroup——重命名群聊 • setGroupIcon——设置群聊头像（macOS Tahoe 上不稳定） • addParticipant / removeParticipant / leaveGroup——管理群成员
openclaw.json
{
  "channels": {
    "bluebubbles": {
      "actions": {
        "reactions": true,
        "edit": true,
        "unsend": true,
        "reply": true,
        "sendWithEffect": true,
        "sendAttachment": true
      }
    }
  }
}
在 macOS Tahoe (26) 上，由于 Private API 变更，edit 操作目前不可用，setGroupIcon 不可靠（API 返回成功但图标不同步）。如果您运行的是 Tahoe，请手动禁用这些操作。

消息发送与分块

OpenClaw 为长 AI 回复提供可配置的分块发送： • textChunkLimit——每条消息块的最大字符数（默认：4000）。iMessage 没有严格限制，但过长的消息在某些设备上可能显示不佳。 • chunkMode——控制文本分割方式： - length（默认）——按 textChunkLimit 字符数硬分割 - newline——在段落边界分割，阅读更自然 • blockStreaming——为 true 时，回复在生成过程中以块方式发送，而非等待完整回复。 已读回执默认发送以保持自然的对话感。AI 回复生成前和生成过程中会自动发送输入指示器。
openclaw.json
{
  "channels": {
    "bluebubbles": {
      "textChunkLimit": 4000,
      "chunkMode": "newline",
      "blockStreaming": false,
      "sendReadReceipts": true
    }
  }
}

媒体与附件

BlueBubbles 支持通过 iMessage 收发媒体： • 传入附件由 Gateway 自动下载和缓存。最大传入文件大小由 mediaMaxMb 控制（默认：8 MB）。 • 可通过 sendAttachment 操作发送语音备忘录，设置 asVoice: true。BlueBubbles 会自动将 MP3 转换为 CAF 格式以实现原生 iMessage 语音备忘录播放。 • 通过 sendAttachment 操作发送外发媒体，需提供 buffer、filename 和可选的 mime 类型参数。
语音备忘录请使用 MP3 或 CAF 格式。BlueBubbles 会自动将 MP3 转换为 CAF 以实现原生 iMessage 播放。
如需处理更大的附件，可调整 mediaMaxMb——默认 8 MB 可覆盖大多数照片和短视频。

消息 ID 处理

BlueBubbles 使用两种消息标识符： • 短 ID——内存中的临时令牌（如 1, 2, 3），速度快但临时性。Gateway 重启或缓存清除后会过期。 • 完整 ID——持久化的提供者标识符（MessageSidFull, ReplyToIdFull），可在重启后保留，适合长期引用。 操作参数（messageId, replyTo 等）接受两种格式。对于需要跨重启引用消息的持久化自动化和集成，请始终使用完整 ID。
对于需要在 Gateway 重启后仍然有效的自动化，请使用完整消息 ID。短 ID 适合交互使用，但重启后会失效。

地址与路由

BlueBubbles 支持多种地址格式进行消息投递。按稳定性排序的首选路由顺序： 1. chat_guid——最稳定格式：chat_guid:iMessage;-;+15555550123 2. chat_id——数字聊天标识符：chat_id:123 3. chat_identifier——聊天标识符字符串 4. 直接地址——电话号码（+15555550123）或邮箱（user@example.com） 当向没有现有聊天的直接地址发送消息时，BlueBubbles 会通过 POST /api/v1/chat/new 自动创建新的私聊（需要 Private API）。
在自动化中使用 chat_guid 格式以获得最可靠的消息路由。

安全与 Webhook 认证

BlueBubbles 使用配置的密码对 Webhook 投递进行认证。Gateway 验证密码参数（通过查询字符串或请求头）是否与 channels.bluebubbles.password 配置匹配。 安全注意事项： • 本地请求（localhost）自动信任，跳过密码验证。 • 同主机反向代理也会绕过密码检查——如果使用同一机器上的反向代理，请添加代理级别认证并配置 gateway.trustedProxies。 • 在 BlueBubbles 服务端启用 HTTPS 以加密通信。 • 使用防火墙规则限制外部对 BlueBubbles API 端口的访问。 生产部署时，务必使用 HTTPS 并确保 Webhook 端点在无认证的情况下不可公开访问。
同主机反向代理会绕过 BlueBubbles 密码认证。使用反向代理时，请务必配置代理级别认证并设置 gateway.trustedProxies。

Messages.app 保活（无头模式/虚拟机）

如果在无头 Mac 或虚拟机上运行 BlueBubbles，Messages.app 可能会进入空闲状态并停止处理消息。解决方案是配置一个 LaunchAgent，每 5 分钟执行一次 AppleScript 来触发 Messages 脚本接口。 此保活脚本会安全地忽略临时性故障，不会抢占其他应用的焦点。它对于 iMessage 桥接的可靠无人值守运行至关重要。 设置一个 macOS LaunchAgent plist，定期运行 AppleScript 以保持 Messages.app 的响应性。
这仅在无头/虚拟机环境下需要。如果您的 Mac 有活跃的桌面会话且 Messages.app 可见，则无需保活。
使用 launchctl 管理 LaunchAgent——设置开机加载以实现完全无人值守运行。

BlueBubbles 配置参考

enabled
Type: booleanDefault: false

启用或禁用 BlueBubbles 渠道

serverUrl
Type: stringDefault: ""

BlueBubbles REST API 基础 URL（例如 http://localhost:1234）

password
Type: stringDefault: ""

用于认证的 BlueBubbles API 密码

webhookPath
Type: stringDefault: "/bluebubbles-webhook"

接收传入消息的 Webhook 端点路径

dmPolicy
Type: stringDefault: "pairing"

控制谁可以私聊机器人。选项：pairing, allowlist, open, disabled

allowFrom
Type: string[]Default: []

允许发消息的电话号码和邮箱（电话使用 E.164 格式）

groupPolicy
Type: stringDefault: "allowlist"

群聊策略。选项：open, allowlist, disabled

groupAllowFrom
Type: string[]Default: []

群聊中授权触发机器人的发送者地址

sendReadReceipts
Type: booleanDefault: true

处理消息时发送已读回执确认

blockStreaming
Type: booleanDefault: false

启用块式响应流，而非等待完整回复

textChunkLimit
Type: numberDefault: 4000

每条外发文本消息块的最大字符数

chunkMode
Type: stringDefault: "length"

文本分割模式。选项：length（按大小）, newline（按段落）

mediaMaxMb
Type: numberDefault: 8

传入附件的最大文件大小（MB）

historyLimit
Type: numberDefault: -

作为 AI 上下文的最大群消息数（0 为禁用）

dmHistoryLimit
Type: numberDefault: -

AI 上下文的私聊历史记录限制

actions.reactions
Type: booleanDefault: true

启用 tapback 表情回应（需要 Private API）

actions.edit
Type: booleanDefault: true

启用消息编辑（需要 macOS 13+；Tahoe 上不可用）

actions.unsend
Type: booleanDefault: true

启用消息撤回（需要 macOS 13+）

actions.reply
Type: booleanDefault: true

启用通过 GUID 的消息线程

actions.sendWithEffect
Type: booleanDefault: true

启用 iMessage 气泡特效（猛击、响亮、温柔等）

actions.sendAttachment
Type: booleanDefault: true

启用媒体和语音备忘录发送

BlueBubbles 常见问题

BlueBubbles 故障排查

Webhook 未收到消息

BlueBubbles 中的 Webhook URL 与 Gateway 端点不匹配，或密码参数不正确。

确认 Webhook URL 设置为 https://your-gateway-host:3000/bluebubbles-webhook?password=YOUR_PASSWORD。检查 channels.bluebubbles.webhookPath 是否与 URL 中的路径匹配。查看 Gateway 日志中的传入 Webhook 请求。
Gateway 已连接但操作失败（表情回应、编辑、撤回）

BlueBubbles Private API 未启用，或服务端版本不支持所需的 API 端点。

在 BlueBubbles 服务端设置中启用 Private API。将 BlueBubbles 更新到最新版本。如果特定操作在 macOS Tahoe 上失败，请单独禁用：channels.bluebubbles.actions.edit=false。
无头 Mac 上 Messages.app 停止响应

Messages.app 在无头/虚拟机环境下进入空闲状态，停止处理脚本接口。

设置 AppleScript 保活 LaunchAgent，每 5 分钟触发一次 Messages 脚本接口。确保 LaunchAgent 通过 launchctl 加载并在开机时运行。
机器人发送的消息不是 iMessage（绿色气泡）

接收方的电话号码或邮箱未注册 iMessage，或 Mac 上的 Apple ID 未启用 iMessage。

在 Mac 的 Messages.app 偏好设置中确认 iMessage 已启用。检查接收方是否使用启用了 iMessage 的 Apple 设备。绿色气泡表示 SMS 回退，BlueBubbles 可能不支持（取决于配置）。
macOS Tahoe 上编辑操作失败

已知问题——macOS Tahoe (26) 破坏了消息编辑的 Private API 端点。

禁用编辑操作：将 channels.bluebubbles.actions.edit 设为 false。这是 Tahoe 上的已知 BlueBubbles 限制。关注 BlueBubbles 更新以获取修复。
查看完整文档返回所有渠道

相关渠道

WhatsApp

Medium

OpenClaw 通过 Baileys 协议扫码连接

配置指南

Telegram

Easy

OpenClaw 通过 grammY 框架的 Bot API 集成

配置指南

Discord

Easy

OpenClaw 使用 discord.js 的 Bot Token 集成

配置指南