iMessage

​

الإعداد السريع

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.
• للإجراءات المتقدمة (التفاعل / التحرير / إلغاء الإرسال / الرد المتسلسل / التأثيرات / الاستطلاعات / عمليات المجموعات)، يجب تعطيل System Integrity Protection — راجع تفعيل API الخاص لـ imsg أدناه. يعمل إرسال/استقبال النصوص والوسائط الأساسي من دونه.

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

Not authorized to send Apple events to Messages. (-1743)

kTCCServiceAppleEvents | /usr/libexec/sshd-keygen-wrapper | auth_value=0 | com.apple.MobileSMS

​

تفعيل API الخاص لـ imsg

• الوضع الأساسي (افتراضي، لا حاجة إلى تغييرات SIP): النصوص والوسائط الصادرة عبر send، ومراقبة/سجل الوارد، وقائمة المحادثات. هذا ما تحصل عليه مباشرة من تثبيت brew install steipete/tap/imsg جديد مع أذونات macOS القياسية أعلاه.
• وضع API الخاص: يحقن imsg مكتبة dylib مساعدة في Messages.app لاستدعاء دوال IMCore داخلية. هذا ما يفعّل react وedit وunsend وreply (المتسلسل)، وsendWithEffect، وpoll وpoll-vote (استطلاعات Messages الأصلية)، وrenameGroup، وsetGroupIcon، وaddParticipant، وremoveParticipant، وleaveGroup، بالإضافة إلى مؤشرات الكتابة وإيصالات القراءة.

الميزات المتقدمة مثل read وtyping وlaunch والإرسال الغني المدعوم بالجسر وتعديل الرسائل وإدارة المحادثات اختيارية. تتطلب تعطيل SIP وحقن مكتبة 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 الحديث) Library Validation. يتطلب حقن مكتبة dylib مساعدة غير تابعة لـ Apple داخل Messages.app الموقّع من Apple إيقاف SIP و تخفيف library validation. خطوة SIP في وضع Recovery خاصة بإصدار macOS:
   • 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 11 والأحدث، لا يكون csrutil disable وحده كافيًا عادةً. لا تزال Apple تفرض library validation على Messages.app باعتباره ثنائيًا للنظام الأساسي، لذلك تُرفض مكتبة مساعدة موقعة adhoc (Library Validation failed: ... platform binary, but mapped file is not) حتى مع إيقاف SIP. بعد تعطيل SIP، عطّل library validation أيضًا وأعد التشغيل:
   sudo defaults write /Library/Preferences/com.apple.security.libraryvalidation.plist DisableLibraryValidation -bool true
   
   macOS 26 (Tahoe)، تم التحقق على 26.5.1: إيقاف SIP مع أمر DisableLibraryValidation أعلاه كافيان لحقن المساعد عبر 26.0 حتى 26.5.x. لا حاجة إلى boot-args. ملف plist هو العامل الحاسم والخطوة الأكثر شيوعًا التي تنقص عند فشل الحقن على Tahoe:
   • مع plist: يحقن imsg launch ويعرض imsg status القيمة advanced_features: true.
   • من دون plist (حتى مع إيقاف SIP): يفشل imsg launch بالرسالة Failed to launch: Timeout waiting for Messages.app to initialize. ترفض AMFI تحميل المساعد الموقّع adhoc، لذلك لا يصبح الجسر جاهزًا أبدًا وتنتهي عملية التشغيل بالمهلة. هذه المهلة هي العرض الأكثر شيوعًا على Tahoe، والإصلاح هو plist أعلاه، وليس أي إجراء أشد.
   تم تأكيد ذلك بمقارنة مضبوطة قبل/بعد على macOS 26.5.1 (Apple Silicon): مع plist، تُحمّل dylib داخل Messages.app ويعمل الجسر؛ أزل plist وأعد التشغيل، وسيُنتج imsg launch فشل المهلة أعلاه من دون تحميل dylib. إذا بدأ حقن imsg launch أو بدأت selectors معيّنة تُرجع false بعد ترقية macOS، فهذه البوابة هي السبب المعتاد. تحقّق من حالة SIP والتحقق من المكتبات قبل افتراض أن خطوة SIP نفسها فشلت. إذا كانت هذه الإعدادات صحيحة وما زال الجسر غير قادر على الحقن، فاجمع imsg status --json مع خرج imsg launch وأبلغ مشروع imsg بذلك بدلاً من إضعاف عناصر تحكم أمان إضافية على مستوى النظام. اتبع مسار Apple في وضع الاسترداد لجهاز Mac لديك لتعطيل SIP قبل تشغيل imsg launch.
3. احقن المساعد. مع تعطيل SIP وتسجيل الدخول إلى Messages.app:
   imsg launch
   
   يرفض imsg launch الحقن عندما يظل SIP مفعلاً، لذلك يعمل هذا أيضاً كتأكيد على نجاح الخطوة 2.
4. تحقّق من الجسر من OpenClaw:
   openclaw channels status --probe
   
   يجب أن يُبلغ إدخال iMessage عن works، ويجب أن يُظهر imsg status --json | jq '{rpc_methods, selectors}' القدرات التي يتيحها بناء macOS لديك. يتطلب إنشاء الاستطلاعات selectors.pollPayloadMessage؛ ويتطلب التصويت كلاً من selectors.pollVoteMessage وطريقة RPC poll.vote. لا يعلن Plugin الخاص بـ OpenClaw إلا عن الإجراءات التي يدعمها الفحص المخزن مؤقتاً، بينما تبقى الذاكرة المؤقتة الفارغة متفائلة وتفحص عند أول إرسال.

​

عندما لا يمكنك تعطيل SIP

• يعود imsg إلى الوضع الأساسي — النص + الوسائط + الاستقبال فقط.
• يظل Plugin الخاص بـ OpenClaw يعلن إرسال النص/الوسائط والمراقبة الواردة؛ لكنه يخفي فقط react وedit وunsend وreply وsendWithEffect وعمليات المجموعات من سطح الإجراءات (وفقاً لبوابة القدرة لكل طريقة).
• يمكنك تشغيل 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

​

إجراءات 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,
        polls: true,
      },
    },
  },
}

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

​

عمليات كتابة الإعدادات

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

​

دمج الرسائل المباشرة ذات الإرسال المقسم (أمر + URL في إنشاء واحد)

1. رسالة نصية ("Dump").
2. بالون معاينة URL ("https://...") مع صور معاينة OG كمرفقات.

{
  channels: {
    imessage: {
      coalesceSameSenderDms: true, // opt in (default: false)
    },
  },
}

{
  messages: {
    inbound: {
      byChannel: {
        // 7000 ms covers observed Messages.app URL-preview delays.
        imessage: 7000,
      },
    },
  },
}

​

السيناريوهات وما يراه الوكيل

​

استرداد الوارد بعد إعادة تشغيل الجسر أو Gateway

• إزالة تكرار إعادة التشغيل. تُسجل كل رسالة واردة مُرسلة بواسطة Apple GUID الخاص بها في حالة Plugin الدائمة (imessage.inbound-dedupe)، وتُحجز عند الإدخال وتُثبت بعد المعالجة (وتُحرر عند فشل عابر حتى يمكن إعادة المحاولة). يُسقط أي شيء عولج مسبقًا بدلًا من إرساله مرتين. هذا ما يسمح لإعادة الاسترداد بأن تكون عدوانية بلا تتبع لكل رسالة.
• استرداد وقت التعطل. عند بدء التشغيل، يتذكر المراقب آخر chat.db rowid مُرسل (مؤشر مستمر لكل حساب) ويمرره إلى imsg watch.subscribe باسم since_rowid، بحيث يعيد imsg تشغيل الصفوف التي وصلت أثناء تعطل Gateway، ثم يتابع المباشر. إعادة التشغيل محدودة بأحدث الصفوف وبالرسائل التي يصل عمرها إلى ~ساعتين، وتُسقط إزالة التكرار أي شيء عولج مسبقًا.
• سياج عمر السجل المتراكم القديم. الصفوف فوق حد بدء التشغيل مباشرة بالفعل؛ أما الصف الذي يكون تاريخ إرساله أقدم من وصوله بأكثر من ~15 دقيقة فهو سجل Push المتراكم المفرغ ويُكبح. تستخدم الصفوف المعاد تشغيلها (عند الحد أو دونه) نافذة الاسترداد الأوسع بدلًا من ذلك، بحيث تُسلّم الرسالة الفائتة مؤخرًا بينما لا يُسلّم التاريخ القديم.

​

إشارة مرئية للمشغل

imessage: suppressed stale inbound backlog account=<id> sent=<iso> recovery=<bool> (<N> suppressed since start)

​

الترحيل

​

استكشاف الأخطاء وإصلاحها

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

imsg chats --limit 10 --json
imsg watch --chat-id <chat-id> --json
sqlite3 ~/Library/Messages/chat.db \
  "select datetime(max(date)/1000000000 + 978307200, 'unixepoch', 'localtime'), max(ROWID) from message;"

launchctl kickstart -k system/com.apple.apsd
launchctl kickstart -k gui/$(id -u)/com.apple.CommCenter
launchctl kickstart -k gui/$(id -u)/com.apple.identityservicesd
launchctl kickstart -k gui/$(id -u)/com.apple.imagent
imsg launch
openclaw gateway restart

#!/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 ومسار imsg iMessage — الإعلان وملخص الترحيل
• الانتقال من BlueBubbles — جدول ترجمة الإعدادات والتحويل خطوة بخطوة
• الاقتران — مصادقة DM وتدفق الاقتران
• المجموعات — سلوك محادثات المجموعات وبوابة الإشارات
• توجيه القنوات — توجيه الجلسات للرسائل
• الأمان — نموذج الوصول والتقوية