ย้ายมาจาก BlueBubbles

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

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

​

รายการตรวจสอบการย้าย

1. ตรวจสอบ imsg โดยตรงบน Mac ที่รัน Messages.app (imsg chats, imsg history, imsg send และ imsg rpc --help)
2. คัดลอกคีย์พฤติกรรมจาก channels.bluebubbles ไปยัง channels.imessage: dmPolicy, allowFrom, groupPolicy, groupAllowFrom, groups, includeAttachments, attachmentRoots, mediaMaxMb, textChunkLimit, coalesceSameSenderDms และ actions
3. ลบคีย์การขนส่งที่ไม่มีอยู่แล้ว: serverUrl, password, URL ของ Webhook และการตั้งค่าเซิร์ฟเวอร์ BlueBubbles
4. หาก Gateway ไม่ได้รันอยู่บน Messages Mac ให้ตั้งค่า channels.imessage.cliPath เป็น SSH wrapper และตั้งค่า remoteHost สำหรับการดึงไฟล์แนบระยะไกล
5. เมื่อหยุด Gateway แล้ว ให้เปิดใช้ channels.imessage จากนั้นรัน openclaw channels status --probe --channel imessage
6. ทดสอบ DM หนึ่งรายการ กลุ่มที่อนุญาตหนึ่งกลุ่ม ไฟล์แนบหากเปิดใช้ และการดำเนินการ private API ทุกอย่างที่คุณคาดว่าเอเจนต์จะใช้
7. ลบเซิร์ฟเวอร์ BlueBubbles และ config channels.bluebubbles เก่าหลังจากตรวจสอบเส้นทาง iMessage แล้ว

​

เมื่อการย้ายนี้เหมาะสม

• คุณรัน imsg อยู่แล้วบน Mac เครื่องเดียวกัน (หรือเครื่องที่เข้าถึงได้ผ่าน SSH) ซึ่ง Messages.app ลงชื่อเข้าใช้อยู่
• คุณต้องการลดชิ้นส่วนที่ต้องดูแลลงหนึ่งอย่าง — ไม่มีเซิร์ฟเวอร์ BlueBubbles แยกต่างหาก ไม่มี REST endpoint ที่ต้องยืนยันตัวตน ไม่มีงานเดินท่อ Webhook ใช้ไบนารี CLI เดียวแทนเซิร์ฟเวอร์ + แอปไคลเอนต์ + helper
• คุณอยู่บน macOS / บิลด์ imsg ที่รองรับ ซึ่ง probe ของ private API รายงาน available: true

​

imsg ทำอะไร

• การอ่านมาจาก ~/Library/Messages/chat.db โดยใช้ handle SQLite แบบอ่านอย่างเดียว
• ข้อความขาเข้าแบบสดมาจาก imsg watch / watch.subscribe ซึ่งติดตาม event ของระบบไฟล์ chat.db พร้อม fallback แบบ polling
• การส่งใช้ระบบอัตโนมัติของ Messages.app สำหรับการส่งข้อความและไฟล์ปกติ
• การดำเนินการขั้นสูงใช้ imsg launch เพื่อฉีด helper ของ imsg เข้าไปใน Messages.app นี่คือสิ่งที่ปลดล็อก read receipts, typing indicators, rich sends, edit, unsend, threaded reply, tapbacks และการจัดการกลุ่ม
• บิลด์ Linux สามารถตรวจสอบ chat.db ที่คัดลอกมาได้ แต่ไม่สามารถส่ง ดูฐานข้อมูล Mac แบบสด หรือขับเคลื่อน Messages.app ได้ สำหรับ OpenClaw iMessage ให้รัน imsg บน Mac ที่ลงชื่อเข้าใช้แล้วหรือผ่าน SSH wrapper ไปยัง Mac เครื่องนั้น

​

ก่อนเริ่มต้น

1. ติดตั้ง imsg บน Mac ที่รัน Messages.app:
   brew install steipete/tap/imsg
   imsg --version
   imsg chats --limit 3
   
   หาก imsg chats ล้มเหลวด้วย unable to open database file, เอาต์พุตว่างเปล่า หรือ authorization denied ให้มอบสิทธิ์ Full Disk Access แก่ terminal, editor, Node process, Gateway service หรือ SSH parent process ที่เปิด imsg จากนั้นเปิด parent process นั้นใหม่
2. ตรวจสอบพื้นผิวการอ่าน การ watch การส่ง และ RPC ก่อนเปลี่ยน config ของ OpenClaw:
   imsg chats --limit 10 --json | jq -s
   imsg history --chat-id 42 --limit 10 --attachments --json | jq -s
   imsg watch --chat-id 42 --reactions --json
   imsg send --chat-id 42 --text "OpenClaw imsg test"
   imsg rpc --help
   
   แทนที่ 42 ด้วย chat id จริงจาก imsg chats การส่งต้องใช้สิทธิ์ Automation สำหรับ Messages.app หาก OpenClaw จะรันผ่าน SSH ให้รันคำสั่งเหล่านี้ผ่าน SSH wrapper หรือบริบทผู้ใช้เดียวกับที่ OpenClaw จะใช้
3. เปิดใช้ bridge ของ private API เมื่อคุณต้องการการดำเนินการขั้นสูง:
   imsg launch
   imsg status --json
   
   imsg launch ต้องปิดใช้ SIP การส่งพื้นฐาน ประวัติ และ watch ทำงานได้โดยไม่ต้องมี imsg launch; การดำเนินการขั้นสูงทำไม่ได้
4. หลังจากคุณเพิ่ม config channels.imessage ที่เปิดใช้งานแล้ว ให้ตรวจสอบ bridge ผ่าน OpenClaw:
   openclaw channels status --probe
   
   คุณต้องการ imessage.privateApi.available: true หากรายงานเป็น false ให้แก้สิ่งนั้นก่อน — ดู การตรวจจับความสามารถ channels status --probe จะ probe เฉพาะบัญชีที่กำหนดค่าและเปิดใช้งานแล้วเท่านั้น
5. สำรอง snapshot ของ config:
   cp ~/.openclaw/openclaw.json5 ~/.openclaw/openclaw.json5.bak
   

​

การแปล config

​

กับดัก group registry

1. allowlist ของผู้ส่ง / เป้าหมายแชต (channels.imessage.groupAllowFrom) — ตรวจโดย isAllowedIMessageSender จับคู่ข้อความขาเข้าตาม handle ผู้ส่ง, chat_guid, chat_identifier, หรือ chat_id รูปทรงเดียวกับ BlueBubbles
2. group registry (channels.imessage.groups) — ตรวจโดย resolveChannelGroupPolicy จาก inbound-processing.ts:199 เมื่อใช้ groupPolicy: "allowlist" gate นี้ต้องมีอย่างใดอย่างหนึ่ง:
   • รายการ wildcard groups: { "*": { ... } } (ตั้งค่า allowAll = true) หรือ
   • รายการต่อ chat_id ที่ชัดเจนใต้ groups

• warn ตอนเริ่มต้นหนึ่งครั้งต่อบัญชี เมื่อมีการตั้งค่า groupPolicy: "allowlist" แต่ channels.imessage.groups ว่างเปล่า (ไม่มี wildcard "*", ไม่มีรายการต่อ chat_id) — ทำงานก่อนที่ข้อความใด ๆ จะเข้ามา
• warn หนึ่งครั้งต่อ chat_id ในครั้งแรกที่กลุ่มใดกลุ่มหนึ่งถูกทิ้งตอน runtime โดยระบุ chat_id และคีย์ที่แน่นอนที่ต้องเพิ่มใน groups เพื่ออนุญาต

{
  channels: {
    imessage: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15555550123", "chat_guid:any;-;..."],
      groups: {
        "*": { requireMention: true },
      },
    },
  },
}

​

ทีละขั้นตอน

1. เพิ่มบล็อก iMessage ข้างบล็อก BlueBubbles ที่มีอยู่ ปิดใช้งานไว้ระหว่างที่ Gateway ยัง route traffic ของ BlueBubbles:
   {
     channels: {
       bluebubbles: {
         enabled: true,
         // ... existing config ...
       },
       imessage: {
         enabled: false,
         cliPath: "/opt/homebrew/bin/imsg",
         dmPolicy: "pairing",
         allowFrom: ["+15555550123"], // copy from bluebubbles.allowFrom
         groupPolicy: "allowlist",
         groupAllowFrom: [], // copy from bluebubbles.groupAllowFrom
         groups: { "*": { requireMention: true } }, // copy from bluebubbles.groups — silently drops groups if missing, see "Group registry footgun" above
         actions: {
           reactions: true,
           edit: true,
           unsend: true,
           reply: true,
           sendWithEffect: true,
           sendAttachment: true,
         },
       },
     },
   }
   
2. ตรวจสอบก่อน traffic มีความสำคัญ — หยุด Gateway, เปิดใช้งานบล็อก iMessage ชั่วคราว และยืนยันว่า iMessage รายงานสถานะปกติจาก CLI:
   openclaw gateway stop
   # edit config: channels.imessage.enabled = true
   openclaw channels status --probe --channel imessage   # expect imessage.privateApi.available: true
   
   channels status --probe ตรวจสอบเฉพาะบัญชีที่กำหนดค่าและเปิดใช้งานแล้วเท่านั้น อย่ารีสตาร์ท Gateway โดยเปิดใช้ทั้ง BlueBubbles และ iMessage พร้อมกัน เว้นแต่ว่าคุณตั้งใจให้ตัว monitor ของทั้งสองช่องทางทำงานอยู่ หากยังไม่ได้ cut over ทันที ให้ตั้งค่า channels.imessage.enabled กลับเป็น false ก่อนรีสตาร์ท Gateway ใช้คำสั่ง imsg โดยตรงใน ก่อนเริ่มต้น เพื่อตรวจสอบ Mac ก่อนเปิดใช้ traffic ของ OpenClaw
3. Cut over เมื่อบัญชี iMessage ที่เปิดใช้งานรายงานสถานะปกติแล้ว ให้ลบ config ของ BlueBubbles และเปิดใช้ iMessage ต่อไป:
   {
     channels: {
       imessage: { enabled: true /* ... */ },
     },
   }
   
   รีสตาร์ท Gateway ตอนนี้ traffic ขาเข้าของ iMessage จะไหลผ่าน Plugin ที่บันเดิลมา
4. ตรวจสอบ DM ส่งข้อความตรงไปยัง agent แล้วยืนยันว่ามี reply กลับมา
5. ตรวจสอบกลุ่มแยกต่างหาก DM และกลุ่มใช้ code path ต่างกัน ความสำเร็จของ DM ไม่ได้พิสูจน์ว่ากลุ่ม route ได้ ส่งข้อความถึง agent ใน group chat ที่ pair แล้ว และยืนยันว่ามี reply กลับมา หากกลุ่มเงียบไป (ไม่มี reply จาก agent, ไม่มี error) ให้ตรวจ log ของ Gateway สำหรับ imessage: dropping group message from chat_id=<id> หรือบรรทัดตอนเริ่มต้น imessage: groupPolicy="allowlist" but channels.imessage.groups is empty ทั้งสองจะแสดงที่ระดับ log เริ่มต้น หากมีบรรทัดใดปรากฏ แสดงว่าบล็อก groups ของคุณหายไปหรือว่างอยู่ โปรดดู “Group registry footgun” ด้านบน
6. ตรวจสอบพื้นผิว action — จาก DM ที่ pair แล้ว ให้ขอให้ agent react, edit, unsend, reply, ส่งรูปภาพ และ (ในกลุ่ม) เปลี่ยนชื่อกลุ่ม / เพิ่มหรือลบผู้เข้าร่วม แต่ละ action ควรไปถึง Messages.app แบบ native หากรายการใดโยน “iMessage <action> requires the imsg private API bridge” ให้รัน imsg launch อีกครั้งแล้ว refresh channels status --probe
7. ลบเซิร์ฟเวอร์และ config ของ BlueBubbles เมื่อยืนยัน DM, กลุ่ม และ action ของ iMessage แล้ว OpenClaw จะไม่ใช้ channels.bluebubbles

​

ภาพรวมความเท่าเทียมของ action

​

การ pairing, session และ binding ของ ACP

• การอนุมัติ pairing จะตามไปด้วยตาม handle คุณไม่จำเป็นต้องอนุมัติผู้ส่งที่รู้จักอีกครั้ง channels.imessage.allowFrom รู้จักสตริง +15555550123 / user@example.com เดียวกับที่ BlueBubbles ใช้
• Session ยังคง scoped ต่อ agent + chat DM จะยุบเข้าเป็น session หลักของ agent ภายใต้ค่าเริ่มต้น session.dmScope=main; session ของกลุ่มยังคงแยกตาม chat_id key ของ session ต่างกัน (agent:<id>:imessage:group:<chat_id> เทียบกับค่าที่เทียบเท่าของ BlueBubbles) ประวัติการสนทนาเดิมภายใต้ key ของ session BlueBubbles จะไม่ย้ายเข้ามาใน session ของ iMessage
• binding ของ ACP ที่อ้างถึง match.channel: "bluebubbles" ต้องอัปเดตเป็น "imessage" รูปแบบ match.peer.id (chat_id:, chat_guid:, chat_identifier:, handle เปล่า) เหมือนกัน

​

ไม่มีช่องทาง rollback

​

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

• การลบ BlueBubbles และ path iMessage ของ imsg — ประกาศสั้นและสรุปสำหรับ operator
• iMessage — เอกสารอ้างอิงช่องทาง iMessage ฉบับเต็ม รวมถึงการตั้งค่า imsg launch และการตรวจจับ capability
• /channels/bluebubbles — URL legacy ที่ redirect ไปยังคู่มือ migration นี้
• Pairing — การยืนยันตัวตน DM และ flow การ pairing
• Channel Routing — วิธีที่ Gateway เลือกช่องทางสำหรับ reply ขาออก