iMessage

​

クイックセットアップ

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: extra allowed attachment roots (merged with the default
      // /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 権限が必要です。
• 高度なアクション（react / edit / unsend / スレッド返信 / エフェクト / 投票 / グループ操作）には System Integrity Protection を無効にする必要があります。imsg private API の有効化を参照してください。基本的なテキストとメディアの送受信は、それなしで動作します。

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

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

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

​

imsg private API の有効化

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

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

​

セットアップ

1. Messages.app を実行する Mac に imsg をインストール（またはアップグレード） します。
   brew install steipete/tap/imsg
   imsg --version
   imsg status --json
   
   imsg status --json 出力は bridge_version、rpc_methods、およびメソッドごとの selectors を報告するため、開始前に現在のビルドが何をサポートしているかを確認できます。
2. System Integrity Protection と、（現代の macOS では）Library Validation を無効にします。 Apple 署名済みの Messages.app に非 Apple の helper dylib を注入するには、SIP をオフにし、かつ library validation を緩和する必要があります。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 をプラットフォームバイナリとして library validation の対象にし続けるため、SIP がオフでも adhoc 署名された helper は拒否されます（Library Validation failed: ... platform binary, but mapped file is not）。SIP を無効にした後、library validation も無効にして再起動します。
   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 まで helper を注入するには十分です。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 helper を拒否するため、ブリッジは準備完了にならず、起動がタイムアウトします。このタイムアウトは Tahoe で多くの人が遭遇する症状です。修正は上記の plist であり、より抜本的な対応ではありません。
   macOS アップグレード後に imsg launch の注入や特定の selectors が false を返し始めた場合、このゲートが通常の原因です。SIP と library-validation の状態を確認してから、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 は、キャッシュされたプローブでサポートされているアクションだけを公開します。一方、空のキャッシュは楽観的に扱われ、最初のディスパッチ時にプローブします。

​

SIP を有効のままにする場合

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

​

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

{
  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 会話バインディング

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

• +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" },
    },
  ],
}

​

デプロイパターン

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

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

​

設定書き込み

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

​

分割送信 DM の結合 (1 つの構成内のコマンド + URL)

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

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

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

​

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

​

ブリッジまたは Gateway 再起動後のインバウンド復旧

• リプレイ重複排除。 ディスパッチされたすべてのインバウンドメッセージは、その Apple GUID によって永続 Plugin 状態（imessage.inbound-dedupe）に記録され、取り込み時に確保され、処理後にコミットされます（一時的な失敗時はリトライできるよう解放されます）。すでに処理済みのものは、二重にディスパッチされる代わりに破棄されます。これにより、メッセージ単位の帳簿管理なしで復旧リプレイを積極的に行えます。
• ダウンタイム復旧。 起動時にモニターは最後にディスパッチした chat.db rowid（アカウントごとに永続化されたカーソル）を記憶し、それを since_rowid として imsg watch.subscribe に渡します。これにより、Gateway が停止している間に到着した行を imsg がリプレイし、その後ライブで追尾します。リプレイは直近 500 行まで、かつ約 2 時間前までのメッセージに制限され、重複排除によって処理済みのものは破棄されます。
• 古いバックログの年齢フェンス。 起動境界より上の行は本当にライブです。送信日時が到着時刻より約 15 分以上古いものは Push フラッシュのバックログであり、抑制されます。リプレイされた行（境界以下）は代わりにより広い復旧ウィンドウを使用するため、最近取り逃したメッセージは配信され、古い履歴は配信されません。

​

オペレーターに見えるシグナル

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

​

移行

​

トラブルシューティング

imsg rpc --help
imsg status --json
openclaw channels status --probe

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

launchctl kickstart -k system/com.apple.apsd
launchctl kickstart -k gui/$(id -u)/com.apple.CommCenter
launchctl kickstart -k gui/$(id -u)/com.apple.identityservicesd
launchctl kickstart -k gui/$(id -u)/com.apple.imagent
imsg launch
openclaw gateway restart

#!/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 からの移行 — 設定変換表と段階的な切り替え
• ペアリング — DM 認証とペアリングフロー
• グループ — グループチャットの動作とメンションゲート
• チャンネルルーティング — メッセージのセッションルーティング
• セキュリティ — アクセスモデルと強化