How to Connect OpenClaw to iMessage

Prerequisites

• ✓A Mac with Messages signed in on the account you want OpenClaw to use (the Mac runs `imsg`).
• ✓Homebrew installed on the Mac so you can install `imsg` with `brew install steipete/tap/imsg`.
• ✓Full Disk Access and Automation permission available for the process context that runs OpenClaw/`imsg` on macOS.
• ✓An OpenClaw gateway environment where you can run `openclaw gateway` and edit the `channels.imessage` configuration.
• ✓SSH access between your OpenClaw gateway host and the Mac if you plan to run `imsg` remotely over SSH or Tailscale.

Steps

1. 1

   Install and verify imsg on your Mac

   Install the `imsg` CLI on the Mac that has iMessage signed in so OpenClaw can talk to Messages via JSON-RPC. Verifying `imsg rpc --help` confirms that the binary is present and supports the RPC mode OpenClaw needs.

   bashCopy

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

2. 2

   Grant macOS permissions for Messages and automation

   app. Run a one-time interactive `imsg` command in the same process context that will run the gateway so macOS shows the Full Disk Access and Automation prompts.

   bashCopy

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

3. 3

   Configure OpenClaw to use the local imsg CLI

   imessage` and pointing `cliPath` and `dbPath` at your Mac’s `imsg` binary and Messages database. This is the minimal config that lets the gateway spawn `imsg rpc` and read/write your iMessage chats.

   jsonCopy

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

4. 4

   Start the OpenClaw gateway with iMessage enabled

   Start the gateway so it can spawn `imsg rpc` and begin probing the iMessage channel. Keep this process running while you test DMs, groups, and pairing.

   bashCopy

   openclaw gateway

5. 5

   Approve the first iMessage DM pairing

   By default, iMessage DMs use pairing mode so unknown senders do not hit your agents automatically. List pending pairings and approve the code you want to trust before it expires after one hour.

   bashCopy

   openclaw pairing list imessage
   openclaw pairing approve imessage <CODE>

6. 6

   Optionally run imsg on a remote Mac over SSH

   If your OpenClaw gateway runs on a different host, point `cliPath` at an SSH wrapper script that runs `imsg` on the remote Mac. This keeps the Messages database on the Mac while the gateway runs on Linux or another VM.

   bashCopy

   #!/usr/bin/env bash
   exec ssh -T gateway-host imsg "$@"

7. 7

   Enable attachments and remote SCP fetches

   When you want OpenClaw to ingest iMessage attachments, enable `includeAttachments` and configure attachment roots and `remoteHost`. This lets the gateway fetch media over SCP while enforcing path allowlists for security.

   jsonCopy

   {
     channels: {
       imessage: {
         enabled: true,
         cliPath: "~/.openclaw/scripts/imsg-ssh",
         remoteHost: "user@gateway-host", // used for SCP attachment fetches
         includeAttachments: true,
         // Optional: override allowed attachment roots.
         // Defaults include /Users/*/Library/Messages/Attachments
         attachmentRoots: ["/Users/*/Library/Messages/Attachments"],
         remoteAttachmentRoots: ["/Users/*/Library/Messages/Attachments"],
       },
     },
   }

8. 8

   Use Tailscale or multi-account patterns for production setups

   For more isolated or scalable deployments, run `imsg` on a dedicated bot macOS user or a Mac in your tailnet. imessage` with the remote host, database path, and per-account overrides so each bot identity stays separate.

   bashCopy

   {
     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 "$@"

Configuration

Troubleshooting

imsg rpc --help
openclaw channels status --probe

openclaw pairing list imessage

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

Frequently asked questions