iMessage (legacy: imsg) 統合ガイド

iMessage の自動化は、多くの開発者にとって頭の痛い課題です。日常的に使うメッセージアプリを自作のツールやワークフローと連携させたいと考えても、Apple のクローズドな仕様が壁となります。ローカルのデータベースを直接読み取ろうとしたり、UI 操作をシミュレートしようとしたりして、パーミッションのエラーに直面した経験がある方も多いのではないでしょうか。

既存の仕組みを壊さずに、ターミナルやスクリプトから iMessage を操作できるようにするのは簡単ではありません。ここでは、imsg という CLI ツールを使用して、OpenClaw Gateway と iMessage を接続する手順を説明します。

注意

新しい iMessage の導入には BlueBubbles を使用してください。 imsg 統合はレガシー機能であり、将来のリリースで削除される可能性があります。

必要なもの

セットアップを始める前に、以下の条件を満たしているか確認してください。

• macOS 環境（imsg を実行するため）
• Messages アプリにサインインしていること
• OpenClaw と imsg を実行するプロセスに対する Full Disk Access 権限
• Messages.app 経由でメッセージを送信するための Automation 権限

クイックスタート

5 分ほどで最小限の構成を立ち上げる手順です。

1. imsg のインストールと確認

Homebrew を使用してインストールし、正しく動作するか確認します。

brew install steipete/tap/imsg
imsg rpc --help

2. OpenClaw の設定

json5 形式で設定ファイルを作成します。<you> の部分は実際のユーザー名に置き換えてください。

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "/usr/local/bin/imsg",
      dbPath: "/Users/<you>/Library/Messages/chat.db",
    },
  },
}

3. Gateway の起動

設定が完了したら、Gateway を開始します。

openclaw gateway

4. DM ペアリングの承認

最初の DM を受信した際、ペアリングの承認が必要です。

openclaw pairing list imessage
openclaw pairing approve imessage <CODE>

ペアリングのリクエストは 1 時間で期限切れになります。

Remote Mac over SSH

OpenClaw は stdio 互換の cliPath を必要とするため、SSH 経由でリモートの Mac 上の imsg を実行するラッパースクリプトを使用できます。

#!/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,
    },
  },
}

remoteHost が未設定の場合、OpenClaw は SSH ラッパースクリプトを解析して自動検出を試みます。

Deployment Patterns

ボット専用の macOS ユーザーを使用する

個人のメッセージとボットのトラフィックを分離するために、専用の Apple ID と macOS ユーザーを作成する方法です。

1. 専用の macOS ユーザーを作成してサインインします。
2. そのユーザーで Messages にボット用の Apple ID でサインインします。
3. そのユーザー環境に imsg をインストールします。
4. SSH ラッパーを作成し、OpenClaw がそのユーザーコンテキストで imsg を実行できるようにします。
5. cliPath と dbPath をそのユーザーのプロファイルに向けます。

Tailscale 経由でリモートの Mac を使用する

Linux 上で Gateway を動かし、Tailscale ネットワーク内の Mac で iMessage を処理する構成です。

{
  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",
    },
  },
}

SSH キーを設定して、対話なしで SSH と SCP が実行できるようにしてください。

トラブルシューティング

imsg が見つからない、または RPC が未サポート

バイナリと RPC サポートを確認してください。

imsg rpc --help
openclaw channels status --probe

RPC が未サポートと報告される場合は、imsg を更新してください。

DM が無視される

以下の項目を確認してください。

• channels.imessage.dmPolicy
• channels.imessage.allowFrom
• ペアリングの承認状態 (openclaw pairing list imessage)

macOS の権限プロンプトが表示されない

GUI ターミナルから対話形式でコマンドを実行し、プロンプトを承認してください。

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

Full Disk Access と Automation の権限が、OpenClaw/imsg を実行するコンテキストに付与されていることを確認してください。

リモートの添付ファイル取得に失敗する

以下の項目を確認してください。

• channels.imessage.remoteHost の設定
• Gateway ホストからの SSH/SCP キー認証
• Mac 上の添付ファイルパスの読み取り権限

セットアップに関する質問がある場合は、AI Setup Assistant を活用してください。

次のステップ

• Configuration reference - iMessage
• Gateway configuration
• Pairing
• BlueBubbles