iMessage

ステータス: ネイティブ外部CLI統合。Gatewayはimsg rpcを起動し、stdio経由でJSON-RPCを使用します。個別のデーモンやポートはありません。完全なiMessageチャンネルを実現するため、Private APIモードを強く推奨します。返信、tapback、エフェクト、投票、添付ファイルへの返信、グループ操作には、imsg launchとPrivate APIプローブの成功が必要です。

一般的なローカル構成では、OpenClawのセットアップ時に、Messagesへサインイン済みのMac上でimsgをHomebrewによりインストールまたは更新するよう、ユーザー確認付きで提案できます。手動セットアップおよびSSHラッパートポロジーは、引き続きオペレーターが管理します。Gatewayまたはラッパーを実行するのと同じユーザーコンテキストにimsgをインストールまたは更新してください。

クイックセットアップ

brew install steipete/tap/imsgbrew update && brew upgrade 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>

ssh messages-mac 'brew install steipete/tap/imsg && brew update && brew upgrade imsg'

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

{channels: {imessage: {  enabled: true,  cliPath: "~/.openclaw/scripts/imsg-ssh",  remoteHost: "user@gateway-host", // SCPによる添付ファイル取得に使用  includeAttachments: true,  // 任意: 追加で許可する添付ファイルのルート（デフォルトの  // /Users/*/Library/Messages/Attachmentsと統合される）。  attachmentRoots: ["/Users/*/Library/Messages/Attachments"],  remoteAttachmentRoots: ["/Users/*/Library/Messages/Attachments"],},},}

要件と権限（macOS）

• imsgを実行するMacでMessagesにサインインしている必要があります。
• OpenClaw/imsgを実行するプロセスコンテキストには、Full Disk Accessが必要です（Messages DBへのアクセス）。
• Messages.appを通じてメッセージを送信するには、Automation権限が必要です。
• 高度な操作（リアクション / 編集 / 送信取り消し / スレッド返信 / エフェクト / 投票 / グループ操作）には、System Integrity Protectionを無効にする必要があります。imsg Private APIの有効化を参照してください。基本的なテキストおよびメディアの送受信は、無効にしなくても機能します。

MessagesにApple eventsを送信する権限がありません。(-1743)

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

imsg Private APIの有効化

imsgには2つの動作モードがあります。OpenClawでは、ユーザーが期待するネイティブなiMessage操作をチャンネルで利用できるため、Private APIモードを推奨します。基本モードは、低リスクのインストール、初期検証、またはSIPを無効にできないホストで引き続き有用です。

• 基本モード（デフォルト、SIPの変更は不要）: sendによるテキストとメディアの送信、受信の監視と履歴、チャット一覧。これは、新規にbrew install steipete/tap/imsgを実行し、上記の標準macOS権限を付与した状態で利用できます。
• Private APIモード: imsgはヘルパーdylibをMessages.appに注入し、内部のIMCore関数を呼び出します。これにより、react、edit、unsend、reply（スレッド形式）、sendWithEffect、pollおよびpoll-vote（Messagesネイティブの投票）、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/imsgbrew update && brew upgrade 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を無効にし、かつLibrary Validationを緩和する必要があります。リカバリーモードでの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を無効にしていてもアドホック署名されたヘルパーは拒否されます（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が読み込み時にアドホック署名されたヘルパーを拒否するため、ブリッジは準備完了にならず、起動がタイムアウトします。このタイムアウトはTahoeで最も多く遭遇する症状です。修正方法は上記のplistであり、より抜本的な対処ではありません。

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

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 Pluginは、キャッシュされたプローブでサポートされているアクションのみを公開します。一方、キャッシュが空の場合は楽観的に動作し、最初のディスパッチ時にプローブします。

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、グループ操作を非表示にします。
• プライマリデバイスではSIPを有効に保ったまま、iMessageワークロード用に別の非Apple Silicon Mac（または専用のボットMac）をSIP無効で運用できます。以下の専用ボット用macOSユーザー（別のiMessage ID）を参照してください。

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

{  channels: {    imessage: {      groupPolicy: "allowlist",      groupAllowFrom: ["+15555550123"],      groups: {        "*": { systemPrompt: "イギリス英語の綴りを使用してください。" },        "8421": {          requireMention: true,          systemPrompt: "これはオンコール当番のチャットです。返信は3文以内にしてください。",        },        "9907": {          // 明示的な抑制：ワイルドカードの「イギリス英語の綴りを使用してください。」はここでは適用されません          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やuser@example.comなどの正規化された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: "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

プライベート API アクション

imsg launch が実行中で、openclaw channels status --probe が privateApi.available: true を報告している場合、メッセージツールでは通常のテキスト送信に加えて、iMessage ネイティブのアクションを使用できます。

すべてのアクションはデフォルトで有効です。個別のアクションを無効にするには channels.imessage.actions を使用します:

{  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でコマンドだけを受け取り、多くの場合、ターン2で URL が到着する前に「URL を送ってください」と返信します。これは Apple の送信パイプラインによるものであり、OpenClaw や imsg が発生させているものではありません。

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

{  channels: {    imessage: {      coalesceSameSenderDms: true, // オプトイン（デフォルト: false）    },  },}

{  messages: {    inbound: {      byChannel: {        // 7000 ms で、観測された Messages.app の URL プレビュー遅延をカバーします。        imessage: 7000,      },    },  },}

シナリオとエージェントから見える内容

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

ブリッジまたは Gateway の再起動後の受信復旧

iMessage は Gateway の停止中に取りこぼしたメッセージを復旧すると同時に、Push 復旧後に Apple が一気に流す可能性のある古い「バックログ爆弾」を抑制します。デフォルト動作は常に有効で、受信重複排除を基盤としています。

• リプレイ重複排除。 ディスパッチされた各受信メッセージは、Apple GUID を使用して永続 Plugin 状態（imessage.inbound-dedupe）に記録されます。取り込み時に確保され、処理後にコミットされます（一時的な失敗時には再試行できるよう解放されます）。すでに処理済みのものは、重複してディスパッチされず破棄されます。これにより、メッセージごとの記帳なしで復旧リプレイを積極的に実行できます。
• 停止期間の復旧。 起動時にモニターは最後にディスパッチされた chat.db の rowid（アカウントごとに永続化されたカーソル）を記憶し、それを since_rowid として imsg watch.subscribe に渡します。これにより、imsg は Gateway の停止中に到着した行をリプレイしてから、ライブの追尾を開始します。リプレイは最新の 500 行および約 2 時間以内のメッセージに制限され、重複排除によって処理済みのものは破棄されます。
• 古いバックログの経過時間フェンス。 起動境界より上の行は実際のライブメッセージです。そのうち送信日時が到着時刻より約 15 分以上古いものは、Push によって一気に流されたバックログとして抑制されます。リプレイされた行（境界以下）には、代わりにより広い復旧ウィンドウが適用されるため、最近取りこぼしたメッセージは配信され、古い履歴は配信されません。

since_rowid リプレイは同じ imsg RPC 接続上で実行されるため、復旧はローカルとリモートの両方の cliPath セットアップで機能します。違いはウィンドウです。Gateway が chat.db を読み取れる場合（ローカル）は、起動時の rowid 境界を基準とし、リプレイ範囲を制限して、最大数時間前までの取りこぼしたメッセージを配信します。リモート SSH cliPath 経由ではデータベースを読み取れないため、リプレイは無制限となり、すべての行にライブ経過時間フェンスが適用されます。それでも最近取りこぼしたメッセージは復旧され、古いバックログも抑制されますが、使用されるライブウィンドウはより狭くなります。より広い復旧ウィンドウを使用するには、Messages を実行している Mac 上で Gateway を実行してください。

オペレーターに表示されるシグナル

抑制されたバックログはデフォルトレベルでログに記録され、暗黙に破棄されることはありません（recovery フラグはどちらのウィンドウが適用されたかを示します）。

imessage: 古い受信バックログを抑制しました account=<id> sent=<iso> recovery=<bool>（起動後の抑制数: &lt;N&gt;）

移行

channels.imessage.catchup.* は非推奨です。停止期間の復旧は自動で行われ、新しいセットアップでは構成は不要です。catchup.enabled: true が設定された既存の構成は、復旧リプレイウィンドウの互換性プロファイルとして引き続き尊重されます。無効化された 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 認証とペアリングフロー
• グループ — グループチャットの動作とメンション制御
• チャンネルルーティング — メッセージのセッションルーティング
• セキュリティ — アクセスモデルとセキュリティ強化