Status: native external CLI integration. Gateway spawns imsg rpc and communicates over JSON-RPC on stdio (no separate daemon/port). Advanced actions require imsg launch and a successful private API probe.
Messages must be signed in on the Mac running imsg.
Full Disk Access is required for the process context running OpenClaw/imsg (Messages DB access).
Automation permission is required to send messages through Messages.app.
For advanced actions (react / edit / unsend / threaded reply / effects / group ops), System Integrity Protection must be disabled — see Enabling the imsg private API below. Basic text and media send/receive work without it.
Basic mode (default, no SIP changes needed): outbound text and media via send, inbound watch/history, chat list. This is what you get out of the box from a fresh brew install steipete/tap/imsg plus the standard macOS permissions above.
Private API mode: imsg injects a helper dylib into Messages.app to call internal IMCore functions. This is what unlocks react, edit, unsend, reply (threaded), sendWithEffect, renameGroup, setGroupIcon, addParticipant, removeParticipant, leaveGroup, plus typing indicators and read receipts.
To reach the advanced action surface that this channel page documents, you need Private API mode. The imsg README is explicit about the requirement:
Advanced features such as read, typing, launch, bridge-backed rich send, message mutation, and chat management are opt-in. They require SIP to be disabled and a helper dylib to be injected into Messages.app. imsg launch refuses to inject when SIP is enabled.
The helper-injection technique uses imsg’s own dylib to reach Messages private APIs. There is no third-party server or BlueBubbles runtime in the OpenClaw iMessage path.
Install (or upgrade) imsg on the Mac that runs Messages.app:
Terminal window
brewinstallsteipete/tap/imsg
imsg--version
imsgstatus--json
The imsg status --json output reports bridge_version, rpc_methods, and per-method selectors so you can see what the current build supports before you start.
Disable System Integrity Protection. This is macOS-version-specific because the underlying Apple requirement depends on the OS and hardware:
macOS 10.13–10.15 (Sierra–Catalina): disable Library Validation via Terminal, reboot to Recovery Mode, run csrutil disable, restart.
macOS 11+ (Big Sur and later), Intel: Recovery Mode (or Internet Recovery), csrutil disable, restart.
macOS 11+, Apple Silicon: power-button startup sequence to enter Recovery; on recent macOS versions hold the Left Shift key when you click Continue, then csrutil disable. Virtual-machine setups follow a separate flow — take a VM snapshot first.
macOS 26 / Tahoe: library-validation policies and imagent private-entitlement checks have tightened further; imsg may need an updated build to keep up. If imsg launch injection or specific selectors start returning false after a macOS major upgrade, check imsg’s release notes before assuming the SIP step succeeded.
Follow Apple’s Recovery-mode flow for your Mac to disable SIP before running imsg launch.
Inject the helper. With SIP disabled and Messages.app signed in:
Terminal window
imsglaunch
imsg launch refuses to inject when SIP is still enabled, so this also doubles as a confirmation that step 2 took.
Verify the bridge from OpenClaw:
Terminal window
openclawchannelsstatus--probe
The iMessage entry should report works, and imsg status --json | jq '.selectors' should show retractMessagePart: true plus whichever edit / typing / read selectors your macOS build exposes. The OpenClaw plugin per-method gating in actions.ts only advertises actions whose underlying selector is true, so the action surface you see in the agent’s tool list reflects what the bridge can actually do on this host.
If openclaw channels status --probe reports the channel as works but specific actions throw “iMessage `
requires the imsg private API bridge" at dispatch time, runimsg launchagain — the helper can fall out (Messages.app restart, OS update, etc.) and the cachedavailable: true` status will keep advertising actions until the next probe refreshes.
If SIP-disabled isn’t acceptable for your threat model:
imsg falls back to basic mode — text + media + receive only.
The OpenClaw plugin still advertises text/media send and inbound monitoring; it just hides react, edit, unsend, reply, sendWithEffect, and group ops from the action surface (per the per-method capability gate).
You can run a separate non-Apple-Silicon Mac (or a dedicated bot Mac) with SIP off for the iMessage workload, while keeping SIP enabled on your primary devices. See Dedicated bot macOS user (separate iMessage identity) below.
channels.imessage.dmPolicy controls direct messages:
pairing (default)
allowlist
open (requires allowFrom to include "*")
disabled
Allowlist field: channels.imessage.allowFrom.
Allowlist entries must identify senders: handles or static sender access groups (`accessGroup:
). Use channels.imessage.groupAllowFromfor chat targets such aschat_id:, chat_guid:, or chat_identifier:*; use channels.imessage.groupsfor numericchat_id` registry keys.
channels.imessage.groupPolicy controls group handling:
allowlist (default when configured)
open
disabled
Group sender allowlist: channels.imessage.groupAllowFrom.
groupAllowFrom entries can also reference static sender access groups (`accessGroup:
`).
Runtime fallback: if `groupAllowFrom` is unset, iMessage group sender checks use `allowFrom`; set `groupAllowFrom` when DM and group admission should differ.
Runtime note: if `channels.imessage` is completely missing, runtime falls back to `groupPolicy="allowlist"` and logs a warning (even if `channels.defaults.groupPolicy` is set).
with no configured patterns, mention gating cannot be enforced
Control commands from authorized senders can bypass mention gating in groups.
Per-group systemPrompt:
Each entry under channels.imessage.groups.* accepts an optional systemPrompt string. The value is injected into the agent’s system prompt on every turn that handles a message in that group. Resolution mirrors the per-group prompt resolution used by channels.whatsapp.groups:
Group-specific system prompt (`groups[”
“].systemPrompt): used when the specific group entry exists in the map **and** its systemPromptkey is defined. IfsystemPrompt is an empty string ("") the wildcard is suppressed and no system prompt is applied to that group. 2. **Group wildcard system prompt** (groups[”*“].systemPrompt): used when the specific group entry is absent from the map entirely, or when it exists but defines no systemPrompt` key.
```json5
{
channels: {
imessage: {
groupPolicy: "allowlist",
groupAllowFrom: ["+15555550123"],
groups: {
"*": { systemPrompt: "Use British spelling." },
"8421": {
requireMention: true,
systemPrompt: "This is the on-call rotation chat. Keep replies under 3 sentences.",
},
"9907": {
// explicit suppression: the wildcard "Use British spelling." does not apply here
systemPrompt: "",
},
},
},
},
}
```
Per-group prompts only apply to group messages — direct messages in this channel are unaffected.
DMs use direct routing; groups use group routing.
With default session.dmScope=main, iMessage DMs collapse into the agent main session.
Group sessions are isolated (`agent:
:imessage:group:
`).
- Replies route back to iMessage using originating channel/target metadata.
Group-ish thread behavior:
Some multi-participant iMessage threads can arrive with `is_group=false`.
If that `chat_id` is explicitly configured under `channels.imessage.groups`, OpenClaw treats it as group traffic (group gating + group session isolation).
Use SSH keys so both SSH and SCP are non-interactive.
Ensure the host key is trusted first (for example ssh [email protected]) so known_hosts is populated.
Multi-account pattern
iMessage supports per-account config under channels.imessage.accounts.
Each account can override fields such as cliPath, dbPath, allowFrom, groupPolicy, mediaMaxMb, history settings, and attachment root allowlists.
inbound attachment ingestion is off by default — set channels.imessage.includeAttachments: true to forward photos, voice memos, video, and other attachments to the agent. With it disabled, attachment-only iMessages are dropped before reaching the agent and may produce no Inbound message log line at all.
remote attachment paths can be fetched via SCP when remoteHost is set
When imsg launch is running and openclaw channels status --probe reports privateApi.available: true, the message tool can use iMessage-native actions in addition to normal text sends.
{
channels: {
imessage: {
actions: {
reactions: true,
edit: true,
unsend: true,
reply: true,
sendWithEffect: true,
sendAttachment: true,
renameGroup: true,
setGroupIcon: true,
addParticipant: true,
removeParticipant: true,
leaveGroup: true,
},
},
},
}
Available actions
react: Add/remove iMessage tapbacks (messageId, emoji, remove). Supported tapbacks map to love, like, dislike, laugh, emphasize, and question.
reply: Send a threaded reply to an existing message (messageId, text or message, plus chatGuid, chatId, chatIdentifier, or to).
sendWithEffect: Send text with an iMessage effect (text or message, effect or effectId).
edit: Edit a sent message on supported macOS/private API versions (messageId, text or newText).
unsend: Retract a sent message on supported macOS/private API versions (messageId).
upload-file: Send media/files (buffer as base64 or a hydrated media/path/filePath, filename, optional asVoice). Legacy alias: sendAttachment.
renameGroup, setGroupIcon, addParticipant, removeParticipant, leaveGroup: Manage group chats when the current target is a group conversation.
Message IDs
Inbound iMessage context includes both short MessageSid values and full message GUIDs when available. Short IDs are scoped to the recent in-memory reply cache and are checked against the current chat before use. If a short ID has expired or belongs to another chat, retry with the full MessageSidFull.
Capability detection
OpenClaw hides private API actions only when the cached probe status says the bridge is unavailable. If the status is unknown, actions remain visible and dispatch probes lazily so the first action can succeed after imsg launch without a separate manual status refresh.
Read receipts and typing
When the private API bridge is up, accepted inbound chats are marked read before dispatch and a typing bubble is shown to the sender while the agent generates. Disable read-marking with:
{
channels: {
imessage: {
sendReadReceipts: false,
},
},
}
Older imsg builds that pre-date the per-method capability list will gate off typing/read silently; OpenClaw logs a one-time warning per restart so the missing receipt is attributable.
Inbound tapbacks
OpenClaw subscribes to iMessage tapbacks and routes accepted reactions as system events instead of normal message text, so a user tapback does not trigger an ordinary reply loop.
Notification mode is controlled by channels.imessage.reactionNotifications:
"own" (default): notify only when users react to bot-authored messages.
"all": notify for all inbound tapbacks from authorized senders.
"off": ignore inbound tapbacks.
Per-account overrides use `channels.imessage.accounts.
When a user types a command and a URL together — e.g. Dump https://example.com/article — Apple’s Messages app splits the send into two separate chat.db rows:
A text message ("Dump").
A URL-preview balloon ("https://...") with OG-preview images as attachments.
The two rows arrive at OpenClaw ~0.8-2.0 s apart on most setups. Without coalescing, the agent receives the command alone on turn 1, replies (often “send me the URL”), and only sees the URL on turn 2 — at which point the command context is already lost. This is Apple’s send pipeline, not anything OpenClaw or imsg introduces.
channels.imessage.coalesceSameSenderDms opts a DM into merging consecutive same-sender rows into a single agent turn. Group chats continue to dispatch per-message so multi-user turn structure is preserved.
Enable when:
You ship skills that expect command + payload in one message (dump, paste, save, queue, etc.).
Your users paste URLs, images, or long content alongside commands.
You can accept the added DM turn latency (see below).
Leave disabled when:
You need minimum command latency for single-word DM triggers.
All your flows are one-shot commands without payload follow-ups.
{
channels: {
imessage: {
coalesceSameSenderDms: true, // opt in (default: false)
},
},
}
With the flag on and no explicit messages.inbound.byChannel.imessage, the debounce window widens to 2500 ms (the legacy default is 0 ms — no debouncing). The wider window is required because Apple’s split-send cadence of 0.8-2.0 s does not fit in a tighter default.
To tune the window yourself:
{
messages: {
inbound: {
byChannel: {
// 2500 ms works for most setups; raise to 4000 ms if your Mac is
// slow or under memory pressure (observed gap can stretch past 2 s
// then).
imessage: 2500,
},
},
},
}
Added latency for DM messages. With the flag on, every DM (including standalone control commands and single-text follow-ups) waits up to the debounce window before dispatching, in case a payload row is coming. Group-chat messages keep instant dispatch.
Merged output is bounded. Merged text caps at 4000 chars with an explicit …[truncated] marker; attachments cap at 20; source entries cap at 10 (first-plus-latest retained beyond that). Every source GUID is tracked in coalescedMessageGuids for downstream telemetry.
DM-only. Group chats fall through to per-message dispatch so the bot stays responsive when multiple people are typing.
Opt-in, per-channel. Other channels (Telegram, WhatsApp, Slack, …) are unaffected. Legacy BlueBubbles configs that set channels.bluebubbles.coalesceSameSenderDms should migrate that value to channels.imessage.coalesceSameSenderDms.
When the gateway is offline (crash, restart, Mac sleep, machine off), imsg watch resumes from the current chat.db state once the gateway comes back up — anything that arrived during the gap is, by default, never seen. Catchup replays those messages on the next startup so the agent does not silently miss inbound traffic.
Catchup is disabled by default. Enable it per channel:
channels: {
imessage: {
catchup: {
enabled: true, // master switch (default: false)
maxAgeMinutes: 120, // skip rows older than now - 2h (default: 120, clamp 1..720)
perRunLimit: 50, // max rows replayed per startup (default: 50, clamp 1..500)
firstRunLookbackMinutes: 30, // first run with no cursor: look back 30 min (default: 30)
maxFailureRetries: 10, // give up on a wedged guid after 10 dispatch failures (default: 10)
One pass per monitorIMessageProvider startup, sequenced as imsg launch ready → watch.subscribe → performIMessageCatchup → live dispatch loop. Catchup itself uses chats.list + per-chat messages.history against the same JSON-RPC client used by imsg watch. Anything that arrives during the catchup pass flows through live dispatch normally; the existing inbound-dedupe cache absorbs any overlap with replayed rows.
Each replayed row is fed through the live dispatch path (evaluateIMessageInbound + dispatchInboundMessage), so allowlists, group policy, debouncer, echo cache, and read receipts behave identically on replayed and live messages.
.json(the OpenClaw state dir defaults to~/.openclaw, overridable with OPENCLAW_STATE_DIR`):
{
"lastSeenMs": 1717900800000,
"lastSeenRowid": 482910,
"updatedAt": 1717900801234,
"failureRetries": { "
”: 1 }
}
- The cursor advances on each successful dispatch and is held when a row's dispatch throws — the next startup retries the same row from the held cursor.
- After `maxFailureRetries` consecutive throws against the same `guid`, catchup logs a `warn` and force-advances the cursor past the wedged message so subsequent startups can make progress.
- Already-given-up guids are skipped on sight (no dispatch attempt) on later runs and counted under `skippedGivenUp` in the run summary.
### Operator-visible signals
imessage catchup: replayed=N skippedFromMe=… skippedGivenUp=… failed=… givenUp=… fetchedCount=…
imessage catchup: giving up on guid=
after
failures; advancing cursor past it
imessage catchup: fetched
rows across chats, capped to perRunLimit=
A `WARN ... capped to perRunLimit` line means a single startup did not drain the full backlog. Raise `perRunLimit` (max 500) if your gaps regularly exceed the default 50-row pass.
### When to leave it off
- Gateway runs continuously with watchdog auto-restart and gaps are always < a few seconds — the default of off is fine.
- DM volume is low and missed messages would not change agent behavior — the `firstRunLookbackMinutes` initial window can dispatch surprising old context on first enable.
When you turn catchup on, the first startup with no cursor only looks back `firstRunLookbackMinutes` (30 min default), not the full `maxAgeMinutes` window — this avoids replaying a long history of pre-enable messages.
## Troubleshooting
imsg not found or RPC unsupported
Validate the binary and RPC support:
Terminal window
imsgrpc--help
imsgstatus--json
openclawchannelsstatus--probe
If probe reports RPC unsupported, update imsg. If private API actions are unavailable, run imsg launch in the logged-in macOS user session and probe again. If the Gateway is not running on macOS, use the Remote Mac over SSH setup above instead of the default local imsg path.
Gateway is not running on macOS
The default `cliPath: "imsg"` must run on the Mac signed into Messages. On Linux or Windows, set `channels.imessage.cliPath` to a wrapper script that SSHes to that Mac and runs `imsg "$@"`.
#!/usr/bin/env bash
execssh-Tmessages-macimsg"$@"
Then run:
Terminal window
openclawchannelsstatus--probe--channelimessage
DMs are ignored
Check:
channels.imessage.dmPolicy
channels.imessage.allowFrom
pairing approvals (openclaw pairing list imessage)