For the usual OpenClaw iMessage deployment, run the Gateway and
imsg on the same signed-in macOS Messages host. If your Gateway runs elsewhere, point channels.imessage.cliPath at a transparent SSH wrapper that runs imsg on the Mac.Inbound recovery is automatic. After a bridge or gateway restart, iMessage replays the messages missed while it was down and suppresses the stale “backlog bomb” Apple can flush after a Push recovery, deduping so nothing is dispatched twice. There is no config to enable — see Inbound recovery after a bridge or gateway restart.imsg rpc and speaks JSON-RPC over stdio — no separate daemon or port. Private API mode is strongly encouraged for a complete iMessage channel. Replies, tapbacks, effects, polls, attachment replies, and group actions require imsg launch and a successful private API probe.
For the common local setup, OpenClaw setup can offer a user-confirmed Homebrew install or update for imsg on the signed-in Messages Mac. Manual setup and SSH-wrapper topologies remain operator-managed: install or update imsg in the same user context that will run the Gateway or wrapper.
Setup
Install the plugin, set up
imsg, and grant the macOS permissions.Private API
Disable SIP, inject the helper, and unlock the native actions.
Troubleshooting
Fixes for silent inbound, ignored chats, and failed attachments.
What each page covers
- iMessage setup — install the plugin, set up
imsgon the Messages Mac, and grant Full Disk Access and Automation. - Enabling the imsg private API — the SIP and library-validation procedure, helper injection, and what stays available when SIP stays on.
- iMessage access control and routing — DM and group policy, mention gating, per-group prompts, ACP bindings, and config writes.
- iMessage deployment patterns — dedicated bot macOS user, remote Mac over Tailscale, multi-account, and DM history.
- iMessage media and attachments — attachment ingestion and staging, outbound chunking, and delivery target formats.
- iMessage private API actions — tapbacks, threaded replies, effects, native polls, approval controls, and question reactions.
- iMessage message behavior — split-send DM coalescing and automatic inbound recovery after a restart.
- iMessage troubleshooting — symptom-first fixes and the configuration reference links.
Where each section moved
Every section heading from the previous single-page version keeps its anchor here, so an existing link such as/channels/imessage#troubleshooting still resolves. Each entry points at the page that now holds 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 deterministic replies
- 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
- Question reactions (1️⃣ / 2️⃣ / 3️⃣ / 4️⃣)
- 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
All supported channels.
Coming from BlueBubbles
Config translation table and step-by-step cutover.
Pairing
DM authentication and pairing flow.
Reactions
Emoji reaction semantics for the
message tool.Groups
Group chat behavior and mention gating.
Channel routing
Session routing for messages.
Configuration reference
Full iMessage field reference.
RPC adapters
The line-delimited JSON-RPC stdio protocol OpenClaw speaks to
imsg rpc.macOS VMs
Run OpenClaw in a sandboxed macOS VM, local or hosted, when you want iMessage isolated from your main Mac.