English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

Mainstream messaging

iMessage

وضعیت: ادغام بومی CLI خارجی. Gateway، imsg rpc را اجرا می‌کند و از طریق JSON-RPC روی stdio ارتباط برقرار می‌کند (بدون daemon/port جداگانه).

BlueBubbles (جایگزین قدیمی)

برای مسیریابی موجودِ مبتنی بر BlueBubbles به استفاده از آن ادامه دهید؛ برای راه‌اندازی‌های جدید، وقتی imsg مناسب است از آن پرهیز کنید.
جفت‌سازی

پیام‌های مستقیم iMessage به‌طور پیش‌فرض از حالت جفت‌سازی استفاده می‌کنند.
مرجع پیکربندی

مرجع کامل فیلدهای iMessage.

راه‌اندازی سریع

Mac محلی (مسیر سریع)

  • نصب و تأیید imsg

    brew install steipete/tap/imsg
imsg rpc --help

  • پیکربندی OpenClaw

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

  • شروع Gateway

    openclaw gateway

  • تأیید نخستین جفت‌سازی پیام مستقیم (dmPolicy پیش‌فرض)

    openclaw pairing list imessage
openclaw pairing approve imessage <CODE>

    درخواست‌های جفت‌سازی پس از ۱ ساعت منقضی می‌شوند.

    • Mac راه‌دور از طریق SSH

    OpenClaw فقط به یک cliPath سازگار با stdio نیاز دارد، بنابراین می‌توانید cliPath را به یک اسکریپت wrapper اشاره دهید که با SSH به یک Mac راه‌دور وصل می‌شود و imsg را اجرا می‌کند.

    #!/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"],
},
},
}

    اگر remoteHost تنظیم نشده باشد، OpenClaw تلاش می‌کند آن را با تحلیل اسکریپت wrapper مربوط به SSH به‌طور خودکار تشخیص دهد. remoteHost باید host یا user@host باشد (بدون فاصله یا گزینه‌های SSH). OpenClaw برای SCP از بررسی سخت‌گیرانه کلید میزبان استفاده می‌کند، بنابراین کلید میزبان relay باید از قبل در ~/.ssh/known_hosts وجود داشته باشد. مسیرهای پیوست در برابر ریشه‌های مجاز (attachmentRoots / remoteAttachmentRoots) اعتبارسنجی می‌شوند.

    الزامات و مجوزها (macOS)

    • Messages باید روی Mac اجراکننده imsg وارد شده باشد.
    • برای context فرایندی که OpenClaw/imsg را اجرا می‌کند، Full Disk Access لازم است (دسترسی به پایگاه داده Messages).
    • برای ارسال پیام از طریق Messages.app، مجوز Automation لازم است.

    کنترل دسترسی و مسیریابی

    سیاست پیام مستقیم

    channels.imessage.dmPolicy پیام‌های مستقیم را کنترل می‌کند:

    • pairing (پیش‌فرض)
    • allowlist
    • open (نیازمند این است که allowFrom شامل "*" باشد)
    • disabled

    فیلد allowlist: channels.imessage.allowFrom.

    ورودی‌های allowlist می‌توانند handleها یا مقصدهای chat باشند (chat_id:*, chat_guid:*, chat_identifier:*).

    سیاست گروه + mentionها

    channels.imessage.groupPolicy مدیریت گروه را کنترل می‌کند:

    • allowlist (پیش‌فرض هنگام پیکربندی)
    • open
    • disabled

    allowlist فرستنده گروه: channels.imessage.groupAllowFrom.

    fallback زمان اجرا: اگر groupAllowFrom تنظیم نشده باشد، بررسی‌های فرستنده گروه iMessage در صورت وجود به allowFrom fallback می‌کنند. نکته زمان اجرا: اگر channels.imessage کاملاً وجود نداشته باشد، runtime به groupPolicy="allowlist" fallback می‌کند و یک هشدار ثبت می‌کند (حتی اگر channels.defaults.groupPolicy تنظیم شده باشد).

    گیتینگ mention برای گروه‌ها:

    • iMessage هیچ فراداده mention بومی ندارد
    • تشخیص mention از الگوهای regex استفاده می‌کند (agents.list[].groupChat.mentionPatterns، fallback به messages.groupChat.mentionPatterns)
    • بدون الگوهای پیکربندی‌شده، گیتینگ mention قابل اعمال نیست

    فرمان‌های کنترلی از فرستنده‌های مجاز می‌توانند گیتینگ mention را در گروه‌ها دور بزنند.

    جلسه‌ها و پاسخ‌های قطعی

    • پیام‌های مستقیم از مسیریابی مستقیم استفاده می‌کنند؛ گروه‌ها از مسیریابی گروهی استفاده می‌کنند.
    • با session.dmScope=main پیش‌فرض، پیام‌های مستقیم iMessage در جلسه اصلی agent ادغام می‌شوند.
    • جلسه‌های گروه ایزوله هستند (agent:<agentId>:imessage:group:<chat_id>).
    • پاسخ‌ها با استفاده از فراداده کانال/مقصد مبدأ دوباره به iMessage مسیریابی می‌شوند.

    رفتار رشته‌های شبیه گروه:

    برخی رشته‌های iMessage چندشرکت‌کننده‌ای ممکن است با is_group=false برسند. اگر آن chat_id به‌طور صریح زیر channels.imessage.groups پیکربندی شده باشد، OpenClaw آن را به‌عنوان ترافیک گروه در نظر می‌گیرد (گیتینگ گروه + ایزوله‌سازی جلسه گروه).

    اتصال‌های مکالمه ACP

    چت‌های قدیمی iMessage نیز می‌توانند به جلسه‌های ACP متصل شوند.

    جریان سریع اپراتور:

    • /acp spawn codex --bind here را داخل پیام مستقیم یا چت گروهی مجاز اجرا کنید.
    • پیام‌های آینده در همان مکالمه iMessage به جلسه ACP ایجادشده مسیریابی می‌شوند.
    • /new و /reset همان جلسه ACP متصل‌شده را درجا reset می‌کنند.
    • /acp close جلسه ACP را می‌بندد و binding را حذف می‌کند.

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

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

    • handle نرمال‌شده پیام مستقیم مانند +15555550123 یا [email protected]
    • chat_id:<id> (برای bindingهای پایدار گروه توصیه می‌شود)
    • 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" },
    },
  ],
}

    برای رفتار مشترک binding در ACP، Agentهای ACP را ببینید.

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

    کاربر اختصاصی bot در macOS (هویت iMessage جداگانه)

    از یک Apple ID و کاربر macOS اختصاصی استفاده کنید تا ترافیک bot از پروفایل شخصی Messages شما جدا بماند.

    جریان معمول:

    1. یک کاربر اختصاصی macOS ایجاد کنید/وارد آن شوید.
    2. در همان کاربر، با Apple ID مربوط به bot وارد Messages شوید.
    3. imsg را در همان کاربر نصب کنید.
    4. اسکریپت wrapper برای SSH بسازید تا OpenClaw بتواند imsg را در context همان کاربر اجرا کند.
    5. channels.imessage.accounts.<id>.cliPath و .dbPath را به پروفایل همان کاربر اشاره دهید.

    اجرای نخست ممکن است در جلسه همان کاربر bot به تأییدهای GUI نیاز داشته باشد (Automation + Full Disk Access).

    Mac راه‌دور از طریق Tailscale (مثال)

    توپولوژی رایج:

    • Gateway روی Linux/VM اجرا می‌شود
    • iMessage + imsg روی یک Mac در tailnet شما اجرا می‌شود
    • wrapper مربوط به cliPath از SSH برای اجرای imsg استفاده می‌کند
    • remoteHost دریافت پیوست‌ها با SCP را فعال می‌کند

    مثال:

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

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

    از کلیدهای SSH استفاده کنید تا هم SSH و هم SCP غیرتعاملی باشند. ابتدا مطمئن شوید کلید میزبان trusted است (برای مثال ssh [email protected]) تا known_hosts پر شود.

    الگوی چندحسابی

    iMessage از پیکربندی به‌ازای هر حساب زیر channels.imessage.accounts پشتیبانی می‌کند.

    هر حساب می‌تواند فیلدهایی مانند cliPath، dbPath، allowFrom، groupPolicy، mediaMaxMb، تنظیمات history، و allowlistهای ریشه پیوست را override کند.

    رسانه، chunking، و مقصدهای تحویل

    پیوست‌ها و رسانه
    • ingest پیوست‌های ورودی اختیاری است: channels.imessage.includeAttachments
    • وقتی remoteHost تنظیم شده باشد، مسیرهای پیوست راه‌دور می‌توانند از طریق SCP دریافت شوند
    • مسیرهای پیوست باید با ریشه‌های مجاز مطابقت داشته باشند:
      • channels.imessage.attachmentRoots (محلی)
      • channels.imessage.remoteAttachmentRoots (حالت SCP راه‌دور)
      • الگوی ریشه پیش‌فرض: /Users/*/Library/Messages/Attachments
    • SCP از بررسی سخت‌گیرانه کلید میزبان استفاده می‌کند (StrictHostKeyChecking=yes)
    • اندازه رسانه خروجی از channels.imessage.mediaMaxMb استفاده می‌کند (پیش‌فرض 16 MB)
    chunking خروجی
    • حد chunk متن: channels.imessage.textChunkLimit (پیش‌فرض 4000)
    • حالت chunk: channels.imessage.chunkMode
      • length (پیش‌فرض)
      • newline (تقسیم با اولویت پاراگراف)
    فرمت‌های آدرس‌دهی

    مقصدهای صریح ترجیحی:

    • chat_id:123 (برای مسیریابی پایدار توصیه می‌شود)
    • chat_guid:...
    • chat_identifier:...

    مقصدهای handle نیز پشتیبانی می‌شوند:

    imsg chats --limit 20

    نوشتن پیکربندی

    iMessage به‌طور پیش‌فرض اجازه نوشتن پیکربندی آغازشده از کانال را می‌دهد (برای /config set|unset وقتی commands.config: true).

    غیرفعال‌سازی:

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

    عیب‌یابی

    imsg پیدا نشد یا RPC پشتیبانی نمی‌شود

    binary و پشتیبانی RPC را اعتبارسنجی کنید:

    imsg rpc --help
openclaw channels status --probe

    اگر probe گزارش دهد RPC پشتیبانی نمی‌شود، imsg را به‌روزرسانی کنید.

    پیام‌های مستقیم نادیده گرفته می‌شوند

    بررسی کنید:

    • channels.imessage.dmPolicy
    • channels.imessage.allowFrom
    • تأییدهای جفت‌سازی (openclaw pairing list imessage)
    پیام‌های گروهی نادیده گرفته می‌شوند

    بررسی کنید:

    • channels.imessage.groupPolicy
    • channels.imessage.groupAllowFrom
    • رفتار allowlist در channels.imessage.groups
    • پیکربندی الگوی mention (agents.list[].groupChat.mentionPatterns)
    پیوست‌های راه‌دور ناموفق می‌شوند

    بررسی کنید:

    • channels.imessage.remoteHost
    • channels.imessage.remoteAttachmentRoots
    • احراز هویت کلید SSH/SCP از میزبان Gateway
    • کلید میزبان در ~/.ssh/known_hosts روی میزبان Gateway وجود دارد
    • خوانایی مسیر راه‌دور روی Mac اجراکننده Messages
    promptهای مجوز macOS از دست رفتند

    در یک ترمینال GUI تعاملی در همان context کاربر/جلسه دوباره اجرا کنید و promptها را تأیید کنید:

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

    تأیید کنید Full Disk Access + Automation برای context فرایندی که OpenClaw/imsg را اجرا می‌کند اعطا شده‌اند.

    اشاره‌گرهای مرجع پیکربندی

    مرتبط