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

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

​

تفعيل واجهة API الخاصة في 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، إضافةً إلى مؤشرات الكتابة وإيصالات القراءة.

الميزات المتقدمة مثل 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 لأن متطلب 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 الحديثة اضغط باستمرار على مفتاح Left Shift عند النقر على Continue، ثم csrutil disable. تتبع إعدادات الآلات الافتراضية مسارًا منفصلًا — خذ لقطة VM أولًا.
   • macOS 26 / Tahoe: أصبحت سياسات library-validation وفحوص استحقاقات imagent الخاصة أكثر تشددًا؛ قد يحتاج imsg إلى بناء محدّث لمواكبة ذلك. إذا بدأت عملية حقن imsg launch أو selectors محددة بإرجاع false بعد ترقية رئيسية لـ macOS، فراجع ملاحظات إصدار imsg قبل افتراض نجاح خطوة SIP.
   اتبع مسار Recovery Mode الخاص بـ 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 '.selectors' القيمة retractMessagePart: true إضافةً إلى محددات التعديل / الكتابة / القراءة التي يوفّرها بناء macOS لديك. لا يعلن تقييد OpenClaw Plugin لكل طريقة في actions.ts إلا عن الإجراءات التي يكون محددها الأساسي true، لذلك يعكس سطح الإجراءات الذي تراه في قائمة أدوات الوكيل ما يستطيع الجسر فعله فعليًا على هذا المضيف.

​

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

• يعود imsg إلى الوضع الأساسي — نص + وسائط + استقبال فقط.
• يظل OpenClaw Plugin يعلن عن إرسال النصوص/الوسائط والمراقبة الواردة؛ لكنه يخفي فقط 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,
      },
    },
  },
}

{
  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: {
        // 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)
    },
  },
}

​

كيف يعمل

​

دلالات المؤشر وإعادة المحاولة

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

• يتقدم المؤشر عند كل إرسال ناجح ويُحجز عندما يرمي إرسال صف خطأ — يعيد بدء التشغيل التالي محاولة الصف نفسه من المؤشر المحجوز.
• بعد maxFailureRetries أخطاء متتالية مقابل guid نفسه، يسجل اللحاق warn ويفرض تقدم المؤشر إلى ما بعد الرسالة العالقة كي تتمكن عمليات بدء التشغيل اللاحقة من التقدم.
• تُتخطى معرفات guid التي تم التخلي عنها بالفعل عند رؤيتها (من دون محاولة إرسال) في التشغيلات اللاحقة وتُحتسب تحت 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 باستمرار مع إعادة تشغيل تلقائية عبر مراقب، والفجوات دائما < بضع ثوان — الافتراضي المتوقف مناسب.
• حجم الرسائل المباشرة منخفض والرسائل الفائتة لن تغير سلوك الوكيل — قد ترسل نافذة firstRunLookbackMinutes الأولية سياقا قديما مفاجئا عند أول تفعيل.

​

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

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