BlueBubbles (iMessage)

状态：作为内置插件，通过 HTTP 与 BlueBubbles macOS 服务器通信。由于其更丰富的 API 和比传统 imsg 通道更简单的设置，推荐用于 iMessage 集成。

概览

通过 BlueBubbles 辅助应用程序 (bluebubbles.app) 在 macOS 上运行。
推荐/已测试：macOS Sequoia (15)。macOS Tahoe (26) 可以工作；但在 Tahoe 上编辑功能目前已损坏，群组图标更新可能会报告成功但无法同步。
OpenClaw 通过其 REST API (GET /api/v1/ping, POST /message/text, POST /chat/:id/*) 与之通信。
传入的消息通过 webhook 到达；发出的回复、正在输入指示器、已读回执和点按回应（tapbacks）则是 REST 调用。
附件和贴纸作为入站媒体被摄取（并在可能的情况下呈现给 Agent）。
配对/白名单与其他通道的工作方式相同（/start/pairing 等），配合 channels.bluebubbles.allowFrom + 配对码。
回应（Reactions）像 Slack/Telegram 一样作为系统事件呈现，因此 Agent 可以在回复之前“感知”到它们。
高级功能：编辑、撤回、回复线程、消息特效、群组管理。

快速开始

在你的 Mac 上安装 BlueBubbles 服务器（按照 bluebubbles.app/install 上的说明操作）。
在 BlueBubbles 配置中，启用 Web API 并设置密码。

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

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

将 BlueBubbles webhook 指向你的网关（例如：https://your-gateway-host:3000/bluebubbles-webhook?password=<password>）。
启动网关；它将注册 webhook 处理程序并开始配对。

引导设置 (Onboarding)

BlueBubbles 可在交互式设置向导中使用：

openclaw onboard

向导会提示输入：

Server URL (必填): BlueBubbles 服务器地址 (例如 http://192.168.1.100:1234)
Password (必填): BlueBubbles 服务器设置中的 API 密码
Webhook path (可选): 默认为 /bluebubbles-webhook
DM policy: pairing (配对), allowlist (白名单), open (开放), 或 disabled (禁用)
Allow list: 电话号码、电子邮件或聊天目标

你也可以通过 CLI 添加 BlueBubbles：

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

访问控制 (私聊 + 群组)

私聊 (DMs):

默认：channels.bluebubbles.dmPolicy = "pairing".
未知发送者会收到一个配对码；消息会被忽略直到获得批准（代码在 1 小时后过期）。
批准方式：
- openclaw pairing list bluebubbles
- openclaw pairing approve bluebubbles <CODE>
配对是默认的令牌交换方式。详情：配对 (Pairing)

群组 (Groups):

channels.bluebubbles.groupPolicy = open | allowlist | disabled (默认: allowlist).
当设置为 allowlist 时，channels.bluebubbles.groupAllowFrom 控制谁可以在群组中触发。

提及门控 (群组)

BlueBubbles 支持群聊的提及门控 (Mention Gating)，匹配 iMessage/WhatsApp 的行为：

使用 agents.list[].groupChat.mentionPatterns (或 messages.groupChat.mentionPatterns) 来检测提及。
当群组启用了 requireMention 时，Agent 仅在被提及时才会响应。
来自授权发送者的控制命令可以绕过提及门控。

每个群组的配置：

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

命令门控 (Command gating)

控制命令（例如 /config, /model）需要授权。
使用 allowFrom 和 groupAllowFrom 来确定命令授权。
授权的发送者即使在群组中未提及也可以运行控制命令。

正在输入 + 已读回执

正在输入指示器：在响应生成之前和期间自动发送。
已读回执：由 channels.bluebubbles.sendReadReceipts 控制 (默认: true)。
正在输入指示器：OpenClaw 发送开始输入事件；BlueBubbles 会在发送或超时时自动清除输入状态（通过 DELETE 手动停止是不可靠的）。

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

高级操作

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

{
  channels: {
    bluebubbles: {
      actions: {
        reactions: true,       // 点按回应 (默认: true)
        edit: true,            // 编辑已发送消息 (macOS 13+, 在 macOS 26 Tahoe 上已损坏)
        unsend: true,          // 撤回消息 (macOS 13+)
        reply: true,           // 通过消息 GUID 进行回复线程
        sendWithEffect: true,  // 消息特效 (slam, loud, etc.)
        renameGroup: true,     // 重命名群聊
        setGroupIcon: true,    // 设置群聊图标/照片 (在 macOS 26 Tahoe 上不稳定)
        addParticipant: true,  // 添加参与者到群组
        removeParticipant: true, // 从群组移除参与者
        leaveGroup: true,      // 离开群聊
        sendAttachment: true   // 发送附件/媒体
      }
    }
  }
}

可用操作：

react: 添加/移除点按回应 (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 上不稳定（API 可能返回成功但图标未同步）。
addParticipant: 添加某人到群组 (chatGuid, address)
removeParticipant: 从群组移除某人 (chatGuid, address)
leaveGroup: 离开群聊 (chatGuid)
sendAttachment: 发送媒体/文件 (to, buffer, filename, asVoice)
- 语音备忘录：设置 asVoice: true 并使用 MP3 或 CAF 音频作为 iMessage 语音消息发送。发送语音备忘录时，BlueBubbles 会将 MP3 转换为 CAF。

消息 ID (短 ID vs 全 ID)

OpenClaw 可能会显示短消息 ID（例如 1, 2）以节省 Token。

MessageSid / ReplyToId 可以是短 ID。
MessageSidFull / ReplyToIdFull 包含提供商的全 ID。
短 ID 存储在内存中；它们可能会在重启或缓存清理时过期。
操作接受短 ID 或全 ID 的 messageId，但如果短 ID 不再可用，将会报错。

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

模板: {{MessageSidFull}}, {{ReplyToIdFull}}
上下文: 入站负载中的 MessageSidFull / ReplyToIdFull

参见配置 (Configuration) 了解模板变量。

块流式传输 (Block streaming)

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

{
  channels: {
    bluebubbles: {
      blockStreaming: true  // 启用块流式传输 (默认行为)
    }
  }
}

媒体 + 限制

入站附件会被下载并存储在媒体缓存中。
媒体上限通过 channels.bluebubbles.mediaMaxMb 设置 (默认: 8 MB)。
出站文本被分块为 channels.bluebubbles.textChunkLimit (默认: 4000 字符)。

配置参考

完整配置：配置 (Configuration)

提供商选项：

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: 私聊白名单 (句柄, 电子邮件, E.164 号码, chat_id:*, chat_guid:*)。
channels.bluebubbles.groupPolicy: open | allowlist | disabled (默认: allowlist)。
channels.bluebubbles.groupAllowFrom: 群组发送者白名单。
channels.bluebubbles.groups: 每个群组的配置 (requireMention 等)。
channels.bluebubbles.sendReadReceipts: 发送已读回执 (默认: true)。
channels.bluebubbles.blockStreaming: 启用块流式传输 (默认: true)。
channels.bluebubbles.textChunkLimit: 出站块大小（字符数）(默认: 4000)。
channels.bluebubbles.chunkMode: length (默认) 仅在超过 textChunkLimit 时拆分；newline 在长度分块之前先在空行（段落边界）拆分。
channels.bluebubbles.mediaMaxMb: 入站媒体上限 MB (默认: 8)。
channels.bluebubbles.historyLimit: 上下文的最大群组消息数 (0 禁用)。
channels.bluebubbles.dmHistoryLimit: 私聊历史记录限制。
channels.bluebubbles.actions: 启用/禁用特定操作。
channels.bluebubbles.accounts: 多账户配置。

寻址 / 投递目标

优先使用 chat_guid 进行稳定的路由：

chat_guid:iMessage;-;+15555550123 (群组首选)
chat_id:123
chat_identifier:...
直接句柄：+15555550123, user@example.com
- 如果直接句柄没有现有的私聊，OpenClaw 将通过 POST /api/v1/chat/new 创建一个。这需要启用 BlueBubbles 私有 API。

安全性

Webhook 请求通过比较 guid/password 查询参数或标头与 channels.bluebubbles.password 进行验证。来自 localhost 的请求也被接受。
对 API 密码和 webhook 端点保密（像对待凭据一样对待它们）。
Localhost 信任意味着同一主机上的反向代理可能会无意中绕过密码。如果你代理网关，请在代理处要求验证并配置 gateway.trustedProxies。参见网关安全性。
如果将 BlueBubbles 服务器暴露在局域网之外，请启用 HTTPS + 防火墙规则。

故障排除

如果正在输入/已读事件停止工作，请检查 BlueBubbles webhook 日志并验证网关路径是否与 channels.bluebubbles.webhookPath 匹配。
配对码一小时后过期；使用 openclaw pairing list bluebubbles 和 openclaw pairing approve bluebubbles <code>。
回应 (Reactions) 需要 BlueBubbles 私有 API (POST /api/v1/message/react)；确保服务器版本暴露了它。
编辑/撤回需要 macOS 13+ 和兼容的 BlueBubbles 服务器版本。在 macOS 26 (Tahoe) 上，由于私有 API 更改，编辑目前已损坏。
群组图标更新在 macOS 26 (Tahoe) 上可能不稳定：API 可能返回成功，但新图标未同步。
OpenClaw 根据 BlueBubbles 服务器的 macOS 版本自动隐藏已知的损坏操作。如果编辑仍然出现在 macOS 26 (Tahoe) 上，请使用 channels.bluebubbles.actions.edit=false 手动禁用它。
获取状态/健康信息：openclaw status --all 或 openclaw status --deep。

有关一般通道工作流程参考，请参见通道 (Channels) 和插件 (Plugins) 指南。