OpenClaw iMessage Setup Guide 2026: imsg, No BlueBubbles

Do not index

OpenClaw iMessage support runs through imsg, a small open-source CLI bridge that lives on a Mac signed into Messages. The OpenClaw Gateway spawns imsg rpc and talks JSON-RPC over stdio: no separate server, no BlueBubbles, no extra port to manage. You do need a Mac somewhere in the chain, because Apple offers no official iMessage API. The Gateway itself can run anywhere, including an always-on cloud instance like Agent37 that bridges to a Mac at home over SSH. This guide covers the fast local setup, the Private API decision, the cloud-plus-Mac topology, and the failures people actually hit.

A warning before you start searching elsewhere: most tutorials ranking for this topic still teach the BlueBubbles server stack, which OpenClaw removed. If a guide mentions server URLs, ngrok tunnels, or a BlueBubbles password, it describes a setup that no longer exists.

How OpenClaw iMessage actually works in 2026

The current iMessage channel is a native CLI integration. You install the official plugin, point OpenClaw at the imsg binary, and the Gateway launches imsg rpc as a child process. The two exchange small newline-framed JSON-RPC messages over stdin and stdout for the lifetime of the channel. There is no daemon to babysit and no webhook to expose.

On the Mac side, imsg reads the Messages database (chat.db) for inbound messages and sends outbound ones through Messages.app. Inbound recovery is automatic: if the bridge or Gateway restarts, OpenClaw replays the messages it missed and dedupes them, so nothing floods your agent after downtime.

Why bother at all? Because iMessage is where your actual life happens. Our OpenClaw use cases roundup includes people negotiating a car purchase over iMessage and having their agent read out 2FA codes. The blue bubble is the interface your family already uses.

What you need before you start

A Mac signed into Messages. imsg's README asks for macOS 14 or newer. Any Mac works: the M1 Mac mini gathering dust, an old MacBook. It has to stay awake for messages to flow.

Strongly recommended: a dedicated Apple ID for the bot. On your personal ID, the agent sees everything sent to your number, and there are multiple reported issues of bots answering messages meant for the human, or echo-looping on their own outbound texts. A separate identity also contains the blast radius: Apple's spam detection is a black box with no appeals process, and it has flagged automated accounts before. Let the bot risk its own Apple ID, not yours.

Homebrew, to install imsg.

Full Disk Access for the process that runs OpenClaw and imsg. That is how the bridge reads the Messages database.

Automation permission, so imsg can send through Messages.app.

OpenClaw itself, which is free and open source. New to it? Start with our complete hosting guide first.

The 15-minute local setup

Everything on one Mac is the fast path. Four steps.

1. Install and verify imsg:

brew install steipete/tap/imsg
imsg rpc --help

2. Install the OpenClaw iMessage plugin, then restart the Gateway:

openclaw plugins install @openclaw/imessage

3. Point OpenClaw at the bridge in ~/.openclaw/openclaw.json:

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "/opt/homebrew/bin/imsg",
      dbPath: "/Users/you/Library/Messages/chat.db",
    },
  },
}

Run which imsg and use that path: Homebrew installs to /opt/homebrew/bin on Apple Silicon and /usr/local/bin on Intel.

4. Start the Gateway and approve yourself. iMessage DMs default to pairing mode, so the first text from an unknown sender gets a one-time code instead of an answer:

openclaw gateway
openclaw pairing list imessage
openclaw pairing approve imessage <CODE>

Codes expire after an hour, with at most three pending at a time. Once approved, text your Mac and the agent answers in the same thread. Verify the channel any time with openclaw channels status --probe; the iMessage entry should report works.

Basic mode vs Private API mode: the SIP decision

imsg runs in two modes, and this is the one real decision in the whole setup.

Basic mode is what a fresh install gives you: outbound text and media, inbound watch and history, chat list. It needs the macOS permissions above and nothing else. SIP stays fully enabled.

Private API mode is what makes the channel feel native. Running imsg launch injects a helper into Messages.app to call internal IMCore functions, which unlocks tapbacks, threaded replies, edit, unsend, screen effects, native polls, group management, typing indicators, and read receipts.

The catch: injection requires System Integrity Protection to be disabled, and on macOS 11 or later you also have to disable library validation and reboot:

sudo defaults write /Library/Preferences/com.apple.security.libraryvalidation.plist DisableLibraryValidation -bool true

Be honest with yourself about this tradeoff. SIP is one of macOS's core protections, and turning it off adds real attack surface. On Apple Silicon it also disables running iOS apps on that Mac. The pattern OpenClaw's own docs recommend: keep SIP on your daily machine, give the bot a dedicated Mac or a dedicated macOS user, and disable SIP only there. If your threat model says SIP stays on everywhere, run basic mode. Text and media in both directions still work fine.

One current gotcha: on macOS 26 (Tahoe, verified through 26.5.x), csrutil disable alone is not enough. Without the library-validation plist above, imsg launch fails with a timeout waiting for Messages.app. The plist is the fix, not anything more drastic.

Coming from BlueBubbles?

If you set up iMessage on OpenClaw in an earlier era, you ran a BlueBubbles server on the Mac, exposed it with a tunnel, and pasted a URL and password into your config. That stack is gone: OpenClaw removed BlueBubbles support entirely, and any channels.bluebubbles config has to move to channels.imessage.

One migration trap is worth calling out. BlueBubbles keyed group chats by chat GUID, while the imsg registry uses numeric chat_id. Copy your old group entries verbatim and every group message silently drops. Re-key them (run imsg chats --limit 20 to see the IDs), and enjoy the upside: one Homebrew binary instead of a server, a tunnel, and a password to rotate.

This is not just OpenClaw moving on, either. The BlueBubbles project's last stable server release shipped in May 2025, and on macOS 26 users report both its helper injection and its AppleScript fallback breaking. The imsg path is the one that tracks current macOS.

Run the Gateway in the cloud, keep only Messages on the Mac

OpenClaw's docs call this topology "Remote Mac over SSH," and it is what makes iMessage practical for people who want an always-on agent without leaving a laptop awake forever.

The Gateway runs on a Linux box that never sleeps. The Mac's only job is Messages plus imsg. Instead of a local binary path, cliPath points at a transparent SSH wrapper on the Gateway host:

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

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

Three rules keep this stable. Use SSH keys and connect once by hand so the Mac's host key lands in known_hosts: OpenClaw enforces strict host-key checking. Make the Mac reachable from the Gateway host over SSH; a tailnet is the usual answer for a Mac behind home NAT. And keep the wrapper a clean stdio pipe: ssh -T host imsg "$@" is safe, while piping through grep or anything that buffers will starve the JSON-RPC stream and look exactly like an iMessage outage.

Why split it this way? Because your agent is more than one channel. WhatsApp, Telegram, Discord, Slack, scheduled jobs: none of that should die when the Mac sleeps or reboots for an update. Those channels need no Apple hardware, so they run out of the box on a managed Agent37 instance from $3.99/mo, always-on, deployed in one click. iMessage then rides OpenClaw's SSH wrapper pattern to whatever Mac you keep at home, and when that Mac wakes from a nap, the automatic replay delivers what it missed. The Mac stops being a single point of failure for your whole agent and becomes just the iMessage antenna. Already running a home Mac mini? Our OpenClaw Mac mini guide covers that half in depth.

Lock down who can talk to your agent

An agent that answers your texts can be texted by anyone who has your number, so the defaults matter. iMessage DMs use pairing mode out of the box: strangers get a one-time code, not an answer, until you approve them. Prefer an explicit list? Set dmPolicy: "allowlist" and put handles in allowFrom.

Groups default to an allowlist with two gates: groupAllowFrom decides which senders are heard, and the groups registry decides which chats are allowed. A common surprise: adding a chat to groups without any sender allowlist still blocks everyone, so set groupAllowFrom first. And since iMessage has no native mention metadata, mention gating works through regex patterns you configure, so the agent only pipes up in groups when called by name.

The six failures everyone hits (and the fixes)

Sends fail with AppleEvents error -1743 over SSH. Inbound works, probes pass, outbound dies. macOS recorded the Automation permission against the SSH daemon instead of imsg. Fix: run the Gateway or bridge in the logged-in Mac user's session (a LaunchAgent works), grant Full Disk Access and Automation there, and verify one real send through the exact wrapper before trusting it.

`imsg rpc timeout (chats.list)`. Almost always a buffering wrapper, not a dead bridge. Strip pipelines and filters from cliPath; forward bytes as they arrive.

Channel reports healthy, inbound is dead. Status probes can pass while imsg is quietly denied Full Disk Access. If messages stop arriving, re-check the FDA grant for the exact process context running imsg before debugging anything else.

`imsg launch` times out on macOS Tahoe. SIP is off but the library-validation plist is missing. Apply it, reboot, relaunch.

Photos and voice memos never reach the agent. Inbound attachments are off by default. Set includeAttachments: true, or attachment-only messages get dropped, often without even a log line.

Reactions worked yesterday, error today. The injected helper falls out when Messages.app restarts or macOS updates. Run imsg launch again.

When in doubt: openclaw channels status --probe and openclaw logs --follow tell you which gate dropped a message and why.

OpenClaw iMessage FAQ

Does OpenClaw work with iMessage without a Mac?

Not natively. Apple has no public iMessage API and licenses macOS only for Apple hardware, so every self-hosted setup includes a real Mac signed into Messages. The workarounds each cost something: hosted Mac providers rent genuine Apple hardware from about $109/mo, and third-party relay services (around $5/mo) give your agent a separate dedicated iMessage number while putting a stranger's server in the middle of those conversations. For your own number at personal-project prices, it is a spare Mac or nothing.

Can I run it on a Linux VPS?

The Gateway, yes. iMessage still needs a Mac on the other end of the SSH wrapper shown above. Every other major OpenClaw channel (WhatsApp, Telegram, Discord, Slack, Signal) runs without any Apple hardware at all.

How much does this cost?

OpenClaw is free and imsg is free. You pay for model API usage plus something always-on to run the stack: a Mac you already own, a VPS if you enjoy doing your own ops (genuinely the cheaper route if you do), or managed hosting from $3.99/mo if you would rather never think about it.

Is it safe to run?

Pairing mode means strangers cannot use your agent by default, and basic mode requires zero security downgrades. The real tradeoffs are two: Private API mode's SIP requirement, which is why the standard advice is a dedicated bot Mac or bot user, never your daily driver; and Apple itself, which publishes no rate limits and runs spam detection you cannot appeal. Keep the volume personal-scale and put the bot on its own Apple ID.

Do green-bubble (SMS) contacts work?

imsg sends through Messages.app, and sms: targets are supported, so texts your Mac can relay work the same way. Whether a contact goes blue or green follows what Messages itself would do.

Get the always-on half in one click

The Mac is the part Apple makes you keep. The rest of the stack is exactly what Agent37 handles for you: managed OpenClaw from $3.99/mo, always-on, deployed in one click, with a task board, web terminal, and 1,000+ app integrations built in. Spin one up, connect WhatsApp and Telegram today, and bridge your Mac for iMessage when you are ready.

OpenClaw iMessage: The Complete Setup Guide for 2026