iMessage (Legacy)

The legacy iMessage integration runs directly on a macOS machine, accessing the local Messages chat.db to read and send messages.

• A macOS machine (Mac Mini, MacBook, etc.).
• Messages app signed in with an Apple ID.
• Full Disk Access granted to OpenClaw (to read chat.db).

1. Install the CLI Tool

   Section titled “Install the CLI Tool”

   We use imsg to bridge OpenClaw to the Messages private API.

   brew install steipete/tap/imsg

2. Configure OpenClaw

   Section titled “Configure OpenClaw”

   Tell OpenClaw where imsg and your chat database are located.

   {
     channels: {
       imessage: {
         enabled: true,
         // Path to the installed binary
         cliPath: "/opt/homebrew/bin/imsg",
         // Your Messages DB
         dbPath: "/Users/yourname/Library/Messages/chat.db"
       }
     }
   }

3. Grant Permissions

   Section titled “Grant Permissions”

   When you first run OpenClaw:

   • macOS will prompt you to grant Full Disk Access to your terminal or the OpenClaw binary. This is required to read chat.db.
   • macOS may prompt for Automation permissions to allow sending messages.

4. Pairing

   Section titled “Pairing”

   Send an iMessage to yourself (or the account running the bot).

   • The bot will reply with a Pairing Code.
   • Run openclaw pairing approve imessage <code> to authorize.

If you run OpenClaw on Linux but have a Mac for iMessage, you can bridge them via SSH and Tailscale.

1. Mac: Enable Remote Login (SSH).

2. Linux: Create a wrapper script to run imsg remotely.

   #!/bin/bash
   ssh user@my-mac-mini.tailscale.net "/opt/homebrew/bin/imsg $@"

3. Config:

   {
     channels: {
       imessage: {
         cliPath: "/usr/local/bin/imsg-ssh",
         remoteHost: "user@my-mac-mini.tailscale.net", // For fetching attachments
         includeAttachments: true
       }
     }
   }

We strongly recommend migrating to BlueBubbles for new deployments.