BlueBubbles

Trạng thái: plugin kế thừa được đóng gói sẵn giao tiếp với máy chủ BlueBubbles trên macOS qua HTTP. Các thiết lập BlueBubbles hiện có vẫn tiếp tục hoạt động, nhưng các triển khai OpenClaw iMessage mới nên ưu tiên plugin iMessage gốc khi các yêu cầu của plugin này phù hợp với máy chủ của bạn.

# Tổng quan

• Chạy trên macOS thông qua ứng dụng trợ giúp BlueBubbles (bluebubbles.app).
• Phương án dự phòng kế thừa cho các bản cài đặt đã phụ thuộc vào ID kênh BlueBubbles, trạng thái webhook, mục tiêu nhóm, phân phối cron, hoặc định tuyến workspace.
• Được khuyến nghị/đã kiểm thử: macOS Sequoia (15). macOS Tahoe (26) hoạt động; chỉnh sửa hiện đang bị lỗi trên Tahoe, và cập nhật biểu tượng nhóm có thể báo thành công nhưng không đồng bộ.
• OpenClaw giao tiếp với nó thông qua REST API (GET /api/v1/ping, POST /message/text, POST /chat/:id/*).
• Tin nhắn đến đi qua webhooks; phản hồi gửi đi, chỉ báo đang nhập, xác nhận đã đọc, và tapbacks là các lệnh gọi REST.
• Tệp đính kèm và nhãn dán được nạp dưới dạng phương tiện đầu vào (và được hiển thị cho agent khi có thể).
• Phản hồi Auto-TTS tổng hợp âm thanh MP3 hoặc CAF được gửi dưới dạng bong bóng ghi âm iMessage thay vì tệp đính kèm thông thường.
• Cơ chế ghép đôi/danh sách cho phép hoạt động giống các kênh khác (/channels/pairing v.v.) với channels.bluebubbles.allowFrom + mã ghép đôi.
• Reactions được hiển thị dưới dạng sự kiện hệ thống giống như Slack/Telegram để agents có thể "nhắc đến" chúng trước khi trả lời.
• Tính năng nâng cao: chỉnh sửa, thu hồi gửi, luồng trả lời, hiệu ứng tin nhắn, quản lý nhóm.

# Bắt đầu nhanh

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

# Giữ Messages.app hoạt động (thiết lập VM / headless)

Một số thiết lập VM macOS / luôn bật có thể khiến Messages.app chuyển sang trạng thái "nhàn rỗi" (sự kiện đến dừng lại cho đến khi ứng dụng được mở/đưa lên trước). Cách khắc phục đơn giản là đánh thức Messages mỗi 5 phút bằng AppleScript + LaunchAgent.

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

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

# Onboarding

BlueBubbles có trong quy trình onboarding tương tác:

openclaw onboard

Trình hướng dẫn yêu cầu:

Bạn cũng có thể thêm BlueBubbles qua CLI:

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

# Kiểm soát truy cập (DMs + nhóm)

# Bổ sung tên liên hệ (macOS, tùy chọn)

Webhooks nhóm của BlueBubbles thường chỉ bao gồm địa chỉ người tham gia thô. Nếu bạn muốn ngữ cảnh GroupMembers hiển thị tên liên hệ cục bộ thay vào đó, bạn có thể chọn bật bổ sung từ Contacts cục bộ trên macOS:

• channels.bluebubbles.enrichGroupParticipantsFromContacts = true bật tra cứu. Mặc định: false.
• Tra cứu chỉ chạy sau khi quyền truy cập nhóm, ủy quyền lệnh, và chặn theo nhắc đến đã cho phép tin nhắn đi qua.
• Chỉ người tham gia bằng số điện thoại chưa có tên mới được bổ sung.
• Số điện thoại thô vẫn là phương án dự phòng khi không tìm thấy khớp cục bộ.

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

# Chặn theo nhắc đến (nhóm)

BlueBubbles hỗ trợ chặn theo nhắc đến cho chat nhóm, khớp với hành vi iMessage/WhatsApp:

• Dùng agents.list[].groupChat.mentionPatterns (hoặc messages.groupChat.mentionPatterns) để phát hiện nhắc đến.
• Khi requireMention được bật cho một nhóm, agent chỉ phản hồi khi được nhắc đến.
• Lệnh điều khiển từ người gửi được ủy quyền bỏ qua chặn theo nhắc đến.

Cấu hình theo nhóm:

{
  channels: {
    bluebubbles: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15555550123"],
      groups: {
        "*": { requireMention: true }, // default for all groups
        "iMessage;-;chat123": { requireMention: false }, // override for specific group
      },
    },
  },
}

# Chặn lệnh

• Lệnh điều khiển (ví dụ: /config, /model) yêu cầu ủy quyền.
• Dùng allowFrom và groupAllowFrom để xác định ủy quyền lệnh.
• Người gửi được ủy quyền có thể chạy lệnh điều khiển ngay cả khi không nhắc đến trong nhóm.

# System prompt theo nhóm

Mỗi mục dưới channels.bluebubbles.groups.* chấp nhận chuỗi systemPrompt tùy chọn. Giá trị này được đưa vào system prompt của agent ở mỗi lượt xử lý tin nhắn trong nhóm đó, vì vậy bạn có thể đặt persona hoặc quy tắc hành vi theo nhóm mà không cần chỉnh sửa prompt của agent:

{
  channels: {
    bluebubbles: {
      groups: {
        "iMessage;-;chat123": {
          systemPrompt: "Keep responses under 3 sentences. Mirror the group's casual tone.",
        },
      },
    },
  },
}

Khóa khớp với bất cứ gì BlueBubbles báo cáo là chatGuid / chatIdentifier / chatId dạng số cho nhóm, và mục wildcard "*" cung cấp mặc định cho mọi nhóm không có khớp chính xác (cùng mẫu được dùng bởi requireMention và chính sách công cụ theo nhóm). Khớp chính xác luôn thắng wildcard. DMs bỏ qua trường này; hãy dùng tùy chỉnh prompt ở cấp agent hoặc cấp tài khoản thay vào đó.

# Ví dụ hoàn chỉnh: trả lời theo luồng và phản ứng tapback (Private API)

Khi bật BlueBubbles Private API, tin nhắn đầu vào đi kèm ID tin nhắn ngắn (ví dụ [[reply_to:5]]) và agent có thể gọi action=reply để trả lời theo luồng vào một tin nhắn cụ thể hoặc action=react để thả một tapback. systemPrompt theo nhóm là cách đáng tin cậy để giữ agent chọn đúng công cụ:

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

Phản ứng tapback và trả lời theo luồng đều yêu cầu BlueBubbles Private API; xem Hành động nâng cao và ID tin nhắn để biết cơ chế nền tảng.

# Liên kết cuộc trò chuyện ACP

Chat BlueBubbles có thể được chuyển thành workspace ACP bền vững mà không thay đổi lớp truyền tải.

Luồng thao tác nhanh:

• Chạy /acp spawn codex --bind here bên trong DM hoặc chat nhóm được phép.
• Các tin nhắn sau này trong cùng cuộc trò chuyện BlueBubbles đó sẽ định tuyến tới phiên ACP đã tạo.
• /new và /reset đặt lại cùng phiên ACP đã liên kết tại chỗ.
• /acp close đóng phiên ACP và xóa liên kết.

Liên kết liên tục được cấu hình cũng được hỗ trợ thông qua các mục bindings[] cấp cao nhất với type: "acp" và match.channel: "bluebubbles".

match.peer.id có thể dùng bất kỳ dạng mục tiêu BlueBubbles nào được hỗ trợ:

• handle DM đã chuẩn hóa như +15555550123 hoặc [email protected]
• chat_id:<id>
• chat_guid:<guid>
• chat_identifier:<identifier>

Để có các liên kết nhóm ổn định, ưu tiên chat_id:* hoặc chat_identifier:*.

Ví dụ:

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

Xem Tác nhân ACP để biết hành vi liên kết ACP dùng chung.

# Đang nhập + biên nhận đã đọc

• Chỉ báo đang nhập: Được gửi tự động trước và trong khi tạo phản hồi.
• Biên nhận đã đọc: Được kiểm soát bởi channels.bluebubbles.sendReadReceipts (mặc định: true).
• Chỉ báo đang nhập: OpenClaw gửi sự kiện bắt đầu nhập; BlueBubbles tự động xóa trạng thái đang nhập khi gửi hoặc hết thời gian chờ (dừng thủ công qua DELETE không đáng tin cậy).

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

# Hành động nâng cao

BlueBubbles hỗ trợ các hành động tin nhắn nâng cao khi được bật trong cấu hình:

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

# ID tin nhắn (ngắn so với đầy đủ)

OpenClaw có thể hiển thị ID tin nhắn ngắn (ví dụ 1, 2) để tiết kiệm token.

• MessageSid / ReplyToId có thể là ID ngắn.
• MessageSidFull / ReplyToIdFull chứa ID đầy đủ của nhà cung cấp.
• ID ngắn nằm trong bộ nhớ; chúng có thể hết hạn khi khởi động lại hoặc khi bộ nhớ đệm bị loại bỏ.
• Các hành động chấp nhận messageId ngắn hoặc đầy đủ, nhưng ID ngắn sẽ báo lỗi nếu không còn khả dụng.

Dùng ID đầy đủ cho tự động hóa và lưu trữ bền vững:

• Mẫu: {{MessageSidFull}}, {{ReplyToIdFull}}
• Ngữ cảnh: MessageSidFull / ReplyToIdFull trong payload đến

Xem Cấu hình để biết các biến mẫu.

# Gộp các DM gửi tách (lệnh + URL trong một lần soạn)

Khi người dùng nhập cùng lúc một lệnh và một URL trong iMessage - ví dụ Dump https://example.com/article - Apple tách lần gửi thành hai lần gửi webhook riêng biệt:

1. Một tin nhắn văn bản ("Dump").
2. Một bong bóng xem trước URL ("https://...") với ảnh xem trước OG dưới dạng tệp đính kèm.

Hai webhook đến OpenClaw cách nhau khoảng 0,8-2,0 giây trên hầu hết thiết lập. Nếu không gộp, tác nhân nhận riêng lệnh ở lượt 1, trả lời (thường là "gửi tôi URL"), và chỉ thấy URL ở lượt 2 - lúc đó ngữ cảnh lệnh đã bị mất.

channels.bluebubbles.coalesceSameSenderDms chọn một DM để gộp các webhook liên tiếp từ cùng người gửi thành một lượt tác nhân duy nhất. Trò chuyện nhóm vẫn khóa theo từng tin nhắn để giữ nguyên cấu trúc lượt nhiều người dùng.

{
  channels: {
    bluebubbles: {
      coalesceSameSenderDms: true, // opt in (default: false)
    },
  },
}

{
  messages: {
    inbound: {
      byChannel: {
        // 2500 ms works for most setups; raise to 4000 ms if your Mac is slow
        // or under memory pressure (observed gap can stretch past 2 s then).
        bluebubbles: 2500,
      },
    },
  },
}

# Tình huống và những gì tác nhân thấy

# Khắc phục sự cố gộp gửi tách

Nếu cờ đã bật nhưng các lần gửi tách vẫn đến thành hai lượt, hãy kiểm tra từng lớp:

grep coalesceSameSenderDms ~/.openclaw/openclaw.json

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

# Truyền phát theo khối

Kiểm soát việc phản hồi được gửi dưới dạng một tin nhắn duy nhất hay được truyền phát theo các khối:

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

# Phương tiện + giới hạn

• Tệp đính kèm đầu vào được tải xuống và lưu trong bộ nhớ đệm phương tiện.
• Giới hạn phương tiện qua channels.bluebubbles.mediaMaxMb cho phương tiện đầu vào và đầu ra (mặc định: 8 MB).
• Văn bản đầu ra được chia nhỏ theo channels.bluebubbles.textChunkLimit (mặc định: 4000 ký tự).

# Tham chiếu cấu hình

Cấu hình đầy đủ: Cấu hình

Các tùy chọn toàn cục liên quan:

• agents.list[].groupChat.mentionPatterns (hoặc messages.groupChat.mentionPatterns).
• messages.responsePrefix.

# Địa chỉ hóa / mục tiêu phân phối

Ưu tiên chat_guid để định tuyến ổn định:

• chat_guid:iMessage;-;+15555550123 (ưu tiên cho nhóm)
• chat_id:123
• chat_identifier:...
• Handle trực tiếp: +15555550123, [email protected]
  • Nếu một handle trực tiếp chưa có cuộc trò chuyện DM hiện có, OpenClaw sẽ tạo một cuộc trò chuyện qua POST /api/v1/chat/new. Việc này yêu cầu bật BlueBubbles Private API.

# Định tuyến iMessage so với SMS

Khi cùng một handle có cả cuộc trò chuyện iMessage và SMS trên Mac (ví dụ một số điện thoại đã đăng ký iMessage nhưng cũng đã nhận các dự phòng bong bóng xanh), OpenClaw ưu tiên cuộc trò chuyện iMessage và không bao giờ âm thầm hạ cấp xuống SMS. Để buộc dùng cuộc trò chuyện SMS, hãy dùng tiền tố mục tiêu sms: rõ ràng (ví dụ sms:+15555550123). Các handle không có cuộc trò chuyện iMessage khớp vẫn sẽ gửi qua bất kỳ cuộc trò chuyện nào BlueBubbles báo cáo.

# Bảo mật

• Các yêu cầu Webhook được xác thực bằng cách so sánh tham số truy vấn hoặc header guid/password với channels.bluebubbles.password.
• Giữ bí mật mật khẩu API và điểm cuối Webhook (xem chúng như thông tin xác thực).
• Không có cơ chế bỏ qua xác thực BlueBubbles Webhook cho localhost. Nếu bạn proxy lưu lượng Webhook, hãy giữ mật khẩu BlueBubbles trên yêu cầu từ đầu đến cuối. gateway.trustedProxies không thay thế channels.bluebubbles.password ở đây. Xem Bảo mật Gateway.
• Bật HTTPS + quy tắc tường lửa trên máy chủ BlueBubbles nếu để lộ nó ra ngoài LAN.

# Khắc phục sự cố

• Nếu sự kiện nhập/xác nhận đọc ngừng hoạt động, hãy kiểm tra nhật ký Webhook của BlueBubbles và xác minh đường dẫn gateway khớp với channels.bluebubbles.webhookPath.
• Mã ghép đôi hết hạn sau một giờ; dùng openclaw pairing list bluebubbles và openclaw pairing approve bluebubbles <code>.
• Phản ứng yêu cầu BlueBubbles private API (POST /api/v1/message/react); hãy đảm bảo phiên bản máy chủ cung cấp API này.
• Chỉnh sửa/thu hồi yêu cầu macOS 13+ và phiên bản máy chủ BlueBubbles tương thích. Trên macOS 26 (Tahoe), chỉnh sửa hiện bị hỏng do các thay đổi trong private API.
• Cập nhật biểu tượng nhóm có thể không ổn định trên macOS 26 (Tahoe): API có thể trả về thành công nhưng biểu tượng mới không đồng bộ.
• OpenClaw tự động ẩn các hành động đã biết là bị hỏng dựa trên phiên bản macOS của máy chủ BlueBubbles. Nếu chỉnh sửa vẫn xuất hiện trên macOS 26 (Tahoe), hãy tắt thủ công bằng channels.bluebubbles.actions.edit=false.
• coalesceSameSenderDms đã bật nhưng các lượt gửi tách (ví dụ Dump + URL) vẫn đến thành hai lượt: xem danh sách kiểm tra khắc phục sự cố gộp lượt gửi tách - nguyên nhân phổ biến là cửa sổ debounce quá chặt, dấu thời gian nhật ký phiên bị đọc nhầm là thời điểm Webhook đến, hoặc một lần gửi trích dẫn trả lời (dùng replyToBody, không phải Webhook thứ hai).
• Để xem thông tin trạng thái/tình trạng: openclaw status --all hoặc openclaw status --deep.

Để tham khảo quy trình kênh chung, xem Kênh và hướng dẫn Plugins.

# Liên quan

• Định tuyến kênh - định tuyến phiên cho tin nhắn
• Tổng quan kênh - tất cả các kênh được hỗ trợ
• Nhóm - hành vi trò chuyện nhóm và kiểm soát nhắc đến
• Ghép đôi - xác thực DM và luồng ghép đôi
• Bảo mật - mô hình truy cập và gia cố