BlueBubbles

สถานะ: Plugin แบบเดิมที่บันเดิลมาด้วย ซึ่งสื่อสารกับเซิร์ฟเวอร์ BlueBubbles บน macOS ผ่าน HTTP การตั้งค่า BlueBubbles ที่มีอยู่ยังคงใช้งานได้ต่อไป แต่การปรับใช้ OpenClaw iMessage ใหม่ควรเลือกใช้ Plugin iMessage แบบเนทีฟเมื่อข้อกำหนดของมันเหมาะกับโฮสต์ของคุณ

# ภาพรวม

• ทำงานบน macOS ผ่านแอปตัวช่วย BlueBubbles (bluebubbles.app)
• ทางเลือกสำรองแบบเดิมสำหรับการติดตั้งที่พึ่งพา ID ช่องทาง BlueBubbles, สถานะ webhook, เป้าหมายกลุ่ม, การส่ง Cron หรือการกำหนดเส้นทางเวิร์กสเปซอยู่แล้ว
• แนะนำ/ทดสอบแล้ว: macOS Sequoia (15) macOS Tahoe (26) ใช้งานได้ แต่ปัจจุบันการแก้ไขยังเสียบน Tahoe และการอัปเดตไอคอนกลุ่มอาจรายงานว่าสำเร็จแต่ไม่ซิงก์
• OpenClaw สื่อสารกับมันผ่าน REST API (GET /api/v1/ping, POST /message/text, POST /chat/:id/*)
• ข้อความขาเข้ามาถึงผ่าน webhooks; การตอบกลับขาออก, ตัวบ่งชี้การพิมพ์, ใบตอบรับการอ่าน และ tapbacks เป็นการเรียก REST
• ไฟล์แนบและสติกเกอร์จะถูกนำเข้าเป็นสื่อขาเข้า (และแสดงให้ agent เห็นเมื่อเป็นไปได้)
• การตอบกลับ Auto-TTS ที่สังเคราะห์เสียง MP3 หรือ CAF จะถูกส่งเป็นบับเบิลบันทึกเสียงของ iMessage แทนไฟล์แนบธรรมดา
• การจับคู่/allowlist ทำงานแบบเดียวกับช่องทางอื่น (/channels/pairing เป็นต้น) ด้วย channels.bluebubbles.allowFrom + โค้ดจับคู่
• ปฏิกิริยาจะถูกแสดงเป็นเหตุการณ์ระบบเหมือน Slack/Telegram เพื่อให้ agents สามารถ "กล่าวถึง" ก่อนตอบกลับได้
• ฟีเจอร์ขั้นสูง: แก้ไข, ยกเลิกการส่ง, เธรดการตอบกลับ, เอฟเฟกต์ข้อความ, การจัดการกลุ่ม

# เริ่มต้นอย่างรวดเร็ว

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

# ทำให้ Messages.app ยังทำงานอยู่ (การตั้งค่า VM / แบบไม่มีหน้าจอ)

การตั้งค่า macOS VM / เปิดตลอดบางแบบอาจทำให้ Messages.app เข้าสถานะ "idle" (เหตุการณ์ขาเข้าหยุดจนกว่าแอปจะถูกเปิด/นำมาอยู่เบื้องหน้า) วิธีเลี่ยงแบบง่ายคือ กระตุ้น Messages ทุก 5 นาที ด้วย 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

# การเริ่มต้นใช้งาน

BlueBubbles พร้อมใช้งานในการเริ่มต้นใช้งานแบบโต้ตอบ:

openclaw onboard

วิซาร์ดจะขอข้อมูล:

คุณยังสามารถเพิ่ม BlueBubbles ผ่าน CLI ได้:

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

# การควบคุมการเข้าถึง (DMs + กลุ่ม)

# การเติมเต็มชื่อผู้ติดต่อ (macOS, ไม่บังคับ)

webhooks กลุ่มของ BlueBubbles มักมีเพียงที่อยู่ผู้เข้าร่วมแบบดิบ หากคุณต้องการให้บริบท GroupMembers แสดงชื่อผู้ติดต่อภายในเครื่องแทน คุณสามารถเลือกใช้การเติมเต็มจาก Contacts ภายในเครื่องบน macOS ได้:

• channels.bluebubbles.enrichGroupParticipantsFromContacts = true เปิดใช้งานการค้นหา ค่าเริ่มต้น: false
• การค้นหาจะทำงานหลังจากการเข้าถึงกลุ่ม, การอนุญาตคำสั่ง และการกั้นการกล่าวถึงอนุญาตให้ข้อความผ่านแล้วเท่านั้น
• เฉพาะผู้เข้าร่วมที่เป็นหมายเลขโทรศัพท์และยังไม่มีชื่อเท่านั้นที่จะถูกเติมเต็ม
• หมายเลขโทรศัพท์ดิบยังคงเป็นทางเลือกสำรองเมื่อไม่พบรายการที่ตรงกันภายในเครื่อง

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

# การกั้นการกล่าวถึง (กลุ่ม)

BlueBubbles รองรับการกั้นการกล่าวถึงสำหรับแชตกลุ่ม โดยสอดคล้องกับพฤติกรรมของ iMessage/WhatsApp:

• ใช้ agents.list[].groupChat.mentionPatterns (หรือ messages.groupChat.mentionPatterns) เพื่อตรวจจับการกล่าวถึง
• เมื่อเปิดใช้งาน requireMention สำหรับกลุ่ม agent จะตอบกลับเฉพาะเมื่อถูกกล่าวถึงเท่านั้น
• คำสั่งควบคุมจากผู้ส่งที่ได้รับอนุญาตจะข้ามการกั้นการกล่าวถึง

การกำหนดค่าต่อกลุ่ม:

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

# การกั้นคำสั่ง

• คำสั่งควบคุม (เช่น /config, /model) ต้องได้รับอนุญาต
• ใช้ allowFrom และ groupAllowFrom เพื่อกำหนดการอนุญาตคำสั่ง
• ผู้ส่งที่ได้รับอนุญาตสามารถเรียกใช้คำสั่งควบคุมได้แม้ไม่ได้กล่าวถึงในกลุ่ม

# system prompt ต่อกลุ่ม

แต่ละรายการภายใต้ channels.bluebubbles.groups.* รับสตริง systemPrompt แบบไม่บังคับ ค่านี้จะถูกฉีดเข้าไปใน system prompt ของ agent ในทุกเทิร์นที่จัดการข้อความในกลุ่มนั้น เพื่อให้คุณตั้งบุคลิกหรือกฎพฤติกรรมต่อกลุ่มได้โดยไม่ต้องแก้ไขพรอมป์ของ agent:

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

คีย์ตรงกับสิ่งที่ BlueBubbles รายงานเป็น chatGuid / chatIdentifier / chatId แบบตัวเลขสำหรับกลุ่ม และรายการ wildcard "*" ให้ค่าเริ่มต้นสำหรับทุกกลุ่มที่ไม่มีรายการตรงแบบเป๊ะ (รูปแบบเดียวกับที่ใช้โดย requireMention และนโยบายเครื่องมือต่อกลุ่ม) รายการที่ตรงแบบเป๊ะชนะ wildcard เสมอ DMs จะละเว้นฟิลด์นี้; ให้ใช้การปรับแต่งพรอมป์ระดับ agent หรือระดับบัญชีแทน

# ตัวอย่างที่ใช้งานจริง: การตอบกลับแบบเธรดและปฏิกิริยา tapback (Private API)

เมื่อเปิดใช้งาน BlueBubbles Private API ข้อความขาเข้าจะมาพร้อม ID ข้อความแบบสั้น (เช่น [[reply_to:5]]) และ agent สามารถเรียก action=reply เพื่อเธรดเข้าไปยังข้อความเฉพาะ หรือ action=react เพื่อวาง tapback ได้ systemPrompt ต่อกลุ่มเป็นวิธีที่เชื่อถือได้ในการทำให้ agent เลือกเครื่องมือที่ถูกต้อง:

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

ทั้งปฏิกิริยา tapback และการตอบกลับแบบเธรดต้องใช้ BlueBubbles Private API; ดู การดำเนินการขั้นสูง และ ID ข้อความ สำหรับกลไกพื้นฐาน

# การผูกการสนทนา ACP

แชต BlueBubbles สามารถเปลี่ยนเป็นเวิร์กสเปซ ACP ที่คงทนได้โดยไม่ต้องเปลี่ยนเลเยอร์การขนส่ง

ขั้นตอนเร็วสำหรับผู้ปฏิบัติงาน:

• เรียกใช้ /acp spawn codex --bind here ภายใน DM หรือแชตกลุ่มที่ได้รับอนุญาต
• ข้อความในอนาคตในบทสนทนา BlueBubbles เดียวกันนั้นจะถูกกำหนดเส้นทางไปยังเซสชัน ACP ที่สร้างขึ้น
• /new และ /reset รีเซ็ตเซสชัน ACP ที่ผูกไว้เดิม ณ จุดเดิม
• /acp close ปิดเซสชัน ACP และลบการผูก

ยังรองรับการผูกถาวรที่กำหนดค่าไว้ผ่านรายการ bindings[] ระดับบนสุดด้วย type: "acp" และ match.channel: "bluebubbles"

match.peer.id สามารถใช้รูปแบบเป้าหมาย BlueBubbles ที่รองรับใดก็ได้:

• แฮนด์เดิล DM ที่ปรับให้เป็นมาตรฐานแล้ว เช่น +15555550123 หรือ [email protected]
• chat_id:<id>
• chat_guid:<guid>
• chat_identifier:<identifier>

สำหรับการผูกกลุ่มที่เสถียร ให้เลือกใช้ chat_id:* หรือ chat_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" },
    },
  ],
}

ดู เอเจนต์ ACP สำหรับพฤติกรรมการผูก ACP ที่ใช้ร่วมกัน

# การกำลังพิมพ์ + ใบตอบรับการอ่าน

• ตัวบ่งชี้การกำลังพิมพ์: ส่งโดยอัตโนมัติก่อนและระหว่างการสร้างคำตอบ
• ใบตอบรับการอ่าน: ควบคุมโดย channels.bluebubbles.sendReadReceipts (ค่าเริ่มต้น: true)
• ตัวบ่งชี้การกำลังพิมพ์: OpenClaw ส่งเหตุการณ์เริ่มพิมพ์ BlueBubbles จะล้างสถานะกำลังพิมพ์โดยอัตโนมัติเมื่อส่งหรือหมดเวลา (การหยุดด้วยตนเองผ่าน DELETE ไม่น่าเชื่อถือ)

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

# การทำงานขั้นสูง

BlueBubbles รองรับการทำงานกับข้อความขั้นสูงเมื่อเปิดใช้ใน config:

{
  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 ข้อความ (แบบสั้นกับแบบเต็ม)

OpenClaw อาจแสดง ID ข้อความแบบ สั้น (เช่น 1, 2) เพื่อประหยัดโทเค็น

• MessageSid / ReplyToId อาจเป็น ID แบบสั้น
• MessageSidFull / ReplyToIdFull มี ID เต็มของผู้ให้บริการ
• ID แบบสั้นอยู่ในหน่วยความจำ และอาจหมดอายุเมื่อรีสตาร์ทหรือเมื่อแคชถูกขับออก
• การทำงานต่าง ๆ รับ messageId แบบสั้นหรือแบบเต็ม แต่ ID แบบสั้นจะแจ้งข้อผิดพลาดหากไม่มีให้ใช้แล้ว

ใช้ ID แบบเต็มสำหรับการทำงานอัตโนมัติและพื้นที่เก็บข้อมูลที่ต้องคงทน:

• เทมเพลต: {{MessageSidFull}}, {{ReplyToIdFull}}
• บริบท: MessageSidFull / ReplyToIdFull ในเพย์โหลดขาเข้า

ดู การกำหนดค่า สำหรับตัวแปรเทมเพลต

# การรวม DM ที่ถูกแยกส่ง (คำสั่ง + URL ในการเขียนครั้งเดียว)

เมื่อผู้ใช้พิมพ์คำสั่งและ URL พร้อมกันใน iMessage - เช่น Dump https://example.com/article - Apple จะแยกการส่งออกเป็น การส่งมอบ Webhook สองรายการแยกกัน:

1. ข้อความตัวอักษร ("Dump")
2. บอลลูนพรีวิว URL ("https://...") พร้อมรูปภาพ OG-preview เป็นไฟล์แนบ

Webhook ทั้งสองมาถึง OpenClaw ห่างกันประมาณ 0.8-2.0 วินาทีในสภาพแวดล้อมส่วนใหญ่ หากไม่มีการรวม เอเจนต์จะได้รับเฉพาะคำสั่งในรอบที่ 1 ตอบกลับ (มักเป็น "ส่ง URL มาให้ฉัน") และเพิ่งเห็น URL ในรอบที่ 2 ซึ่ง ณ ตอนนั้นบริบทของคำสั่งก็หายไปแล้ว

channels.bluebubbles.coalesceSameSenderDms เลือกให้ DM รวม Webhook ที่ติดต่อกันจากผู้ส่งเดียวกันเป็นรอบเอเจนต์เดียว แชตกลุ่มยังคงจัดคีย์แยกตามข้อความเพื่อรักษาโครงสร้างรอบของผู้ใช้หลายคนไว้

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

# สถานการณ์และสิ่งที่เอเจนต์เห็น

# การแก้ปัญหาการรวม split-send

หากเปิดแฟล็กแล้ว แต่ split-send ยังมาถึงเป็นสองรอบ ให้ตรวจสอบแต่ละชั้น:

grep coalesceSameSenderDms ~/.openclaw/openclaw.json

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

# การสตรีมแบบบล็อก

ควบคุมว่าจะส่งคำตอบเป็นข้อความเดียวหรือสตรีมเป็นบล็อก:

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

# สื่อ + ขีดจำกัด

• ไฟล์แนบขาเข้าจะถูกดาวน์โหลดและเก็บไว้ในแคชสื่อ
• ขีดจำกัดสื่อผ่าน channels.bluebubbles.mediaMaxMb สำหรับสื่อขาเข้าและขาออก (ค่าเริ่มต้น: 8 MB)
• ข้อความขาออกถูกแบ่งเป็นชิ้นตาม channels.bluebubbles.textChunkLimit (ค่าเริ่มต้น: 4000 อักขระ)

# ข้อมูลอ้างอิงการกำหนดค่า

การกำหนดค่าแบบเต็ม: การกำหนดค่า

ตัวเลือกระดับ global ที่เกี่ยวข้อง:

• agents.list[].groupChat.mentionPatterns (หรือ messages.groupChat.mentionPatterns)
• messages.responsePrefix

# การระบุที่อยู่ / เป้าหมายการจัดส่ง

ควรใช้ chat_guid เพื่อการกำหนดเส้นทางที่เสถียร:

• chat_guid:iMessage;-;+15555550123 (แนะนำสำหรับกลุ่ม)
• chat_id:123
• chat_identifier:...
• handles โดยตรง: +15555550123, [email protected]
  • หาก handle โดยตรงไม่มีแชท DM ที่มีอยู่ OpenClaw จะสร้างให้ผ่าน POST /api/v1/chat/new ซึ่งต้องเปิดใช้ BlueBubbles Private API

# การกำหนดเส้นทาง iMessage เทียบกับ SMS

เมื่อ handle เดียวกันมีทั้งแชท iMessage และ SMS บน Mac (เช่น หมายเลขโทรศัพท์ที่ลงทะเบียน iMessage แล้ว แต่เคยได้รับ fallback แบบ green-bubble ด้วย) OpenClaw จะเลือกแชท iMessage และจะไม่ลดระดับเป็น SMS แบบเงียบ ๆ หากต้องการบังคับใช้แชท SMS ให้ใช้ prefix เป้าหมาย sms: อย่างชัดเจน (เช่น sms:+15555550123) Handles ที่ไม่มีแชท iMessage ตรงกันจะยังส่งผ่านแชทใดก็ตามที่ BlueBubbles รายงาน

# ความปลอดภัย

• คำขอ Webhook จะได้รับการยืนยันตัวตนโดยเปรียบเทียบ query params หรือ headers ของ guid/password กับ channels.bluebubbles.password
• เก็บรหัสผ่าน API และ endpoint ของ Webhook เป็นความลับ (ปฏิบัติกับสิ่งเหล่านี้เหมือน credentials)
• ไม่มีการข้ามการยืนยันตัวตน Webhook ของ BlueBubbles สำหรับ localhost หากคุณ proxy ทราฟฟิก Webhook ให้คงรหัสผ่าน BlueBubbles ไว้ในคำขอแบบ end-to-end gateway.trustedProxies ไม่ได้แทนที่ channels.bluebubbles.password ที่นี่ ดู ความปลอดภัยของ Gateway
• เปิดใช้ HTTPS + กฎ firewall บนเซิร์ฟเวอร์ BlueBubbles หากเปิดเผยออกนอก LAN ของคุณ

# การแก้ปัญหา

• หากเหตุการณ์ typing/read หยุดทำงาน ให้ตรวจสอบบันทึก Webhook ของ BlueBubbles และยืนยันว่าพาธ Gateway ตรงกับ channels.bluebubbles.webhookPath
• โค้ด pairing หมดอายุหลังหนึ่งชั่วโมง; ใช้ openclaw pairing list bluebubbles และ openclaw pairing approve bluebubbles <code>
• Reactions ต้องใช้ private API ของ BlueBubbles (POST /api/v1/message/react); ตรวจสอบให้แน่ใจว่าเวอร์ชันเซิร์ฟเวอร์เปิดเผย API นี้
• Edit/unsend ต้องใช้ macOS 13+ และเวอร์ชันเซิร์ฟเวอร์ BlueBubbles ที่เข้ากันได้ บน macOS 26 (Tahoe) ขณะนี้ edit ใช้งานไม่ได้เนื่องจากการเปลี่ยนแปลง private API
• การอัปเดตไอคอนกลุ่มอาจไม่เสถียรบน macOS 26 (Tahoe): API อาจส่งคืนว่าสำเร็จ แต่ไอคอนใหม่ไม่ sync
• OpenClaw จะซ่อนการกระทำที่ทราบว่าเสียโดยอัตโนมัติตามเวอร์ชัน macOS ของเซิร์ฟเวอร์ BlueBubbles หาก edit ยังคงปรากฏบน macOS 26 (Tahoe) ให้ปิดด้วยตนเองโดยใช้ channels.bluebubbles.actions.edit=false
• เปิดใช้ coalesceSameSenderDms แล้ว แต่ split-sends (เช่น Dump + URL) ยังมาถึงเป็นสองรอบ: ดู checklist การแก้ปัญหาการรวม split-send - สาเหตุทั่วไปคือหน้าต่าง debounce แคบเกินไป, อ่าน timestamp ของ session-log ผิดเป็นเวลาที่ Webhook มาถึง, หรือการส่งแบบ reply-quote (ซึ่งใช้ replyToBody ไม่ใช่ Webhook ที่สอง)
• สำหรับข้อมูลสถานะ/สุขภาพ: openclaw status --all หรือ openclaw status --deep

สำหรับอ้างอิง workflow ของแชนเนลทั่วไป โปรดดู แชนเนล และคู่มือ Plugins

# ที่เกี่ยวข้อง

• การกำหนดเส้นทางแชนเนล - การกำหนดเส้นทาง session สำหรับข้อความ
• ภาพรวมแชนเนล - แชนเนลที่รองรับทั้งหมด
• กลุ่ม - พฤติกรรมแชทกลุ่มและการคัดกรองด้วย mention
• Pairing - การยืนยันตัวตน DM และ flow การ pairing
• ความปลอดภัย - โมเดลการเข้าถึงและการเสริมความแข็งแกร่ง