iMessage

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.

# Quick setup

brew install steipete/tap/imsg
imsg rpc --help
imsg launch
openclaw channels status --probe

{
channels: {
imessage: {
enabled: true,
cliPath: "/usr/local/bin/imsg",
dbPath: "/Users/user/Library/Messages/chat.db",
},
},
}

openclaw gateway

openclaw pairing list imessage
openclaw pairing approve imessage <CODE>

#!/usr/bin/env bash
exec ssh -T gateway-host imsg "$@"

{
channels: {
imessage: {
  enabled: true,
  cliPath: "~/.openclaw/scripts/imsg-ssh",
  remoteHost: "user@gateway-host", // used for SCP attachment fetches
  includeAttachments: true,
  // Optional: override allowed attachment roots.
  // Defaults include /Users/*/Library/Messages/Attachments
  attachmentRoots: ["/Users/*/Library/Messages/Attachments"],
  remoteAttachmentRoots: ["/Users/*/Library/Messages/Attachments"],
},
},
}

# Requirements and permissions (macOS)

• 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.

# Enabling the imsg private API

imsg ships in two operational modes:

• 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.

# Setup

1. Install (or upgrade) imsg on the Mac that runs Messages.app:

   brew install steipete/tap/imsg
   imsg --version
   imsg status --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.

2. 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.

3. Inject the helper. With SIP disabled and Messages.app signed in:

   imsg launch
   

   imsg launch refuses to inject when SIP is still enabled, so this also doubles as a confirmation that step 2 took.

4. Verify the bridge from OpenClaw:

   openclaw channels status --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 <action> requires the imsg private API bridge" at dispatch time, run imsg launch again — the helper can fall out (Messages.app restart, OS update, etc.) and the cached available: true status will keep advertising actions until the next probe refreshes.

# When you can't disable SIP

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.

# Access control and routing

{
  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: "",
        },
      },
    },
  },
}

# ACP conversation bindings

Legacy iMessage chats can also be bound to ACP sessions.

Fast operator flow:

• Run /acp spawn codex --bind here inside the DM or allowed group chat.
• Future messages in that same iMessage conversation route to the spawned ACP session.
• /new and /reset reset the same bound ACP session in place.
• /acp close closes the ACP session and removes the binding.

Configured persistent bindings are supported through top-level bindings[] entries with type: "acp" and match.channel: "imessage".

match.peer.id can use:

• normalized DM handle such as +15555550123 or [email protected]
• chat_id:<id> (recommended for stable group bindings)
• chat_guid:<guid>
• chat_identifier:<identifier>

Example:

{
  agents: {
    list: [
      {
        id: "codex",
        runtime: {
          type: "acp",
          acp: { agent: "codex", backend: "acpx", mode: "persistent" },
        },
      },
    ],
  },
  bindings: [
    {
      type: "acp",
      agentId: "codex",
      match: {
        channel: "imessage",
        accountId: "default",
        peer: { kind: "group", id: "chat_id:123" },
      },
      acp: { label: "codex-group" },
    },
  ],
}

See ACP Agents for shared ACP binding behavior.

# Deployment patterns

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "~/.openclaw/scripts/imsg-ssh",
      remoteHost: "[email protected]",
      includeAttachments: true,
      dbPath: "/Users/bot/Library/Messages/chat.db",
    },
  },
}

#!/usr/bin/env bash
exec ssh -T [email protected] imsg "$@"

# Media, chunking, and delivery targets

imsg chats --limit 20

# Private API actions

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,
      },
    },
  },
}

{
  channels: {
    imessage: {
      sendReadReceipts: false,
    },
  },
}

# Config writes

iMessage allows channel-initiated config writes by default (for /config set|unset when commands.config: true).

Disable:

{
  channels: {
    imessage: {
      configWrites: false,
    },
  },
}

# Coalescing split-send DMs (command + URL in one composition)

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:

1. A text message ("Dump").
2. 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.

{
  channels: {
    imessage: {
      coalesceSameSenderDms: true, // opt in (default: false)
    },
  },
}

{
  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,
      },
    },
  },
}

# Scenarios and what the agent sees

# Catching up after gateway downtime

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)
    },
  },
}

# How it runs

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.

# Cursor and retry semantics

Catchup keeps a per-account cursor at <openclawStateDir>/imessage/catchup/<account>__<hash>.json (the OpenClaw state dir defaults to ~/.openclaw, overridable with OPENCLAW_STATE_DIR):

{
  "lastSeenMs": 1717900800000,
  "lastSeenRowid": 482910,
  "updatedAt": 1717900801234,
  "failureRetries": { "<guid>": 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=<guid> after &lt;N&gt; failures; advancing cursor past it
imessage catchup: fetched &lt;X&gt; rows across chats, capped to perRunLimit=&lt;Y&gt;

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 rpc --help
imsg status --json
openclaw channels status --probe

#!/usr/bin/env bash
exec ssh -T messages-mac imsg "$@"

openclaw channels status --probe --channel imessage

imsg chats --limit 1
imsg send <handle> "test"

# Configuration reference pointers

• Configuration reference - iMessage
• Gateway configuration
• Pairing

# Related

• Channels Overview — all supported channels
• Coming from BlueBubbles — config translation table and step-by-step cutover
• Pairing — DM authentication and pairing flow
• Groups — group chat behavior and mention gating
• Channel Routing — session routing for messages
• Security — access model and hardening