BlueBubbles

​

概要

• 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 経由で受け取り、返信送信、タイピングインジケーター、既読通知、Tapback は REST 呼び出しで処理します。
• 添付ファイルやステッカーは受信メディアとして取り込まれ、可能であればエージェントにも渡されます。
• ペアリングや許可リストの扱いは他のチャンネル (/channels/pairing など) と同様で、channels.bluebubbles.allowFrom とペアリングコードを利用します。
• リアクションは Slack や Telegram と同様にシステムイベントとして扱われるため、エージェントは返信前にその内容へ触れられます。
• 高度な機能として、編集、送信取り消し、スレッド返信、メッセージエフェクト、グループ管理を利用できます。

​

クイックスタート

1. Mac に BlueBubbles サーバーをインストールします (bluebubbles.app/install の手順に従ってください)。
2. BlueBubbles の設定で、Web API を有効にし、パスワードを設定します。
3. openclaw onboard を実行して BlueBubbles を選択するか、手動で設定します。
   Copy

   Ask AI

   {
     channels: {
       bluebubbles: {
         enabled: true,
         serverUrl: "http://192.168.1.100:1234",
         password: "example-password",
         webhookPath: "/bluebubbles-webhook",
       },
     },
   }
   
4. BlueBubbles の webhook をゲートウェイへ向けます (例: https://your-gateway-host:3000/bluebubbles-webhook?password=<password>)。
5. ゲートウェイを起動します。webhook ハンドラーが登録され、ペアリングが始まります。

• webhook 用のパスワードは必ず設定してください。
• webhook 認証は常に必須です。ループバックやプロキシ構成に関係なく、channels.bluebubbles.password と一致するパスワードまたは GUID を含まない BlueBubbles の webhook リクエストは拒否されます (例: ?password=<password> または x-password)。
• パスワード認証は、webhook 本文を最後まで読み込んだり解析したりする前に実行されます。

​

Messages.app をアクティブに保つ (VM / ヘッドレスセットアップ)

​

1) AppleScript を保存する

• ~/Scripts/poke-messages.scpt

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

    -- プロセスの応答性を維持するためにスクリプティングインターフェースに触れる
    set _chatCount to (count of chats)
  end tell
on error
  -- 一時的な障害 (初回起動プロンプト、ロックされたセッションなど) を無視する
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 の Automation プロンプト (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

​

オンボーディング

openclaw onboard

• サーバー URL (必須): BlueBubbles サーバーアドレス (例: http://192.168.1.100:1234)
• パスワード (必須): BlueBubbles サーバー設定からの API パスワード
• webhook パス (オプション): デフォルトは /bluebubbles-webhook
• DM ポリシー: pairing、allowlist、open、または disabled
• 許可リスト: 電話番号、メールアドレス、またはチャットターゲット

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

​

アクセス制御 (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 でグループ内の実行許可元を制御します。

​

メンションゲーティング (グループ)

• メンションの検出には 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, // 既読確認を無効にする
    },
  },
}

​

高度なアクション

{
  channels: {
    bluebubbles: {
      actions: {
        reactions: true, // tapbacks (デフォルト: true)
        edit: true, // 送信済みメッセージの編集 (macOS 13+、macOS 26 Tahoe では壊れています)
        unsend: true, // メッセージの送信取り消し (macOS 13+)
        reply: true, // メッセージ GUID による返信スレッド
        sendWithEffect: true, // メッセージエフェクト (スラム、ラウドなど)
        renameGroup: true, // グループチャットの名前変更
        setGroupIcon: true, // グループチャットのアイコン/写真の設定 (macOS 26 Tahoe では不安定)
        addParticipant: true, // グループへの参加者の追加
        removeParticipant: true, // グループからの参加者の削除
        leaveGroup: true, // グループチャットからの退出
        sendAttachment: true, // 添付ファイル/メディアの送信
      },
    },
  },
}

• react: Tapback リアクションの追加または削除 (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 の音声を iMessage のボイスメッセージとして送るには asVoice: true を設定します。BlueBubbles は送信時に MP3 を CAF へ変換します。

​

メッセージ ID (短い vs 完全)

• MessageSid と ReplyToId には短い ID が入ることがあります。
• MessageSidFull / ReplyToIdFull にはプロバイダーの完全な ID が含まれています。
• 短い ID はメモリ上にのみ保持されるため、再起動やキャッシュ削除で失効する可能性があります。
• 各アクションは短い messageId と完全な messageId の両方を受け付けますが、短い 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: 送信時に使えるローカルメディアパスとして許可する絶対ディレクトリの明示的な allowlist です。これを設定しない限り、ローカルパスからの送信は既定で拒否されます。アカウント単位で上書きする場合は 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:iMessage;-;+15555550123 (グループに推奨)
• chat_id:123
• chat_identifier:...
• ダイレクトハンドル: +15555550123, user@example.com
  • ダイレクトハンドルに既存の DM チャットがない場合、OpenClaw は POST /api/v1/chat/new を使って新規作成します。この操作には BlueBubbles Private API を有効にしておく必要があります。

​

セキュリティ

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

​

トラブルシューティング

• タイピングや既読イベントが止まった場合は、BlueBubbles の webhook ログを確認し、ゲートウェイのパスが 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) では、プライベート API の変更により、編集は現在壊れています。
• macOS 26 (Tahoe) ではグループアイコン更新も不安定で、API が成功を返しても新しいアイコンが同期されないことがあります。
• OpenClaw は BlueBubbles サーバーの macOS バージョンに基づいて、既知の不具合があるアクションを自動的に隠します。macOS 26 (Tahoe) で編集がまだ表示される場合は、channels.bluebubbles.actions.edit=false を設定して手動で無効化してください。
• ステータスやヘルス情報は openclaw status --all または openclaw status --deep で確認できます。