iMessage（レガシー：imsg）

警告： 新しいiMessageデプロイメントにはBlueBubblesを使用してください。

imsg連携はレガシーであり、将来のリリースで削除される可能性があります。

ステータス：レガシーの外部CLI連携。Gatewayはimsg rpcを起動し、stdio上のJSON-RPCで通信します（デーモンやポートは不要）。

クイックセットアップ

ローカルMac（高速パス）

  ### ステップ1：imsgのインストールと検証
brew install steipete/tap/imsg
imsg rpc --help
  ### ステップ2：OpenClawの設定
{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "/usr/local/bin/imsg",
      dbPath: "/Users/<you>/Library/Messages/chat.db",
    },
  },
}
  ### ステップ3：Gatewayの起動
openclaw gateway
  ### ステップ4：最初のDMペアリングの承認（デフォルトのdmPolicy使用時）
openclaw pairing list imessage
openclaw pairing approve imessage <CODE>
    ペアリングリクエストは1時間後に期限切れになります。

リモートMac（SSH経由）

OpenClawはstdio互換の`cliPath`のみを必要とするため、リモートMacにSSHで接続して`imsg`を実行するラッパースクリプトを`cliPath`に指定できます。
#!/usr/bin/env bash
exec ssh -T gateway-host imsg "$@"
添付ファイルが有効な場合の推奨設定：
{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "~/.openclaw/scripts/imsg-ssh",
      remoteHost: "user@gateway-host", // SCP添付ファイル取得に使用
      includeAttachments: true,
      // 任意：許可する添付ファイルルートのオーバーライド。
      // デフォルトは /Users/*/Library/Messages/Attachments を含む
      attachmentRoots: ["/Users/*/Library/Messages/Attachments"],
      remoteAttachmentRoots: ["/Users/*/Library/Messages/Attachments"],
    },
  },
}
`remoteHost`が未設定の場合、OpenClawはSSHラッパースクリプトを解析して自動検出を試みます。
`remoteHost`は`host`または`user@host`の形式でなければなりません（スペースやSSHオプションは不可）。
OpenClawはSCPに厳格なホストキーチェックを使用するため、リレーホストのキーが`~/.ssh/known_hosts`に存在している必要があります。
添付ファイルパスは許可ルート（`attachmentRoots` / `remoteAttachmentRoots`）に対して検証されます。

要件と権限（macOS）

  • imsgを実行するMacでMessagesにサインインしている必要があります。
  • OpenClaw/imsgを実行するプロセスコンテキストにフルディスクアクセスが必要です（Messages DBへのアクセス）。
  • Messages.app経由でメッセージを送信するにはオートメーション権限が必要です。

ヒント： 権限はプロセスコンテキストごとに付与されます。Gatewayがヘッドレス（LaunchAgent/SSH）で実行される場合、同じコンテキストでインタラクティブなコマンドを一度実行してプロンプトを表示させてください：

imsg chats --limit 1
# または
imsg send <handle> "test"

アクセス制御とルーティング

DMポリシー

`channels.imessage.dmPolicy`でダイレクトメッセージを制御します：

- `pairing`（デフォルト）
- `allowlist`
- `open`（`allowFrom`に`"*"`を含む必要あり）
- `disabled`

許可リストフィールド：`channels.imessage.allowFrom`

許可リストのエントリはハンドルまたはチャットターゲット（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）を使用できます。

グループポリシー + メンション

`channels.imessage.groupPolicy`でグループ処理を制御します：

- `allowlist`（設定時のデフォルト）
- `open`
- `disabled`

グループ送信者許可リスト：`channels.imessage.groupAllowFrom`

ランタイムフォールバック：`groupAllowFrom`が未設定の場合、iMessageのグループ送信者チェックは利用可能な`allowFrom`にフォールバックします。
注意：`channels.imessage`が完全に存在しない場合、`channels.defaults.groupPolicy`が設定されていてもランタイムは`groupPolicy="allowlist"`にフォールバックし、警告をログに記録します。

グループでのメンションゲーティング：

- iMessageにはネイティブのメンションメタデータがありません
- メンション検出は正規表現パターン（`agents.list[].groupChat.mentionPatterns`、フォールバック`messages.groupChat.mentionPatterns`）を使用
- パターンが設定されていない場合、メンションゲーティングは強制できません

権限のある送信者からのコントロールコマンドはグループ内のメンションゲーティングをバイパスできます。

セッションと決定的返信

- DMはダイレクトルーティング、グループはグループルーティングを使用します。
- デフォルトの`session.dmScope=main`では、iMessage DMはAgent メインセッションに集約されます。
- グループセッションは隔離されます（`agent:<agentId>:imessage:group:<chat_id>`）。
- 返信は送信元チャンネル/ターゲットメタデータを使用してiMessageにルーティングされます。

グループ風スレッドの動作：

一部のマルチパーティiMessageスレッドは`is_group=false`で到着する場合があります。
その`chat_id`が`channels.imessage.groups`で明示的に設定されている場合、OpenClawはグループトラフィックとして扱います（グループゲーティング + グループセッション隔離）。

デプロイパターン

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

一般的な手順：

1. 専用のmacOSユーザーを作成/サインイン。
2. BotのApple IDでそのユーザーのMessagesにサインイン。
3. そのユーザーに`imsg`をインストール。
4. OpenClawがそのユーザーコンテキストで`imsg`を実行できるようSSHラッパーを作成。
5. `channels.imessage.accounts.<id>.cliPath`と`.dbPath`をそのユーザープロファイルに向ける。

初回実行時にそのBotユーザーセッションでGUI承認（オートメーション + フルディスクアクセス）が必要になる場合があります。
Tailscale経由のリモートMac（例） 
一般的なトポロジ：

- GatewayはLinux/VMで実行
- iMessage + `imsg`はtailnet内のMacで実行
- `cliPath`ラッパーがSSHで`imsg`を実行
- `remoteHost`でSCP添付ファイル取得を有効化

設定例：
{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "~/.openclaw/scripts/imsg-ssh",
      remoteHost: "[email protected]",
      includeAttachments: true,
      dbPath: "/Users/bot/Library/Messages/chat.db",
    },
  },
}
#!/usr/bin/env bash
exec ssh -T [email protected] imsg "$@"
SSHとSCPが非インタラクティブに動作するようSSHキーを使用してください。
ホストキーが最初に信頼されていることを確認してください（例：`ssh [email protected]`）。`known_hosts`への登録が必要です。
マルチアカウントパターン 
iMessageは`channels.imessage.accounts`でアカウントごとの設定をサポートしています。

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

メディア、チャンキング、配信先

添付ファイルとメディア 
- 受信添付ファイルの取り込みは任意：`channels.imessage.includeAttachments`
- `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.chunkMode`
  - `length`（デフォルト）
  - `newline`（段落優先の分割）
アドレス形式 
推奨される明示的ターゲット：

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

ハンドルターゲットもサポートされています：

- `imessage:+1555...`
- `sms:+1555...`
- `[email protected]`
imsg chats --limit 20

設定書き込み

iMessageはデフォルトでチャンネルから起動された設定書き込みを許可します（commands.config: trueの場合の/config set|unset）。

無効化：

{
  channels: {
    imessage: {
      configWrites: false,
    },
  },
}

トラブルシューティング

imsgが見つからない、またはRPC非対応 
バイナリとRPCサポートを検証してください：
imsg rpc --help
openclaw channels status --probe
probeがRPC非対応と報告する場合は、`imsg`を更新してください。
DMが無視される 
確認事項：

- `channels.imessage.dmPolicy`
- `channels.imessage.allowFrom`
- ペアリング承認（`openclaw pairing list imessage`）
グループメッセージが無視される 
確認事項：

- `channels.imessage.groupPolicy`
- `channels.imessage.groupAllowFrom`
- `channels.imessage.groups`の許可リスト動作
- メンションパターン設定（`agents.list[].groupChat.mentionPatterns`）
リモート添付ファイルが失敗する 
確認事項：

- `channels.imessage.remoteHost`
- `channels.imessage.remoteAttachmentRoots`
- GatewayホストからのSSH/SCPキー認証
- Gatewayホストの`~/.ssh/known_hosts`にホストキーが存在するか
- Messagesを実行しているMacでのリモートパスの読み取り可能性
macOS権限プロンプトを見逃した場合 
同じユーザー/セッションコンテキストでインタラクティブなGUIターミナルから再実行し、プロンプトを承認してください：
imsg chats --limit 1
imsg send <handle> "test"
OpenClaw/`imsg`を実行するプロセスコンテキストに対してフルディスクアクセス + オートメーションが付与されていることを確認してください。

設定リファレンスポインター

arrow_back
前へ
Googlechat
次へ
Irc
arrow_forward