iMessage

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 an 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:

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

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

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.

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.

Set channels.imessage.dmHistoryLimit to seed new direct-message sessions with recent decoded imsg history for that conversation. Use channels.imessage.dms["<sender>"].historyLimit for per-sender overrides, including 0 to disable history for a sender.

iMessage DM history is fetched on demand from imsg. Leaving dmHistoryLimit unset disables global DM history seeding, but a positive per-sender channels.imessage.dms["<sender>"].historyLimit still enables seeding for that sender.

• 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
• attachment paths must match allowed roots:
  • channels.imessage.attachmentRoots (local)
  • channels.imessage.remoteAttachmentRoots (remote SCP mode)
  • configured roots extend the default root pattern /Users/*/Library/Messages/Attachments (merged, not replaced)
• 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.streaming.chunkMode
  • length (default)
  • newline (paragraph-first splitting)
• outbound markdown bold/italic/underline/strikethrough is converted to native styled text (macOS 15+ recipients render the styling; older recipients see plain text without the markers); markdown tables are converted per the channel markdown table mode
• channels.imessage.sendTransport (auto default, bridge, applescript) selects how imsg delivers sends

Preferred explicit targets:

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

Handle targets are also supported:

• imessage:+1555...
• sms:+1555...
• [email protected]

imsg chats --limit 20

• react: Add/remove iMessage tapbacks (messageId, emoji, remove). Supported tapbacks map to love, like, dislike, laugh, emphasize, and question. Removing without an emoji clears whichever tapback was set.
• reply: Send a threaded reply to an existing message (messageId, text or message, plus chatGuid, chatId, chatIdentifier, or to). Reply-with-attachment additionally needs an imsg build whose send-rich supports --file.
• sendWithEffect: Send text with an iMessage effect (text or message, effect or effectId). Short names: slam, loud, gentle, invisibleink, confetti, lasers, fireworks, balloon, heart, echo, happybirthday, shootingstar, sparkles, spotlight.
• edit: Edit a sent message on supported macOS/private API versions (messageId, text or newText). Only messages the gateway itself sent can be edited.
• unsend: Retract a sent message on supported macOS/private API versions (messageId). Only messages the gateway itself sent can be unsent.
• 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. These mutate the host's Messages identity, so they require an owner sender or an operator.admin Gateway client.
• poll: Create a native Apple Messages poll (pollQuestion, pollOption repeated 2 to 12 times, plus chatGuid, chatId, chatIdentifier, or to). Recipients on iOS/iPadOS/macOS 26+ see and vote on it natively; older OS versions get a "Sent a poll" text fallback. Requires selectors.pollPayloadMessage.
• poll-vote: Vote on an existing poll (pollId or messageId, plus exactly one of pollOptionIndex, pollOptionId, or pollOptionText). Requires selectors.pollVoteMessage and the poll.vote RPC method.

Accepted inbound polls are rendered for the agent with the question, numbered option labels, vote counts, and the poll message ID needed by poll-vote.

Inbound iMessage context includes both short MessageSid values and full message GUIDs (MessageSidFull) when available. Short IDs are scoped to the recent SQLite-backed reply cache and are checked against the current chat before use. If a short ID expires, retry with its MessageSidFull while targeting the conversation that supplied it. Full IDs do not bypass conversation or account binding, so replace an ID from another chat with one from the current target. Remote delegated calls can reject stale full IDs when current-conversation evidence is unavailable.

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 and direct chats show a typing bubble as soon as the turn is accepted, while the agent prepares context and generates. Disable read-marking with:

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

Older imsg builds that pre-date the per-method capability list gate off typing/read silently; OpenClaw logs a one-time warning per restart so the missing receipt is attributable.

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.<id>.reactionNotifications.

When approvals.exec.enabled or approvals.plugin.enabled is true and the request routes natively to iMessage, the gateway delivers an approval prompt with native controls:

• On a probed private API bridge with poll and caption-suppression support, the prompt includes a Messages poll with each allowed decision. Older imsg releases without poll send --no-comment stay on text controls.
• If polls are disabled with channels.imessage.actions.polls: false, the bridge lacks poll support, the poll send fails, or fewer than two decisions are available, the prompt keeps the text and tapback controls.
• The text fallback maps 👍 (Like) to allow-once and 👎 (Dislike) to deny. It also includes /approve <id> <decision> commands, including allow-always when the request permits it.

Poll votes and reactions require the acting user's handle to be an explicit approver. The approver list is read from channels.imessage.allowFrom (or channels.imessage.accounts.<id>.allowFrom); add the user's phone number in E.164 form or their Apple ID email (chat targets such as chat_id:* are not valid approver entries). The wildcard entry "*" is honored but allows any sender to approve; an empty approver list disables poll and reaction shortcuts entirely. These shortcuts intentionally bypass reactionNotifications, dmPolicy, and groupAllowFrom because the explicit-approver allowlist is the only gate that matters for approval resolution.

Native poll controls are currently limited to channel-native delivery in the originating iMessage session or an iMessage approver DM. Explicit forwarding targets selected by approvals.exec.mode: "targets" (and the target half of "both") continue to use the existing forwarded approval message instead of an iMessage poll.

/approve text command authorization follows the same list: when channels.imessage.allowFrom is non-empty, /approve <id> <decision> is authorized against that approver list (not the broader DM allowlist), and senders permitted on the DM allowlist but not in allowFrom receive an explicit denial. When allowFrom is empty, the same-chat fallback stays in effect and /approve authorizes anyone the DM allowlist permits. Add every operator who should approve — via /approve or via reactions — to allowFrom.

Operator notes:

• Poll and reaction bindings are stored both in memory and in the gateway's persistent keyed store (TTL matched to the approval expiry), and the gateway also polls pending prompts for tapbacks. After a gateway restart, a tap on an old control is recognized and swallowed instead of entering agent chat, but the restart ends the in-flight command; request a new approval rather than expecting the old control to resume it.
• The operator's own is_from_me=true tapback (for example from a paired Apple device) resolves the approval when that handle is an explicit approver.
• Approval prompts route into a group conversation only when explicit approvers are configured; otherwise any group member could approve.
• Legacy text-style tapbacks (Liked "…" plain text from very old Apple clients) cannot resolve approvals because they carry no message GUID; reaction resolution requires the structured tapback metadata that current macOS / iOS clients emit.

For an ask_user prompt with one non-secret, single-select question and one to four options, OpenClaw adds numbered emoji choices. React to the delivered prompt with the matching number to answer it. The reaction must carry the stable GUID of the bot-authored message; OpenClaw then maps the number to the canonical option through the Gateway. Stale or duplicate taps are ignored.

Multi-question, multi-select, and free-text prompts remain text-reply-only. Question reactions follow normal iMessage DM/group admission rules. They are recognized even when general reactionNotifications is "off", without turning unrelated reactions into agent events.

Validate the binary and RPC support:

imsg rpc --helpimsg status --jsonopenclaw channels status --probe

If the 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.

First prove whether the message reached the local Mac. If chat.db does not change, OpenClaw cannot receive the message even when imsg status --json reports a healthy bridge.

imsg chats --limit 10 --jsonimsg watch --chat-id <chat-id> --jsonsqlite3 ~/Library/Messages/chat.db \"select datetime(max(date)/1000000000 + 978307200, 'unixepoch', 'localtime'), max(ROWID) from message;"

If phone-sent messages create no new rows, repair the macOS Messages and Apple Push layer before changing OpenClaw config. A one-shot service refresh is often enough:

launchctl kickstart -k system/com.apple.apsdlaunchctl kickstart -k gui/$(id -u)/com.apple.CommCenterlaunchctl kickstart -k gui/$(id -u)/com.apple.identityservicesdlaunchctl kickstart -k gui/$(id -u)/com.apple.imagentimsg launchopenclaw gateway restart

Send a fresh iMessage from the phone and confirm a new chat.db row or imsg watch event before debugging OpenClaw sessions. Do not run this as a periodic bridge-relaunch loop; repeated imsg launch plus gateway restarts during active work can interrupt deliveries and strand in-flight channel runs.

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 bashexec 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.entries.*.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:

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

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