imsg

imsg

アクションが現在の iMessage スキーマで公開されている場合は、まず汎用の message ツールを使用してください。タスクでローカルの Messages.app の履歴、宛先の特定、監視、または message では公開されていない管理機能やプライベート API の機能が必要な場合は、imsg を使用してください。

Telegram、Signal、WhatsApp、Discord、Slack にはこのスキルを使用しないでください。また、設定済みのチャンネルで返信がすでにルーティングされている場合、現在の OpenClaw の会話内で返信する際にも使用しないでください。

エージェントのフロー

1. まず会話を特定します。
2. DM、既存のグループ、新しいグループのいずれかを選択します。
3. 利用可能な message アクションを優先し、それ以外の場合は、要求された動作を維持できる範囲で最も権限の低い imsg コマンドを選択します。
4. ユーザーが宛先、内容、アクションをすでに正確に指定している場合を除き、送信または画面上に表示される状態変更を確認します。
5. 安定した識別子を使って実行します。通常の送信、監視、履歴には --chat-id を優先し、ブリッジアクションにはチャット GUID の --chat を優先します。

複数のチャットやハンドルが該当する可能性がある場合、カジュアルな名前だけから宛先を推測しないでください。送信前に、一致した表示名、ハンドル、グループ参加者、メッセージの内容またはアクションを提示してください。

ホスト要件

• 送信、リアクション、ブリッジアクションを行うには、macOS 14 以降で Messages.app にサインインしている必要があります。
• OpenClaw の iMessage には、プライベート API モードの利用を強く推奨します。このモードでは、返信、正確な Tapback、エフェクト、投票、添付ファイルへの返信、既読・入力中の状態変更、グループ管理が利用可能になります。基本モードは、読み取りとプレーンテキストまたはファイルの送信に限定した代替手段です。
• imsg または OpenClaw を実行するプロセスのコンテキストにフルディスクアクセスが必要です。Messages の DB にアクセスできない場合、読み取りに失敗します。
• 公開の send を使用する場合、Messages.app の自動化を許可する必要があります。
• 公開の imsg react を実行するプロセスのコンテキストにアクセシビリティの許可が必要です。この機能は System Events の UI 自動化を使用します。ブリッジの tapback は代わりにプライベート API を使用します。
• 連絡先名を解決する場合は、連絡先へのアクセス許可を任意で付与できます。
• SMS の送信には、ユーザーの iPhone からこの Mac へのテキストメッセージ転送が必要です。
• Linux で読み取れるのはコピーされた chat.db のみです。送信、リアクション、Messages.app の起動、既読への変更、入力はできません。

宛先の特定

--json を使って読み取ります。出力は改行区切りの JSON です。jq が利用可能な場合は jq -s を使用するか、各行のオブジェクトを直接処理してください。

imsg chats --limit 25 --json | jq -s
imsg search --query "dinner" --match contains --json | jq -s
imsg history --chat-id 42 --limit 20 --attachments --json | jq -s
imsg group --chat-id 42 --json

宛先のルール：

• 電話番号またはメールアドレスへの DM：ユーザーが正確なハンドルを指定した場合、または一意に一致するチャットが見つかった後に imsg send --to を使用します。
• 既存の DM スレッド：名前を再度解決するより、imsg send --chat-id <id> を使用する方が安全です。
• 既存のグループ：imsg group --chat-id <id> --json で確認します。送信には --chat-id を使用し、ブリッジには group から取得したチャット GUID を使用します。
• 新しいグループ：ユーザーが明示的にグループの作成を依頼した場合、または一致する既存のグループがない場合に限り、chat-create を使用します。
• 名前が曖昧なグループ：表示名だけでなく、参加者も確認します。
• SMS：依頼された場合、または iMessage へのフォールバックが望ましくない場合に限り、--service sms を使用します。SMS リレーにはテキストメッセージ転送が必要です。

このスキルで jq を必須にしないでください。例を整形するための便利なツールにすぎません。

機能の選択

現在の message スキーマで操作に対応できない場合、またはローカルの履歴が必要な場合は、imsg の標準コマンドを使用します。

• 読み取り／一覧表示／検索／監視：chats、group、history、search、watch
• 基本的なテキスト／ファイルの送信：send
• チャット内の最新の受信メッセージへの標準タップバック：react

OpenClaw ユーザーが通常期待する、iMessage のネイティブ操作にはプライベート API ブリッジを使用します。

• リッチ返信、テキスト書式、エフェクト、件名、複数パートの送信
• Apple Messages のネイティブな投票と投票
• メッセージ GUID を指定したタップバック、またはタップバックの削除
• 編集、送信取り消し、削除、「通知を許可」
• 開封確認、入力インジケーター、ブリッジイベントの監視
• グループの作成／名前／写真／メンバー／退出／削除／既読操作
• アカウント、whois、ニックネームの確認

OpenClaw チャネルを設定する際は、早い段階でブリッジが利用可能か確認します。

imsg status --json

ホストがブリッジ操作に対応していても、Messages にまだインジェクトされていない場合は、imsg launch を実行する前に確認してください。Messages.app を終了して再起動し、ブリッジをインジェクトするため、ユーザーから見える状態変更として扱います。

imsg launch
imsg status --json

SIP、ライブラリ検証、プライベート権限の確認、またはセレクターの欠落が引き続き機能を妨げている場合は、要求されたプライベート API 操作がこのホストでは利用できないことを説明し、可能であれば最も近いブリッジを使わない操作を提示します。スレッド返信、エフェクト、件名、投票、GUID を指定したタップバックを、黙って通常の送信／リアクションに置き換えないでください。

DM のシナリオ

正確なハンドルを指定した基本的な送信：

imsg send --to "+14155551212" --text "On my way" --service auto

既知の DM スレッド：

imsg send --chat-id 42 --text "On my way"
imsg send --chat-id 42 --file /path/to/photo.jpg

ユーザーが要求した場合にのみ、チャネルを明示的に指定します。

imsg send --to "+14155551212" --text "green bubble" --service sms
imsg send --to "+14155551212" --text "iMessage only" --service imessage --no-sms-fallback

スレッド返信、書式、エフェクト、または添付ファイルへの返信：

imsg send-rich --chat 'iMessage;-;+15551234567' \
  --reply-to <message-guid> --text "reply text"
imsg send-rich --chat 'iMessage;-;+15551234567' --text 'hello world' \
  --format '[{"start":0,"length":5,"styles":["bold"]}]'
imsg send-rich --chat 'iMessage;-;+15551234567' --text "boom" --effect impact
imsg send-attachment --chat 'iMessage;-;+15551234567' \
  --reply-to <message-guid> --file /path/to/file.jpg

書式範囲は UTF-16 の位置で指定します。対応するスタイルには bold、italic、underline、strikethrough があります。生成した JSON には --format-file を使用します。

グループのシナリオ

操作の前に確認します。

imsg group --chat-id 42 --json
imsg history --chat-id 42 --limit 20 --json | jq -s

既存のグループに送信：

imsg send --chat-id 42 --text "Works for me"

既存のグループでブリッジ返信または投票を行う：

imsg send-rich --chat 'iMessage;+;chat0000' \
  --reply-to <message-guid> --text "replying in thread"
imsg poll send --chat 'iMessage;+;chat0000' \
  --question "Dinner?" --option "Pizza" --option "Sushi"

グループの作成や変更は、明示的に要求された場合にのみ行います。

imsg chat-create --addresses '+15551111111,+15552222222' --name 'Crew' --text 'gm'
imsg chat-name --chat 'iMessage;+;chat0000' --name 'Renamed'
imsg chat-photo --chat 'iMessage;+;chat0000' --file /path/to/group.jpg
imsg chat-add-member --chat 'iMessage;+;chat0000' --address +15553333333
imsg chat-remove-member --chat 'iMessage;+;chat0000' --address +15553333333
imsg chat-leave --chat 'iMessage;+;chat0000'
imsg chat-delete --chat 'iMessage;+;chat0000'
imsg chat-mark --chat 'iMessage;+;chat0000' --read

グループの変更はユーザーから見えやすい操作です。メンバー、名前、写真、既読状態の変更、退出、削除を行う前に、対象のグループと参加者の一覧を正確に確認してください。

リアクションと返信

公開されている react の機能には制限があり、チャット内の最新の受信メッセージにのみリアクションできます。

imsg react --chat-id 42 --reaction like
imsg react --chat-id 42 --reaction love
imsg react --chat-id 42 --reaction dislike
imsg react --chat-id 42 --reaction laugh
imsg react --chat-id 42 --reaction emphasis
imsg react --chat-id 42 --reaction question

特定のメッセージ GUID を指定する場合や削除する場合は、ブリッジの tapback を使用します。

imsg tapback --chat 'iMessage;-;+15551234567' --message <message-guid> --kind love
imsg tapback --chat 'iMessage;-;+15551234567' --message <message-guid> --kind love --remove

スレッド返信には send-rich --reply-to <message-guid> を使用します。ユーザーが「それ」や「前のもの」と言う場合は、参照するメッセージを確認してください。

投票

Apple Messages のネイティブな投票にはブリッジが必要です。作成時には、少なくとも 2 つの --option 値が必要です。投票には --option-id、--option-index、--option のいずれかを指定する必要があります。

Messages では投票バルーンに選択肢のみが表示されるため、現在の imsg poll send は、可能な範囲で --question を投票の後に通常のキャプションとして送信します。キャプションを上書きするには --comment を使用します。キャプションの送信だけに失敗した場合は、自動的に再試行しないでください。投票はすでに配信されている可能性があります。

imsg poll send --chat 'iMessage;-;+15551234567' \
  --question "Dinner?" --option "Pizza" --option "Sushi" --comment "Vote by 5pm"
imsg poll send --chat 'iMessage;+;chat0000' --reply-to <message-guid> \
  --question "Approve?" --option "Yes" --option "No"
imsg poll vote --chat 'iMessage;+;chat0000' \
  --poll <poll-message-guid> --option-id <option-id>

投票 ID と選択肢を確認するには、次を使用します。

imsg history --chat-id 42 --limit 20 --json | jq -s '.[] | select(.poll != null) | {guid, poll}'

history と watch は、タイトルのない受信ネイティブ投票の poll.question に、クリーンなキャプション行の内容を補完します。投票の投票行はタップバックではなく poll イベントです。これらを確認するために watch --reactions は必要ありません。

監視と長時間実行エージェント

短時間だけ待機する場合は、watch を使用します。

imsg watch --chat-id 42 --since-rowid 9000 --json
imsg watch --chat-id 42 --attachments --convert-attachments --json
imsg watch --chat-id 42 --reactions --json
imsg watch --chat-id 42 --bb-events --json

--since-rowid は指定した行を含みません。指定しない場合、watch は最新の行から開始します。watch はファイルシステムイベントと低頻度のポーリングフォールバックを使用するため、SQLite のサイドカーイベントを取りこぼした後でも追いつけます。ポーリングオブジェクトは --reactions なしで表示されます。

デーモンまたは複数のチャットと連携する場合は、imsg rpc を使用します。標準入力／標準出力を介した JSON-RPC 2.0 を使用します。新しいブリッジまたは投票メソッドを使用する前に、imsg status --json で rpc_methods を確認してください。

安全ルール

• ユーザーの依頼に正確な値がすでに含まれている場合を除き、送信のたびに宛先、チャット、内容を確認してください。
• 既読通知、入力中インジケーター、編集、送信取り消し、削除、投票、タップバック、グループメンバー、グループ名や写真、チャットからの退出や削除など、画面上で確認できる状態変更を確認してください。
• 承認を得ずに、不明な番号や連絡先名が曖昧に一致する相手に送信しないでください。
• 添付ファイルが存在し、意図したファイルであることを確認してください。
• E.164 形式の電話番号を優先してください。ローカル形式で必要な場合のみ、--region US または別の地域を指定してください。
• ブリッジ固有の動作にはブリッジアクションを使用します。ただし、画面上で確認できる状態変更や破壊的な操作は、事前に確認してください。