iMessage Channel Setup via imsg for OpenClaw

Note

In the standard OpenClaw iMessage deployment, the Gateway and imsg run together on the same macOS Messages host that is signed in. Should your Gateway live somewhere else, configure channels.imessage.cliPath to use a transparent SSH wrapper that invokes imsg on the Mac.

Inbound recovery happens on its own. Once a bridge or gateway restarts, iMessage re-sends whatever arrived while it was offline, and it also filters out the stale "backlog bomb" that Apple may flush following a Push recovery. Deduplication guarantees that no message is dispatched twice. Nothing needs to be configured to turn this on, see Inbound recovery after a bridge or gateway restart.

Warning

BlueBubbles support has been dropped. Move your channels.bluebubbles configs over to channels.imessage. iMessage works in OpenClaw only via imsg. For the brief announcement, begin with BlueBubbles removal and the imsg iMessage path; for the complete migration table, see Coming from BlueBubbles.

Status: native external CLI integration. imsg rpc is spawned by the Gateway, and the two communicate through JSON-RPC over stdio, so there is no separate daemon and no port. A complete iMessage channel is best achieved with private API mode, which is strongly encouraged. imsg launch plus a passing private API check are needed for replies, tapbacks, effects, polls, attachment replies, and group actions.

In the typical local setup, OpenClaw setup can propose a Homebrew install or update of imsg on the signed-in Messages Mac, with the user confirming it. Manual setups and SSH-wrapper topologies stay under operator control: install or update imsg under the same user context that will run the Gateway or the wrapper.

• Setup, Install the plugin, configure imsg, and grant the macOS permissions.

• Private API, Turn off SIP, inject the helper, and enable the native actions.

• Troubleshooting, Remedies for silent inbound, ignored chats, and attachments that fail.

What each page covers

• iMessage setup, install the plugin, configure imsg on the Messages Mac, and grant Full Disk Access and Automation.
• Enabling the imsg private API, how to handle SIP and library validation, inject the helper, and what remains available if SIP stays enabled.
• iMessage access control and routing, DM and group policy, mention gating, per-group prompts, ACP bindings, and config writes.
• iMessage deployment patterns, a dedicated bot macOS user, a remote Mac over Tailscale, multiple accounts, and DM history.
• iMessage media and attachments, how attachments are ingested and staged, outbound chunking, and delivery target formats.
• iMessage private API actions, tapbacks, threaded replies, effects, native polls, approval controls, and agent questions.
• iMessage message behavior, split-send DM coalescing and automatic inbound recovery following a restart.
• iMessage troubleshooting, symptom-first fixes alongside links to the configuration reference.

Where each section moved

All section headings carried over from the earlier single-page version retain their anchors here, so a link you already have, such as /channels/imessage#troubleshooting, still resolves. Every entry directs you to the page that now contains the content.

• Install the plugin
• Quick setup
• Requirements and permissions (macOS)
• Enabling the imsg private API
• Setup
• When SIP stays enabled
• Access control and routing
• ACP conversation bindings
• Deployment patterns
• Media, chunking, and delivery targets
• Private API actions
• Config writes
• Coalescing split-send DMs (command + URL in one composition)
• Coalescing split-send DMs (command + URL in one composition)
• Inbound recovery after a bridge or gateway restart
• Operator-visible signal
• Migration
• Troubleshooting
• Configuration reference pointers
• Requirements and permissions (macOS)
• Media, chunking, and delivery targets
• Coalescing split-send DMs (command + URL in one composition)
• Local Mac (fast path)
• Install and verify imsg
• Configure OpenClaw
• Start gateway
• Approve first DM pairing (default dmPolicy)
• Remote Mac over SSH
• SSH wrapper sends fail with AppleEvents -1743
• DM policy
• Group policy + mentions
• Sessions and reply routing
• Dedicated bot macOS user (separate iMessage identity)
• Remote Mac over Tailscale (example)
• Multi-account pattern
• Direct-message history
• Attachments and media
• Outbound text and chunking
• Addressing formats
• Available actions
• Message IDs
• Capability detection
• Read receipts and typing
• Inbound tapbacks
• Approval polls and reactions
• Agent questions
• imsg not found or RPC unsupported
• Messages send but inbound iMessages do not arrive
• Gateway is not running on macOS
• DMs are ignored
• Group messages are ignored
• Remote attachments fail
• macOS permission prompts were missed

Related

• Channels Overview: every channel that is supported.

• Coming from BlueBubbles: a table for translating config, plus a cutover you can follow one step at a time.

• Pairing: how DM authentication and the pairing flow work.

• Reactions: what emoji reactions mean for the message tool.

• Groups: how group chats behave and how mention gating is applied.

• Channel routing, How sessions get routed for messages.

• Configuration reference, Complete reference for iMessage fields.

• RPC adapters, The line-delimited JSON-RPC stdio protocol that OpenClaw uses to communicate with imsg rpc.

• macOS VMs, If you need iMessage kept apart from your main Mac, run OpenClaw inside a sandboxed macOS VM, either local or hosted.