Skip to main content
新規の iMessage 構成では BlueBubbles を使ってください。imsg 統合はレガシー扱いであり、将来のリリースで削除される可能性があります。
ステータス: レガシーな外部 CLI 連携です。ゲートウェイは imsg rpc を起動し、stdio 上の JSON-RPC で通信します。別個のデーモンや専用ポートは不要です。

BlueBubbles (recommended)

新規構成ではこちらを推奨します。

Pairing

iMessage の DM はデフォルトでペアリングモードです。

Configuration reference

iMessage の設定項目一覧です。

​
Quick setup

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

ゲートウェイを起動する

openclaw gateway
4

最初の DM ペアリングを承認する (デフォルト dmPolicy)

openclaw pairing list imessage
openclaw pairing approve imessage <CODE>
ペアリング要求の有効期限は 1 時間です。

​
Requirements and permissions (macOS)

  • imsg を実行する Mac で Messages にサインインしている必要があります。
  • OpenClaw / imsg を実行するプロセスコンテキストには、Messages DB へアクセスするための Full Disk Access が必要です。
  • Messages.app 経由でメッセージを送信するには Automation 権限が必要です。
権限はプロセスコンテキスト単位で付与されます。ゲートウェイをヘッドレス (LaunchAgent / SSH) で動かす場合は、同じコンテキストで一度だけ対話型コマンドを実行して、権限プロンプトを表示させてください。
imsg chats --limit 1
# or
imsg send <handle> "test"

​
Access control and routing

channels.imessage.dmPolicy でダイレクトメッセージを制御します。
  • pairing (デフォルト)
  • allowlist
  • open (allowFrom に "*" を含める必要があります)
  • disabled
allowlist フィールドは channels.imessage.allowFrom です。allowlist のエントリには、handle またはチャットターゲット (chat_id:*, chat_guid:*, chat_identifier:*) を使えます。

​
Deployment patterns

専用の 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 の承認が必要になる場合があります。
よくある構成例:
  • ゲートウェイは 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 bash
exec ssh -T bot@mac-mini.tailnet-1234.ts.net imsg "$@"
SSH キーを使い、SSH と SCP の両方が非対話で動作するようにしてください。 また、最初にホストキーを信頼して known_hosts を埋める必要があります。たとえば ssh bot@mac-mini.tailnet-1234.ts.net を一度実行してください。
iMessage では channels.imessage.accounts の下でアカウントごとの設定を行えます。各アカウントでは、cliPath、dbPath、allowFrom、groupPolicy、mediaMaxMb、履歴設定、添付ファイルルート allowlist などを上書きできます。

​
Media, chunking, and delivery targets

  • 受信添付ファイルの取り込みはオプションです: 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:...
handle ベースのターゲットも使えます:
  • imessage:+1555...
  • sms:+1555...
  • user@example.com
imsg chats --limit 20

​
Config writes

iMessage ではデフォルトで、チャンネル開始の設定書き込みを許可します (commands.config: true のときの /config set|unset)。 無効にするには: 
{
  channels: {
    imessage: {
      configWrites: false,
    },
  },
}

​
Troubleshooting

バイナリと RPC サポートを確認します。
imsg rpc --help
openclaw channels status --probe
probe が RPC 非対応を報告する場合は、imsg を更新してください。
確認事項:
  • channels.imessage.dmPolicy
  • channels.imessage.allowFrom
  • ペアリング承認 (openclaw pairing list imessage)
確認事項:
  • channels.imessage.groupPolicy
  • channels.imessage.groupAllowFrom
  • channels.imessage.groups の allowlist 挙動
  • メンションパターン設定 (agents.list[].groupChat.mentionPatterns)
確認事項:
  • channels.imessage.remoteHost
  • channels.imessage.remoteAttachmentRoots
  • ゲートウェイホストからの SSH / SCP キー認証
  • ゲートウェイホスト上の ~/.ssh/known_hosts にホストキーがあること
  • Messages を実行している Mac 上で、リモートパスが読み取り可能であること
同じユーザー / セッションコンテキストの対話型 GUI ターミナルで再実行し、プロンプトを承認してください。
imsg chats --limit 1
imsg send <handle> "test"
OpenClaw / imsg を実行するプロセスコンテキストに Full Disk Access と Automation が付与されていることも確認してください。

​
Configuration reference pointers