​

BlueBubbles（macOS REST）

​

内置插件

​

概览

• 通过 BlueBubbles 辅助应用在 macOS 上运行（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 调用发送。
• 附件和贴纸会作为传入媒体接收（并在可能时提供给智能体）。
• 配对/allowlist 的工作方式与其他渠道相同（/channels/pairing 等），使用 channels.bluebubbles.allowFrom + 配对码。
• 回应会像 Slack/Telegram 一样作为系统事件呈现，因此智能体可以在回复前“提及”它们。
• 高级功能：编辑、撤回、回复线程、消息效果、群组管理。

​

快速开始

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

• 始终设置 webhook 密码。
• 始终要求进行 webhook 身份验证。OpenClaw 会拒绝 BlueBubbles webhook 请求，除非它们包含与 channels.bluebubbles.password 匹配的 password/guid（例如 ?password=<password> 或 x-password），无论 loopback/proxy 拓扑如何。
• 在读取/解析完整 webhook 请求体之前，会先检查密码身份验证。

​

让 Messages.app 保持活跃（VM / 无头部署）

​

1）保存 AppleScript

• ~/Scripts/poke-messages.scpt

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

    -- Touch the scripting interface to keep the process responsive.
    set _chatCount to (count of chats)
  end tell
on error
  -- Ignore transient failures (first-run prompts, locked session, etc).
end try

​

2）安装 LaunchAgent

• ~/Library/LaunchAgents/com.user.poke-messages.plist

<?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 的同一用户会话中批准它们。

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

​

新手引导

openclaw onboard

• Server URL（必填）：BlueBubbles 服务器地址（例如 http://192.168.1.100:1234）
• Password（必填）：BlueBubbles Server 设置中的 API 密码
• Webhook path（可选）：默认为 /bluebubbles-webhook
• DM 策略：pairing、allowlist、open 或 disabled
• 允许列表：电话号码、电子邮件地址或聊天目标

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）。
• 当设置为 allowlist 时，channels.bluebubbles.groupAllowFrom 用于控制哪些人可以在群组中触发。

​

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

• channels.bluebubbles.enrichGroupParticipantsFromContacts = true 启用查找。默认值：false。
• 只有在群组访问、命令授权和提及门控都允许消息通过之后，才会执行查找。
• 仅增强未命名的电话参与者。
• 如果未找到本地匹配项，仍会回退为原始电话号码。

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

​

提及门控（群组）

• 使用 agents.list[].groupChat.mentionPatterns（或 messages.groupChat.mentionPatterns）检测提及。
• 当某个群组启用了 requireMention 时，智能体只会在被提及时响应。
• 来自已授权发送者的控制命令会绕过提及门控。

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

​

命令门控

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

​

ACP 会话绑定

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

• 规范化的私信句柄，例如 +15555550123 或 user@example.com
• chat_id:<id>
• chat_guid:<guid>
• chat_identifier:<identifier>

{
  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" },
    },
  ],
}

​

输入状态 + 已读回执

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

{
  channels: {
    bluebubbles: {
      sendReadReceipts: false, // disable read receipts
    },
  },
}

​

高级操作

{
  channels: {
    bluebubbles: {
      actions: {
        reactions: true, // tapbacks (default: true)
        edit: true, // edit sent messages (macOS 13+, broken on macOS 26 Tahoe)
        unsend: true, // unsend messages (macOS 13+)
        reply: true, // reply threading by message GUID
        sendWithEffect: true, // message effects (slam, loud, etc.)
        renameGroup: true, // rename group chats
        setGroupIcon: true, // set group chat icon/photo (flaky on macOS 26 Tahoe)
        addParticipant: true, // add participants to groups
        removeParticipant: true, // remove participants from groups
        leaveGroup: true, // leave group chats
        sendAttachment: true, // send attachments/media
      },
    },
  },
}

• 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 上不稳定（API 可能返回成功，但图标不会同步）。
• addParticipant：向群组添加成员（chatGuid、address）
• removeParticipant：从群组移除成员（chatGuid、address）
• leaveGroup：离开群聊（chatGuid）
• upload-file：发送媒体/文件（to、buffer、filename、asVoice）
  • 语音备忘录：将 MP3 或 CAF 音频与 asVoice: true 搭配使用，以 iMessage 语音消息形式发送。BlueBubbles 在发送语音备忘录时会将 MP3 转换为 CAF。
• 旧别名：sendAttachment 仍然可用，但 upload-file 是规范操作名称。

​

消息 ID（短 ID 与完整 ID）

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

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

​

分块流式传输

{
  channels: {
    bluebubbles: {
      blockStreaming: true, // enable block streaming (off by default)
    },
  },
}

​

媒体 + 限制

• 传入附件会被下载并存储在媒体缓存中。
• 通过 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：私信 allowlist（句柄、电子邮件、E.164 号码、chat_id:*、chat_guid:*）。
• channels.bluebubbles.groupPolicy：open | allowlist | disabled（默认值：allowlist）。
• channels.bluebubbles.groupAllowFrom：群组发送者 allowlist。
• 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：允许用于传出本地媒体路径的绝对本地目录显式 allowlist。默认拒绝发送本地路径，除非配置此项。按账户覆盖：channels.bluebubbles.accounts.<accountId>.mediaLocalRoots。
• channels.bluebubbles.historyLimit：用于上下文的最大群组消息数（0 表示禁用）。
• channels.bluebubbles.dmHistoryLimit：私信历史上限。
• channels.bluebubbles.actions：启用/禁用特定操作。
• channels.bluebubbles.accounts：多账户配置。

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

​

寻址 / 传递目标

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

​

安全

• Webhook 请求通过将查询参数或请求头中的 guid/password 与 channels.bluebubbles.password 比较来进行身份验证。
• 请妥善保管 API 密码和 webhook 端点机密（将它们视为凭证）。
• BlueBubbles webhook 身份验证没有 localhost 绕过。如果你代理 webhook 流量，请在整个请求链路中保留 BlueBubbles 密码。这里的 gateway.trustedProxies 不能替代 channels.bluebubbles.password。请参见 Gateway 安全。
• 如果要在 LAN 之外暴露 BlueBubbles 服务器，请启用 HTTPS + 防火墙规则。

​

故障排除

• 如果输入状态/已读事件停止工作，请检查 BlueBubbles webhook 日志，并确认 Gateway 网关路径与 channels.bluebubbles.webhookPath 匹配。
• 配对码会在一小时后过期；使用 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。

​

相关内容

• 渠道概览 — 所有受支持的渠道
• 配对 — 私信身份验证和配对流程
• 群组 — 群聊行为和提及门控
• 渠道路由 — 消息的会话路由
• 安全 — 访问模型与加固