BlueBubbles
BlueBubbles macOS Server（REST）経由で iMessage を接続：送受信、入力状態、リアクション、拡張アクション。
状態：内蔵プラグインで、BlueBubbles macOS Server と HTTP で通信します。API が豊富でセットアップもスムーズなため、iMessage 連携は BlueBubbles を推奨します（旧 imsg チャンネルより優先）。
Overview
- macOS 上で動作：BlueBubbles helper app（bluebubbles.app）。
- 推奨/検証：macOS Sequoia（15）。macOS Tahoe（26）でも動作しますが、Tahoe では編集（edit）が現在壊れています。また、グループアイコン更新は成功しても同期しない場合があります。
- OpenClaw は REST API 経由で操作します（例：GET /api/v1/ping、POST /message/text、POST /chat/:id/*）。
- 受信は webhook で到達し、送信返信・入力状態・既読・tapback は REST 呼び出しで行います。
- 添付やステッカーは受信メディアとしてメディアパイプラインに入り（可能な限り agent に提示されます）。
- pairing/allowlist は他チャンネルと同様（/start/pairing）：channels.bluebubbles.allowFrom + ペアリングコード。
- リアクションは Slack/Telegram のようにシステムイベントとしてコンテキストに入り、agent が「リアクションに触れてから返信」しやすくなります。
- 拡張機能：編集、取り消し、引用返信、メッセージエフェクト、グループ管理。
クイックスタート
1. Mac に BlueBubbles Server をインストール（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. Point the BlueBubbles webhook to your Gateway (example: https://your-gateway-host:3000/bluebubbles-webhook?password=<password>).
5. Gateway を起動すると、webhook handler を登録し、pairing フローを開始します。
Onboarding
BlueBubbles は対話式ウィザードに対応しています：
openclaw onboard
ウィザードで聞かれる内容：
- Server URL（必須）：BlueBubbles server のアドレス（例：http://192.168.1.100:1234）
- Password（必須）：BlueBubbles Server 設定の API パスワード
- Webhook path（任意）：既定は /bluebubbles-webhook
- DM ポリシー：pairing、allowlist、open、disabled
- Allow list：電話番号、メール、または chat targets
CLI から追加することもできます：
openclaw channels add bluebubbles --http-url http://192.168.1.100:1234 --password <password>
アクセス制御（DM + グループ）
DM：
- Default: channels.bluebubbles.dmPolicy = "pairing".
- 未知の送信者にはペアリングコードが返され、承認までメッセージは無視されます（コードは 1 時間で期限切れ）。
- Approve via:
- openclaw pairing list bluebubbles
- openclaw pairing approve bluebubbles <CODE>
- pairing は既定の token exchange です。詳細：/start/pairing
グループ：
- channels.bluebubbles.groupPolicy = open | allowlist | disabled (default allowlist).
- allowlist の場合、channels.bluebubbles.groupAllowFrom が「グループで起動できる送信者」を制御します。
mention ゲーティング（グループ）
BlueBubbles のグループ mention ゲーティングは iMessage/WhatsApp と同様の挙動です：
- agents.list[].groupChat.mentionPatterns（または messages.groupChat.mentionPatterns）で mention を検出します。
- グループの requireMention が有効な場合、mention されたときだけ返信します。
- 信頼された制御コマンド送信者は mention ゲーティングをバイパスできます。
グループ別の設定：
{
channels: {
bluebubbles: {
groupPolicy: "allowlist",
groupAllowFrom: ["+15555550123"],
groups: {
"*": { requireMention: true },
"iMessage;-;chat123": { requireMention: false },
},
},
},
}コマンドゲーティング
- 制御コマンド（例：/config、/model）は認可が必要です。
- 認可は allowFrom と groupAllowFrom で判定します。
- 認可済みの送信者は、グループでも @mention なしで制御コマンドを実行できます。
Typing state + read receipts
- 入力状態（Typing）：返信生成の前後で自動送信します。
- 既読：channels.bluebubbles.sendReadReceipts で制御（既定 true）。
- 入力状態は送信後またはタイムアウト後に BlueBubbles 側で自動クリアされます（DELETE による手動 stop は不安定）。
{
channels: {
bluebubbles: {
sendReadReceipts: false
},
},
}拡張アクション（Actions）
有効化すると、BlueBubbles は高度なメッセージアクションに対応します：
{
channels: {
bluebubbles: {
actions: {
reactions: true,
edit: true,
unsend: true,
reply: true,
sendWithEffect: true,
renameGroup: true,
setGroupIcon: true,
addParticipant: true,
removeParticipant: true,
leaveGroup: true,
sendAttachment: true,
},
},
},
}アクション一覧：
- react：tapback の追加/削除（messageId、emoji、remove）
- edit：送信済みメッセージの編集（messageId、text）（macOS 13+；macOS 26 Tahoe では現在不可）
- unsend：メッセージの取り消し（messageId）（macOS 13+）
- reply：指定メッセージへの引用返信（messageId、text、to）
- sendWithEffect：iMessage エフェクト付き送信（text、to、effectId）
- renameGroup：グループ名変更（chatGuid、displayName）
- setGroupIcon：グループアイコン設定（chatGuid、media）（macOS 26 Tahoe では成功しても同期しない場合あり）
- addParticipant: add a participant (chatGuid, address)
- removeParticipant: remove a participant (chatGuid, address)
- leaveGroup：グループ退出（chatGuid）
- sendAttachment：添付/メディア送信（to、buffer、filename、asVoice）
- ボイスノート：asVoice: true を設定し、MP3 または CAF 音声を渡すと iMessage のボイスメッセージとして送信できます。BlueBubbles は MP3 を CAF に変換します。
Message IDs（短 ID vs フル ID）
トークン節約のため、OpenClaw はコンテキスト内で「短い message id」（例：1、2）を露出することがあります。
- MessageSid / ReplyToId は短 ID の可能性があります。
- MessageSidFull / ReplyToIdFull はプロバイダのフル ID です。
- 短 ID はメモリキャッシュのため、再起動やキャッシュ追い出しで無効になります。
- Actions は短/フルの messageId を受け付けますが、短 ID が無効だとエラーになります。
長期の自動化/保存を行う場合はフル ID を使ってください：
- テンプレート：<code>'{'{MessageSidFull}'}'</code>、<code>'{'{ReplyToIdFull}'}'</code>
- コンテキスト：受信 payload 内の MessageSidFull / ReplyToIdFull
テンプレート変数の詳細は /gateway/configuration を参照してください。
ブロックストリーミング
返信を一括送信するか、ブロック単位でストリーミング送信するかを制御します：
{
channels: {
bluebubbles: {
blockStreaming: true
},
},
}メディアと制限
- 受信添付はダウンロードされ、メディアキャッシュに保存されます。
- Limit: channels.bluebubbles.mediaMaxMb (default 8 MB).
- 送信テキストは channels.bluebubbles.textChunkLimit に従って分割されます（既定 4000 文字）。
設定リファレンス
完全な設定：/gateway/configuration
Provider オプション：
- channels.bluebubbles.enabled
- channels.bluebubbles.serverUrl
- channels.bluebubbles.password
- channels.bluebubbles.webhookPath (default /bluebubbles-webhook)
- channels.bluebubbles.dmPolicy: pairing | allowlist | open | disabled (default pairing)
- channels.bluebubbles.allowFrom：DM allowlist（handles、emails、E.164、chat_id:*、chat_guid:*）
- channels.bluebubbles.groupPolicy: open | allowlist | disabled (default allowlist)
- channels.bluebubbles.groupAllowFrom
- channels.bluebubbles.groups（グループ別 override：requireMention など）
- channels.bluebubbles.sendReadReceipts (default true)
- channels.bluebubbles.blockStreaming (default true)
- channels.bluebubbles.textChunkLimit (default 4000)
- channels.bluebubbles.chunkMode: length (default) / newline
- channels.bluebubbles.mediaMaxMb (default 8)
- channels.bluebubbles.historyLimit（グループコンテキスト件数；0 で無効）
- channels.bluebubbles.dmHistoryLimit
- channels.bluebubbles.actions
- channels.bluebubbles.accounts
関連するグローバルオプション：
- agents.list[].groupChat.mentionPatterns（または messages.groupChat.mentionPatterns）
- messages.responsePrefix
アドレスと targets
安定したルーティングには chat_guid の利用を推奨します：
- chat_guid:iMessage;-;+15555550123（グループ優先）
- chat_id:123
- chat_identifier:...
- Direct handles: +15555550123, [email protected]
- 既存の DM chat がない場合、OpenClaw は POST /api/v1/chat/new で作成します（BlueBubbles Private API が必要）。
セキュリティ
- webhook リクエストは、query params または headers の guid/password を channels.bluebubbles.password と比較して認証します。localhost からのリクエストも受け入れます。
- API パスワードと webhook エンドポイントは資格情報として扱ってください（漏らさない）。
- localhost を信頼すると、同一ホストのリバースプロキシが意図せずパスワードをバイパスする可能性があります。Gateway を proxy する場合は proxy 側で認証し、gateway.trustedProxies を設定してください。Gateway security 参照。
- BlueBubbles server を LAN 外へ公開する場合は、HTTPS を有効にし、ファイアウォールを設定してください。
トラブルシューティング
- 入力状態/既読イベントが動かない：BlueBubbles webhook logs を確認し、Gateway path が channels.bluebubbles.webhookPath と一致しているか確認してください。
- ペアリングコードは 1 時間で期限切れ：openclaw pairing list bluebubbles / openclaw pairing approve bluebubbles <code>。
- リアクションには BlueBubbles Private API（POST /api/v1/message/react）が必要です。server バージョンがその API を公開しているか確認してください。
- edit/unsend には macOS 13+ と互換 BlueBubbles server が必要です。macOS 26（Tahoe）では private API 変更により edit が現在利用できません。
- グループアイコン更新は macOS 26（Tahoe）で不安定な場合があります：API は成功しても同期しないことがあります。
- OpenClaw は macOS バージョンに応じて利用不可のアクションを自動的に隠します。macOS 26（Tahoe）で edit が表示される場合は channels.bluebubbles.actions.edit=false で手動無効化できます。
- 状態/健康情報：openclaw status --all または openclaw status --deep。