OpenClaw and iMessage: what it really takes

Why iMessage is the special-case channel

Telegram, Discord, and Slack hand out bot APIs; Apple doesn’t. The only sanctioned way to send an iMessage is through Messages.app on real Apple hardware, so OpenClaw’s iMessage channel works by driving a signed-in Mac via the imsg tool (published, fittingly, by OpenClaw’s own creator). That one fact drives every requirement on this page, and it’s why the Mac Mini is the pet hardware of this corner of the agent community: if iMessage is a must-have, a Mac has to be in the loop. And it means a real Mac: OpenClaw’s creator says plainly that iMessage is unreliable in virtual machines (the project itself tests the channel on physical Apple hardware driven over a remote KVM), so a macOS virtual machine, including the cheap rented kind, is shaky ground for it. A Mac mini rented in a data center is real Apple hardware, with catches of its own, Apple’s terms for leasing a Mac among them. (Historical note: older guides mention BlueBubbles. That integration was removed, and imsg is the only supported path now.)

The setup, in two stages

• Stage 1, plain texting (no scary steps): install imsg via Homebrew, sign the Mac into Messages, grant the process Full Disk Access (to read the Messages database) and Automation permission (to send). Enable the channel:

  {
    channels: {
      imessage: {
        enabled: true,
        dmPolicy: "pairing",
      },
    },
  }

  Copied
  Sending and receiving text and media now works, with OpenClaw’s usual pairing approval for unknown senders.
• Stage 2, the private-API extras: tapbacks, threaded replies, message edit/unsend, effects, native polls, read receipts, and group management require imsg launch injecting a helper into Messages.app, which requires System Integrity Protection disabled. SIP is one of macOS’s core protections; turning it off system-wide adds attack surface (and on Apple Silicon also disables running iOS apps). Skip stage 2 unless a specific feature matters to you, and if you do it, dedicate the Mac to the agent rather than your daily driver.

The details that save you debugging time

• Gateway elsewhere, Mac as bridge: the gateway doesn’t have to run on the Mac. cliPath can point at an SSH wrapper reaching the Mac. The wrapper must be a transparent stdio pipe (no buffering), and remote attachments require remoteHost with strict SSH host-key checking.
• Restarts are graceful: after downtime, the channel replays missed messages and dedupes the “backlog bomb” Apple can flush after a push recovery. Nothing dispatches twice, no config needed.
• Defaults worth knowing: outbound text chunks at 4,000 characters, media capped at 16 MB, DMs share the agent’s main session while each group chat is isolated.

Should you use it?

If your household runs on blue bubbles, an agent that lives there too is delightful, and stage 1 is a reasonable afternoon. If you just want the easiest path to chatting with your agent from your phone, Telegram or Signal delivers the same conversation without dedicating Apple hardware to it, and works identically wherever your agent lives, laptop, VPS, or managed pod.