iMessage

専用の Apple ID と macOS ユーザーを使用して、ボットのトラフィックを個人用の Messages プロファイルから分離します。

一般的な手順：

1. 専用の macOS ユーザーを作成し、サインインします。
2. そのユーザーで、ボット用 Apple ID を使用して Messages にサインインします。
3. そのユーザーに imsg をインストールします。
4. OpenClaw がそのユーザーコンテキストで imsg を実行できるように、SSH ラッパーを作成します。
5. channels.imessage.accounts.<id>.cliPath と .dbPath がそのユーザープロファイルを参照するように設定します。

初回実行時は、そのボットユーザーのセッションで GUI の承認（Automation + Full Disk Access）が必要になる場合があります。

一般的な構成：

• Gateway は Linux/VM 上で動作
• iMessage + imsg は tailnet 内の Mac 上で動作
• cliPath ラッパーは SSH を使用して imsg を実行
• remoteHost は SCP による添付ファイル取得を有効化

例：

{  channels: {    imessage: {      enabled: true,      cliPath: "~/.openclaw/scripts/imsg-ssh",      remoteHost: "bot@mac-mini.tailnet-1234.ts.net",      includeAttachments: true,      dbPath: "/Users/bot/Library/Messages/chat.db",    },  },}

#!/usr/bin/env bashexec ssh -T bot@mac-mini.tailnet-1234.ts.net imsg "$@"

SSH と SCP の両方が非対話式になるよう、SSH キーを使用します。 known_hosts に情報が登録されるよう、最初にホストキーを信頼済みにしてください（例：ssh bot@mac-mini.tailnet-1234.ts.net）。

iMessage は channels.imessage.accounts 配下のアカウント別設定をサポートしています。

各アカウントでは、cliPath、dbPath、allowFrom、groupPolicy、mediaMaxMb、履歴設定、添付ファイルルートの許可リストなどのフィールドを上書きできます。

channels.imessage.dmHistoryLimit を設定すると、新しいダイレクトメッセージセッションに、その会話のデコード済み imsg 履歴の直近分を投入できます。送信者ごとの上書きには channels.imessage.dms["<sender>"].historyLimit を使用します。これには、送信者の履歴を無効にする 0 も含まれます。

iMessage の DM 履歴は、必要に応じて imsg から取得されます。dmHistoryLimit を未設定にすると、グローバルな DM 履歴の投入は無効になりますが、送信者ごとの channels.imessage.dms["<sender>"].historyLimit が正の値であれば、その送信者に対する投入は引き続き有効になります。

• 受信添付ファイルの取り込みはデフォルトで無効です。写真、ボイスメモ、動画、その他の添付ファイルをエージェントに転送するには、channels.imessage.includeAttachments: true を設定します。無効の場合、添付ファイルのみの iMessage はエージェントに到達する前に破棄され、Inbound message ログ行がまったく生成されないことがあります。
• remoteHost が設定されている場合、リモートの添付ファイルパスを SCP 経由で取得可能
• 添付ファイルパスは、許可されたルートと一致する必要があります：
  • channels.imessage.attachmentRoots（ローカル）
  • channels.imessage.remoteAttachmentRoots（リモート SCP モード）
  • 設定したルートは、デフォルトのルートパターン /Users/*/Library/Messages/Attachments を拡張します（置換ではなくマージ）
• SCP は厳格なホストキーチェック（StrictHostKeyChecking=yes）を使用
• 送信メディアのサイズには channels.imessage.mediaMaxMb を使用（デフォルト 16 MB）

• テキストのチャンク上限：channels.imessage.textChunkLimit（デフォルト 4000）
• チャンクモード：channels.imessage.streaming.chunkMode
  • length（デフォルト）
  • newline（段落を優先して分割）
• 送信時の Markdown の太字／斜体／下線／取り消し線は、ネイティブのスタイル付きテキストに変換されます（macOS 15 以降の受信者ではスタイルが表示され、古い環境の受信者にはマーカーなしのプレーンテキストが表示されます）。Markdown テーブルは、チャンネルの Markdown テーブルモードに従って変換されます
• channels.imessage.sendTransport（デフォルトは auto、ほかに bridge、applescript）で、imsg による送信方法を選択

推奨される明示的な送信先：

• chat_id:123（安定したルーティングに推奨）
• chat_guid:...
• chat_identifier:...

ハンドルによる送信先もサポートされています：

• imessage:+1555...
• sms:+1555...
• user@example.com

imsg chats --limit 20

• react：iMessage の Tapback を追加／削除します（messageId、emoji、remove）。サポートされる Tapback は、love、like、dislike、laugh、emphasize、question に対応します。絵文字を指定せずに削除すると、設定されている Tapback が消去されます。
• reply：既存のメッセージにスレッド形式で返信します（messageId、text または message に加え、chatGuid、chatId、chatIdentifier、または to）。添付ファイル付きの返信には、--file をサポートする send-rich を備えた imsg ビルドも必要です。
• sendWithEffect：iMessage エフェクト付きでテキストを送信します（text または message、effect または effectId）。短縮名：slam、loud、gentle、invisibleink、confetti、lasers、fireworks、balloon、heart、echo、happybirthday、shootingstar、sparkles、spotlight。
• edit：対応する macOS／プライベート API バージョンで、送信済みメッセージを編集します（messageId、text または newText）。Gateway 自身が送信したメッセージのみ編集できます。
• unsend：対応する macOS／プライベート API バージョンで、送信済みメッセージを取り消します（messageId）。Gateway 自身が送信したメッセージのみ取り消せます。
• upload-file：メディア／ファイルを送信します（base64 の buffer、または実体化された media／path／filePath、filename、任意の asVoice）。従来のエイリアス：sendAttachment。
• renameGroup、setGroupIcon、addParticipant、removeParticipant、leaveGroup：現在の送信先がグループ会話の場合に、グループチャットを管理します。これらはホストの Messages ID を変更するため、所有者である送信者、または operator.admin Gateway クライアントが必要です。
• poll：Apple Messages ネイティブの投票を作成します（pollQuestion、2～12 回繰り返す pollOption に加え、chatGuid、chatId、chatIdentifier、または to）。iOS／iPadOS／macOS 26 以降の受信者はネイティブに表示して投票できます。古い OS バージョンでは「投票を送信しました」という代替テキストが表示されます。selectors.pollPayloadMessage が必要です。
• poll-vote：既存の投票に投票します（pollId または messageId に加え、pollOptionIndex、pollOptionId、pollOptionText のいずれか 1 つのみ）。selectors.pollVoteMessage と poll.vote RPC メソッドが必要です。

受け付けられた受信投票は、質問、番号付きの選択肢ラベル、得票数、poll-vote に必要な投票メッセージ ID とともにエージェント向けにレンダリングされます。

受信した iMessage のコンテキストには、短い MessageSid 値と、利用可能な場合は完全なメッセージ GUID（MessageSidFull）の両方が含まれます。短い ID は、SQLite ベースの直近の返信キャッシュをスコープとし、使用前に現在のチャットと照合されます。短い ID の有効期限が切れた場合は、その ID を提供した会話を送信先に指定し、対応する MessageSidFull で再試行してください。完全な ID でも会話やアカウントへの紐付けは回避できないため、別のチャットの ID は現在の送信先の ID に置き換えてください。リモート委任呼び出しでは、現在の会話を示す証拠が利用できない場合、古い完全 ID が拒否されることがあります。

OpenClaw がプライベート API アクションを非表示にするのは、キャッシュされたプローブステータスがブリッジを利用不可と示している場合のみです。ステータスが不明な場合、アクションは表示されたままとなり、ディスパッチ時にプローブが遅延実行されます。そのため、imsg launch の後、手動でステータスを別途更新しなくても最初のアクションを成功させられます。

プライベート API ブリッジが稼働している場合、受け付けられた受信チャットは既読になり、ダイレクトチャットではターンが受け付けられるとすぐに入力中の吹き出しが表示されます。その間、エージェントはコンテキストを準備して生成を行います。既読化を無効にするには、次のように設定します：

{  channels: {    imessage: {      sendReadReceipts: false,    },  },}

メソッド別の機能リストより前の古い imsg ビルドでは、入力中表示／開封確認が通知なしにゲートで無効化されます。OpenClaw は再起動ごとに一度だけ警告を記録するため、確認通知がない原因を特定できます。

OpenClaw は iMessage の Tapback を購読し、受け付けられたリアクションを通常のメッセージテキストではなくシステムイベントとしてルーティングします。そのため、ユーザーの Tapback によって通常の返信ループがトリガーされることはありません。

通知モードは channels.imessage.reactionNotifications で制御します：

• "own"（デフォルト）：ユーザーがボット作成のメッセージにリアクションした場合のみ通知します。
• "all"：許可された送信者からのすべての受信 Tapback を通知します。
• "off"：受信 Tapback を無視します。

アカウント別の上書きには channels.imessage.accounts.<id>.reactionNotifications を使用します。

approvals.exec.enabled または approvals.plugin.enabled が true で、リクエストが iMessage にルーティングされる場合、Gateway は承認プロンプトをネイティブに配信し、Tapback による解決を受け付けます：

• 👍（Like Tapback）→ allow-once
• 👎（Dislike Tapback）→ deny
• allow-always は手動の代替手段として引き続き利用できます。/approve <id> allow-always を通常の返信として送信します。

リアクション処理では、リアクションしたユーザーのハンドルが明示的な承認者である必要があります。承認者リストは channels.imessage.allowFrom（または channels.imessage.accounts.<id>.allowFrom）から読み込まれます。ユーザーの電話番号を E.164 形式で追加するか、Apple ID のメールアドレスを追加してください（chat_id:* のようなチャット送信先は、有効な承認者エントリではありません）。ワイルドカードエントリ "*" は有効ですが、すべての送信者による承認を許可します。承認者リストが空の場合、リアクションによるショートカットは完全に無効になります。承認の解決で重要なのは明示的な承認者の許可リストだけであるため、このリアクションショートカットは意図的に reactionNotifications、dmPolicy、groupAllowFrom を迂回します。

/approve テキストコマンドの認可も同じリストに従います。channels.imessage.allowFrom が空でない場合、/approve <id> <decision> はより広範な DM 許可リストではなく、その承認者リストに照らして認可されます。DM 許可リストでは許可されていても allowFrom に含まれない送信者には、明示的な拒否が返されます。allowFrom が空の場合、同一チャットの代替動作が引き続き有効となり、/approve は DM 許可リストで許可されたすべてのユーザーを認可します。/approve またはリアクションを通じて承認する必要があるすべてのオペレーターを、allowFrom に追加してください。

オペレーター向けメモ:

• リアクションの関連付けは、メモリと Gateway の永続的なキー付きストア（TTL は承認の有効期限に合わせられます）の両方に保存されます。また、Gateway は保留中のプロンプトに対するタップバックもポーリングするため、Gateway の再起動直後に届いたタップバックでも承認を解決できます。
• オペレーター自身の is_from_me=true タップバック（たとえば、ペアリング済みの Apple デバイスからのもの）は、そのハンドルが明示的な承認者である場合に承認を解決します。
• 承認プロンプトがグループ会話にルーティングされるのは、明示的な承認者が設定されている場合のみです。そうでなければ、任意のグループメンバーが承認できてしまいます。
• 従来のテキスト形式のタップバック（非常に古い Apple クライアントからの Liked "…" プレーンテキスト）はメッセージ GUID を持たないため、承認を解決できません。リアクションによる解決には、現在の macOS / iOS クライアントが送信する構造化されたタップバックメタデータが必要です。

機密ではない単一選択の質問が 1 つあり、選択肢が 1～4 個の ask_user プロンプトでは、OpenClaw が番号付きの絵文字の選択肢を追加します。配信されたプロンプトに対応する番号でリアクションすると回答できます。リアクションには、ボットが作成したメッセージの安定した GUID が含まれている必要があります。その後、OpenClaw は Gateway を通じて番号を正規の選択肢に対応付けます。古いタップや重複したタップは無視されます。

複数の質問、複数選択、自由記述のプロンプトは、引き続きテキスト返信でのみ回答できます。質問へのリアクションには、通常の iMessage の DM／グループ受け入れルールが適用されます。一般的な reactionNotifications が "off" の場合でも認識されますが、無関係なリアクションがエージェントイベントになることはありません。

バイナリと RPC のサポートを検証します:

imsg rpc --helpimsg status --jsonopenclaw channels status --probe

プローブで RPC がサポートされていないと報告された場合は、imsg を更新してください。プライベート API のアクションを利用できない場合は、ログイン中の macOS ユーザーセッションで imsg launch を実行し、再度プローブしてください。Gateway が macOS 上で実行されていない場合は、デフォルトのローカル imsg パスではなく、前述の SSH 経由のリモート Mac セットアップを使用してください。

まず、メッセージがローカル Mac に到達したかどうかを確認します。chat.db が変化しない場合、imsg status --json が正常なブリッジを報告していても、OpenClaw はメッセージを受信できません。

imsg chats --limit 10 --jsonimsg watch --chat-id <chat-id> --jsonsqlite3 ~/Library/Messages/chat.db \"select datetime(max(date)/1000000000 + 978307200, 'unixepoch', 'localtime'), max(ROWID) from message;"

電話から送信したメッセージによって新しい行が作成されない場合は、OpenClaw の設定を変更する前に、macOS の Messages と Apple Push レイヤーを修復してください。通常は 1 回限りのサービス更新で十分です:

launchctl kickstart -k system/com.apple.apsdlaunchctl kickstart -k gui/$(id -u)/com.apple.CommCenterlaunchctl kickstart -k gui/$(id -u)/com.apple.identityservicesdlaunchctl kickstart -k gui/$(id -u)/com.apple.imagentimsg launchopenclaw gateway restart

電話から新しい iMessage を送信し、新しい chat.db 行または imsg watch イベントを確認してから、OpenClaw セッションをデバッグしてください。これを定期的なブリッジ再起動ループとして実行しないでください。作業中に imsg launch と Gateway の再起動を繰り返すと、配信が中断され、処理中のチャンネル実行が取り残される可能性があります。

デフォルトの cliPath: "imsg" は、Messages にサインインしている Mac 上で実行する必要があります。Linux または Windows では、channels.imessage.cliPath に、その Mac へ SSH 接続して imsg "$@" を実行するラッパースクリプトを設定します。

#!/usr/bin/env bashexec ssh -T messages-mac imsg "$@"

次に実行します:

openclaw channels status --probe --channel imessage

以下を確認します:

• channels.imessage.dmPolicy
• channels.imessage.allowFrom
• ペアリングの承認（openclaw pairing list imessage）

以下を確認します:

• channels.imessage.groupPolicy
• channels.imessage.groupAllowFrom
• channels.imessage.groups 許可リストの動作
• メンションパターンの設定（agents.entries.*.groupChat.mentionPatterns）

以下を確認します:

• channels.imessage.remoteHost
• channels.imessage.remoteAttachmentRoots
• Gateway ホストからの SSH/SCP キー認証
• Gateway ホスト上の ~/.ssh/known_hosts にホストキーが存在すること
• Messages を実行している Mac 上でリモートパスを読み取れること

同じユーザー／セッションコンテキストの対話型 GUI ターミナルで再実行し、プロンプトを承認します:

imsg chats --limit 1imsg send <handle> "test"

OpenClaw／imsg を実行するプロセスコンテキストに「フルディスクアクセス」と「オートメーション」が許可されていることを確認してください。