BlueBubbles からの移行

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.

​

この移行が適している場合

• Messages.app にサインイン済みの同じ Mac（または SSH で到達可能な Mac）で、すでに imsg を実行している。
• 可動部分を 1 つ減らしたい。別個の BlueBubbles サーバーも、認証する REST エンドポイントも、Webhook 配線も不要です。サーバー + クライアントアプリ + ヘルパーではなく、単一の CLI バイナリになります。
• private API プローブが available: true を報告する、サポート対象の macOS / imsg ビルドを使用している。

​

imsg の機能

• 読み取りは、読み取り専用 SQLite ハンドルを使用して ~/Library/Messages/chat.db から行われます。
• ライブ受信メッセージは imsg watch / watch.subscribe から来ます。これはポーリングのフォールバック付きで chat.db のファイルシステムイベントを追跡します。
• 通常のテキスト送信とファイル送信には Messages.app の自動化を使用します。
• 高度なアクションでは、imsg launch を使って imsg ヘルパーを Messages.app に注入します。これにより、開封確認、入力インジケーター、リッチ送信、編集、送信取り消し、スレッド返信、タップバック、グループ管理が有効になります。
• Linux ビルドではコピーされた chat.db を検査できますが、送信、ライブ Mac データベースの監視、Messages.app の駆動はできません。OpenClaw iMessage では、サインイン済みの Mac 上で imsg を実行するか、その Mac への SSH ラッパー経由で実行してください。

​

始める前に

1. Messages.app を実行する Mac に imsg をインストールします。
   brew install steipete/tap/imsg
   imsg --version
   imsg chats --limit 3
   
   imsg chats が unable to open database file、空の出力、または authorization denied で失敗する場合は、imsg を起動するターミナル、エディター、Node プロセス、Gateway サービス、または SSH 親プロセスにフルディスクアクセスを付与し、その親プロセスを再度開いてください。
2. OpenClaw 設定を変更する前に、読み取り、監視、送信、RPC サーフェスを検証します。
   imsg chats --limit 10 --json | jq -s
   imsg history --chat-id 42 --limit 10 --attachments --json | jq -s
   imsg watch --chat-id 42 --reactions --json
   imsg send --chat-id 42 --text "OpenClaw imsg test"
   imsg rpc --help
   
   42 は imsg chats から取得した実際のチャット ID に置き換えてください。送信には Messages.app の Automation 権限が必要です。OpenClaw を SSH 経由で実行する場合は、OpenClaw が使用するのと同じ SSH ラッパーまたはユーザーコンテキストでこれらのコマンドを実行してください。
3. 高度なアクションが必要な場合は、private API ブリッジを有効にします。
   imsg launch
   imsg status --json
   
   imsg launch には SIP を無効にする必要があります。基本的な送信、履歴、監視は imsg launch なしで動作しますが、高度なアクションは動作しません。
4. OpenClaw 経由でブリッジを検証します。
   openclaw channels status --probe
   
   imessage.privateApi.available: true になっている必要があります。false と報告される場合は、まずそれを修正してください。機能検出を参照してください。
5. 設定のスナップショットを作成します。
   cp ~/.openclaw/openclaw.json5 ~/.openclaw/openclaw.json5.bak
   

​

設定の変換

​

グループレジストリの落とし穴

1. 送信者 / チャットターゲット allowlist（channels.imessage.groupAllowFrom）— isAllowedIMessageSender によってチェックされます。受信メッセージを送信者 handle、chat_guid、chat_identifier、または chat_id で照合します。形は BlueBubbles と同じです。
2. グループレジストリ（channels.imessage.groups）— inbound-processing.ts:199 の resolveChannelGroupPolicy によってチェックされます。groupPolicy: "allowlist" では、このゲートは次のいずれかを要求します:
   • groups: { "*": { ... } } ワイルドカードエントリ（allowAll = true を設定）、または
   • groups の下にある明示的な chat_id ごとのエントリ。

• groupPolicy: "allowlist" が設定されているが channels.imessage.groups が空（"*" ワイルドカードも chat_id ごとのエントリもない）の場合、アカウントごとに起動時に一度だけ出る warn — メッセージが届く前に発火します。
• 特定のグループが実行時に初めて破棄されたときに、chat_id ごとに一度だけ出る warn。chat_id と、それを許可するために groups に追加すべき正確なキーを示します。

{
  channels: {
    imessage: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15555550123", "chat_guid:any;-;..."],
      groups: {
        "*": { requireMention: true },
      },
    },
  },
}

​

手順

1. 既存の BlueBubbles ブロックの横に iMessage ブロックを追加します。新しいパスが検証されるまでは、古いブロックはコピー元としてのみ残します。
   {
     channels: {
       bluebubbles: {
         enabled: true,
         // ... existing config ...
       },
       imessage: {
         enabled: false, // turn on after the dry run below
         cliPath: "/opt/homebrew/bin/imsg",
         dmPolicy: "pairing",
         allowFrom: ["+15555550123"], // copy from bluebubbles.allowFrom
         groupPolicy: "allowlist",
         groupAllowFrom: [], // copy from bluebubbles.groupAllowFrom
         groups: { "*": { requireMention: true } }, // copy from bluebubbles.groups — silently drops groups if missing, see "Group registry footgun" above
         actions: {
           reactions: true,
           edit: true,
           unsend: true,
           reply: true,
           sendWithEffect: true,
           sendAttachment: true,
         },
       },
     },
   }
   
2. ドライランのプローブ — Gateway を起動し、iMessage が正常と報告されることを確認します。
   openclaw gateway
   openclaw channels status
   openclaw channels status --probe   # expect imessage.privateApi.available: true
   
   imessage.enabled はまだ false のため、インバウンドの iMessage トラフィックはまだルーティングされません。ただし --probe はブリッジを実行するため、切り替え前に権限やインストールの問題を検出できます。
3. 切り替えます。 1 回の設定編集で BlueBubbles 設定を削除し、iMessage を有効にします。
   {
     channels: {
       imessage: { enabled: true /* ... */ },
     },
   }
   
   Gateway を再起動します。インバウンドの iMessage トラフィックは、同梱 Plugin を通るようになります。
4. DM を検証します。 エージェントにダイレクトメッセージを送信し、返信が届くことを確認します。
5. グループを別途検証します。 DM とグループは異なるコードパスを通ります。DM の成功は、グループがルーティングされている証明にはなりません。ペアリング済みのグループチャットでエージェントにメッセージを送信し、返信が届くことを確認します。グループが無反応になる場合（エージェントの返信なし、エラーなし）、Gateway ログに imessage: dropping group message from chat_id=<id>、または起動時の imessage: groupPolicy="allowlist" but channels.imessage.groups is empty 行がないか確認します。どちらもデフォルトのログレベルで出力されます。どちらかが表示される場合、groups ブロックがないか空です。上記の「グループレジストリの落とし穴」を参照してください。
6. アクションサーフェスを検証します — ペアリング済み DM から、リアクション、編集、送信取り消し、返信、写真送信、（グループ内での）グループ名変更 / 参加者の追加または削除をエージェントに依頼します。各アクションは Messages.app にネイティブに反映される必要があります。いずれかが「iMessage <action> requires the imsg private API bridge」をスローする場合は、imsg launch を再度実行し、channels status --probe を更新してください。
7. iMessage の DM、グループ、アクションが検証されたら、BlueBubbles サーバーと設定を削除します。OpenClaw は channels.bluebubbles を使用しません。

​

アクションの対応状況の概要

​

ペアリング、セッション、ACP バインディング

• ペアリング承認 はハンドルごとに引き継がれます。既知の送信者を再承認する必要はありません。channels.imessage.allowFrom は、BlueBubbles が使用していた同じ +15555550123 / user@example.com 文字列を認識します。
• セッション はエージェント + チャットごとにスコープされます。DM はデフォルトの session.dmScope=main の下でエージェントのメインセッションにまとめられます。グループセッションは chat_id ごとに分離されます。セッションキーは異なります（agent:<id>:imessage:group:<chat_id> と BlueBubbles の同等のキー）。BlueBubbles セッションキーの下にある古い会話履歴は iMessage セッションに引き継がれません。
• match.channel: "bluebubbles" を参照する ACP バインディング は "imessage" に更新する必要があります。match.peer.id の形（chat_id:、chat_guid:、chat_identifier:、裸のハンドル）は同一です。

​

ロールバック用チャンネルはありません

​

関連

• iMessage — imsg launch のセットアップと機能検出を含む、完全な iMessage チャンネルリファレンス。
• /channels/bluebubbles — この移行ガイドにリダイレクトする従来の URL。
• ペアリング — DM 認証とペアリングフロー。
• チャンネルルーティング — Gateway がアウトバウンド返信のチャンネルを選択する方法。