OpenClaw iMessage media and attachments

Attachments on iMessage cross a machine boundary that other channels never see: the file lives on the Messages Mac, and the Gateway may not. OpenClaw’s media rules are written around that boundary, plus the two things every send needs, chunking for long text and an unambiguous target. Here are the attachment rules, the text rules, and the addressing formats.

Attachments

• Inbound attachment ingestion is off by default; the include-attachments setting forwards photos, voice memos, video and other attachments to the agent, and with it off an attachment-only iMessage is dropped before the agent and may produce no inbound log line at all.
• Remote inbound attachment paths are fetched over SCP when the remote host is set, and outbound files are staged into an owner-only temporary path on the configured or auto-detected Messages Mac, passed to imsg by that remote path, and cleaned up best-effort after success, failure or timeout, with a warning and possible owner-only residue when cleanup fails.
• Attachment paths must match allowed roots, local roots for the local case and remote roots for SCP mode, and configured roots extend rather than replace the default pattern under the Messages attachments directory of any user; SCP uses strict host-key checking, and outbound media size is bounded by the media cap, sixteen megabytes by default.
• Outbound text is chunked at four thousand characters by default, in length mode or a newline mode that splits paragraph-first; markdown bold, italic, underline and strikethrough convert to native styled text that recent macOS recipients render and older ones see as plain text, markdown tables follow the channel’s table mode, and a send-transport setting of auto, bridge or AppleScript selects how imsg delivers.

Bare contact names and mixed alphanumeric aliases are rejected instead of being converted to a phone number.

Addressing

The preferred explicit targets are a chat id, recommended for stable routing, a chat GUID or a chat identifier. Direct handles also work, a phone number bare or with a telephone, iMessage or SMS prefix, or an email address. A contact name or a mixed alphanumeric alias needs a service-qualified target: an auto prefix lets Messages choose iMessage or SMS, an iMessage prefix requires iMessage, and an SMS prefix requires SMS. Bare names are rejected rather than converted, so an existing automation that used one gains a prefix to make the intended service explicit; the chats command lists the ids to use.

Three habits

• Turn on attachment ingestion deliberately, because the failure mode is silence: a photo that never appears and no log line to explain it.
• Address by chat id wherever a target is stored, in cron jobs, bindings and allowlists, since handles can resolve differently over time and names never resolve at all.
• Keep the roots narrow: the default Messages attachments pattern is already broad, and every extra root is another directory the Gateway may read or write on the Mac.

OpenClaw on iMessage is the channel post these rules belong to, and OpenClaw iMessage deployment patterns the patterns that decide whether the remote-host fields apply.

Chunking elsewhere

The chunk limit and modes here are the iMessage instance of the shared outbound text pipeline, which every channel tunes to its own message length. OpenClaw streaming and chunking covers that pipeline, and Connect your first channel in five minutes the channels Diali links today.

On Diali

iMessage is not among the channels Diali connects today: WhatsApp, Telegram, Discord, Slack, Mattermost, Matrix, SMS and voice. Hosted OpenClaw on Diali is the assistant and Diali security describes the boundary that applies to each connected channel.

• Attachments are off until you say otherwise.
• Owner-only staging, strict host keys, sixteen megabytes.
• Chat ids first; bare names never.