Connect OpenClaw to iMessage

OpenClaw’s iMessage integration uses the external imsg CLI. The normal setup runs the Gateway and imsg on the same Mac, under the same signed-in user that owns the Messages database.

Confirm the Mac boundary

Messages.app must be signed in. The Gateway process needs the macOS permissions required to read Messages data and automate the app. Grant permissions to the actual process context that runs the managed service, not only to an unrelated terminal.

Install the plugin and bridge

openclaw plugins install @openclaw/imessage
brew install steipete/tap/imsg
imsg rpc --help

The official documentation strongly recommends the private API bridge for full channel behavior. Follow its current security and macOS-version instructions before running:

imsg launch

Do not weaken additional system security controls beyond the exact, current imsg requirements.

Configure and probe

Set channels.imessage.enabled, the imsg CLI path, and the Messages database path for the signed-in macOS user. Then restart and inspect the channel:

openclaw gateway restart
openclaw channels status --probe --channel imessage
imsg status --json

Pair the first sender

openclaw pairing list imessage
openclaw pairing approve imessage <CODE>

Pairing requests expire, so approve a fresh request.

Expected result

The iMessage probe reports a working bridge, a new inbound message appears in the local Messages database, and an approved sender receives a reply.

Remote Gateway setup

If the Gateway cannot run on the Messages Mac, point channels.imessage.cliPath to a transparent SSH wrapper that executes imsg on that Mac. Use non-interactive SSH keys, establish the host key beforehand, and test the wrapper directly before probing OpenClaw.

If imsg reports healthy but inbound messages never arrive, confirm that a fresh phone message creates a new row in chat.db. When it does not, repair the macOS Messages/Apple Push layer before changing OpenClaw policy.