iMessage

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

クイックセットアップ

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: 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 chats --limit 1
# or
imsg send <handle> "test"

​

imsg Private API の有効化

• 基本モード (デフォルト、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 に加えて、入力インジケーターと既読通知が利用可能になります。

read、typing、launch、ブリッジバックのリッチ送信、メッセージ変更、チャット管理などの高度な機能はオプトインです。SIP を無効にし、ヘルパー 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 を無効にします。 基礎となる 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 のアクションだけを広告するため、エージェントのツールリストに表示されるアクションサーフェスは、このホスト上でブリッジが実際に実行できる内容を反映します。

​

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: { "*": { "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,
      },
    },
  },
}

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

​

設定書き込み

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

​

分割送信 DM の結合（1 つの作成内容内のコマンド + URL）

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

{
  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 停止後のキャッチアップ

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)
    },
  },
}

​

実行方法

​

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

{
  "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 <N> failures; advancing cursor past it
imessage catchup: fetched <X> rows across chats, capped to perRunLimit=<Y>

​

オフのままにする場合

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

​

トラブルシューティング

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

#!/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 認証とペアリングフロー
• グループ — グループチャットの動作とメンションゲート
• チャンネルルーティング — メッセージのセッションルーティング
• セキュリティ — アクセスモデルと強化