文档
渠道（Channels）
BlueBubbles（macOS REST）

BlueBubbles（macOS REST）

适用范围

在以下情况使用本页：

  • 设置 BlueBubbles 渠道
  • 排除 webhook 配对故障
  • 在 macOS 上配置 iMessage

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

概述

  • 通过 BlueBubbles 辅助应用（bluebubbles.app）在 macOS 上运行。
  • 推荐/测试：macOS Sequoia (15)。macOS Tahoe (26) 可用；在 Tahoe 上编辑目前损坏，群组图标更新可能报告成功但不同步。
  • Clawdbot 通过其 REST API 与之通信（GET /api/v1/ping、POST /message/text、POST /chat/:id/*）。
  • 入站消息通过 webhooks 到达；出站回复、输入指示器、已读回执和轻点都是 REST 调用。
  • 附件和贴纸作为入站媒体摄取（并尽可能向 agent 暴露）。
  • 配对/白名单的工作方式与其他渠道相同（/start/pairing 等），具有 channels.bluebubbles.allowFrom + 配对码。
  • 反应像 Slack/Telegram 一样作为系统事件暴露，以便 agent 可以在回复之前"提及"它们。
  • 高级功能：编辑、撤回、回复主题串、消息效果、群组管理。

快速开始

  1. 在您的 Mac 上安装 BlueBubbles 服务器（按照 bluebubbles.app/install 上的说明操作）。
  2. 在 BlueBubbles 配置中，启用 web API 并设置密码。
  3. 运行 clawdbot onboard 并选择 BlueBubbles，或手动配置：
    {
  channels: {
    bluebubbles: {
      enabled: true,
      serverUrl: "http://192.168.1.100:1234",
      password: "example-password",
      webhookPath: "/bluebubbles-webhook"
    }
  }
}
  4. 将 BlueBubbles webhooks 指向您的 gateway（例如：https://your-gateway-host:3000/bluebubbles-webhook?password=<password>）。
  5. 启动 gateway；它将注册 webhook 处理程序并开始配对。

入门配置

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

clawdbot onboard

向导提示输入：

  • 服务器 URL（必需）：BlueBubbles 服务器地址（例如，http://192.168.1.100:1234）
  • 密码（必需）：来自 BlueBubbles 服务器设置的 API 密码
  • Webhook 路径（可选）：默认为 /bluebubbles-webhook
  • 私信策略：配对、白名单、公开或禁用
  • 允许列表：电话号码、电子邮件或聊天目标

您也可以通过 CLI 添加 BlueBubbles：

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

访问控制（私信 + 群组）

私信：

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

群组：

  • channels.bluebubbles.groupPolicy = open | allowlist | disabled（默认：allowlist）。
  • channels.bluebubbles.groupAllowFrom 控制在设置 allowlist 时谁可以在群组中触发。

提及门控（群组）

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

  • 使用 agents.list[].groupChat.mentionPatterns（或 messages.groupChat.mentionPatterns）检测提及。
  • 当为群组启用 requireMention 时，agent 仅在被提及时响应。
  • 来自授权发送者的控制命令绕过提及门控。

每个群组配置：

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

命令门控

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

输入 + 已读回执

  • 输入指示器：在响应生成之前和期间自动发送。
  • 已读回执：由 channels.bluebubbles.sendReadReceipts 控制（默认：true）。
  • 输入指示器：Clawdbot 发送输入开始事件；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 等）
        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（短 vs 完整）

Clawdbot 可能会暴露短消息 ID（例如 1、2）以节省令牌。

  • MessageSid / ReplyToId 可以是短 ID。
  • MessageSidFull / ReplyToIdFull 包含提供商完整 ID。
  • 短 ID 在内存中；它们可能在重启或缓存驱逐时过期。
  • 操作接受短或完整的 messageId，但如果短 ID 不再可用则会出错。

对持久的自动化和存储使用完整 ID：

  • 模板：{{MessageSidFull}}、{{ReplyToIdFull}}
  • 上下文：入站负载中的 MessageSidFull / ReplyToIdFull

有关模板变量，请参阅配置。

阻止流式传输

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

{
  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：私信白名单（句柄、电子邮件、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：多账户配置。

相关全局选项：

  • agents.list[].groupChat.mentionPatterns（或 messages.groupChat.mentionPatterns）。
  • messages.responsePrefix。

寻址 / 投递目标

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

  • chat_guid:iMessage;-;+15555550123（推荐用于群组）
  • chat_id:123
  • chat_identifier:...
  • 直接句柄：+15555550123、[email protected]
    • 如果直接句柄没有现有的私信聊天，Clawdbot 将通过 POST /api/v1/chat/new 创建一个。这需要启用 BlueBubbles 私有 API。

安全

  • Webhook 请求通过将 guid/password 查询参数或标头与 channels.bluebubbles.password 进行比较来验证。来自 localhost 的请求也被接受。
  • 保管 API 密码和 webhook 端点秘密（将它们视为凭据）。
  • 如果在 LAN 外暴露 BlueBubbles 服务器，请在 BlueBubbles 服务器上启用 HTTPS + 防火墙规则。

故障排除

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

有关一般渠道工作流程参考，请参阅渠道和插件指南。

Channel location parsing