Can an OpenClaw Gateway on a Linux VPS offer iMessage, and what does OpenClaw's iMessage channel need from a Mac?
answer
- Apple keeps Messages on Apple hardware
- a child process, not a server
- signed-in Messages user
- cliPath pointing at an SSH wrapper
basics
~20 sYes, but a Mac is still required. OpenClaw's iMessage channel drives the imsg tool on a Mac signed into Messages; a Linux Gateway reaches it by pointing channels.imessage.cliPath at an SSH wrapper that runs imsg on that Mac.
solid answer
~40 sOpenClaw supports iMessage only through `imsg`: the Gateway spawns `imsg rpc` and speaks JSON-RPC over stdio, with no extra server or port. `imsg` must run on a Mac where Messages is signed in, with **Full Disk Access** (to read the Messages database) and **Automation** (to send through Messages.app) granted to the process that runs it. The simplest setup puts the Gateway on that Mac. A Gateway on Linux points `channels.imessage.cliPath` at a wrapper such as `exec ssh -T messages-mac imsg "$@"`, sets `remoteHost`, and needs the Mac's host key in `known_hosts`. Either way, iMessage makes a Mac part of the hosting plan and it has to stay on; the old BlueBubbles bridge was removed in 2026.5.12.
code
json · 10 lines{
"channels": {
"imessage": {
"enabled": true,
"cliPath": "/home/openclaw/.openclaw/scripts/imsg-ssh",
"remoteHost": "bot@messages-mac",
"dbPath": "/Users/bot/Library/Messages/chat.db"
}
}
}go deeper
Remember that iMessage needs a Mac signed into Messages, even when the Gateway runs somewhere else.
Explain imsg as a child process speaking JSON-RPC over stdio, the permissions it needs, and the cliPath SSH wrapper for a Linux Gateway.
Diagnose the remote failure modes: a buffering wrapper, missing known_hosts entries, and Automation granted to the wrong process context.
Weigh whether iMessage is worth adding a Mac to the uptime and identity budget, and whose Apple ID the agent should hold.
## Why iMessage forces a platform Most OpenClaw channels connect to a cloud service: a Telegram bot token, a Slack or Discord app, a WhatsApp linked device. Any host with a network connection can carry them. iMessage is different, because Apple exposes Messages only on Apple devices. OpenClaw's answer is the official `@openclaw/imessage` plugin, which drives a separate command-line tool, **`imsg`**: - The Gateway spawns `imsg rpc` as a child process and exchanges newline-framed **JSON-RPC** messages over its stdin and stdout. - There is no separate daemon, webhook or listening port. - `imsg` reads the Messages database (`chat.db`) and sends through Messages.app, so it must run on a Mac where Messages is signed in. So "where do I host it" has a hard constraint as soon as iMessage is on the list: some Mac has to be on, signed in, and reachable. ## What the Mac has to provide 1. **A signed-in Messages account** in the macOS user that runs `imsg`. 2. **Full Disk Access** for the process context running OpenClaw or `imsg`, so it can read the Messages database. 3. **Automation** permission, so it can send through Messages.app. 4. Optionally, the **private API**: replies, tapbacks, edits, effects, polls and group actions need `imsg launch` and System Integrity Protection disabled. Basic text and media send and receive work without it. Permissions are granted per process context. A headless Gateway started by a LaunchAgent or over SSH needs a one-time interactive `imsg` command in that same context to trigger the prompts. ## The topologies | Topology | Gateway runs on | How iMessage is reached | | --- | --- | --- | | Single Mac | The Messages Mac | Local `imsg`; the simplest setup | | Linux or VPS Gateway | Linux | `channels.imessage.cliPath` set to an SSH wrapper that runs `imsg` on the Mac | | macOS VM | A macOS VM on Apple Silicon, or a hosted Mac | Local `imsg` inside the VM, isolated from your daily Mac | The remote case looks like this on the Gateway host: ```bash #!/usr/bin/env bash exec ssh -T bot@messages-mac imsg "$@" ``` with `cliPath` set to that script's absolute path and `remoteHost` naming the Mac, which OpenClaw also uses to fetch inbound attachments and stage outbound files over SSH and SCP. OpenClaw uses strict host-key checking, so the Mac's key must already be in the Gateway host's `~/.ssh/known_hosts`. ## Traps in the remote setup - **The wrapper must be a transparent pipe.** A wrapper that buffers stdin, or a pipeline through a line-buffered filter, starves the small JSON-RPC frames and looks like an iMessage outage (`imsg rpc timeout`), even though `imsg` is healthy. - **Sends can fail while everything else works.** Over SSH, macOS may record the Automation entry for the SSH server-side process rather than `imsg`, and sends fail with AppleEvents error `-1743` while reads and `openclaw channels status --probe` pass. The documented fix is to run the Gateway, or at least the `imsg` bridge, in the logged-in Messages user's own session, for example under a LaunchAgent for that user. - **The Mac is still a host.** Moving the Gateway to a VPS does not remove the Mac from the uptime budget; if it sleeps, iMessage stops while other channels keep working. ## Checking the setup - `openclaw channels status --probe` (or `--probe --channel imessage`) asks the running channel to answer. If the probe reports RPC unsupported, update `imsg`. - If a headless Gateway never triggered the macOS prompts, run a one-time interactive command such as `imsg chats --limit 1` in the same user context that runs the Gateway or the wrapper. - If the Gateway is not on macOS at all, the default local `imsg` path cannot work; use the remote-Mac wrapper instead. Because the Mac now carries a channel, give it the same care as any always-on host: keep it on mains power, turn sleep off, and for a headless macOS VM enable automatic login so the Messages user session exists after a reboot. ## Identity, and some history The deployment docs recommend a dedicated Apple ID in a dedicated macOS user, so bot traffic stays out of your personal Messages profile; an agent running `imsg` in your own user can read all of your conversations. Older guides describe a BlueBubbles server; OpenClaw removed that channel in 2026.5.12, and `channels.bluebubbles` configs migrate to `channels.imessage`. For hosting, the result is simple: no iMessage, any host works; iMessage, either the Gateway lives on a Mac or a Mac stays on beside it.
- Why would you give the bot its own Apple ID and macOS user?Whatever account `imsg` runs as, the agent can read that account's whole Messages history and send as it. A dedicated Apple ID in a dedicated macOS user keeps bot traffic and its permissions separate from your personal conversations; the deployment docs describe that pattern, with an SSH wrapper so the Gateway runs `imsg` in the bot user's context.
- Which iMessage features keep working if you leave SIP enabled?Basic text and media send and receive, history and attachments work through the normal `imsg` surfaces. Threaded replies, tapbacks, edit and unsend, effects, polls and group management need the private API, which requires `imsg launch` with System Integrity Protection disabled.
- Installing imsg on the Linux VPS is enough to get iMessage.
- iMessage works through the BlueBubbles server in current OpenClaw.
- Disabling SIP is required for any iMessage send and receive.
- Once the Gateway is on a VPS, the Mac can sleep without affecting iMessage.
- If the status probe passes, outbound iMessage sends will work too.