BlueBubbles からの移行

​

移行チェックリスト

1. Messages.app を実行している Mac 上で imsg を直接確認します（imsg chats、imsg history、imsg send、imsg rpc --help）。
2. channels.bluebubbles から channels.imessage に動作設定キーをコピーします：dmPolicy、allowFrom、groupPolicy、groupAllowFrom、groups、includeAttachments、attachmentRoots、mediaMaxMb、textChunkLimit、および actions。
3. 存在しなくなったトランスポート設定キーを削除します：serverUrl、password、Webhook URL、および BlueBubbles サーバー設定。
4. Gateway が Messages Mac 上で動作していない場合は、channels.imessage.cliPath に SSH ラッパーを設定し、リモート添付ファイル取得用に remoteHost を設定します。
5. channels.imessage を有効にして Gateway を再起動し、openclaw channels status --probe --channel imessage を実行します。
6. DM を 1 件、許可されたグループを 1 件、添付ファイルが有効な場合は添付ファイル、さらにエージェントが使用する予定のすべてのプライベート API アクションをテストします。
7. iMessage パスを確認した後、BlueBubbles サーバーと古い channels.bluebubbles 設定を削除します。

​

imsg の動作

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

​

開始前の準備

1. Messages.app を実行している Mac に imsg をインストールします。
   brew install steipete/tap/imsg
   brew update && brew upgrade imsg
   imsg --version
   imsg chats --limit 3
   
   通常のローカル設定では、OpenClaw のセットアップ時に、サインイン済みの Messages Mac 上の imsg をユーザーの確認を得て Homebrew でインストールまたは更新できます。手動設定および SSH ラッパートポロジーは引き続き運用者が管理します。imsg を実行するのと同じローカルまたはリモートのユーザーコンテキストで Homebrew の更新を繰り返してください。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 ラッパーまたはユーザーコンテキストを通じて、これらのコマンドを実行してください。読み取りは成功するものの、送信が AppleEvents の -1743 で失敗する場合は、Automation 権限が /usr/libexec/sshd-keygen-wrapper に付与されているか確認してください。SSH ラッパーでの送信が AppleEvents -1743 で失敗するを参照してください。
3. プライベート API ブリッジを有効にします。返信、Tapback、エフェクト、投票、添付ファイルへの返信、グループアクションはこれに依存するため、OpenClaw iMessage では有効化を強く推奨します。
   imsg launch
   imsg status --json
   
   imsg launch を使用するには SIP を無効にする必要があります（最新の macOS ではライブラリ検証の緩和も必要です。imsg プライベート API の有効化を参照してください）。基本的な送信、履歴、監視は imsg launch なしでも動作しますが、OpenClaw iMessage のすべてのアクションサーフェスは利用できません。
4. channels.imessage を有効にして Gateway を起動した後、OpenClaw を通じてブリッジを確認します。
   openclaw channels status --probe
   
   iMessage アカウントは works と報告する必要があります。--json がある場合、プローブのペイロードには privateApi.available: true が含まれます。false と報告された場合は、まずそれを修正してください。機能検出を参照してください。プローブには到達可能な Gateway が必要です（到達できない場合、CLI は設定情報のみの出力にフォールバックします）。また、設定済みかつ有効なアカウントのみがプローブされます。
5. 設定のスナップショットを作成します。
   cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak
   

​

設定の変換

​

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

1. 送信者／チャット対象の許可リスト（channels.imessage.groupAllowFrom）— 送信者ハンドルまたはチャット対象（chat_id:、chat_guid:、chat_identifier: のエントリ）と照合します。groupAllowFrom が未設定の場合、このゲートは allowFrom にフォールバックします。明示的に groupAllowFrom: [] を指定するとそのフォールバックが無効になり、groupPolicy: "allowlist" ではすべてのグループメッセージが破棄されます。
2. グループレジストリ（channels.imessage.groups）— 数値の iMessage chat_id をキーとします。
   • groups ブロックがない場合（または空の場合）：ゲート 1 の実効的な送信者許可リストが空でなければ、グループはこのゲートを通過します。送信者フィルタリングがアクセスを制御し、全件破棄を示す起動時警告は発生しません。
   • groups にエントリがあるものの "*" がない場合：一覧にある chat_id キーだけが通過します。グループを 1 つでも列挙すると、groupPolicy: "open" の場合でもレジストリが許可リストになります。
   • groups: { "*": { ... } }：すべてのグループがこのゲートを通過します。

• groupPolicy: "allowlist" が設定され、実効的なグループ送信者許可リストが空の場合、起動時にアカウントごとに 1 回：imessage: groupPolicy="allowlist" for account "<id>" but no group sender allowlist is configured ...。送信者を許可するには groupAllowFrom（または allowFrom）を設定します。groups を追加するだけでは送信者ゲートの条件を満たしません。
• レジストリがグループを破棄した場合、実行時に chat_id ごとに 1 回：imessage: dropping group message from chat_id=<id> ... not in channels.imessage.groups allowlist。追加すべき正確なキーが示されます。

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

​

手順

1. 設定を変換します。編集中は新しいブロックを無効のままにしてください。現在の OpenClaw は古い channels.bluebubbles ブロックを無視するため、参照用として併記できます。
   {
     channels: {
       imessage: {
         enabled: false, // 切り替える準備ができたら true に変更
         cliPath: "/opt/homebrew/bin/imsg",
         dmPolicy: "pairing",
         allowFrom: ["+15555550123"], // bluebubbles.allowFrom からコピー
         groupPolicy: "allowlist",
         groupAllowFrom: [], // bluebubbles.groupAllowFrom からコピー
         groups: { "*": { requireMention: true } }, // ワイルドカードはそのままコピーし、チャットごとのエントリは chat_id をキーとして付け直す
         // アクションはデフォルトで有効。無効にするには個別のトグルを false に設定
       },
     },
   }
   
2. 切り替えてプローブします。 channels.imessage.enabled: true を設定し、Gateway を再起動して、チャンネルが正常と報告されることを確認します。
   openclaw gateway restart
   openclaw channels status --probe --channel imessage   # 「works」になることを確認。--json では privateApi.available: true と表示される
   
   プローブには到達可能な Gateway が必要で、設定済みかつ有効なアカウントのみがプローブされます。Mac 自体を検証するには、開始する前ににある直接実行用の imsg コマンドを使用してください。
3. DM を検証します。 エージェントにダイレクトメッセージを送信し、返信が届くことを確認します。
4. グループを個別に検証します。 DM とグループでは異なるコードパスが使用されるため、DM の成功だけではグループがルーティングされていることを証明できません。許可されたグループチャットでメッセージを送信し、返信が届くことを確認します。グループが無反応になる場合（エージェントからの返信もエラーもない場合）は、Gateway ログで、上記の「グループレジストリの落とし穴」にある 2 行の warn を確認してください。起動時の警告は、有効な送信者許可リストが空であることを意味します。chat_id ごとの警告は、データが格納された groups レジストリにそのチャットが含まれていないことを意味します。
5. アクションサーフェスを検証します。 ペアリング済みの DM から、リアクション、編集、送信取り消し、返信、写真の送信、および（グループ内での）グループ名の変更や参加者の追加・削除をエージェントに依頼します。各アクションは Messages.app でネイティブに反映される必要があります。いずれかのアクションで iMessage <action> requires the imsg private API bridge が発生した場合は、imsg launch を再度実行し、openclaw channels status --probe で更新してください。
6. iMessage の DM、グループ、アクションを検証したら、BlueBubbles サーバーと channels.bluebubbles ブロックを削除します。OpenClaw は channels.bluebubbles を読み取りません。

​

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

​

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

• 許可リストはハンドル単位で引き継がれます。 channels.imessage.allowFrom は、BlueBubbles で使用していたものと同じ +15555550123 / user@example.com 文字列を認識します。そのままコピーしてください。
• ペアリングストアの承認は移行されません。 ペアリングストアはチャンネルごとに分かれており、古い BlueBubbles ストアは移行されません。ペアリングによってのみ承認されていた送信者は、iMessage で再度ペアリングする必要があります。または、そのハンドルを allowFrom に追加してください。
• セッションのスコープは、引き続きエージェントとチャットの組み合わせごとです。デフォルトの session.dmScope=main では、DM はエージェントのメインセッションに統合されます。グループセッションは chat_id（agent:<agentId>:imessage:group:<chat_id>）ごとに分離されたままです。BlueBubbles のセッションキーに保存された古い会話履歴は、iMessage セッションには引き継がれません。
• match.channel: "bluebubbles" を参照する ACP バインディングは、"imessage" に変更する必要があります。match.peer.id の形式（chat_id:、chat_guid:、chat_identifier:、ハンドルのみ）は同一です。

​

ロールバック先のチャンネルなし

​

関連項目

• BlueBubbles の削除と imsg iMessage パス — 短い告知と運用者向け概要。
• iMessage — imsg launch のセットアップと機能検出を含む、iMessage チャンネルの完全なリファレンス。
• /channels/bluebubbles — この移行ガイドにリダイレクトされる旧 URL。
• ペアリング — DM の認証とペアリングの流れ。
• チャンネルルーティング — Gateway が送信返信に使用するチャンネルを選択する仕組み。