BlueBubbles 是目前推荐的 OpenClaw iMessage 集成方案。在 macOS 上安装 BlueBubbles 辅助 App，配置 REST API + Webhook，即可让龙虾通过 iMessage 收发消息、发打字提示、处理 Tapback 回应、管理群组。本文覆盖快速上手、访问控制、ACP 会话绑定、高级动作和故障排查。

BlueBubbles (macOS REST)

状态：内置插件，通过 BlueBubbles macOS 服务端 HTTP 接口通信。推荐用于 iMessage 集成，比传统 imsg 渠道 API 更丰富、配置更简单。

内置插件

当前 OpenClaw 发行版已内置 BlueBubbles 插件，正常安装包无需额外执行 openclaw plugins install。

功能概览

运行在 macOS 上，依赖 BlueBubbles 辅助应用（bluebubbles.app）
推荐/测试系统：macOS Sequoia (15)；macOS Tahoe (26) 可用，但编辑消息功能当前在 Tahoe 上已损坏，群组图标更新可能报告成功但实际不同步
OpenClaw 通过 REST API 与其通信：GET /api/v1/ping、POST /message/text、POST /chat/:id/*
收到消息通过 Webhook；回复、打字状态、已读回执和 Tapback 通过 REST 调用
附件和贴纸作为入站媒体处理（尽可能传递给 Agent）
配对/白名单与其他渠道相同（/openclaw/channels/pairing 等），使用 channels.bluebubbles.allowFrom + 配对码
回应（Reactions）作为系统事件暴露，就像 Slack/Telegram 一样，Agent 可以在回复前"感知"它们
高级功能：编辑消息、撤回、回复线程、消息特效、群组管理

快速开始

在 Mac 上安装 BlueBubbles 服务端（参考 bluebubbles.app/install 的说明）
在 BlueBubbles 配置中启用 Web API 并设置密码

运行 openclaw onboard 选择 BlueBubbles，或手动配置：

json5

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

在 BlueBubbles 中将 Webhook 指向你的 Gateway（示例：https://your-gateway-host:3000/bluebubbles-webhook?password=<password>）
启动 Gateway，它会自动注册 Webhook 处理器并开始配对

安全说明：

务必设置 Webhook 密码
Webhook 认证始终必须。OpenClaw 会拒绝不含与 channels.bluebubbles.password 匹配的密码/guid 的请求（无论是 ?password=<password> 还是 x-password 头），即使是本地环回/代理拓扑也不例外
密码认证在读取/解析完整 Webhook 请求体之前进行

保持 Messages.app 活跃（虚拟机 / 无头设置）

某些 macOS VM 或常驻设置可能导致 Messages.app 进入"空闲"状态（直到打开/前台化之前不再收到入站事件）。简单解决方法是每 5 分钟"戳一下" Messages，使用 AppleScript + LaunchAgent。

1) 保存 AppleScript

保存为：~/Scripts/poke-messages.scpt

applescript

try
  tell application "Messages"
    if not running then
      launch
    end if

    -- 触摸脚本接口以保持进程响应
    set _chatCount to (count of chats)
  end tell
on error
  -- 忽略偶发错误（首次运行提示、锁定会话等）
end try

2) 安装 LaunchAgent

保存为：~/Library/LaunchAgents/com.user.poke-messages.plist

xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>Label</key>
    <string>com.user.poke-messages</string>

    <key>ProgramArguments</key>
    <array>
      <string>/bin/bash</string>
      <string>-lc</string>
      <string>/usr/bin/osascript &quot;$HOME/Scripts/poke-messages.scpt&quot;</string>
    </array>

    <key>RunAtLoad</key>
    <true/>

    <key>StartInterval</key>
    <integer>300</integer>

    <key>StandardOutPath</key>
    <string>/tmp/poke-messages.log</string>
    <key>StandardErrorPath</key>
    <string>/tmp/poke-messages.err</string>
  </dict>
</plist>

注意：

每 300 秒运行一次，并在登录时运行
首次运行可能触发 macOS 自动化权限提示（osascript → Messages），需在运行 LaunchAgent 的同一用户会话中批准

加载：

bash

launchctl unload ~/Library/LaunchAgents/com.user.poke-messages.plist 2>/dev/null || true
launchctl load ~/Library/LaunchAgents/com.user.poke-messages.plist

引导向导

BlueBubbles 在交互式引导向导中可用：

openclaw onboard

向导会询问：

服务器 URL（必填）：BlueBubbles 服务器地址（如 http://192.168.1.100:1234）
密码（必填）：BlueBubbles 服务器设置中的 API 密码
Webhook 路径（可选）：默认为 /bluebubbles-webhook
私信策略：配对、白名单、开放或禁用
白名单：电话号码、邮箱或聊天目标

也可通过 CLI 添加 BlueBubbles：

openclaw channels add bluebubbles --http-url http://192.168.1.100:1234 --password <password>

访问控制（私信 + 群组）

私信：

默认：channels.bluebubbles.dmPolicy = "pairing"
未知发件人会收到配对码；在批准前消息被忽略（码 1 小时后过期）
通过以下方式批准：
- openclaw pairing list bluebubbles
- openclaw pairing approve bluebubbles <CODE>
配对是默认的令牌交换方式。详情见配对

群组：

channels.bluebubbles.groupPolicy = open | allowlist | disabled（默认：allowlist）
channels.bluebubbles.groupAllowFrom 在 allowlist 模式下控制谁可以在群组中触发

联系人姓名增强（macOS，可选）

BlueBubbles 群组 Webhook 通常只包含原始参与者地址。如果你想让 GroupMembers 上下文显示本地联系人姓名而非原始地址，可以在 macOS 上启用本地通讯录增强：

channels.bluebubbles.enrichGroupParticipantsFromContacts = true 启用查找，默认 false
仅在群组访问、命令授权和提及门控通过后才执行查找
只增强未命名的电话参与者
找不到本地匹配时，仍以原始电话号码兜底

json5

{
  channels: {
    bluebubbles: {
      enrichGroupParticipantsFromContacts: true,
    },
  },
}

提及门控（群组）

BlueBubbles 支持群聊提及门控，与 iMessage/WhatsApp 行为一致：

使用 agents.list[].groupChat.mentionPatterns（或 messages.groupChat.mentionPatterns）检测提及
当群组启用 requireMention 时，Agent 只在被提及时才响应
授权发件人的控制命令可绕过提及门控

每群组配置：

json5

{
  channels: {
    bluebubbles: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15555550123"],
      groups: {
        "*": { requireMention: true }, // 所有群组的默认设置
        "iMessage;-;chat123": { requireMention: false }, // 特定群组覆盖
      },
    },
  },
}

命令门控

控制命令（如 /config、/model）需要授权
使用 allowFrom 和 groupAllowFrom 决定命令授权
授权发件人可以在群组中不提及的情况下运行控制命令

ACP 会话绑定

BlueBubbles 聊天可以在不改变传输层的情况下变成持久 ACP 工作区。

快速操作流程：

在 DM 或允许的群聊中运行 /acp spawn codex --bind here
该 BlueBubbles 对话中的后续消息会路由到已创建的 ACP 会话
/new 和 /reset 就地重置同一绑定的 ACP 会话
/acp close 关闭 ACP 会话并移除绑定

也支持通过顶层 bindings[] 条目配置持久绑定，设置 type: "acp" 和 match.channel: "bluebubbles"。

match.peer.id 可以使用任意支持的 BlueBubbles 目标形式：

标准化的 DM 句柄，如 +15555550123 或 user@example.com
chat_id:<id>
chat_guid:<guid>
chat_identifier:<identifier>

对于稳定的群组绑定，优先使用 chat_id:* 或 chat_identifier:*。

示例：

json5

{
  agents: {
    list: [
      {
        id: "codex",
        runtime: {
          type: "acp",
          acp: { agent: "codex", backend: "acpx", mode: "persistent" },
        },
      },
    ],
  },
  bindings: [
    {
      type: "acp",
      agentId: "codex",
      match: {
        channel: "bluebubbles",
        accountId: "default",
        peer: { kind: "dm", id: "+15555550123" },
      },
      acp: { label: "codex-imessage" },
    },
  ],
}

详见 ACP Agents。

打字状态 + 已读回执

打字状态：在生成响应前和期间自动发送
已读回执：由 channels.bluebubbles.sendReadReceipts 控制（默认：true）
OpenClaw 发送打字开始事件；BlueBubbles 在发送或超时时自动清除打字状态

json5

{
  channels: {
    bluebubbles: {
      sendReadReceipts: false, // 禁用已读回执
    },
  },
}

高级操作

BlueBubbles 在配置中启用后支持高级消息操作：

json5

{
  channels: {
    bluebubbles: {
      actions: {
        reactions: true,       // Tapback 回应（默认：true）
        edit: true,            // 编辑已发送消息（macOS 13+，在 macOS 26 Tahoe 上已损坏）
        unsend: true,          // 撤回消息（macOS 13+）
        reply: true,           // 通过消息 GUID 进行回复线程
        sendWithEffect: true,  // 消息特效（重击、大声等）
        renameGroup: true,     // 重命名群聊
        setGroupIcon: true,    // 设置群聊图标/头像（在 macOS 26 Tahoe 上不稳定）
        addParticipant: true,  // 向群组添加参与者
        removeParticipant: true, // 从群组移除参与者
        leaveGroup: true,      // 离开群聊
        sendAttachment: true,  // 发送附件/媒体
      },
    },
  },
}

可用操作：

react：添加/移除 Tapback 回应（messageId、emoji、remove）
edit：编辑已发送消息（messageId、text）
unsend：撤回消息（messageId）
reply：回复特定消息（messageId、text、to）
sendWithEffect：用 iMessage 特效发送（text、to、effectId）
renameGroup：重命名群聊（chatGuid、displayName）
setGroupIcon：设置群聊图标（chatGuid、media）——在 macOS 26 Tahoe 上不稳定
addParticipant：向群组添加成员（chatGuid、address）
removeParticipant：从群组移除成员（chatGuid、address）
leaveGroup：离开群聊（chatGuid）
upload-file：发送媒体/文件（to、buffer、filename、asVoice）
- 语音备忘录：设置 asVoice: true 并使用 MP3 或 CAF 音频以发送 iMessage 语音消息；BlueBubbles 发送语音备忘录时会将 MP3 转换为 CAF
旧别名：sendAttachment 仍然可用，但 upload-file 是规范操作名

消息 ID（短 vs 完整）

OpenClaw 可能会显示短消息 ID（如 1、2）以节省 token。

MessageSid / ReplyToId 可以是短 ID
MessageSidFull / ReplyToIdFull 包含完整的提供商 ID
短 ID 在内存中；重启或缓存清除后可能失效
操作接受短或完整 messageId，但短 ID 如果不再可用会报错

对于持久自动化和存储，请使用完整 ID：

模板：、
上下文：入站 payload 中的 MessageSidFull / ReplyToIdFull

详见配置中的模板变量。

块流式传输

控制响应是作为单条消息发送还是分块流式传输：

json5

{
  channels: {
    bluebubbles: {
      blockStreaming: true, // 启用块流式传输（默认关闭）
    },
  },
}

媒体 + 限制

入站附件下载并存储在媒体缓存中
通过 channels.bluebubbles.mediaMaxMb 限制入站和出站媒体大小（默认：8 MB）
出站文本按 channels.bluebubbles.textChunkLimit 分块（默认：4000 字符）

配置参考

完整配置：配置

提供商选项：

channels.bluebubbles.enabled：启用/禁用渠道
channels.bluebubbles.serverUrl：BlueBubbles REST API 基础 URL
channels.bluebubbles.password：API 密码
channels.bluebubbles.webhookPath：Webhook 端点路径（默认：/bluebubbles-webhook）
channels.bluebubbles.dmPolicy：pairing | allowlist | open | disabled（默认：pairing）
channels.bluebubbles.allowFrom：DM 白名单（句柄、邮箱、E.164 号码、chat_id:*、chat_guid:*）
channels.bluebubbles.groupPolicy：open | allowlist | disabled（默认：allowlist）
channels.bluebubbles.groupAllowFrom：群组发件人白名单
channels.bluebubbles.enrichGroupParticipantsFromContacts：在 macOS 上，门控通过后可选增强未命名群组参与者的本地联系人，默认 false
channels.bluebubbles.groups：每群组配置（requireMention 等）
channels.bluebubbles.sendReadReceipts：发送已读回执（默认：true）
channels.bluebubbles.blockStreaming：启用块流式传输（默认：false）
channels.bluebubbles.textChunkLimit：出站块大小（字符，默认：4000）
channels.bluebubbles.chunkMode：length（默认）仅在超过 textChunkLimit 时分割；newline 在长度分块前按空行（段落边界）分割
channels.bluebubbles.mediaMaxMb：入站/出站媒体上限（MB，默认：8）
channels.bluebubbles.mediaLocalRoots：出站本地媒体路径的绝对本地目录白名单；默认情况下拒绝本地路径发送，除非配置了此项
channels.bluebubbles.historyLimit：上下文的最大群组消息数（0 禁用）
channels.bluebubbles.dmHistoryLimit：DM 历史限制
channels.bluebubbles.actions：启用/禁用特定操作
channels.bluebubbles.accounts：多账号配置

寻址 / 投递目标

优先使用 chat_guid 以实现稳定路由：

chat_guid:iMessage;-;+15555550123（推荐用于群组）
chat_id:123
chat_identifier:...
直接句柄：+15555550123、user@example.com
- 如果直接句柄没有现有的 DM 聊天，OpenClaw 会通过 POST /api/v1/chat/new 创建一个。这需要启用 BlueBubbles Private API。

安全

Webhook 请求通过比较 guid/password 查询参数或头部与 channels.bluebubbles.password 进行验证
保持 API 密码和 Webhook 端点的保密性（像凭据一样对待）
BlueBubbles Webhook 认证没有本地回环绕过。如果你代理 Webhook 流量，请在请求全程保留 BlueBubbles 密码。gateway.trustedProxies 不替代此处的 channels.bluebubbles.password。详见 Gateway 安全
如果将 BlueBubbles 服务器暴露到局域网外，请启用 HTTPS + 防火墙规则

故障排查

如果打字/已读事件停止工作，检查 BlueBubbles Webhook 日志并验证 Gateway 路径是否与 channels.bluebubbles.webhookPath 一致
配对码 1 小时后过期；使用 openclaw pairing list bluebubbles 和 openclaw pairing approve bluebubbles <code>
回应需要 BlueBubbles private API（POST /api/v1/message/react）；确保服务器版本支持该接口
编辑/撤回需要 macOS 13+ 和兼容的 BlueBubbles 服务器版本。在 macOS 26 (Tahoe) 上，编辑功能由于 private API 变更目前已损坏
群组图标更新在 macOS 26 (Tahoe) 上可能不稳定：API 可能返回成功但新图标不同步
OpenClaw 根据 BlueBubbles 服务器的 macOS 版本自动隐藏已知损坏的操作。如果编辑仍出现在 macOS 26 (Tahoe) 上，手动禁用：channels.bluebubbles.actions.edit=false
状态/健康信息：openclaw status --all 或 openclaw status --deep

更多渠道工作流参考，见渠道和插件指南。

常见问题

Q: BlueBubbles 和 imsg 有什么区别，我该选哪个？

A: BlueBubbles 是目前推荐方案，功能更丰富（支持编辑、撤回、Tapback 回应、群组图标等），配置也更简单（REST API，无需特殊权限）。imsg 是旧版方案，可能在未来移除。新部署直接用 BlueBubbles。

Q: macOS 26 Tahoe 上 edit 功能失效了，怎么办？

A: macOS 26 Tahoe 修改了私有 API 导致 edit 功能暂时失效。可以手动禁用：channels.bluebubbles.actions.edit = false，避免触发报错。等待 BlueBubbles 适配新 API 后恢复。

Q: 群组消息中龙虾不回复，但私信正常？

A: 检查 groupPolicy（是否为 disabled）和 requireMention（是否需要 @提及）。默认配置下群组需要 @提及龙虾才会回复，通过 channels.bluebubbles.groups."*".requireMention = false 可关闭。

BlueBubbles (macOS REST) ​

内置插件 ​

功能概览 ​

快速开始 ​

保持 Messages.app 活跃（虚拟机 / 无头设置） ​

1) 保存 AppleScript ​

2) 安装 LaunchAgent ​

引导向导 ​

访问控制（私信 + 群组） ​

联系人姓名增强（macOS，可选） ​

提及门控（群组） ​

命令门控 ​

ACP 会话绑定 ​

打字状态 + 已读回执 ​

高级操作 ​

消息 ID（短 vs 完整） ​

块流式传输 ​

媒体 + 限制 ​

配置参考 ​

寻址 / 投递目标 ​

安全 ​

故障排查 ​

常见问题 ​

相关链接 ​

BlueBubbles (macOS REST)

内置插件

功能概览

快速开始

保持 Messages.app 活跃（虚拟机 / 无头设置）

1) 保存 AppleScript

2) 安装 LaunchAgent

引导向导

访问控制（私信 + 群组）

联系人姓名增强（macOS，可选）

提及门控（群组）

命令门控

ACP 会话绑定

打字状态 + 已读回执

高级操作

消息 ID（短 vs 完整）

块流式传输

媒体 + 限制

配置参考

寻址 / 投递目标

安全

故障排查

常见问题

相关链接