BlueBubbles

ステータス: BlueBubbles macOS サーバーと HTTP 経由で通信するバンドル済みレガシー Plugin。既存の BlueBubbles セットアップは引き続き動作しますが、新しい OpenClaw iMessage デプロイでは、ホストの要件に合う場合はネイティブの iMessage Plugin を優先してください。

# 概要

• BlueBubbles ヘルパーアプリ（bluebubbles.app）を介して macOS 上で動作します。
• BlueBubbles チャネル ID、webhook 状態、グループターゲット、cron 配信、またはワークスペースルーティングにすでに依存しているインストール向けのレガシーフォールバックです。
• 推奨/テスト済み: macOS Sequoia (15)。macOS Tahoe (26) でも動作します。Tahoe では現在編集が壊れており、グループアイコンの更新は成功と報告されても同期されない場合があります。
• OpenClaw は REST API（GET /api/v1/ping、POST /message/text、POST /chat/:id/*）を通じて通信します。
• 受信メッセージは webhooks 経由で届きます。送信返信、入力インジケーター、既読通知、tapback は REST 呼び出しです。
• 添付ファイルとステッカーは受信メディアとして取り込まれます（可能な場合はエージェントにも提示されます）。
• MP3 または CAF 音声を合成する自動 TTS 返信は、通常のファイル添付ではなく iMessage のボイスメモバブルとして配信されます。
• ペアリング/許可リストは、channels.bluebubbles.allowFrom + ペアリングコードを使い、他のチャネル（/channels/pairing など）と同じ方法で動作します。
• リアクションは Slack/Telegram と同様にシステムイベントとして提示されるため、エージェントは返信前にそれらに「メンション」できます。
• 高度な機能: 編集、送信取り消し、返信スレッド、メッセージエフェクト、グループ管理。

# クイックスタート

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

# Messages.app を稼働状態に保つ（VM / ヘッドレスセットアップ）

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

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

<?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>

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

ウィザードは次の項目を求めます。

CLI から BlueBubbles を追加することもできます。

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

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

# 連絡先名の補完（macOS、任意）

BlueBubbles のグループ webhooks には、多くの場合、生の参加者アドレスだけが含まれます。代わりに GroupMembers コンテキストにローカル連絡先名を表示したい場合は、macOS 上のローカル連絡先補完を有効にできます。

• channels.bluebubbles.enrichGroupParticipantsFromContacts = true でルックアップを有効にします。デフォルト: false。
• ルックアップは、グループアクセス、コマンド認可、メンションゲートがメッセージの通過を許可した後にのみ実行されます。
• 名前のない電話参加者のみ補完されます。
• ローカル一致が見つからない場合、生の電話番号がフォールバックとして残ります。

{
  channels: {
    bluebubbles: {
      enrichGroupParticipantsFromContacts: true,
    },
  },
}

# メンションゲート（グループ）

BlueBubbles は、iMessage/WhatsApp の動作に合わせてグループチャットのメンションゲートをサポートします。

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

グループごとの設定:

{
  channels: {
    bluebubbles: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15555550123"],
      groups: {
        "*": { requireMention: true }, // default for all groups
        "iMessage;-;chat123": { requireMention: false }, // override for specific group
      },
    },
  },
}

# コマンドゲート

• 制御コマンド（例: /config、/model）には認可が必要です。
• allowFrom と groupAllowFrom を使ってコマンド認可を判定します。
• 認可済み送信者は、グループでメンションしなくても制御コマンドを実行できます。

# グループごとのシステムプロンプト

channels.bluebubbles.groups.* 配下の各エントリは、任意の systemPrompt 文字列を受け付けます。この値は、そのグループ内のメッセージを処理するすべてのターンでエージェントのシステムプロンプトに注入されるため、エージェントプロンプトを編集せずにグループごとのペルソナや動作ルールを設定できます。

{
  channels: {
    bluebubbles: {
      groups: {
        "iMessage;-;chat123": {
          systemPrompt: "Keep responses under 3 sentences. Mirror the group's casual tone.",
        },
      },
    },
  },
}

キーは、BlueBubbles がグループに対して報告する chatGuid / chatIdentifier / 数値 chatId のいずれかと一致します。また、"*" ワイルドカードエントリは、完全一致がないすべてのグループにデフォルトを提供します（requireMention とグループごとのツールポリシーで使われるものと同じパターンです）。完全一致は常にワイルドカードより優先されます。DM はこのフィールドを無視します。代わりにエージェントレベルまたはアカウントレベルのプロンプトカスタマイズを使用してください。

# 実例: スレッド返信と tapback リアクション（Private API）

BlueBubbles Private API が有効な場合、受信メッセージには短いメッセージ ID（例: [[reply_to:5]]）が付与され、エージェントは action=reply を呼び出して特定のメッセージにスレッド返信したり、action=react で tapback を付けたりできます。グループごとの systemPrompt は、エージェントに適切なツールを選ばせ続ける信頼性の高い方法です。

{
  channels: {
    bluebubbles: {
      groups: {
        "iMessage;+;chat-family": {
          systemPrompt: "When replying in this group, always call action=reply with the [[reply_to:N]] messageId from context so your response threads under the triggering message. Never send a new unlinked message. For short acknowledgements ('ok', 'got it', 'on it'), use action=react with an appropriate tapback emoji (❤️, 👍, 😂, ‼️, ❓) instead of sending a text reply.",
        },
      },
    },
  },
}

Tapback リアクションとスレッド返信はいずれも BlueBubbles Private API が必要です。基礎となる仕組みについては、高度なアクション と メッセージ ID を参照してください。

# ACP 会話バインディング

BlueBubbles チャットは、トランスポート層を変更せずに永続的な ACP ワークスペースへ変換できます。

高速なオペレーターフロー:

• DM または許可されたグループチャット内で /acp spawn codex --bind here を実行します。
• 以後、その同じ BlueBubbles 会話内のメッセージは、生成された ACP セッションにルーティングされます。
• /new と /reset は、同じバインド済み ACP セッションをその場でリセットします。
• /acp close は ACP セッションを閉じ、バインディングを削除します。

設定済みの永続バインディングも、type: "acp" と match.channel: "bluebubbles" を持つトップレベルの bindings[] エントリを通じてサポートされます。

match.peer.id には、サポートされている任意の BlueBubbles ターゲット形式を使用できます。

• 正規化された DM ハンドル（+15555550123 や [email protected] など）
• chat_id:<id>
• chat_guid:<guid>
• chat_identifier:<identifier>

安定したグループバインディングには、chat_id:* または chat_identifier:* を優先してください。

例:

{
  agents: {
    list: [
      {
        id: "codex",
        runtime: {
          type: "acp",
          acp: { agent: "codex", backend: "acpx", mode: "persistent" },
        },
      },
    ],
  },
  bindings: [
    {
      type: "acp",
      agentId: "codex",
      match: {
        channel: "bluebubbles",
        accountId: "default",
        peer: { kind: "dm", id: "+15555550123" },
      },
      acp: { label: "codex-imessage" },
    },
  ],
}

共有 ACP バインディングの動作については、ACPエージェントを参照してください。

# 入力中 + 既読通知

• 入力インジケーター: 応答生成の前および生成中に自動送信されます。
• 既読通知: channels.bluebubbles.sendReadReceipts で制御します（デフォルト: true）。
• 入力インジケーター: OpenClaw は入力開始イベントを送信します。BlueBubbles は送信時またはタイムアウト時に入力中状態を自動的に解除します（DELETE による手動停止は信頼できません）。

{
  channels: {
    bluebubbles: {
      sendReadReceipts: false, // disable read receipts
    },
  },
}

# 高度なアクション

BlueBubbles は、設定で有効化されている場合に高度なメッセージアクションをサポートします。

{
  channels: {
    bluebubbles: {
      actions: {
        reactions: true, // tapbacks (default: true)
        edit: true, // edit sent messages (macOS 13+, broken on macOS 26 Tahoe)
        unsend: true, // unsend messages (macOS 13+)
        reply: true, // reply threading by message GUID
        sendWithEffect: true, // message effects (slam, loud, etc.)
        renameGroup: true, // rename group chats
        setGroupIcon: true, // set group chat icon/photo (flaky on macOS 26 Tahoe)
        addParticipant: true, // add participants to groups
        removeParticipant: true, // remove participants from groups
        leaveGroup: true, // leave group chats
        sendAttachment: true, // send attachments/media
      },
    },
  },
}

# メッセージ ID（短縮形式と完全形式）

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

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

永続的な自動化と保存には完全な ID を使用してください。

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

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

# 分割送信 DM の結合（1 回の入力にコマンド + URL）

ユーザーが iMessage でコマンドと URL を一緒に入力した場合（例: Dump https://example.com/article）、Apple は送信を2 つの別個の Webhook 配信に分割します。

1. テキストメッセージ（"Dump"）。
2. OG プレビュー画像を添付した URL プレビューバルーン（"https://..."）。

ほとんどの環境では、2 つの Webhook は OpenClaw に約 0.8〜2.0 秒間隔で到着します。結合しない場合、エージェントは 1 ターン目でコマンドだけを受け取り、返信し（多くの場合「URL を送ってください」）、2 ターン目で初めて URL を見ます。この時点ではコマンドのコンテキストはすでに失われています。

channels.bluebubbles.coalesceSameSenderDms は、DM で連続する同一送信者の Webhook を 1 回のエージェントターンに統合するようにします。グループチャットはメッセージごとのキーを引き続き使用するため、複数ユーザーのターン構造は保持されます。

{
  channels: {
    bluebubbles: {
      coalesceSameSenderDms: true, // opt in (default: false)
    },
  },
}

{
  messages: {
    inbound: {
      byChannel: {
        // 2500 ms works for most setups; raise to 4000 ms if your Mac is slow
        // or under memory pressure (observed gap can stretch past 2 s then).
        bluebubbles: 2500,
      },
    },
  },
}

# シナリオとエージェントに見える内容

# 分割送信の結合に関するトラブルシューティング

フラグがオンでも分割送信がまだ 2 ターンとして到着する場合は、各レイヤーを確認してください。

grep coalesceSameSenderDms ~/.openclaw/openclaw.json

grep -E "Dispatching event to webhook" main.log | tail -20

# ブロックストリーミング

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

{
  channels: {
    bluebubbles: {
      blockStreaming: true, // enable block streaming (off by default)
    },
  },
}

# メディア + 上限

• 受信した添付ファイルはダウンロードされ、メディアキャッシュに保存されます。
• 受信および送信メディアのメディア上限は channels.bluebubbles.mediaMaxMb で指定します（デフォルト: 8 MB）。
• 送信テキストは channels.bluebubbles.textChunkLimit に従って分割されます（デフォルト: 4000 文字）。

# 設定リファレンス

完全な設定: 設定

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

• 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 が有効である必要があります。

# iMessage と SMS のルーティング

同じハンドルに Mac 上で iMessage チャットと SMS チャットの両方がある場合 (たとえば、iMessage に登録済みだが、緑色の吹き出しのフォールバックも受信したことがある電話番号)、OpenClaw は iMessage チャットを優先し、暗黙に SMS へダウングレードすることはありません。SMS チャットを強制するには、明示的な sms: ターゲットプレフィックスを使用してください (例: sms:+15555550123)。一致する iMessage チャットがないハンドルは、BlueBubbles が報告する任意のチャットを通じて送信されます。

# セキュリティ

• Webhook リクエストは、guid/password クエリパラメーターまたはヘッダーを channels.bluebubbles.password と比較して認証されます。
• API パスワードと Webhook エンドポイントは秘密にしてください (資格情報として扱ってください)。
• BlueBubbles Webhook 認証に localhost バイパスはありません。Webhook トラフィックをプロキシする場合は、リクエストのエンドツーエンドで BlueBubbles パスワードを保持してください。ここでは gateway.trustedProxies は channels.bluebubbles.password の代わりにはなりません。Gateway セキュリティを参照してください。
• 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 で手動で無効化してください。
• coalesceSameSenderDms が有効でも分割送信 (例: Dump + URL) がまだ 2 つのターンとして届く場合は、分割送信統合のトラブルシューティング チェックリストを参照してください - 一般的な原因は、デバウンスウィンドウが短すぎる、セッションログのタイムスタンプを Webhook 到着時刻と誤読している、または返信引用送信 (replyToBody を使用し、2 つ目の Webhook ではない) です。
• ステータス/ヘルス情報: openclaw status --all または openclaw status --deep。

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

# 関連

• チャンネルルーティング - メッセージのセッションルーティング
• チャンネル概要 - サポートされているすべてのチャンネル
• グループ - グループチャットの動作とメンションゲート
• ペアリング - DM 認証とペアリングフロー
• セキュリティ - アクセスモデルと強化