BlueBubbles (macOS REST)

ステータス: HTTP経由でBlueBubbles macOSサーバーと通信するバンドルプラグインです。従来の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呼び出しです。
  • 添付ファイルとステッカーは受信メディアとして取り込まれ、可能な場合はエージェントに表示されます。
  • ペアリング/許可リストは他のChannel（チャンネル）と同じように動作します（/start/pairingなど）。channels.bluebubbles.allowFrom + ペアリングコードを使用します。
  • リアクションはSlack/Telegramと同様にシステムイベントとして表示されるため、エージェントは返信前に「言及」できます。
  • 高度な機能: 編集、送信取り消し、返信スレッド、メッセージエフェクト、グループ管理。

クイックスタート

  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ハンドラーが登録され、ペアリングが開始されます。

オンボーディング

BlueBubblesは対話型セットアップウィザードで利用できます:

openclaw onboard

ウィザードは以下を要求します:

  • Server URL（必須）: BlueBubblesサーバーアドレス（例: http://192.168.1.100:1234）
  • Password（必須）: BlueBubbles Server設定からのAPIパスワード
  • Webhook path（オプション）: デフォルトは/bluebubbles-webhook
  • DM policy: pairing、allowlist、open、またはdisabled
  • Allow list: 電話番号、メールアドレス、またはチャットターゲット

CLI経由でBlueBubblesを追加することもできます:

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>
  • ペアリングはデフォルトのトークン交換です。詳細: Pairing

グループ:

  • channels.bluebubbles.groupPolicy = open | allowlist | disabled（デフォルト: allowlist）。
  • channels.bluebubbles.groupAllowFromは、allowlistが設定されている場合にグループ内で誰がトリガーできるかを制御します。

メンション制御（グループ）

BlueBubblesは、iMessage/WhatsAppの動作に一致するグループチャットのメンション制御をサポートします:

  • agents.list[].groupChat.mentionPatterns（またはmessages.groupChat.mentionPatterns）を使用してメンションを検出します。
  • グループでrequireMentionが有効な場合、エージェントはメンションされた時のみ応答します。
  • 認証された送信者からの制御コマンドはメンション制御をバイパスします。

グループごとの設定:

{
  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）
    • ボイスメモ: MP3またはCAFオーディオでasVoice: trueを設定すると、iMessageボイスメッセージとして送信されます。BlueBubblesはボイスメモ送信時にMP3をCAFに変換します。

メッセージID（短縮 vs 完全）

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

  • MessageSid / ReplyToIdは短縮IDの場合があります。
  • MessageSidFull / ReplyToIdFullにはプロバイダーの完全IDが含まれます。
  • 短縮IDはメモリ内にあり、再起動またはキャッシュ削除時に期限切れになる可能性があります。
  • アクションは短縮または完全なmessageIdを受け付けますが、短縮IDが利用できなくなるとエラーになります。

永続的な自動化とストレージには完全IDを使用してください:

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

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

ブロックストリーミング

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

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

メディア + 制限

  • 受信添付ファイルはダウンロードされ、メディアキャッシュに保存されます。
  • channels.bluebubbles.mediaMaxMbによるメディア上限（デフォルト: 8 MB）。
  • 送信テキストはchannels.bluebubbles.textChunkLimitにチャンク化されます（デフォルト: 4000文字）。

設定リファレンス

完全な設定: Configuration

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

  • 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: ブロックストリーミングの有効化（デフォルト: true）。
  • channels.bluebubbles.textChunkLimit: 送信チャンクサイズ（文字数、デフォルト: 4000）。
  • channels.bluebubbles.chunkMode: length（デフォルト）はtextChunkLimitを超える場合のみ分割します。newlineは長さチャンク化の前に空白行（段落境界）で分割します。
  • channels.bluebubbles.mediaMaxMb: 受信メディア上限（MB、デフォルト: 8）。
  • 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 securityを参照してください。
  • LAN外でBlueBubblesサーバーを公開する場合は、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。

一般的なチャンネルワークフローのリファレンスについては、ChannelsとPluginsガイドを参照してください。

← ドキュメントに戻る