openclaw/docs/channels/imessage.md

summary, read_when, title

summary	read_when	title
Native iMessage support via imsg (JSON-RPC over stdio), with private API actions for replies, tapbacks, effects, attachments, and group management. Preferred for new OpenClaw iMessage setups when host requirements fit.	Setting up iMessage support Debugging iMessage send/receive	iMessage

For OpenClaw iMessage deployments, use `imsg` on a signed-in macOS Messages host. If your Gateway runs on Linux or Windows, point `channels.imessage.cliPath` at an SSH wrapper that runs `imsg` on the Mac.

Known gap: no gateway-downtime catchup. Messages that arrive while the gateway is down (crash, restart, Mac sleep, machine off) are not delivered to the agent once the gateway comes back up — imsg watch resumes from the current state and ignores anything that landed in chat.db during the gap. Tracked at openclaw#78649.

BlueBubbles is deprecated and no longer ships as a bundled OpenClaw channel. Migrate `channels.bluebubbles` configs to `channels.imessage`; OpenClaw now supports iMessage through `imsg` only. If you still need a BlueBubbles-backed bridge, publish or install it as a third-party plugin outside core.

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.

Replies, tapbacks, effects, attachments, and group management. iMessage DMs default to pairing mode. Use an SSH wrapper when the Gateway is not running on the Messages Mac. Full iMessage field reference.

Quick setup

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

  </Step>

  <Step title="Configure OpenClaw">

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

  </Step>

  <Step title="Start gateway">

openclaw gateway

  </Step>

  <Step title="Approve first DM pairing (default dmPolicy)">

openclaw pairing list imessage
openclaw pairing approve imessage <CODE>

    Pairing requests expire after 1 hour.
  </Step>
</Steps>

OpenClaw only requires a stdio-compatible `cliPath`, so you can point `cliPath` at a wrapper script that SSHes to a remote Mac and runs `imsg`.

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

Recommended config when attachments are enabled:

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

If `remoteHost` is not set, OpenClaw attempts to auto-detect it by parsing the SSH wrapper script.
`remoteHost` must be `host` or `user@host` (no spaces or SSH options).
OpenClaw uses strict host-key checking for SCP, so the relay host key must already exist in `~/.ssh/known_hosts`.
Attachment paths are validated against allowed roots (`attachmentRoots` / `remoteAttachmentRoots`).

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.

Permissions are granted per process context. If gateway runs headless (LaunchAgent/SSH), run a one-time interactive command in that same context to trigger prompts:

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

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 is a manual port of the BlueBubbles private-API surface (Apache-2.0 inspired) into imsg's own dylib — no third-party binary, but the same SIP-disabled requirement that BlueBubbles' Private API mode has. There is no SIP-asymmetry between the two channels.

**Disabling SIP is a real security tradeoff.** SIP is one of macOS's core protections against running modified system code; turning it off system-wide opens up additional attack surface and side effects. Notably, **disabling SIP on Apple Silicon Macs also disables the ability to install and run iOS apps on your Mac**.

Treat this as a deliberate operational choice, not a default. If your threat model can't tolerate SIP being off, both bundled iMessage and BlueBubbles will be limited to their basic modes — text and media send/receive only, no reactions / edit / unsend / effects / group ops on either channel.

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, identical to the BlueBubbles flow because the underlying Apple requirement is the same:

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

   The BlueBubbles Private API installation guide is the canonical step-by-step for the SIP-disable flow itself; the macOS-side steps are not specific to BB, only the helper that gets injected differs.

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:

• Both imsg and BlueBubbles fall 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.dmPolicy` controls direct messages:

- `pairing` (default)
- `allowlist`
- `open` (requires `allowFrom` to include `"*"`)
- `disabled`

Allowlist field: `channels.imessage.allowFrom`.

Allowlist entries can be handles or chat targets (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`).

`channels.imessage.groupPolicy` controls group handling:

- `allowlist` (default when configured)
- `open`
- `disabled`

Group sender allowlist: `channels.imessage.groupAllowFrom`.

Runtime fallback: if `groupAllowFrom` is unset, iMessage group sender checks fall back to `allowFrom` when available.
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).

<Warning>
Group routing has **two** allowlist gates running back-to-back, and both must pass:

1. **Sender / chat-target allowlist** (`channels.imessage.groupAllowFrom`) — handle, `chat_guid`, `chat_identifier`, or `chat_id`.
2. **Group registry** (`channels.imessage.groups`) — with `groupPolicy: "allowlist"`, this gate requires either a `groups: { "*": { ... } }` wildcard entry (sets `allowAll = true`), or an explicit per-`chat_id` entry under `groups`.

If gate 2 has nothing in it, every group message is dropped. The plugin emits two `warn`-level signals at the default log level:

- one-time per account at startup: `imessage: groupPolicy="allowlist" but channels.imessage.groups is empty for account "<id>"`
- one-time per `chat_id` at runtime: `imessage: dropping group message from chat_id=<id> ...`

DMs continue to work because they take a different code path.

Minimum config to keep groups flowing under `groupPolicy: "allowlist"`:

```json5
{
  channels: {
    imessage: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15555550123"],
      groups: { "*": { "requireMention": true } },
    },
  },
}
```

If those `warn` lines appear in the gateway log, gate 2 is dropping — add the `groups` block.
</Warning>

Mention gating for groups:

- iMessage has no native mention metadata
- mention detection uses regex patterns (`agents.list[].groupChat.mentionPatterns`, fallback `messages.groupChat.mentionPatterns`)
- with no configured patterns, mention gating cannot be enforced

Control commands from authorized senders can bypass mention gating in groups.

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

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 user@example.com
• 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

Use a dedicated Apple ID and macOS user so bot traffic is isolated from your personal Messages profile.

Typical flow:

1. Create/sign in a dedicated macOS user.
2. Sign into Messages with the bot Apple ID in that user.
3. Install `imsg` in that user.
4. Create SSH wrapper so OpenClaw can run `imsg` in that user context.
5. Point `channels.imessage.accounts.<id>.cliPath` and `.dbPath` to that user profile.

First run may require GUI approvals (Automation + Full Disk Access) in that bot user session.

Common topology:

- gateway runs on Linux/VM
- iMessage + `imsg` runs on a Mac in your tailnet
- `cliPath` wrapper uses SSH to run `imsg`
- `remoteHost` enables SCP attachment fetches

Example:

```json5
{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "~/.openclaw/scripts/imsg-ssh",
      remoteHost: "bot@mac-mini.tailnet-1234.ts.net",
      includeAttachments: true,
      dbPath: "/Users/bot/Library/Messages/chat.db",
    },
  },
}
```

```bash
#!/usr/bin/env bash
exec ssh -T bot@mac-mini.tailnet-1234.ts.net imsg "$@"
```

Use SSH keys so both SSH and SCP are non-interactive.
Ensure the host key is trusted first (for example `ssh bot@mac-mini.tailnet-1234.ts.net`) so `known_hosts` is populated.

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.

Media, chunking, and delivery targets

- inbound attachment ingestion is optional: `channels.imessage.includeAttachments` - remote attachment paths can be fetched via SCP when `remoteHost` is set - attachment paths must match allowed roots: - `channels.imessage.attachmentRoots` (local) - `channels.imessage.remoteAttachmentRoots` (remote SCP mode) - default root pattern: `/Users/*/Library/Messages/Attachments` - SCP uses strict host-key checking (`StrictHostKeyChecking=yes`) - outbound media size uses `channels.imessage.mediaMaxMb` (default 16 MB) - text chunk limit: `channels.imessage.textChunkLimit` (default 4000) - chunk mode: `channels.imessage.chunkMode` - `length` (default) - `newline` (paragraph-first splitting) Preferred explicit targets:

- `chat_id:123` (recommended for stable routing)
- `chat_guid:...`
- `chat_identifier:...`

Handle targets are also supported:

- `imessage:+1555...`
- `sms:+1555...`
- `user@example.com`

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

- **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. 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`. 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. 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:

```json5
{
  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.

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, so the same fix applies as it does on the BlueBubbles channel.

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.

```json5 { 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:

```json5
{
  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. The BlueBubbles channel has the same opt-in under `channels.bluebubbles.coalesceSameSenderDms`.

Scenarios and what the agent sees

User composes	chat.db produces	Flag off (default)	Flag on + 2500 ms window
Dump https://example.com (one send)	2 rows ~1 s apart	Two agent turns: "Dump" alone, then URL	One turn: merged text Dump https://example.com
Save this 📎image.jpg caption (attachment + text)	2 rows	Two turns (attachment dropped on merge)	One turn: text + image preserved
/status (standalone command)	1 row	Instant dispatch	Wait up to window, then dispatch
URL pasted alone	1 row	Instant dispatch	Instant dispatch (only one entry in bucket)
Text + URL sent as two deliberate separate messages, minutes apart	2 rows outside window	Two turns	Two turns (window expires between them)
Rapid flood (>10 small DMs inside window)	N rows	N turns	One turn, bounded output (first + latest, text/attachment caps applied)
Two people typing in a group chat	N rows from M senders	M+ turns (one per sender bucket)	M+ turns — group chats are not coalesced

Troubleshooting

Validate the binary and RPC support:

```bash
imsg rpc --help
imsg status --json
openclaw channels status --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.

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
exec ssh -T messages-mac imsg "$@"

Then run:

openclaw channels status --probe --channel imessage

Check:

- `channels.imessage.dmPolicy`
- `channels.imessage.allowFrom`
- pairing approvals (`openclaw pairing list imessage`)

Check:

- `channels.imessage.groupPolicy`
- `channels.imessage.groupAllowFrom`
- `channels.imessage.groups` allowlist behavior
- mention pattern configuration (`agents.list[].groupChat.mentionPatterns`)

Check:

- `channels.imessage.remoteHost`
- `channels.imessage.remoteAttachmentRoots`
- SSH/SCP key auth from the gateway host
- host key exists in `~/.ssh/known_hosts` on the gateway host
- remote path readability on the Mac running Messages

Re-run in an interactive GUI terminal in the same user/session context and approve prompts:

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

Confirm Full Disk Access + Automation are granted for the process context that runs OpenClaw/`imsg`.

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