iMessage

สถานะ: การผสานรวม CLI ภายนอกแบบเนทีฟ Gateway สร้างโปรเซส imsg rpc และสื่อสารผ่าน JSON-RPC บน stdio (ไม่มีดีมอน/พอร์ตแยกต่างหาก) การกระทำขั้นสูงต้องใช้ imsg launch และการตรวจสอบ private API ที่สำเร็จ

ตั้งค่าอย่างรวดเร็ว

brew install steipete/tap/imsgimsg rpc --helpimsg launchopenclaw channels status --probe

{channels: {imessage: {enabled: true,cliPath: "/usr/local/bin/imsg",dbPath: "/Users/user/Library/Messages/chat.db",},},}

openclaw gateway

openclaw pairing list imessageopenclaw pairing approve imessage <CODE>

#!/usr/bin/env bashexec ssh -T gateway-host imsg "$@"

{channels: {imessage: {  enabled: true,  cliPath: "~/.openclaw/scripts/imsg-ssh",  remoteHost: "user@gateway-host", // used for SCP attachment fetches  includeAttachments: true,  // Optional: override allowed attachment roots.  // Defaults include /Users/*/Library/Messages/Attachments  attachmentRoots: ["/Users/*/Library/Messages/Attachments"],  remoteAttachmentRoots: ["/Users/*/Library/Messages/Attachments"],},},}

ข้อกำหนดและสิทธิ์อนุญาต (macOS)

• Messages ต้องลงชื่อเข้าใช้บน Mac ที่เรียกใช้ imsg
• ต้องมี Full Disk Access สำหรับบริบทโปรเซสที่เรียกใช้ OpenClaw/imsg (การเข้าถึงฐานข้อมูล Messages)
• ต้องมีสิทธิ์ Automation เพื่อส่งข้อความผ่าน Messages.app
• สำหรับการกระทำขั้นสูง (react / edit / unsend / threaded reply / effects / group ops) ต้องปิด System Integrity Protection — ดู การเปิดใช้ imsg private API ด้านล่าง การส่ง/รับข้อความพื้นฐานและสื่อใช้งานได้โดยไม่ต้องปิด

การเปิดใช้ imsg private API

imsg มาพร้อมโหมดการทำงานสองโหมด:

• โหมดพื้นฐาน (ค่าเริ่มต้น ไม่ต้องเปลี่ยน SIP): ข้อความและสื่อขาออกผ่าน send, การเฝ้าดู/ประวัติขาเข้า, รายการแชท นี่คือสิ่งที่คุณได้ทันทีจากการติดตั้ง brew install steipete/tap/imsg ใหม่พร้อมสิทธิ์ macOS มาตรฐานด้านบน
• โหมด Private API: imsg ฉีด helper dylib เข้าไปใน Messages.app เพื่อเรียกฟังก์ชัน IMCore ภายใน นี่คือสิ่งที่ปลดล็อก react, edit, unsend, reply (แบบเธรด), sendWithEffect, renameGroup, setGroupIcon, addParticipant, removeParticipant, leaveGroup รวมถึงตัวบ่งชี้การพิมพ์และใบตอบรับการอ่าน

เพื่อเข้าถึงพื้นผิวการกระทำขั้นสูงที่หน้าช่องทางนี้บันทึกไว้ คุณต้องใช้โหมด Private API README ของ imsg ระบุข้อกำหนดไว้อย่างชัดเจน:

ฟีเจอร์ขั้นสูง เช่น read, typing, launch, การส่งแบบ rich ที่หนุนด้วยบริดจ์, การเปลี่ยนแปลงข้อความ และการจัดการแชท เป็นแบบเลือกเปิดใช้ ฟีเจอร์เหล่านี้ต้องปิด SIP และต้องฉีด helper dylib เข้าไปใน Messages.app imsg launch จะปฏิเสธการฉีดเมื่อเปิดใช้ SIP อยู่

เทคนิคการฉีด helper ใช้ dylib ของ imsg เองเพื่อเข้าถึง private API ของ Messages ไม่มีเซิร์ฟเวอร์บุคคลที่สามหรือรันไทม์ BlueBubbles ในเส้นทาง OpenClaw iMessage

การตั้งค่า

1. ติดตั้ง (หรืออัปเกรด) imsg บน Mac ที่เรียกใช้ Messages.app:

   brew install steipete/tap/imsgimsg --versionimsg status --json

   เอาต์พุต imsg status --json รายงาน bridge_version, rpc_methods และ selectors รายเมธอด เพื่อให้คุณเห็นว่าบิลด์ปัจจุบันรองรับอะไรบ้างก่อนเริ่มใช้งาน

2. ปิด System Integrity Protection ขั้นตอนนี้ขึ้นกับเวอร์ชัน macOS เพราะข้อกำหนดของ Apple ที่อยู่เบื้องหลังขึ้นกับ OS และฮาร์ดแวร์:

   • macOS 10.13–10.15 (Sierra–Catalina): ปิด Library Validation ผ่าน Terminal, รีบูตเข้าสู่ Recovery Mode, เรียกใช้ csrutil disable, รีสตาร์ต
   • macOS 11+ (Big Sur และใหม่กว่า), Intel: Recovery Mode (หรือ Internet Recovery), csrutil disable, รีสตาร์ต
   • macOS 11+, Apple Silicon: ลำดับการเริ่มต้นด้วยปุ่มเปิด/ปิดเพื่อเข้าสู่ Recovery; บน macOS เวอร์ชันล่าสุดให้กดปุ่ม Left Shift ค้างไว้เมื่อคลิก Continue แล้วจึง csrutil disable การตั้งค่าเครื่องเสมือนใช้ขั้นตอนแยกต่างหาก — ให้ถ่ายสแนปช็อต VM ก่อน
   • macOS 26 / Tahoe: นโยบาย library-validation และการตรวจสอบ private-entitlement ของ imagent เข้มงวดขึ้นอีก; imsg อาจต้องใช้บิลด์ที่อัปเดตเพื่อให้ตามทัน หากการฉีด imsg launch หรือ selectors เฉพาะเริ่มคืนค่า false หลังจากอัปเกรด macOS รุ่นหลัก ให้ตรวจสอบบันทึกประจำรุ่นของ imsg ก่อนสรุปว่าขั้นตอน SIP สำเร็จ

   ทำตามขั้นตอน Recovery-mode ของ Apple สำหรับ Mac ของคุณเพื่อปิด SIP ก่อนเรียกใช้ imsg launch

3. ฉีด helper เมื่อปิด SIP และ Messages.app ลงชื่อเข้าใช้แล้ว:

   imsg launch

   imsg launch จะปฏิเสธการฉีดเมื่อ SIP ยังเปิดอยู่ ดังนั้นคำสั่งนี้จึงใช้ยืนยันได้ด้วยว่าขั้นตอนที่ 2 มีผลแล้ว

4. ตรวจสอบบริดจ์จาก OpenClaw:

   openclaw channels status --probe

   รายการ iMessage ควรรายงาน works และ imsg status --json | jq '.selectors' ควรแสดง retractMessagePart: true พร้อมกับ selector สำหรับ edit / typing / read ใด ๆ ที่บิลด์ macOS ของคุณเปิดเผย การกั้นตามเมธอดของ Plugin OpenClaw ใน actions.ts จะโฆษณาเฉพาะการกระทำที่ selector พื้นฐานเป็น true ดังนั้นพื้นผิวการกระทำที่คุณเห็นในรายการเครื่องมือของเอเจนต์จะสะท้อนสิ่งที่บริดจ์ทำได้จริงบนโฮสต์นี้

หาก openclaw channels status --probe รายงานว่าช่องทางเป็น works แต่การกระทำเฉพาะโยนข้อผิดพลาด "iMessage <action> requires the imsg private API bridge" ขณะ dispatch ให้เรียกใช้ imsg launch อีกครั้ง — helper อาจหลุดออกไปได้ (Messages.app รีสตาร์ต, อัปเดต OS ฯลฯ) และสถานะ available: true ที่แคชไว้จะยังคงโฆษณาการกระทำจนกว่าการ probe ครั้งถัดไปจะรีเฟรช

เมื่อคุณปิด SIP ไม่ได้

หากการปิด SIP ไม่เป็นที่ยอมรับสำหรับโมเดลภัยคุกคามของคุณ:

• imsg จะถอยกลับไปใช้โหมดพื้นฐาน — ข้อความ + สื่อ + การรับเท่านั้น
• Plugin OpenClaw ยังคงโฆษณาการส่งข้อความ/สื่อและการเฝ้าดูขาเข้า เพียงแต่ซ่อน react, edit, unsend, reply, sendWithEffect และ group ops จากพื้นผิวการกระทำ (ตามการกั้นความสามารถรายเมธอด)
• คุณสามารถเรียกใช้ Mac ที่ไม่ใช่ Apple Silicon แยกต่างหาก (หรือ Mac สำหรับบอตโดยเฉพาะ) โดยปิด SIP สำหรับภาระงาน iMessage ในขณะที่ยังคงเปิด SIP บนอุปกรณ์หลักของคุณ ดู ผู้ใช้ macOS สำหรับบอตโดยเฉพาะ (ตัวตน iMessage แยกต่างหาก) ด้านล่าง

การควบคุมการเข้าถึงและการกำหนดเส้นทาง

{  channels: {    imessage: {      groupPolicy: "allowlist",      groupAllowFrom: ["+15555550123"],      groups: {        "*": { systemPrompt: "Use British spelling." },        "8421": {          requireMention: true,          systemPrompt: "This is the on-call rotation chat. Keep replies under 3 sentences.",        },        "9907": {          // explicit suppression: the wildcard "Use British spelling." does not apply here          systemPrompt: "",        },      },    },  },}

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

แชต iMessage แบบเดิมยังสามารถผูกกับเซสชัน ACP ได้ด้วย

โฟลว์ผู้ปฏิบัติงานแบบเร็ว:

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

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

match.peer.id สามารถใช้:

• แฮนเดิลข้อความโดยตรงที่ทำให้เป็นมาตรฐานแล้ว เช่น +15555550123 หรือ [email protected]
• 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: "imessage",        accountId: "default",        peer: { kind: "group", id: "chat_id:123" },      },      acp: { label: "codex-group" },    },  ],}

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

รูปแบบการดีพลอย

{  channels: {    imessage: {      enabled: true,      cliPath: "~/.openclaw/scripts/imsg-ssh",      remoteHost: "[email protected]",      includeAttachments: true,      dbPath: "/Users/bot/Library/Messages/chat.db",    },  },}

#!/usr/bin/env bashexec ssh -T [email protected] imsg "$@"

สื่อ การแบ่งชิ้น และเป้าหมายการส่งมอบ

imsg chats --limit 20

แอ็กชัน Private API

เมื่อ imsg launch กำลังทำงานและ openclaw channels status --probe รายงาน privateApi.available: true เครื่องมือข้อความสามารถใช้แอ็กชันเนทีฟของ iMessage เพิ่มเติมจากการส่งข้อความปกติได้

{  channels: {    imessage: {      actions: {        reactions: true,        edit: true,        unsend: true,        reply: true,        sendWithEffect: true,        sendAttachment: true,        renameGroup: true,        setGroupIcon: true,        addParticipant: true,        removeParticipant: true,        leaveGroup: true,      },    },  },}

{  channels: {    imessage: {      sendReadReceipts: false,    },  },}

การเขียนการกำหนดค่า

iMessage อนุญาตให้ช่องทางเริ่มการเขียนการกำหนดค่าได้โดยค่าเริ่มต้น (สำหรับ /config set|unset เมื่อ commands.config: true)

ปิดใช้งาน:

{  channels: {    imessage: {      configWrites: false,    },  },}

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

เมื่อผู้ใช้พิมพ์คำสั่งและ URL พร้อมกัน — เช่น Dump https://example.com/article — แอป Messages ของ Apple จะแยกการส่งออกเป็น สองแถว chat.db แยกกัน:

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

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

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

{  channels: {    imessage: {      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).        imessage: 2500,      },    },  },}

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

การตามข้อความหลัง Gateway หยุดทำงาน

เมื่อ Gateway ออฟไลน์ (แครช รีสตาร์ท Mac เข้าสู่โหมดพัก เครื่องปิด) imsg watch จะกลับมาทำงานต่อจากสถานะ chat.db ปัจจุบันเมื่อ Gateway กลับขึ้นมา — ตามค่าเริ่มต้น สิ่งใดก็ตามที่เข้ามาในช่วงขาดหายจะไม่ถูกเห็นเลย การตามข้อความย้อนหลังจะเล่นซ้ำข้อความเหล่านั้นในการเริ่มต้นครั้งถัดไป เพื่อให้เอเจนต์ไม่พลาด traffic ขาเข้าโดยไม่รู้ตัว

การตามข้อความย้อนหลังถูก ปิดไว้ตามค่าเริ่มต้น เปิดใช้เป็นรายช่องทาง:

channels: {  imessage: {    catchup: {      enabled: true,             // master switch (default: false)      maxAgeMinutes: 120,        // skip rows older than now - 2h (default: 120, clamp 1..720)      perRunLimit: 50,           // max rows replayed per startup (default: 50, clamp 1..500)      firstRunLookbackMinutes: 30, // first run with no cursor: look back 30 min (default: 30)      maxFailureRetries: 10,     // give up on a wedged guid after 10 dispatch failures (default: 10)    },  },}

วิธีทำงาน

ทำงานหนึ่งรอบต่อการเริ่มต้น monitorIMessageProvider แต่ละครั้ง โดยเรียงลำดับเป็น imsg launch พร้อม → watch.subscribe → performIMessageCatchup → วนลูปส่งต่อสด ตัวการตามข้อความย้อนหลังเองใช้ chats.list + messages.history รายแชทผ่าน JSON-RPC client เดียวกับที่ imsg watch ใช้ สิ่งใดก็ตามที่เข้ามาระหว่างรอบการตามข้อความย้อนหลังจะไหลผ่านการส่งต่อสดตามปกติ cache inbound-dedupe ที่มีอยู่จะดูดซับส่วนที่ซ้อนทับกับแถวที่เล่นซ้ำ

แต่ละแถวที่เล่นซ้ำจะถูกป้อนผ่านเส้นทางการส่งต่อสด (evaluateIMessageInbound + dispatchInboundMessage) ดังนั้นรายการอนุญาต นโยบายกลุ่ม debouncer echo cache และใบยืนยันการอ่านจะทำงานเหมือนกันทั้งกับข้อความที่เล่นซ้ำและข้อความสด

ความหมายของ cursor และการ retry

การตามข้อความย้อนหลังเก็บ cursor รายบัญชีไว้ที่ <openclawStateDir>/imessage/catchup/<account>__<hash>.json (ไดเรกทอรีสถานะ OpenClaw มีค่าเริ่มต้นเป็น ~/.openclaw และ override ได้ด้วย OPENCLAW_STATE_DIR):

{  "lastSeenMs": 1717900800000,  "lastSeenRowid": 482910,  "updatedAt": 1717900801234,  "failureRetries": { "<guid>": 1 }}

• cursor จะเลื่อนไปข้างหน้าหลัง dispatch สำเร็จแต่ละครั้ง และจะค้างไว้เมื่อ dispatch ของแถว throw — การเริ่มต้นครั้งถัดไปจะลองแถวเดิมอีกครั้งจาก cursor ที่ค้างไว้
• หลังจาก throw ติดต่อกัน maxFailureRetries ครั้งกับ guid เดียวกัน การตามข้อความย้อนหลังจะบันทึก warn และบังคับเลื่อน cursor ข้ามข้อความที่ติดค้าง เพื่อให้การเริ่มต้นครั้งต่อ ๆ ไปเดินหน้าต่อได้
• guid ที่ยอมแพ้ไปแล้วจะถูกข้ามทันทีที่พบ (ไม่มีความพยายาม dispatch) ในการรันภายหลัง และถูกนับใต้ skippedGivenUp ในสรุปการรัน

สัญญาณที่ผู้ปฏิบัติการเห็นได้

imessage catchup: replayed=N skippedFromMe=… skippedGivenUp=… failed=… givenUp=… fetchedCount=…imessage catchup: giving up on guid=<guid> after &lt;N&gt; failures; advancing cursor past itimessage catchup: fetched &lt;X&gt; rows across chats, capped to perRunLimit=&lt;Y&gt;

บรรทัด WARN ... capped to perRunLimit หมายความว่าการเริ่มต้นครั้งเดียวไม่ได้ระบาย backlog ทั้งหมด เพิ่ม perRunLimit (สูงสุด 500) หากช่วงขาดหายของคุณเกินการผ่านค่าเริ่มต้น 50 แถวเป็นประจำ

เมื่อใดควรปล่อยให้ปิดไว้

• Gateway ทำงานต่อเนื่องพร้อม watchdog รีสตาร์ทอัตโนมัติ และช่วงขาดหายมัก < สองสามวินาที — ค่าเริ่มต้นที่ปิดไว้ก็เพียงพอ
• ปริมาณ DM ต่ำ และข้อความที่พลาดไปจะไม่เปลี่ยนพฤติกรรมของเอเจนต์ — หน้าต่างเริ่มต้น firstRunLookbackMinutes อาจ dispatch บริบทเก่าที่ไม่คาดคิดเมื่อเปิดใช้ครั้งแรก

เมื่อคุณเปิดใช้การตามข้อความย้อนหลัง การเริ่มต้นครั้งแรกที่ยังไม่มี cursor จะมองย้อนหลังแค่ firstRunLookbackMinutes (ค่าเริ่มต้น 30 นาที) ไม่ใช่หน้าต่าง maxAgeMinutes ทั้งหมด — วิธีนี้หลีกเลี่ยงการเล่นซ้ำประวัติยาว ๆ ของข้อความก่อนเปิดใช้

การแก้ปัญหา

imsg rpc --helpimsg status --jsonopenclaw channels status --probe

#!/usr/bin/env bashexec ssh -T messages-mac imsg "$@"

openclaw channels status --probe --channel imessage

imsg chats --limit 1imsg send <handle> "test"

ตัวชี้ไปยังเอกสารอ้างอิงการกำหนดค่า

• เอกสารอ้างอิงการกำหนดค่า - iMessage
• การกำหนดค่า Gateway
• การจับคู่

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

• ภาพรวมช่องทาง — ช่องทางที่รองรับทั้งหมด
• การนำ BlueBubbles ออกและพาธ iMessage ของ imsg — ประกาศและสรุปการย้าย
• ย้ายมาจาก BlueBubbles — ตารางแปลงการกำหนดค่าและขั้นตอนการเปลี่ยนระบบทีละขั้นตอน
• การจับคู่ — การยืนยันตัวตน DM และ flow การจับคู่
• กลุ่ม — พฤติกรรมแชทกลุ่มและการควบคุมด้วยการกล่าวถึง
• การกำหนดเส้นทางช่องทาง — การกำหนดเส้นทาง session สำหรับข้อความ
• ความปลอดภัย — โมเดลการเข้าถึงและการเสริมความแข็งแกร่ง