OpenClaw iMessage setup

iMessage is the only OpenClaw channel that needs a Mac signed into Messages, so setup is really about where that Mac is: under the gateway, or somewhere the gateway reaches over SSH. Here is the plugin install, the local fast path, the remote topology with its wrapper rules, and the macOS permissions that decide whether sends work at all.

Local fast path

• The official plugin is installed on the gateway host with the plugins install command for the iMessage package, and the docs say to check the application result before continuing; iMessage DMs default to pairing, private-API actions cover replies, tapbacks, effects, polls, attachments and group management, and a remote Mac uses an SSH wrapper.
• On the Messages Mac you install imsg from its Homebrew tap, update and upgrade it, check the RPC help, run the launch command and probe the channel; when the local wizard detects a missing default imsg it can offer to install it through Homebrew, and a Homebrew-managed imsg can be reinstalled or updated, while custom CLI-path wrappers are left alone.
• The config enables the channel and sets the CLI path to the imsg binary and the database path to the Messages chat database under the user's library, then the gateway is started.
• The first DM is approved with the pairing list and approve commands, and pairing requests expire after one hour.

Permissions are granted per process context.

Remote Mac over SSH

Most setups need no SSH; the remote topology is for a gateway that cannot run on the signed-in Messages Mac. The CLI path then points at a stdio-compatible wrapper on the gateway host, given as an absolute path so service launches do not depend on shell home expansion, that SSHes to the Messages Mac and runs imsg, with imsg installed and updated on the remote Mac rather than the gateway host. The recommended config with attachments on sets the wrapper path, the remote host as user at host, the database path interpreted on the Messages Mac, inbound attachments enabled, and optional attachment roots merged with the default Messages attachments folder on both sides. The remote host identifies the Messages Mac for inbound attachment fetches and outbound attachment staging: for outbound files OpenClaw creates an owner-only temporary path on that Mac, copies the file over the strict SSH and SCP transport, passes only the remote path to imsg, and attempts removal after success, failure or timeout, with a failed cleanup call logged as a warning that can leave the directory behind. An explicit remote host wins; for compatibility OpenClaw auto-detects the simple transparent wrapper shape once per process and reuses the host, but option-rich wrappers with proxy jumps or proxy commands must set the remote host, the value must be host or user at host with no spaces or SSH options, strict host-key checking means the Mac's host key must already be in the gateway's known hosts, and attachment paths are validated against the allowed roots. The warning that follows matters most: any wrapper or proxy in front of imsg must behave like a transparent stdio pipe for long-lived JSON-RPC, forwarding each stdin and stdout chunk as soon as bytes are available, preserving newlines, avoiding fixed-size blocking reads and keeping stderr separate, because a wrapper that buffers stdin until a block fills produces RPC timeouts and repeated channel restarts that look like an iMessage outage even though imsg itself is healthy; the plain SSH wrapper is safe, and pipelines that filter output through line-buffered tools are not unless every stage is line-buffered.

macOS permissions

• Messages must be signed in on the Mac running imsg, Full Disk Access is required for the process context running OpenClaw or imsg so it can read the Messages database, Automation permission is required to send through the Messages app, and the advanced actions, react, edit, unsend, threaded reply, effects, polls and group operations, need System Integrity Protection disabled while basic text and media work without it.
• Permissions are granted per process context, so a headless gateway under a LaunchAgent or SSH should run a one-time interactive command in that same context, listing one chat or sending a test message, to trigger the prompts.
• A remote-SSH setup can read chats, pass the probe and process inbound messages while outbound sends fail with an AppleEvents not-authorised error; when the Automation entry in the TCC database or the Privacy settings is recorded for the SSH key-generation wrapper rather than imsg or a local shell, macOS may expose no usable Messages toggle for that server-side client, resetting AppleEvents or rerunning the send keeps failing, and the fix is a supported process context: run the gateway or at least the imsg bridge in the logged-in user's local session, start it from a LaunchAgent for that user after granting both permissions from that session, or, if the two-user SSH topology stays, verify a real outbound send through the exact wrapper before enabling the channel and fall back to a single-user setup when Automation cannot be granted.

OpenClaw on iMessage is the channel post this setup belongs to, and OpenClaw iMessage deployment the dedicated-user and remote-Mac patterns it builds on.

The wrapper is the channel

Everything the gateway knows about Messages passes through one stdio pipe, which is why a buffering wrapper is indistinguishable from a dead channel and why the docs spell out what the pipe must do. OpenClaw iMessage private API covers the SIP tradeoff behind the advanced actions, and Connect your first channel in five minutes the channels where none of this applies.

On Diali

iMessage is not among the channels Diali connects today: WhatsApp, Telegram, Discord, Slack, Mattermost, Matrix, SMS and voice. Hosted OpenClaw on Diali is the assistant and Diali security describes the boundary that applies to each connected channel.

• A signed-in Mac, imsg from Homebrew, one pairing code.
• The SSH wrapper must forward bytes as they arrive.
• Grant Full Disk Access and Automation in the context that runs imsg.