iMessage

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.

​

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

brew install steipete/tap/imsg
imsg rpc --help
imsg launch
openclaw channels status --probe

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

openclaw gateway

openclaw pairing list imessage
openclaw pairing approve imessage <CODE>

#!/usr/bin/env bash
exec 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 chats --limit 1
# or
imsg send <handle> "test"

​

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

• โหมดพื้นฐาน (ค่าเริ่มต้น ไม่ต้องเปลี่ยน 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 รวมถึงตัวบ่งชี้การพิมพ์และใบตอบรับการอ่าน

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

​

การตั้งค่า

1. ติดตั้ง (หรืออัปเกรด) imsg บน Mac ที่เรียกใช้ Messages.app:
   brew install steipete/tap/imsg
   imsg --version
   imsg 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 ดังนั้นพื้นผิวการกระทำที่คุณเห็นในรายการเครื่องมือของเอเจนต์จะสะท้อนสิ่งที่บริดจ์ทำได้จริงบนโฮสต์นี้

​

เมื่อคุณปิด 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: { "*": { "requireMention": true } },
    },
  },
}

{
  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

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

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

​

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

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "~/.openclaw/scripts/imsg-ssh",
      remoteHost: "bot@mac-mini.tailnet-1234.ts.net",
      includeAttachments: true,
      dbPath: "/Users/bot/Library/Messages/chat.db",
    },
  },
}

#!/usr/bin/env bash
exec ssh -T bot@mac-mini.tailnet-1234.ts.net imsg "$@"

​

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

imsg chats --limit 20

​

แอ็กชัน Private API

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

​

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

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

​

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

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

{
  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 หยุดทำงาน

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

​

วิธีทำงาน

​

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

{
  "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 <N> failures; advancing cursor past it
imessage catchup: fetched <X> rows across chats, capped to perRunLimit=<Y>

​

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

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

​

การแก้ปัญหา

imsg rpc --help
imsg status --json
openclaw channels status --probe

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

openclaw channels status --probe --channel imessage

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

​

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

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

​

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

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