iMessage

ステータス: ネイティブ外部 CLI 統合。Gateway は imsg rpc を起動し、stdio 上の JSON-RPC で通信します (別個のデーモン/ポートはありません)。高度なアクションには imsg launch と、Private 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 Private API の有効化を参照してください。基本的なテキストとメディアの送受信は、それなしで動作します。

imsg Private API の有効化

imsg は 2 つの運用モードで提供されます。

• 基本モード (デフォルト、SIP の変更不要): send による送信テキストとメディア、受信ウォッチ/履歴、チャットリスト。新規の brew install steipete/tap/imsg と上記の標準 macOS 権限だけで、そのまま利用できるものです。
• Private API モード: imsg はヘルパー dylib を Messages.app に注入し、内部の IMCore 関数を呼び出します。これにより react、edit、unsend、reply (スレッド)、sendWithEffect、renameGroup、setGroupIcon、addParticipant、removeParticipant、leaveGroup に加えて、入力インジケーターと既読通知が利用可能になります。

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

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

ヘルパー注入の手法は、Messages の Private 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 を無効にします。 基礎となる Apple の要件が OS とハードウェアに依存するため、これは 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 26 / Tahoe: library-validation ポリシーと imagent Private Entitlement チェックがさらに厳格化されています。imsg は追従のために更新されたビルドが必要になる場合があります。macOS のメジャーアップグレード後に imsg launch 注入や特定の selectors が false を返し始めた場合は、SIP 手順が成功したと判断する前に imsg のリリースノートを確認してください。

   imsg launch を実行する前に、使用している Mac 向けの Apple の Recovery-mode フローに従って SIP を無効にします。

3. ヘルパーを注入します。 SIP を無効にし、Messages.app にサインインした状態で:

   imsg launch

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

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

   openclaw channels status --probe

   iMessage エントリは works を報告し、imsg status --json | jq '.selectors' は retractMessagePart: true に加えて、macOS ビルドが公開する編集 / 入力 / 既読の各セレクターを表示するはずです。actions.ts の OpenClaw Plugin のメソッドごとのゲートは、基礎となるセレクターが true のアクションだけを広告するため、エージェントのツールリストに表示されるアクションサーフェスは、このホスト上でブリッジが実際に実行できる内容を反映します。

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

SIP を無効にできない場合

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

• imsg は基本モードにフォールバックします — テキスト + メディア + 受信のみ。
• OpenClaw Plugin は引き続きテキスト/メディア送信と受信監視を広告しますが、アクションサーフェスから react、edit、unsend、reply、sendWithEffect、グループ操作を隠すだけです (メソッドごとの機能ゲートに従います)。
• iMessage ワークロード用に SIP をオフにした別の非 Apple Silicon Mac (または専用 Bot Mac) を実行し、主要デバイスでは SIP を有効のままにできます。下記の 専用 Bot 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 セッションにもバインドできます。

高速なオペレーターフロー:

• DM または許可されたグループチャット内で /acp spawn codex --bind here を実行します。
• 同じ iMessage 会話内の以後のメッセージは、生成された ACP セッションにルーティングされます。
• /new と /reset は、同じバインド済み ACP セッションをその場でリセットします。
• /acp close は ACP セッションを閉じ、バインディングを削除します。

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

match.peer.id には次を使えます。

• +15555550123 や [email protected] などの正規化済み DM ハンドル
• 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: "[email protected]",      includeAttachments: true,      dbPath: "/Users/bot/Library/Messages/chat.db",    },  },}

#!/usr/bin/env bashexec ssh -T [email protected] 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 は既定でチャネル起点の設定書き込みを許可します（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 で同じ送信者から連続して届く行を1つのエージェントターンにマージするようにします。グループチャットは、複数ユーザーのターン構造を保つため、引き続きメッセージ単位でディスパッチされます。

{  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 の起動ごとに1回実行され、imsg launch ready → watch.subscribe → performIMessageCatchup → ライブディスパッチループの順に進みます。キャッチアップ自体は、imsg watch と同じ JSON-RPC クライアントに対して chats.list + チャットごとの messages.history を使います。キャッチアップ処理中に到着したものは、通常どおりライブディスパッチを通ります。既存の受信重複排除キャッシュが、再生された行との重複を吸収します。

再生された各行はライブディスパッチパス（evaluateIMessageInbound + dispatchInboundMessage）に渡されるため、許可リスト、グループポリシー、デバウンサー、エコーキャッシュ、開封確認は、再生メッセージとライブメッセージで同じように動作します。

カーソルとリトライのセマンティクス

キャッチアップは、アカウントごとのカーソルを <openclawStateDir>/imessage/catchup/<account>__<hash>.json に保持します（OpenClaw の状態ディレクトリはデフォルトで ~/.openclaw、OPENCLAW_STATE_DIR で上書き可能）。

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

• カーソルはディスパッチが成功するたびに進み、行のディスパッチが例外を投げた場合は保持されます。次回起動時には、保持されたカーソルから同じ行をリトライします。
• 同じ guid に対して連続して maxFailureRetries 回例外が発生した後、キャッチアップは warn をログに出し、詰まったメッセージを越えてカーソルを強制的に進めます。これにより、以降の起動で処理を進められます。
• すでに諦めた 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 行は、1回の起動でバックログ全体を処理しきれなかったことを意味します。ギャップが定期的にデフォルトの50行パスを超える場合は、perRunLimit（最大500）を上げてください。

オフのままにする場合

• Gateway がウォッチドッグ自動再起動付きで継続稼働しており、ギャップが常に数秒未満である場合、デフォルトのオフで問題ありません。
• DM の量が少なく、見逃したメッセージがエージェントの動作を変えない場合。初回有効化時には、firstRunLookbackMinutes の初期ウィンドウにより、予想外の古いコンテキストがディスパッチされることがあります。

キャッチアップをオンにしたとき、カーソルがない初回起動では、maxAgeMinutes の全ウィンドウではなく firstRunLookbackMinutes（デフォルト30分）だけを遡ります。これにより、有効化前の長い履歴を再生することを避けます。

トラブルシューティング

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 設定
• ペアリング

関連

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