BlueBubbles（macOS REST）

ステータス：BlueBubbles macOSサーバーとHTTP経由で通信するバンドルプラグインです。レガシーのimsgチャンネルと比較して、APIが充実しておりセットアップも容易なため、iMessage連携にはこちらを推奨します。

概要

  • BlueBubblesヘルパーアプリ（bluebubbles.app）を通じてmacOS上で動作します。
  • 推奨/テスト済み：macOS Sequoia（15）。macOS Tahoe（26）も動作しますが、Tahoeでは編集機能が現在動作せず、グループアイコンの更新は成功と表示されても同期されない場合があります。
  • OpenClawはREST API（GET /api/v1/ping、POST /message/text、POST /chat/:id/*）を通じて通信します。
  • 受信メッセージはWebhook経由で到着し、送信返信・タイピングインジケーター・既読レシート・タップバックはRESTコールで行います。
  • 添付ファイルとスタンプは受信メディアとして取り込まれ、可能な場合はAgentに表示されます。
  • ペアリング/許可リストは他のチャンネルと同様に動作します（/channels/pairingなど）。channels.bluebubbles.allowFrom + ペアリングコードを使用します。
  • リアクションはSlack/Telegramと同様にシステムイベントとして表示されるため、Agentは返信前にそれらを「メンション」できます。
  • 高度な機能：編集、送信取消、リプライスレッド、メッセージエフェクト、グループ管理。

クイックスタート

  1. Macに BlueBubblesサーバーをインストールします（bluebubbles.app/installの手順に従ってください）。

  2. BlueBubbles設定でWeb APIを有効にし、パスワードを設定します。

  3. openclaw onboard を実行してBlueBubblesを選択するか、手動で設定します：

    {
  channels: {
    bluebubbles: {
      enabled: true,
      serverUrl: "http://192.168.1.100:1234",
      password: "example-password",
      webhookPath: "/bluebubbles-webhook",
    },
  },
}

  4. BlueBubblesのWebhookをGatewayに向けます（例：https://your-gateway-host:3000/bluebubbles-webhook?password=<password>）。

  5. Gatewayを起動すると、Webhookハンドラーが登録されペアリングが開始されます。

セキュリティに関する注意：

  • 必ずWebhookパスワードを設定してください。
  • Webhook認証は常に必須です。OpenClawは、ループバック/プロキシのトポロジに関わらず、channels.bluebubbles.passwordに一致するpassword/guid（例：?password=<password>やx-password）が含まれないBlueBubbles Webhookリクエストを拒否します。
  • パスワード認証はWebhookボディの読み取り/解析前にチェックされます。

Messages.appの維持（VM/ヘッドレス環境）

一部のmacOS VM/常時稼働環境では、Messages.appが「アイドル」状態になることがあります（アプリを開く/前面に出すまで受信イベントが停止します）。簡単な回避策は、AppleScript + LaunchAgentで5分ごとにMessagesを呼び出すことです。

1) AppleScriptの保存

以下を保存してください：

  • ~/Scripts/poke-messages.scpt

スクリプト例（非インタラクティブ、フォーカスを奪いません）：

try
  tell application "Messages"
    if not running then
      launch
    end if

    -- Touch the scripting interface to keep the process responsive.
    set _chatCount to (count of chats)
  end tell
on error
  -- Ignore transient failures (first-run prompts, locked session, etc).
end try

2) LaunchAgentのインストール

以下を保存してください：

  • ~/Library/LaunchAgents/com.user.poke-messages.plist
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>Label</key>
    <string>com.user.poke-messages</string>

    <key>ProgramArguments</key>
    <array>
      <string>/bin/bash</string>
      <string>-lc</string>
      <string>/usr/bin/osascript &quot;$HOME/Scripts/poke-messages.scpt&quot;</string>
    </array>

    <key>RunAtLoad</key>
    <true/>

    <key>StartInterval</key>
    <integer>300</integer>

    <key>StandardOutPath</key>
    <string>/tmp/poke-messages.log</string>
    <key>StandardErrorPath</key>
    <string>/tmp/poke-messages.err</string>
  </dict>
</plist>

注意事項：

  • 300秒ごとおよびログイン時に実行されます。
  • 初回実行時にmacOSのオートメーション許可プロンプト（osascript → Messages）が表示される場合があります。LaunchAgentを実行するのと同じユーザーセッションで承認してください。

読み込み：

launchctl unload ~/Library/LaunchAgents/com.user.poke-messages.plist 2>/dev/null || true
launchctl load ~/Library/LaunchAgents/com.user.poke-messages.plist

オンボーディング

BlueBubblesはインタラクティブセットアップウィザードで利用可能です：

openclaw onboard

ウィザードで入力が求められる項目：

  • サーバーURL（必須）：BlueBubblesサーバーのアドレス（例：http://192.168.1.100:1234）
  • パスワード（必須）：BlueBubbles Server設定のAPIパスワード
  • Webhookパス（任意）：デフォルトは/bluebubbles-webhook
  • DMポリシー：pairing、allowlist、open、disabled
  • 許可リスト：電話番号、メールアドレス、またはチャット対象

CLIでの追加も可能です：

openclaw channels add bluebubbles --http-url http://192.168.1.100:1234 --password <password>

アクセス制御（DM + グループ）

DM：

  • デフォルト：channels.bluebubbles.dmPolicy = "pairing"
  • 不明な送信者にはペアリングコードが送信されます。承認されるまでメッセージは無視されます（コードは1時間後に期限切れ）。
  • 承認方法：
    • openclaw pairing list bluebubbles
    • openclaw pairing approve bluebubbles <CODE>
  • ペアリングはデフォルトのトークン交換です。詳細：ペアリング

グループ：

  • channels.bluebubbles.groupPolicy = open | allowlist | disabled（デフォルト：allowlist）
  • allowlist設定時、channels.bluebubbles.groupAllowFromでグループ内でトリガーできるユーザーを制御します。

メンションゲーティング（グループ）

BlueBubblesはグループチャットでのメンションゲーティングをサポートしており、iMessage/WhatsAppと同様の動作をします：

  • agents.list[].groupChat.mentionPatterns（またはmessages.groupChat.mentionPatterns）でメンション検出を行います。
  • グループでrequireMentionが有効な場合、Agentはメンションされた場合のみ応答します。
  • 権限のある送信者からのコントロールコマンドはメンションゲーティングをバイパスします。

グループごとの設定：

{
  channels: {
    bluebubbles: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15555550123"],
      groups: {
        "*": { requireMention: true }, // 全グループのデフォルト
        "iMessage;-;chat123": { requireMention: false }, // 特定グループのオーバーライド
      },
    },
  },
}

コマンドゲーティング

  • コントロールコマンド（例：/config、/model）には認可が必要です。
  • allowFromとgroupAllowFromでコマンドの認可を判定します。
  • 権限のある送信者は、グループ内でメンションなしでもコントロールコマンドを実行できます。

タイピング + 既読レシート

  • タイピングインジケーター：返信生成前および生成中に自動送信されます。
  • 既読レシート：channels.bluebubbles.sendReadReceiptsで制御します（デフォルト：true）。
  • タイピングインジケーター：OpenClawはタイピング開始イベントを送信します。BlueBubblesは送信時またはタイムアウト時に自動的にクリアします（DELETEによる手動停止は信頼性が低いです）。
{
  channels: {
    bluebubbles: {
      sendReadReceipts: false, // 既読レシートを無効化
    },
  },
}

高度なアクション

BlueBubblesは設定で有効にした場合、高度なメッセージアクションをサポートします：

{
  channels: {
    bluebubbles: {
      actions: {
        reactions: true, // タップバック（デフォルト：true）
        edit: true, // 送信済みメッセージの編集（macOS 13+、macOS 26 Tahoeでは動作しない）
        unsend: true, // メッセージの送信取消（macOS 13+）
        reply: true, // メッセージGUIDによるリプライスレッド
        sendWithEffect: true, // メッセージエフェクト（slam、loudなど）
        renameGroup: true, // グループチャットのリネーム
        setGroupIcon: true, // グループチャットのアイコン/写真設定（macOS 26 Tahoeでは不安定）
        addParticipant: true, // グループへの参加者追加
        removeParticipant: true, // グループからの参加者削除
        leaveGroup: true, // グループチャットからの退出
        sendAttachment: true, // 添付ファイル/メディアの送信
      },
    },
  },
}

利用可能なアクション：

  • react：タップバックリアクションの追加/削除（messageId、emoji、remove）
  • edit：送信済みメッセージの編集（messageId、text）
  • unsend：メッセージの送信取消（messageId）
  • reply：特定メッセージへの返信（messageId、text、to）
  • sendWithEffect：iMessageエフェクト付き送信（text、to、effectId）
  • renameGroup：グループチャットのリネーム（chatGuid、displayName）
  • setGroupIcon：グループチャットのアイコン/写真設定（chatGuid、media）— macOS 26 Tahoeでは不安定（APIは成功を返しますがアイコンが同期されないことがあります）。
  • addParticipant：グループに参加者を追加（chatGuid、address）
  • removeParticipant：グループから参加者を削除（chatGuid、address）
  • leaveGroup：グループチャットから退出（chatGuid）
  • sendAttachment：メディア/ファイルの送信（to、buffer、filename、asVoice）
    • ボイスメモ：asVoice: trueに設定し、MP3またはCAFオーディオを使用するとiMessageボイスメッセージとして送信されます。BlueBubblesはボイスメモ送信時にMP3 → CAFに変換します。

メッセージID（短縮 vs フル）

OpenClawはトークン節約のために_短縮_メッセージID（例：1、2）を表示する場合があります。

  • MessageSid / ReplyToIdは短縮IDの場合があります。
  • MessageSidFull / ReplyToIdFullにはプロバイダーのフルIDが含まれます。
  • 短縮IDはメモリ内にあり、再起動やキャッシュ追い出しで失われる可能性があります。
  • アクションは短縮またはフルのmessageIdを受け付けますが、短縮IDが利用不可になっているとエラーになります。

永続的な自動化やストレージにはフルIDを使用してください：

  • テンプレート：{{MessageSidFull}}、{{ReplyToIdFull}}
  • コンテキスト：受信ペイロードのMessageSidFull / ReplyToIdFull

テンプレート変数については設定を参照してください。

ブロックストリーミング

返信を単一メッセージとして送信するか、ブロック単位でストリーミングするかを制御します：

{
  channels: {
    bluebubbles: {
      blockStreaming: true, // ブロックストリーミングを有効化（デフォルトはオフ）
    },
  },
}

メディア + 制限

  • 受信添付ファイルはダウンロードされメディアキャッシュに保存されます。
  • メディア上限はchannels.bluebubbles.mediaMaxMbで受信/送信メディアを制御します（デフォルト：8 MB）。
  • 送信テキストはchannels.bluebubbles.textChunkLimitでチャンク分割されます（デフォルト：4000文字）。

設定リファレンス

完全な設定：設定

プロバイダーオプション：

  • channels.bluebubbles.enabled：チャンネルの有効/無効
  • channels.bluebubbles.serverUrl：BlueBubbles REST APIベースURL
  • channels.bluebubbles.password：APIパスワード
  • channels.bluebubbles.webhookPath：Webhookエンドポイントパス（デフォルト：/bluebubbles-webhook）
  • channels.bluebubbles.dmPolicy：pairing | allowlist | open | disabled（デフォルト：pairing）
  • channels.bluebubbles.allowFrom：DM許可リスト（ハンドル、メールアドレス、E.164番号、chat_id:*、chat_guid:*）
  • channels.bluebubbles.groupPolicy：open | allowlist | disabled（デフォルト：allowlist）
  • channels.bluebubbles.groupAllowFrom：グループ送信者許可リスト
  • channels.bluebubbles.groups：グループごとの設定（requireMentionなど）
  • channels.bluebubbles.sendReadReceipts：既読レシートの送信（デフォルト：true）
  • channels.bluebubbles.blockStreaming：ブロックストリーミングの有効化（デフォルト：false。ストリーミング返信に必要）
  • channels.bluebubbles.textChunkLimit：送信チャンクサイズ（文字数）（デフォルト：4000）
  • channels.bluebubbles.chunkMode：length（デフォルト）はtextChunkLimit超過時のみ分割。newlineは空行（段落境界）で先に分割してから長さで分割
  • channels.bluebubbles.mediaMaxMb：受信/送信メディア上限（MB）（デフォルト：8）
  • channels.bluebubbles.mediaLocalRoots：送信ローカルメディアパスに許可する絶対ディレクトリの明示的リスト。設定しない限りローカルパス送信はデフォルトで拒否されます。アカウントごとのオーバーライド：channels.bluebubbles.accounts.<accountId>.mediaLocalRoots
  • channels.bluebubbles.historyLimit：コンテキスト用のグループメッセージ上限（0で無効化）
  • channels.bluebubbles.dmHistoryLimit：DM履歴上限
  • channels.bluebubbles.actions：個別アクションの有効/無効
  • channels.bluebubbles.accounts：マルチアカウント設定

関連するグローバルオプション：

  • agents.list[].groupChat.mentionPatterns（またはmessages.groupChat.mentionPatterns）
  • messages.responsePrefix

アドレス指定 / 配信先

安定したルーティングにはchat_guidを推奨します：

  • chat_guid:iMessage;-;+15555550123（グループに推奨）
  • chat_id:123
  • chat_identifier:...
  • 直接ハンドル：+15555550123、[email protected]
    • 直接ハンドルに既存のDMチャットがない場合、OpenClawはPOST /api/v1/chat/newで新規作成します。これにはBlueBubbles Private APIの有効化が必要です。

セキュリティ

  • Webhookリクエストはguid/passwordクエリパラメータまたはヘッダーをchannels.bluebubbles.passwordと照合して認証されます。localhostからのリクエストも受け入れられます。
  • APIパスワードとWebhookエンドポイントは秘密にしてください（認証情報と同様に扱ってください）。
  • Localhost信頼により、同一ホスト上のリバースプロキシが意図せずパスワードをバイパスする可能性があります。Gatewayをプロキシする場合は、プロキシ側で認証を要求しgateway.trustedProxiesを設定してください。Gatewayセキュリティを参照してください。
  • BlueBubblesサーバーをLAN外に公開する場合は、HTTPS + ファイアウォールルールを有効にしてください。

トラブルシューティング

  • タイピング/既読イベントが動作しなくなった場合、BlueBubblesのWebhookログを確認し、Gatewayパスがchannels.bluebubbles.webhookPathと一致しているか検証してください。
  • ペアリングコードは1時間後に期限切れになります。openclaw pairing list bluebubblesとopenclaw pairing approve bluebubbles <code>を使用してください。
  • リアクションにはBlueBubbles Private API（POST /api/v1/message/react）が必要です。サーバーバージョンがこれを公開していることを確認してください。
  • 編集/送信取消にはmacOS 13+と互換性のあるBlueBubblesサーバーバージョンが必要です。macOS 26（Tahoe）ではPrivate APIの変更により編集が現在動作しません。
  • グループアイコンの更新はmacOS 26（Tahoe）で不安定な場合があります：APIは成功を返しますが新しいアイコンが同期されません。
  • OpenClawはBlueBubblesサーバーのmacOSバージョンに基づいて、既知の非対応アクションを自動的に非表示にします。macOS 26（Tahoe）で編集が表示されたままの場合は、channels.bluebubbles.actions.edit=falseで手動で無効にしてください。
  • ステータス/ヘルス情報：openclaw status --allまたはopenclaw status --deep

チャンネル全般のワークフローについては、チャンネルおよびプラグインガイドを参照してください。

arrow_back
前へ
Channels
次へ
Discord
arrow_forward