iMessage

ステータス: ネイティブ外部 CLI 統合。Gateway は imsg rpc を起動し、stdio 上の JSON-RPC で通信します（別個のデーモン/ポートはありません）。高度なアクションには 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）

• imsg を実行する Mac で Messages にサインインしている必要があります。
• OpenClaw/imsg を実行するプロセスコンテキストには、フルディスクアクセスが必要です（Messages DB へのアクセス）。
• Messages.app 経由でメッセージを送信するには、オートメーション権限が必要です。
• 高度なアクション（リアクション / 編集 / 送信取り消し / スレッド返信 / エフェクト / 投票 / グループ操作）には、System Integrity Protection を無効にする必要があります — 下記の imsg プライベート API の有効化を参照してください。基本的なテキストとメディアの送受信は、それなしでも動作します。

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

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

imsg プライベート API の有効化

imsg には 2 つの運用モードがあります。

• 基本モード（デフォルト、SIP の変更不要）: send によるアウトバウンドテキストとメディア、インバウンド watch/history、チャット一覧。これは、新しい 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 に加え、入力インジケーターと既読通知が利用可能になります。

このチャネルページで説明している高度なアクションサーフェスに到達するには、プライベート API モードが必要です。imsg README はこの要件を明示しています。

read、typing、launch、ブリッジ支援のリッチ送信、メッセージ変更、チャット管理などの高度な機能はオプトインです。SIP を無効にし、ヘルパー dylib を Messages.app に注入する必要があります。SIP が有効な場合、imsg launch は注入を拒否します。

ヘルパー注入の手法では、Messages のプライベート API に到達するために imsg 自身の dylib を使用します。OpenClaw iMessage パスには、サードパーティサーバーや BlueBubbles ランタイムはありません。

セットアップ

1. Messages.app を実行する Mac に **imsg をインストール（またはアップグレード）**します。

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

   imsg status --json の出力は、開始前に現在のビルドが何をサポートしているか確認できるように、bridge_version、rpc_methods、メソッドごとの selectors を報告します。

2. System Integrity Protection と、（最新の macOS では）Library Validation を無効化します。 Apple 署名済みの Messages.app に非 Apple のヘルパー dylib を注入するには、SIP をオフにし、かつライブラリ検証を緩和する必要があります。Recovery モードでの SIP 手順は macOS バージョン固有です。

   • macOS 10.13-10.15（Sierra-Catalina）: Terminal で Library Validation を無効にし、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 を実行します。仮想マシンセットアップは別のフローに従うため、先に VM スナップショットを取得してください。

   macOS 11 以降では、通常 csrutil disable だけでは不十分です。 Apple は Messages.app をプラットフォームバイナリとしてライブラリ検証の対象にし続けるため、SIP がオフでも adhoc 署名のヘルパーは拒否されます（Library Validation failed: ... platform binary, but mapped file is not）。SIP を無効にした後、ライブラリ検証も無効にして再起動してください。

   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 はマップされません。

   macOS アップグレード後に imsg launch の注入や特定の selectors が false を返し始めた場合、通常はこのゲートが原因です。SIP 手順自体が失敗したと判断する前に、SIP とライブラリ検証の状態を確認してください。これらの設定が正しく、それでもブリッジが注入できない場合は、追加のシステム全体のセキュリティ制御を弱めるのではなく、imsg status --json と imsg launch の出力を収集して imsg プロジェクトに報告してください。

   imsg launch を実行する前に、使用している Mac 向けの Apple のリカバリモード手順に従って SIP を無効化します。

3. ヘルパーを注入します。 SIP が無効で Messages.app にサインイン済みの状態で、次を実行します。

   imsg launch

   SIP がまだ有効な場合、imsg launch は注入を拒否するため、これは手順 2 が反映されたことの確認も兼ねます。

4. OpenClaw からブリッジを検証します。

   openclaw channels status --probe

   iMessage の項目は works を報告し、imsg status --json | jq '{rpc_methods, selectors}' は使用している macOS ビルドで公開されている機能を示すはずです。投票作成には selectors.pollPayloadMessage が必要です。投票には selectors.pollVoteMessage と poll.vote RPC メソッドの両方が必要です。OpenClaw プラグインはキャッシュ済みプローブでサポートされるアクションだけを公開します。一方、空のキャッシュは楽観的に扱われ、最初のディスパッチ時にプローブします。

openclaw channels status --probe がチャンネルを works と報告しているのに、特定のアクションがディスパッチ時に "iMessage <action> requires the imsg private API bridge" を投げる場合は、imsg launch を再実行してください。ヘルパーが外れることがあり（Messages.app の再起動、OS 更新など）、キャッシュ済みの available: true 状態は次のプローブで更新されるまでアクションを公開し続けます。

SIP を無効化できない場合

SIP 無効化が脅威モデル上許容できない場合:

• imsg は基本モードにフォールバックします。テキスト + メディア + 受信のみです。
• OpenClaw プラグインはテキスト/メディア送信と受信監視を引き続き公開します。ただし、メソッド単位の機能ゲートに従って、アクション面から react、edit、unsend、reply、sendWithEffect、グループ操作を隠します。
• 主要デバイスでは SIP を有効にしたまま、iMessage ワークロード用に SIP を無効化した別の非 Apple Silicon Mac（または専用ボット Mac）を実行できます。以下の 専用ボット macOS ユーザー（別の iMessage ID） を参照してください。

アクセス制御とルーティング

{  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 を実行します。
• 同じ iMessage 会話内の以後のメッセージは、生成された ACP セッションにルーティングされます。
• /new と /reset は、同じバインド済み ACP セッションをその場でリセットします。
• /acp close は ACP セッションを閉じ、バインディングを削除します。

設定済みの永続バインディングは、トップレベルの bindings[] エントリで type: "acp" と match.channel: "imessage" を使用してサポートされます。

match.peer.id には次を使用できます。

• +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

Private 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,        polls: true,      },    },  },}

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

設定書き込み

iMessage はデフォルトでチャネル起点の設定書き込みを許可します (commands.config: true の場合の /config set|unset)。

無効化:

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

分割送信された DM の合体 (1 回の入力にコマンド + URL)

ユーザーがコマンドと URL を一緒に入力した場合 — 例: Dump https://example.com/article — Apple の Messages アプリは送信を2 つの別々の chat.db 行に分割します:

1. テキストメッセージ ("Dump")。
2. 添付ファイルとして OG プレビュー画像を含む URL プレビューバルーン ("https://...")。

ほとんどの環境では、この 2 行は約 0.8-2.0 秒離れて OpenClaw に到着します。合体しない場合、エージェントはターン 1 でコマンドだけを受け取り、(多くの場合「URL を送ってください」と) 返信し、ターン 2 でようやく URL を見ます。その時点ではコマンドのコンテキストはすでに失われています。これは Apple の送信パイプラインであり、OpenClaw や imsg が導入しているものではありません。

channels.imessage.coalesceSameSenderDms は、DM で同一送信者の連続行をバッファリングするようオプトインします。imsg がソース行の 1 つに構造的な URL プレビューマーカー balloon_bundle_id: "com.apple.messages.URLBalloonProvider" を公開している場合、OpenClaw はその実際の分割送信のみをマージし、他のバッファ済み行は別々のターンとして保持します。バルーンメタデータをまったく出力しない古い imsg ビルドでは、OpenClaw は分割送信と別々の送信を判別できないため、バケットのマージにフォールバックします。これにより、Dump <url> の分割送信が 2 ターンに退行するのではなく、メタデータ導入前の挙動が維持されます。グループチャットは、複数ユーザーのターン構造を保つため、引き続きメッセージ単位でディスパッチされます。

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

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

シナリオと agent が見るもの

「フラグオン」列は、balloon_bundle_id を emit する imsg ビルドでの挙動を示す。balloon メタデータをまったく emit しない古い imsg ビルドでは、下で「2 ターン」/「N ターン」と示された行は代わりにレガシーマージ（1 ターン）にフォールバックする。OpenClaw は分割送信と別々の送信を構造的に判別できないため、メタデータ導入前のマージを維持する。ビルドが balloon メタデータを emit するようになると、正確な分離が有効になる。

bridge または Gateway 再起動後の inbound recovery

iMessage は Gateway 停止中に見逃したメッセージを復旧し、同時に Push recovery 後に Apple が吐き出す可能性のある古い「backlog bomb」を抑制する。デフォルトの挙動は常にオンで、inbound dedupe の上に構築されている。

• Replay dedupe。 ディスパッチされたすべての inbound メッセージは、Apple GUID によって永続 Plugin 状態（imessage.inbound-dedupe）に記録され、ingestion 時に claim され、処理後に commit される（一時的な失敗時は再試行できるよう release される）。すでに処理済みのものは、2 回ディスパッチされる代わりに破棄される。これにより、メッセージ単位の bookkeeping なしで recovery replay を積極的に実行できる。
• Downtime recovery。 起動時に monitor は最後にディスパッチされた chat.db rowid（永続化されたアカウント単位の cursor）を記憶し、それを since_rowid として imsg watch.subscribe に渡す。これにより、imsg は Gateway 停止中に到着した行を replay し、その後 live を tail する。Replay は最新行と約 2 時間前までのメッセージに制限され、dedupe はすでに処理済みのものを破棄する。
• 古い backlog の age fence。 起動境界より上の行は本当に live である。送信日時が到着より約 15 分以上古い行は Push-flush backlog として抑制される。Replay された行（境界以下）は代わりにより広い recovery window を使うため、最近見逃したメッセージは配信され、古い履歴は配信されない。

Recovery は local と remote の両方の cliPath セットアップで機能する。since_rowid replay は同じ imsg RPC 接続上で動くためである。違いは window にある。Gateway が chat.db を読める場合（local）、起動 rowid 境界を anchor し、replay span を制限し、最大で数時間前までの見逃したメッセージを配信する。remote SSH cliPath 越しではデータベースを読めないため、replay は無制限になり、すべての行が live age fence を使う。それでも最近見逃したメッセージは復旧し、古い backlog も抑制するが、より狭い live window になる。より広い recovery window が必要な場合は、Messages Mac 上で Gateway を実行する。

operator から見えるシグナル

抑制された backlog はデフォルトレベルでログに記録され、黙って破棄されることはない（recovery フラグは適用された window を示す）。

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

移行

channels.imessage.catchup.* は非推奨である。downtime recovery は現在自動であり、新しいセットアップでは設定を必要としない。catchup.enabled: true を含む既存設定は、recovery replay window の互換プロファイルとして引き続き尊重される。無効化された catchup ブロック（enabled: false または enabled: true なし）は廃止され、openclaw doctor --fix がそれらを削除する。

トラブルシューティング

imsg rpc --helpimsg status --jsonopenclaw channels status --probe

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

launchctl kickstart -k system/com.apple.apsdlaunchctl kickstart -k gui/$(id -u)/com.apple.CommCenterlaunchctl kickstart -k gui/$(id -u)/com.apple.identityservicesdlaunchctl kickstart -k gui/$(id -u)/com.apple.imagentimsg launchopenclaw gateway restart

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

openclaw channels status --probe --channel imessage

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

設定リファレンスへのポインター

• 設定リファレンス - iMessage
• Gateway 設定
• ペアリング

関連

• チャンネル概要 — サポートされているすべてのチャンネル
• BlueBubbles の削除と imsg iMessage パス — 告知と移行の概要
• BlueBubbles からの移行 — 設定変換表と段階的な切り替え
• ペアリング — DM 認証とペアリングフロー
• グループ — グループチャットの挙動と mention gating
• チャンネルルーティング — メッセージのセッションルーティング
• セキュリティ — アクセスモデルと hardening