BlueBubbles

Documentation Index

Fetch the complete documentation index at: https://openclaw.zhcndoc.com/llms.txt

Use this file to discover all available pages before exploring further.

​

概览

• 通过 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 调用。
• 附件和贴纸会作为入站媒体被接收（并在可能时展示给代理）。
• 自动 TTS 回复生成的 MP3 或 CAF 音频会以 iMessage 语音备忘气泡的形式发送，而不是普通文件附件。
• 配对/允许名单与其他渠道（/channels/pairing 等）一致，使用 channels.bluebubbles.allowFrom + 配对代码。
• 反应会像 Slack/Telegram 一样作为系统事件呈现，因此代理可以在回复前“提及”它们。
• 高级功能：编辑、撤回、回复线程、消息效果、群组管理。

​

快速开始

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

​

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

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

    -- 触碰脚本接口以保持进程响应。
    set _chatCount to (count of chats)
  end tell
on error
  -- 忽略临时性失败（首次运行提示、锁定会话等）。
end try

<?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>

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

​

入门配置

openclaw onboard

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

​

访问控制（DM + 群组）

​

联系人姓名增强（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 }, // 所有群组的默认值
        "iMessage;-;chat123": { requireMention: false }, // 针对特定群组的覆盖
      },
    },
  },
}

​

命令门控

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

​

每群组系统提示词

{
  channels: {
    bluebubbles: {
      groups: {
        "iMessage;-;chat123": {
          systemPrompt: "保持回复不超过 3 句话。模仿群组的随意语气。",
        },
      },
    },
  },
}

​

详细示例：线程回复和 tapback 反应（Private API）

{
  channels: {
    bluebubbles: {
      groups: {
        "iMessage;+;chat-family": {
          systemPrompt: "When replying in this group, always call action=reply with the [[reply_to:N]] messageId from context so your response threads under the triggering message. Never send a new unlinked message. For short acknowledgements ('ok', 'got it', 'on it'), use action=react with an appropriate tapback emoji (❤️, 👍, 😂, ‼️, ❓) instead of sending a text reply.",
        },
      },
    },
  },
}

​

ACP 对话绑定

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

• 规范化的 DM 句柄，例如 +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, // 禁用已读回执
    },
  },
}

​

高级操作

{
  channels: {
    bluebubbles: {
      actions: {
        reactions: true, // tapback（默认：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, // 发送附件/媒体
      },
    },
  },
}

​

消息 ID（短 ID 与完整 ID）

• MessageSid / ReplyToId 可以是短 ID。
• MessageSidFull / ReplyToIdFull 包含提供方的完整 ID。
• 短 ID 只存在于内存中；重启或缓存回收后可能过期。
• 操作接受短或完整的 messageId，但如果短 ID 不再可用则会报错。

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

​

合并拆分发送的 DM（命令 + URL 在同一条消息中）

1. 一条文本消息（"Dump"）。
2. 一个 URL 预览气泡（"https://..."），并附带 OG 预览图片作为附件。

{
  channels: {
    bluebubbles: {
      coalesceSameSenderDms: true, // 启用（默认：false）
    },
  },
}

{
  messages: {
    inbound: {
      byChannel: {
        // 2500 ms 适用于大多数环境；如果你的 Mac 较慢
        // 或处于内存压力下，可提高到 4000 ms（此时观测到的间隔可能会超过 2 秒）。
        bluebubbles: 2500,
      },
    },
  },
}

​

场景以及代理会看到什么

​

拆分发送合并排查

grep coalesceSameSenderDms ~/.openclaw/openclaw.json

grep -E "Dispatching event to webhook" main.log | tail -20

​

块流式输出

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

​

媒体 + 限制

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

​

配置参考

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

​

寻址 / 送达目标

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

​

iMessage 与 SMS 路由

​

安全

• Webhook 请求通过将 guid/password 查询参数或请求头与 channels.bluebubbles.password 比对来认证。
• 保持 API 密码和 webhook 端点的机密性（将它们视为凭据）。
• BlueBubbles webhook 认证没有 localhost 绕过。如果你代理 webhook 流量，请确保在请求端到端保留 BlueBubbles 密码。这里的 gateway.trustedProxies 不能替代 channels.bluebubbles.password。参见 Gateway security。
• 如果将 BlueBubbles 服务器暴露到 LAN 之外，请启用 HTTPS + 防火墙规则。

​

故障排查

• 如果输入/已读事件停止工作，请检查 BlueBubbles webhook 日志并验证网关路径是否与 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）上，由于私有 API 变更，编辑功能当前不可用。
• 群组图标更新在 macOS 26（Tahoe）上可能不稳定：API 可能返回成功，但新图标不会同步。
• OpenClaw 会根据 BlueBubbles 服务器的 macOS 版本自动隐藏已知失效的操作。如果在 macOS 26（Tahoe）上编辑仍然显示，请使用 channels.bluebubbles.actions.edit=false 手动禁用。
• 已启用 coalesceSameSenderDms 但拆分发送（例如 Dump + URL）仍然作为两个回合到达：请参见 拆分发送合并故障排查 清单——常见原因是去抖窗口过紧、会话日志时间戳被误读为 webhook 到达时间，或者是回复引用发送（它使用 replyToBody，而不是第二个 webhook）。
• 状态/健康信息：openclaw status --all 或 openclaw status --deep。

​

相关内容

• Channel Routing — 消息的会话路由
• Channels Overview — 所有支持的通道
• Groups — 群聊行为和 mention 门禁
• Pairing — DM 认证和配对流程
• Security — 访问模型和加固