OpenClaw

OpenClaw BlueBubbles チャンネル

メッセージング
普通

BlueBubbles REST API を通じて OpenClaw を iMessage に接続します。この統合により Mac が iMessage ゲートウェイに変わります — BlueBubbles サーバーアプリをインストールし、Web API を有効にすれば、AI アシスタントが iMessage メッセージ、tapback リアクション、メディア添付ファイルの送受信が可能になります。BlueBubbles はレガシー imsg CLI に代わる推奨の iMessage チャネルです。

基本情報
難易度普通
カテゴリメッセージング
対応機能数4 / 6

BlueBubbles 対応機能

テキストメッセージ

対応

メディア・ファイル

対応

リアクション

対応

スレッド

非対応

音声メッセージ

非対応

グループチャット

対応

BlueBubbles 前提条件

  • macOS High Sierra (10.13) 以降を実行する Mac（全機能には Ventura 13+ を推奨、Tahoe 26 は一部制限あり）
  • BlueBubbles サーバーアプリがインストール済み（bluebubbles.app からダウンロード）
  • BlueBubbles 設定で Web API を有効化しパスワードを設定済み
  • OpenClaw Gateway が実行・設定済み

BlueBubbles クイックセットアップ

1

Mac に BlueBubbles サーバーをインストール

bluebubbles.app/install から BlueBubbles サーバーアプリをダウンロードしてインストールします。アプリを起動し、Apple ID でサインインし、初期設定を完了します。Mac で iMessage が正常に動作していることを確認してください。

2

Web API を有効化

BlueBubbles サーバー設定で Web/REST API を有効にし、強力なパスワードを設定します。サーバー URL（例：http://localhost:1234）をメモしておきます — OpenClaw の設定で使用します。

3

BlueBubbles チャネル設定を追加

'openclaw onboard' を実行して BlueBubbles を選択するか、~/.openclaw/openclaw.json に serverUrl と password を手動で設定します。必要に応じて webhookPath も設定できます。

4

Webhook を設定してテスト

BlueBubbles の Webhook を Gateway に向けます：https://your-gateway-host:3000/bluebubbles-webhook?password=<password>。Gateway を起動し、テスト用の iMessage を送信して接続を確認します。pairing ポリシーを使用している場合は、'openclaw pairing approve bluebubbles <code>' で送信者を承認します。

BlueBubbles 設定例

config.json
{
  "channels": {
    "bluebubbles": {
      "enabled": true,
      "serverUrl": "http://localhost:1234",
      "password": "YOUR_BLUEBUBBLES_PASSWORD",
      "webhookPath": "/bluebubbles-webhook",
      "dmPolicy": "pairing"
    }
  }
}

BlueBubbles 詳細ドキュメント

アーキテクチャ概要

OpenClaw は Mac 上で動作する BlueBubbles サーバーアプリを通じて iMessage に接続します。BlueBubbles は REST API を公開し、Gateway はこの API を使用してメッセージの送信、リアクション、チャット管理を行います。受信メッセージは Webhook で配信されます — BlueBubbles が新しいメッセージイベントを Gateway の Webhook エンドポイントにプッシュします。 アーキテクチャの流れ：iMessage が Mac に到着 → BlueBubbles サーバー → Webhook で Gateway にプッシュ → OpenClaw が AI で処理 → REST API で BlueBubbles にコールバック → iMessage 配信。 このアプローチには常時オンラインの Mac（物理マシンまたは VM）が必要です。iMessage は Apple 専用サービスのためです。Mac が Apple のメッセージングエコシステムと OpenClaw アシスタント間のブリッジとして機能します。
専用の Mac Mini または macOS VM が、BlueBubbles を永続的な iMessage ゲートウェイとして運用するのに最適です。
BlueBubbles は Private API をサポートし、tapback リアクション、メッセージ編集、取り消しなどの高度な機能を実現します — BlueBubbles の設定で有効にしてください。

BlueBubbles サーバーのセットアップ

BlueBubbles のセットアップには Mac にサーバーアプリをインストールする必要があります： 1. bluebubbles.app/install から BlueBubbles をダウンロードしてアプリを起動。 2. Apple ID でサインインし、Mac で iMessage が正常に動作していることを確認。 3. BlueBubbles の設定で Web/REST API を有効化。 4. 強力な API パスワードを設定 — このパスワードですべての API リクエストと Webhook 配信を認証します。 5. アプリに表示されるサーバー URL をメモ（デフォルト：http://localhost:1234）。 6. オプション：Private API を有効にして高度な機能（リアクション、編集、取り消し）を利用。 サーバーは常に実行されている必要があります。信頼性のために BlueBubbles を起動時に自動起動するよう設定してください。
webhook URL
# Gateway 用の Webhook URL フォーマット
https://your-gateway-host:3000/bluebubbles-webhook?password=YOUR_PASSWORD
BlueBubbles API パスワードを安全に保管してください。ネットワーク公開サーバーの場合は、BlueBubbles で HTTPS を有効にし、ファイアウォールルールでアクセスを制限してください。同一ホストのリバースプロキシはパスワード認証をバイパスします — プロキシレベルの認証を追加し、gateway.trustedProxies を設定してください。

DM ポリシー

DM（ダイレクトメッセージ）ポリシーは、iMessage 経由で AI アシスタントとやり取りできるユーザーを制御します。OpenClaw は4つのポリシーをサポートしています： • pairing（デフォルト）— 不明な送信者には時間制限付きペアリングコード（1時間で期限切れ）が送信されます。'openclaw pairing approve bluebubbles <CODE>' で承認または拒否します。承認後は自由にチャットできます。 • allowlist — allowFrom リストに記載された電話番号とメールアドレスのみがメッセージを送信できます。それ以外は無視されます。電話番号は E.164 形式をサポート。 • open — メッセージを送信した全員に返信します。慎重に使用してください。 • disabled — DM 処理を完全に無効化します。
openclaw.json
{
  "channels": {
    "bluebubbles": {
      "dmPolicy": "allowlist",
      "allowFrom": ["+15551234567", "user@example.com"]
    }
  }
}
allowFrom フィールドは電話番号（E.164 形式、例：+15551234567）とメールアドレスの両方を受け付け、iMessage ルーティングに使用されます。

グループチャット管理

OpenClaw は BlueBubbles を通じて iMessage グループチャットをサポートし、柔軟なアクセス制御を提供します： • groupPolicy でグループチャット内でボットをトリガーできるユーザーを制御： - open — グループメンバー全員が対話可能 - allowlist — groupAllowFrom リストのアドレスのみがトリガー可能 - disabled（デフォルト）— グループメッセージを無視 • メンション検知 — requireMention が true（グループのデフォルト）の場合、ボットはメンションされた時のみ応答。メンションパターンは agents.list[].groupChat.mentionPatterns で設定。 • グループ別設定 — groups オブジェクトで特定のグループチャットに異なる requireMention ルールを設定。
openclaw.json
{
  "channels": {
    "bluebubbles": {
      "groupPolicy": "allowlist",
      "groupAllowFrom": ["+15551234567"],
      "groups": {
        "iMessage;+;chat123456": {
          "requireMention": false
        }
      }
    }
  }
}

iMessage アクションとエフェクト

BlueBubbles は Private API を通じて豊富な iMessage ネイティブアクションを公開します。各アクションは個別に切り替え可能： • reactions — tapback リアクションの送受信（ハート、いいね、よくないね、笑い、強調、はてな） • edit — 送信済みメッセージの編集（macOS 13+ 必須；macOS Tahoe では現在使用不可） • unsend — 送信済みメッセージの取り消し（macOS 13+） • reply — GUID によるメッセージスレッディング • sendWithEffect — バブルエフェクト付きメッセージ送信（スラム、ラウド、ジェントル、インビジブルインクなど） • sendAttachment — メディアファイルとボイスメモの送信（ボイスは MP3/CAF 形式；BlueBubbles が MP3→CAF 変換を自動処理） グループ管理アクション： • renameGroup — グループチャット名の変更 • setGroupIcon — グループチャット写真の設定（macOS Tahoe では不安定） • addParticipant / removeParticipant / leaveGroup — グループメンバーの管理
openclaw.json
{
  "channels": {
    "bluebubbles": {
      "actions": {
        "reactions": true,
        "edit": true,
        "unsend": true,
        "reply": true,
        "sendWithEffect": true,
        "sendAttachment": true
      }
    }
  }
}
macOS Tahoe (26) では、Private API の変更により edit アクションが現在使用できず、setGroupIcon は信頼性が低い（API は成功を返すがアイコンが同期されない）状態です。Tahoe を実行している場合は、これらのアクションを手動で無効にしてください。

メッセージ配信とチャンキング

OpenClaw は長い AI レスポンスに対してチャンキング配信を設定可能です： • textChunkLimit — メッセージチャンクあたりの最大文字数（デフォルト：4000）。iMessage に厳密な制限はありませんが、長すぎるメッセージは一部のデバイスで表示が崩れる場合があります。 • chunkMode — テキスト分割方法の制御： - length（デフォルト）— textChunkLimit の文字数で強制分割 - newline — 段落境界で分割し、より自然な読み心地に • blockStreaming — true の場合、レスポンスは生成中にブロック単位で送信され、完全なレスポンスを待ちません。 既読通知はデフォルトで送信され、自然な会話感を維持します。AI レスポンス生成前・生成中に入力インジケーターが自動送信されます。
openclaw.json
{
  "channels": {
    "bluebubbles": {
      "textChunkLimit": 4000,
      "chunkMode": "newline",
      "blockStreaming": false,
      "sendReadReceipts": true
    }
  }
}

メディアと添付ファイル

BlueBubbles は iMessage を通じたメディアの送受信をサポートします： • 受信添付ファイルは Gateway によって自動的にダウンロード・キャッシュされます。最大受信ファイルサイズは mediaMaxMb で制御されます（デフォルト：8 MB）。 • sendAttachment アクションで asVoice: true を設定してボイスメモを送信できます。BlueBubbles は MP3 を CAF に自動変換し、ネイティブな iMessage ボイスメモ再生を実現します。 • 送信メディアは sendAttachment アクションで buffer、filename、オプションの mime タイプパラメータを使用して送信します。
ボイスメモは MP3 または CAF 形式を使用してください。BlueBubbles が MP3 を CAF に自動変換してネイティブ iMessage 再生を実現します。
より大きな添付ファイルを扱う場合は mediaMaxMb を調整してください — デフォルトの 8 MB はほとんどの写真と短い動画をカバーします。

メッセージ ID の処理

BlueBubbles は2種類のメッセージ識別子を使用します： • ショート ID — メモリ内の一時的なトークン（1, 2, 3 など）。高速ですが一時的です。Gateway の再起動やキャッシュクリアで失効します。 • フル ID — 永続的なプロバイダー識別子（MessageSidFull, ReplyToIdFull）。再起動後も保持され、長期的な参照に適しています。 アクションパラメータ（messageId, replyTo など）は両方の形式を受け付けます。再起動を跨いでメッセージを参照する必要がある永続的な自動化には、常にフル ID を使用してください。
Gateway の再起動後も有効な自動化には、フルメッセージ ID を使用してください。ショート ID は対話的な使用に便利ですが、再起動後は無効になります。

アドレッシングとルーティング

BlueBubbles はメッセージ配信に複数のアドレス形式をサポートします。安定性順の優先ルーティング順序： 1. chat_guid — 最も安定した形式：chat_guid:iMessage;-;+15555550123 2. chat_id — 数値チャット識別子：chat_id:123 3. chat_identifier — チャット識別子文字列 4. 直接アドレス — 電話番号（+15555550123）またはメール（user@example.com） 既存のチャットがない直接アドレスに送信する場合、BlueBubbles は POST /api/v1/chat/new で自動的に新しい DM を作成します（Private API が必要）。
自動化では最も信頼性の高いメッセージルーティングのために chat_guid 形式を使用してください。

セキュリティと Webhook 認証

BlueBubbles は設定されたパスワードで Webhook 配信を認証します。Gateway はパスワードパラメータ（クエリ文字列またはヘッダー経由）が channels.bluebubbles.password の設定と一致するかを検証します。 セキュリティに関する注意事項： • localhost リクエストは自動的に信頼され、パスワード検証をスキップします。 • 同一ホストのリバースプロキシもパスワードチェックをバイパスします — 同じマシン上でリバースプロキシを使用する場合は、プロキシレベルの認証を追加し、gateway.trustedProxies を設定してください。 • BlueBubbles サーバーで HTTPS を有効にして通信を暗号化。 • ファイアウォールルールで BlueBubbles API ポートへの外部アクセスを制限。 本番デプロイでは、必ず HTTPS を使用し、Webhook エンドポイントが認証なしで公開されないようにしてください。
同一ホストのリバースプロキシは BlueBubbles のパスワード認証をバイパスします。リバースプロキシ使用時は、必ずプロキシレベルの認証を設定し、gateway.trustedProxies を構成してください。

Messages.app キープアライブ（ヘッドレス/VM）

ヘッドレス Mac や VM で BlueBubbles を実行する場合、Messages.app がアイドル状態になりメッセージ処理を停止することがあります。解決策は、5分ごとに AppleScript を実行して Messages のスクリプティングインターフェースにアクセスする LaunchAgent を設定することです。 このキープアライブスクリプトは一時的なエラーを安全に無視し、他のアプリケーションからフォーカスを奪いません。iMessage ブリッジの信頼性ある無人運用に不可欠です。 macOS LaunchAgent plist を設定し、定期的に AppleScript を実行して Messages.app の応答性を維持してください。
これはヘッドレス/VM 環境でのみ必要です。Mac にアクティブなデスクトップセッションがあり Messages.app が表示されている場合、キープアライブは不要です。
launchctl で LaunchAgent を管理 — 起動時にロードして完全な無人運用を実現してください。

BlueBubbles 設定リファレンス

enabled
Type: booleanDefault: false

BlueBubbles チャネルの有効化/無効化

serverUrl
Type: stringDefault: ""

BlueBubbles REST API ベース URL（例：http://localhost:1234）

password
Type: stringDefault: ""

認証用の BlueBubbles API パスワード

webhookPath
Type: stringDefault: "/bluebubbles-webhook"

受信メッセージ用の Webhook エンドポイントパス

dmPolicy
Type: stringDefault: "pairing"

ボットに DM できるユーザーを制御。選択肢：pairing, allowlist, open, disabled

allowFrom
Type: string[]Default: []

メッセージ送信を許可する電話番号とメール（電話は E.164 形式）

groupPolicy
Type: stringDefault: "allowlist"

グループチャットポリシー。選択肢：open, allowlist, disabled

groupAllowFrom
Type: string[]Default: []

グループチャットでボットをトリガーする権限を持つ送信者アドレス

sendReadReceipts
Type: booleanDefault: true

メッセージ処理時に既読通知を送信

blockStreaming
Type: booleanDefault: false

完全なレスポンスを待つ代わりにブロックベースのレスポンスストリーミングを有効化

textChunkLimit
Type: numberDefault: 4000

送信テキストメッセージチャンクあたりの最大文字数

chunkMode
Type: stringDefault: "length"

テキスト分割モード。選択肢：length（サイズベース）, newline（段落ベース）

mediaMaxMb
Type: numberDefault: 8

受信添付ファイルの最大ファイルサイズ（MB）

historyLimit
Type: numberDefault: -

AI コンテキストとして含めるグループメッセージの最大数（0 で無効）

dmHistoryLimit
Type: numberDefault: -

AI コンテキストの DM 会話履歴制限

actions.reactions
Type: booleanDefault: true

tapback リアクションを有効化（Private API 必須）

actions.edit
Type: booleanDefault: true

メッセージ編集を有効化（macOS 13+ 必須；Tahoe では使用不可）

actions.unsend
Type: booleanDefault: true

メッセージ取り消しを有効化（macOS 13+ 必須）

actions.reply
Type: booleanDefault: true

GUID によるメッセージスレッディングを有効化

actions.sendWithEffect
Type: booleanDefault: true

iMessage バブルエフェクト（スラム、ラウドなど）を有効化

actions.sendAttachment
Type: booleanDefault: true

メディアとボイスメモの配信を有効化

BlueBubbles よくある質問

BlueBubbles トラブルシューティング

Webhook がメッセージを受信しない

BlueBubbles の Webhook URL が Gateway エンドポイントと一致しないか、パスワードパラメータが正しくない。

Webhook URL が https://your-gateway-host:3000/bluebubbles-webhook?password=YOUR_PASSWORD に設定されていることを確認。channels.bluebubbles.webhookPath が URL のパスと一致するか確認。Gateway ログで受信 Webhook リクエストを確認。
Gateway は接続済みだがアクションが失敗する（リアクション、編集、取り消し）

BlueBubbles Private API が有効化されていないか、サーバーバージョンが必要な API エンドポイントをサポートしていない。

BlueBubbles サーバー設定で Private API を有効化。BlueBubbles を最新バージョンに更新。特定のアクションが macOS Tahoe で失敗する場合は個別に無効化：channels.bluebubbles.actions.edit=false。
ヘッドレス Mac で Messages.app が応答しなくなる

Messages.app がヘッドレス/VM 環境でアイドル状態になり、スクリプティングインターフェースの処理を停止。

AppleScript キープアライブ LaunchAgent を設定し、5分ごとに Messages のスクリプティングインターフェースにアクセス。LaunchAgent が launchctl でロードされ、起動時に実行されることを確認。
ボットが送信したメッセージが iMessage ではない（緑のバブル）

受信者の電話番号またはメールが iMessage に登録されていないか、Mac の Apple ID で iMessage が無効。

Mac の Messages.app の環境設定で iMessage が有効であることを確認。受信者が iMessage 対応の Apple デバイスを使用しているか確認。緑のバブルは SMS フォールバックを示し、BlueBubbles は設定によってサポートしない場合があります。
macOS Tahoe で編集アクションが失敗する

既知の問題 — macOS Tahoe (26) がメッセージ編集の Private API エンドポイントを破壊。

編集アクションを無効化：channels.bluebubbles.actions.edit を false に設定。これは Tahoe における BlueBubbles の既知の制限です。修正については BlueBubbles のリリースを注視してください。
完全なドキュメントを見るすべてのチャンネルに戻る

関連チャンネル

WhatsApp

Medium

OpenClaw を Baileys プロトコルでQRコード接続

セットアップガイド

Telegram

Easy

OpenClaw の grammY フレームワーク経由Bot API連携

セットアップガイド

Discord

Easy

OpenClaw の discord.js Bot Token連携

セットアップガイド