iMessage

وضعیت: یکپارچه‌سازی بومی CLI خارجی. Gateway، imsg rpc را اجرا می‌کند و از طریق JSON-RPC روی stdio ارتباط برقرار می‌کند (بدون daemon/port جداگانه). کنش‌های پیشرفته به imsg launch و یک بررسی موفق 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 وارد حساب شده باشد.
• برای زمینه فرایندی که OpenClaw/imsg را اجرا می‌کند، دسترسی کامل دیسک لازم است (دسترسی به پایگاه داده Messages).
• برای ارسال پیام‌ها از طریق Messages.app، مجوز Automation لازم است.
• برای کنش‌های پیشرفته (واکنش / ویرایش / لغو ارسال / پاسخ رشته‌ای / افکت‌ها / عملیات گروهی)، System Integrity Protection باید غیرفعال باشد — بخش فعال‌سازی API خصوصی imsg را در پایین ببینید. ارسال/دریافت متن و رسانه پایه بدون آن کار می‌کند.

فعال‌سازی API خصوصی imsg

imsg در دو حالت عملیاتی عرضه می‌شود:

• حالت پایه (پیش‌فرض، بدون نیاز به تغییر SIP): متن و رسانه خروجی از طریق send، پایش/تاریخچه ورودی، فهرست گفتگوها. این همان چیزی است که بلافاصله پس از یک brew install steipete/tap/imsg تازه، همراه با مجوزهای استاندارد macOS در بالا، دریافت می‌کنید.
• حالت API خصوصی: imsg یک dylib کمکی را به Messages.app تزریق می‌کند تا توابع داخلی IMCore را فراخوانی کند. این همان چیزی است که react، edit، unsend، reply (رشته‌ای)، sendWithEffect، renameGroup، setGroupIcon، addParticipant، removeParticipant، leaveGroup، به‌علاوه نشانگرهای تایپ و رسیدهای خواندن را فعال می‌کند.

برای رسیدن به سطح کنش پیشرفته‌ای که این صفحه کانال مستند می‌کند، به حالت API خصوصی نیاز دارید. README مربوط به imsg درباره این نیاز صریح است:

قابلیت‌های پیشرفته مانند read، typing، launch، ارسال غنی مبتنی بر bridge، تغییر پیام، و مدیریت گفتگو اختیاری هستند. آن‌ها نیاز دارند SIP غیرفعال باشد و یک dylib کمکی به Messages.app تزریق شود. وقتی SIP فعال باشد، imsg launch از تزریق خودداری می‌کند.

روش تزریق کمکی از dylib خود imsg برای دسترسی به APIهای خصوصی Messages استفاده می‌کند. در مسیر iMessage مربوط به OpenClaw هیچ سرور شخص ثالث یا runtime مربوط به BlueBubbles وجود ندارد.

راه‌اندازی

1. imsg را نصب (یا ارتقا) کنید روی Macی که Messages.app را اجرا می‌کند:

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

   خروجی imsg status --json، bridge_version، rpc_methods و selectors مربوط به هر روش را گزارش می‌کند تا پیش از شروع ببینید build فعلی از چه چیزهایی پشتیبانی می‌کند.

2. System Integrity Protection را غیرفعال کنید. این مورد وابسته به نسخه macOS است، چون نیاز زیربنایی Apple به سیستم‌عامل و سخت‌افزار بستگی دارد:

   • 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 هنگام کلیک روی Continue کلید Left Shift را نگه دارید، سپس csrutil disable. تنظیمات ماشین مجازی مسیر جداگانه‌ای دارند — ابتدا یک snapshot از VM بگیرید.
   • macOS 26 / Tahoe: سیاست‌های library-validation و بررسی‌های مجوز خصوصی imagent سخت‌گیرانه‌تر شده‌اند؛ ممکن است imsg برای همگام ماندن به build به‌روز نیاز داشته باشد. اگر پس از ارتقای عمده macOS، تزریق imsg launch یا selectors خاص شروع به برگرداندن false کردند، پیش از فرض موفق بودن مرحله SIP، یادداشت‌های انتشار imsg را بررسی کنید.

   پیش از اجرای imsg launch، جریان Recovery-mode مربوط به Apple را برای Mac خود دنبال کنید تا SIP را غیرفعال کنید.

3. کمک‌کننده را تزریق کنید. با SIP غیرفعال و Messages.app وارد حساب‌شده:

   imsg launch

   وقتی SIP هنوز فعال باشد، imsg launch از تزریق خودداری می‌کند، بنابراین این فرمان همچنین تأییدی است که مرحله ۲ اثر کرده است.

4. bridge را از OpenClaw بررسی کنید:

   openclaw channels status --probe

   ورودی iMessage باید works گزارش کند، و imsg status --json | jq '.selectors' باید retractMessagePart: true را به‌همراه هر selector ویرایش / تایپ / خواندنی که build macOS شما ارائه می‌دهد نشان دهد. دروازه‌بندی هر روش در Plugin مربوط به OpenClaw در actions.ts فقط کنش‌هایی را تبلیغ می‌کند که selector زیربنایی آن‌ها true باشد، بنابراین سطح کنشی که در فهرست ابزارهای agent می‌بینید بازتاب‌دهنده کاری است که bridge واقعاً می‌تواند روی این میزبان انجام دهد.

اگر openclaw channels status --probe کانال را به‌عنوان works گزارش می‌کند اما کنش‌های مشخص در زمان dispatch خطای "iMessage <action> requires the imsg private API bridge" می‌دهند، imsg launch را دوباره اجرا کنید — کمک‌کننده ممکن است از کار بیفتد (راه‌اندازی مجدد Messages.app، به‌روزرسانی OS و غیره) و وضعیت cache‌شده available: true تا زمانی که بررسی بعدی تازه‌سازی شود، همچنان کنش‌ها را تبلیغ می‌کند.

وقتی نمی‌توانید SIP را غیرفعال کنید

اگر غیرفعال بودن SIP برای مدل تهدید شما قابل قبول نیست:

• imsg به حالت پایه برمی‌گردد — فقط متن + رسانه + دریافت.
• Plugin مربوط به OpenClaw همچنان ارسال متن/رسانه و پایش ورودی را تبلیغ می‌کند؛ فقط react، edit، unsend، reply، sendWithEffect و عملیات گروهی را از سطح کنش پنهان می‌کند (مطابق دروازه قابلیت هر روش).
• می‌توانید برای بار کاری iMessage یک Mac جداگانه غیر Apple-Silicon (یا یک Mac اختصاصی bot) با SIP خاموش اجرا کنید، در حالی که SIP را روی دستگاه‌های اصلی خود فعال نگه می‌دارید. بخش کاربر macOS اختصاصی bot (هویت 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 را داخل DM یا گفتگوی گروهی مجاز اجرا کنید.
• پیام‌های آینده در همان مکالمهٔ iMessage به جلسهٔ ACP ایجادشده مسیریابی می‌شوند.
• /new و /reset همان جلسهٔ ACP متصل را درجا بازنشانی می‌کنند.
• /acp close جلسهٔ ACP را می‌بندد و اتصال را حذف می‌کند.

اتصال‌های پایدار پیکربندی‌شده از طریق ورودی‌های سطح بالای bindings[] با type: "acp" و match.channel: "imessage" پشتیبانی می‌شوند.

match.peer.id می‌تواند از این موارد استفاده کند:

• شناسهٔ نرمال‌شدهٔ DM مانند +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" },    },  ],}

برای رفتار مشترک اتصال ACP، عامل‌های ACP را ببینید.

الگوهای استقرار

{  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 bashexec ssh -T bot@mac-mini.tailnet-1234.ts.net imsg "$@"

رسانه، تکه‌بندی، و هدف‌های تحویل

imsg chats --limit 20

کنش‌های 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,    },  },}

ادغام DMهای ارسال‌شده به‌صورت جداشده (فرمان + URL در یک ترکیب)

وقتی کاربر یک فرمان و یک URL را با هم تایپ می‌کند — مثلاً Dump https://example.com/article — برنامهٔ Messages اپل ارسال را به دو ردیف جداگانهٔ chat.db تقسیم می‌کند:

1. یک پیام متنی ("Dump").
2. یک بالون پیش‌نمایش URL ("https://...") با تصاویر پیش‌نمایش OG به‌عنوان پیوست.

این دو ردیف در بیشتر راه‌اندازی‌ها با فاصله حدود 0.8 تا 2.0 ثانیه به OpenClaw می‌رسند. بدون ادغام، عامل در نوبت 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 پس از بالا آمدن دوباره Gateway از وضعیت فعلی chat.db ادامه می‌دهد؛ هر چیزی که در این فاصله رسیده باشد، به‌صورت پیش‌فرض هرگز دیده نمی‌شود. جبران این پیام‌ها را در راه‌اندازی بعدی بازپخش می‌کند تا عامل بی‌صدا ترافیک ورودی را از دست ندهد.

جبران به‌صورت پیش‌فرض غیرفعال است. آن را برای هر کانال فعال کنید:

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 که imsg watch استفاده می‌کند، بهره می‌برد. هر چیزی که هنگام گذر جبران برسد، طبق معمول از مسیر ارسال زنده عبور می‌کند؛ کش موجود حذف تکرار ورودی، هر همپوشانی با ردیف‌های بازپخش‌شده را جذب می‌کند.

هر ردیف بازپخش‌شده از مسیر ارسال زنده (evaluateIMessageInbound + dispatchInboundMessage) عبور داده می‌شود، بنابراین فهرست‌های مجاز، سیاست گروه، دیبانسر، کش echo، و رسیدهای خواندن برای پیام‌های بازپخش‌شده و زنده رفتار یکسانی دارند.

معناشناسی cursor و تلاش دوباره

جبران برای هر حساب یک cursor در <openclawStateDir>/imessage/catchup/<account>__<hash>.json نگه می‌دارد (دایرکتوری وضعیت OpenClaw به‌صورت پیش‌فرض ~/.openclaw است و با OPENCLAW_STATE_DIR قابل بازنویسی است):

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

• cursor در هر ارسال موفق جلو می‌رود و وقتی ارسال یک ردیف خطا می‌دهد، نگه داشته می‌شود؛ راه‌اندازی بعدی همان ردیف را از cursor نگه‌داشته‌شده دوباره امتحان می‌کند.
• پس از maxFailureRetries خطای پیاپی برای همان guid، جبران یک warn ثبت می‌کند و cursor را به‌اجبار از پیام گیرکرده عبور می‌دهد تا راه‌اندازی‌های بعدی بتوانند پیشرفت کنند.
• guidهایی که از قبل کنار گذاشته شده‌اند در اجراهای بعدی به‌محض دیده‌شدن رد می‌شوند (بدون تلاش برای ارسال) و در خلاصه اجرا زیر 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 را تخلیه نکرده است. اگر فاصله‌های شما مرتباً از گذر پیش‌فرض 50 ردیفی بیشتر می‌شوند، perRunLimit (حداکثر 500) را افزایش دهید.

چه زمانی خاموش بماند

• Gateway به‌صورت پیوسته با راه‌اندازی دوباره خودکار watchdog اجرا می‌شود و فاصله‌ها همیشه کمتر از چند ثانیه‌اند؛ پیش‌فرض خاموش مناسب است.
• حجم DM کم است و پیام‌های ازدست‌رفته رفتار عامل را تغییر نمی‌دهند؛ پنجره اولیه firstRunLookbackMinutes می‌تواند هنگام اولین فعال‌سازی زمینه قدیمی غیرمنتظره‌ای را ارسال کند.

وقتی جبران را روشن می‌کنید، اولین راه‌اندازی بدون 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
• Pairing

مرتبط

• نمای کلی کانال‌ها — همه کانال‌های پشتیبانی‌شده
• حذف BlueBubbles و مسیر imsg iMessage — اعلان و خلاصه مهاجرت
• مهاجرت از BlueBubbles — جدول ترجمه پیکربندی و cutover گام‌به‌گام
• Pairing — احراز هویت DM و جریان pairing
• گروه‌ها — رفتار گفتگوی گروهی و gating بر پایه mention
• مسیریابی کانال — مسیریابی نشست برای پیام‌ها
• امنیت — مدل دسترسی و سخت‌سازی