iMessage

​

クイックセットアップ

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

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

#!/usr/bin/env bash
exec 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 を実行するプロセスコンテキストには、フルディスクアクセスが必要です（Messages データベースへのアクセス）。
• Messages.app 経由でメッセージを送信するには、オートメーション権限が必要です。
• 高度な操作（リアクション / 編集 / 送信取り消し / スレッド返信 / エフェクト / 投票 / グループ操作）には、システム整合性保護を無効にする必要があります。詳細はimsg Private API の有効化を参照してください。基本的なテキストおよびメディアの送受信は、無効にしなくても動作します。

imsg chats --limit 1
# または
imsg send <handle> "test"

Messages への Apple Event の送信が認可されていません。(-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 はヘルパー dylib を Messages.app に注入し、内部の IMCore 関数を呼び出します。これにより、react、edit、unsend、reply（スレッド形式）、sendWithEffect、poll と poll-vote（Messages ネイティブの投票）、renameGroup、setGroupIcon、addParticipant、removeParticipant、leaveGroup に加え、入力中インジケーターと既読通知が利用可能になります。

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

​

セットアップ

1. Messages.app を実行する Mac に **imsg をインストール（またはアップグレード）**します。
   brew install steipete/tap/imsg
   brew update && brew upgrade imsg
   imsg --version
   imsg status --json
   
   imsg status --json の出力には、bridge_version、rpc_methods、およびメソッドごとの selectors が表示されるため、開始前に現在のビルドでサポートされる機能を確認できます。
2. System Integrity Protection、および（最新の macOS では）ライブラリ検証を無効にします。 Apple 署名済みの Messages.app に Apple 製ではないヘルパー dylib を注入するには、SIP をオフにし、かつライブラリ検証を緩和する必要があります。リカバリモードでの SIP の手順は、macOS のバージョンによって異なります。
   • macOS 10.13-10.15（Sierra-Catalina）： Terminal でライブラリ検証を無効にし、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 はキャッシュされたプローブでサポートされているアクションのみを公開しますが、キャッシュが空の場合は楽観的に扱い、最初のディスパッチ時にプローブします。

​

SIP を有効にしたままにする場合

• imsg は基本モードにフォールバックします。利用できるのはテキスト、メディア、受信のみです。
• OpenClaw Plugin は引き続きテキスト／メディアの送信と受信監視を公開しますが、アクションサーフェスから react、edit、unsend、reply、sendWithEffect、およびグループ操作を非表示にします（メソッド単位の機能ゲートに従います）。
• プライマリデバイスでは SIP を有効にしたまま、iMessage のワークロード用に SIP をオフにした別の非 Apple Silicon Mac（または専用のボット Mac）を実行できます。以下の専用ボット用 macOS ユーザー（個別の iMessage ID）を参照してください。

​

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

{
  channels: {
    imessage: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15555550123"],
      groups: { "*": { "requireMention": true } },
    },
  },
}

{
  channels: {
    imessage: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15555550123"],
      groups: {
        "*": { systemPrompt: "イギリス式のスペルを使用してください。" },
        "8421": {
          requireMention: true,
          systemPrompt: "これはオンコール当番のチャットです。返信は 3 文未満にしてください。",
        },
        "9907": {
          // 明示的な抑制：ワイルドカード「イギリス式のスペルを使用してください。」はここでは適用されません
          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 を送信）

brew update && brew upgrade imsg

​

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

• 永続的なリプレイ保護。 復旧カーソルを進める前に、OpenClaw は各未加工行を共有 SQLite 受信キューに記録し、その Apple GUID をイベント ID として使用します。完了した行は約 4 時間、最大 10,000 件のトゥームストーンを残すため、再起動後でも同じ GUID のリプレイは破棄されます。保留中の行は、ディスパッチが引き取るまで復旧可能な状態を維持します。
• 停止中の復旧。 起動時に、モニターは永続的に受け入れられた最後の chat.db rowid（アカウントごとに永続化されたカーソル）を記憶し、それを since_rowid として imsg watch.subscribe に渡します。これにより、imsg はまだ記録されていない行をリプレイした後、ライブ監視を続けます。クラッシュ前に記録された行は SQLite から再開されます。リプレイは直近の 500 行、および最大約 2 時間前までのメッセージに制限され、GUID トゥームストーンによって処理済みのものはすべて破棄されます。
• 古いバックログの経過時間フェンス。 起動時の境界より後の行は実際のライブメッセージです。そのうち送信日時が到着日時より約 15 分以上古いものは Push によって一気に送信されたバックログとして抑制されます。リプレイされた行（境界以前）は代わりに、より広い復旧期間を使用するため、最近取りこぼしたメッセージは配信されますが、古すぎる履歴は配信されません。

​

オペレーターが確認できるシグナル

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

​

移行

​

トラブルシューティング

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 認証とペアリングの流れ
• グループ — グループチャットの動作とメンションによる制御
• チャンネルルーティング — メッセージのセッションルーティング
• セキュリティ — アクセスモデルと強化策