What you need for OpenClaw iMessage
iMessage only runs on Apple hardware. There's no way to use it from Windows or Linux alone.
The Mac must be signed in to Messages with the Apple Account OpenClaw will use.
imsg toolOpenClaw talks to Messages through imsg, installed with Homebrew. BlueBubbles is no longer supported.
Full Disk Access to read the Messages database, and Automation to send through Messages.
Replies and reminders only work while the Mac is awake. A Mac mini is ideal.
Keeps the assistant separate from your personal messages. Strongly advised if you use private API mode.
Which iMessage setup fits you?
Two ways to run OpenClaw with iMessage
Gateway on the Mac
OpenClaw runs on the same Mac that's signed in to Messages. Everything is local, and setup takes about 15 minutes.
- Fewest moving parts
- Perfect for a home Mac mini
- The Mac must stay awake
Gateway elsewhere, Mac as relay
OpenClaw runs on a VPS or another computer and reaches imsg on your Mac over SSH, using a small wrapper script.
- Keep your main gateway on a server
- The Mac only handles Messages
- Needs SSH keys set up between them
Basic mode vs private API mode
Basic mode works with Apple's normal security left on. Private API mode injects a helper into Messages for the full experience, but it means turning off System Integrity Protection (SIP).
| Feature | Basic | Private API |
|---|---|---|
| Send and receive text | Yes | Yes |
| Attachments | Yes | Yes |
| Tapbacks (♥, 👍…) | No | Yes |
| Threaded replies | No | Yes |
| Message effects | No | Yes |
| Native polls | No | Yes |
| Typing indicators and read receipts | No | Yes |
| Group management actions | No | Yes |
| SIP must be off | No | Yes |
SIP is a core macOS protection. With it off, malware has more room to do damage, and on Apple silicon Macs you also lose the ability to run iOS apps. The official docs recommend a dedicated Mac for private API mode, not your main computer.
Prepare the Mac
- Sign in to Messages with the Apple Account OpenClaw will use. A separate Apple Account gives your assistant its own number or email.
- Install OpenClaw on this Mac if the gateway will run here. See the Mac install guide.
- Stop it sleeping in System Settings › Energy if you want replies around the clock.
Install the imsg tool
When you choose iMessage in openclaw onboard, setup can offer to install or update imsg with Homebrew for you. To do it yourself:
brew install imsgInstall it as the same macOS user that runs the OpenClaw gateway. OpenClaw starts imsg rpc itself, so there's no separate service to run.
Grant the macOS permissions
Open System Settings › Privacy & Security and grant both to the app that runs the gateway: the OpenClaw app, Terminal, or your SSH process.
Configure the iMessage channel
iMessage config builder
Add the phone numbers (with +country code) and Apple Account emails allowed to message your assistant.
dmPolicy | What it does |
|---|---|
| pairing default | New senders get a code to approve |
| allowlist | Only handles in allowFrom |
| open | Anyone (needs allowFrom: ["*"]). Not recommended. |
| disabled | No direct messages |
Restart, test and approve
openclaw gateway restart
openclaw channels status --probeFrom your iPhone, send a message to the Apple Account signed in on the Mac. With pairing on, approve it:
openclaw pairing list imessage
openclaw pairing approve imessage <CODE>If the Mac or gateway restarts, OpenClaw replays missed messages automatically, skips stale backlog from Apple's push recovery and avoids handling anything twice.
Enable private API mode
Only if you want tapbacks, threaded replies, effects, polls and typing indicators, and you're using a dedicated Mac.
- Update
imsgwith Homebrew. - Turn off SIP from macOS Recovery. The steps differ by Mac and macOS version, from Sierra through Tahoe.
- Turn off Library Validation (macOS 11 and later) with the Terminal command in the official guide.
- Inject the helper: run
imsg launch. - Verify:
imsg status --jsonoropenclaw channels status --probe.
Follow the exact Recovery steps for your Mac in the official private API guide. The helper can stop working after Messages restarts or a macOS update. If rich actions stop, run imsg launch again.
Use iMessage with a gateway on another machine
Run OpenClaw on a VPS and let your Mac handle Messages. Set up SSH key login from the server to the Mac, then create a wrapper that runs imsg on the Mac:
#!/bin/bash
ssh user@mac-host imsg "$@"chmod +x ~/bin/imsg-wrapperPoint cliPath at the wrapper (enter its full path in the builder above). On the Mac, grant Full Disk Access and Automation to the SSH process that runs imsg.
OpenClaw in iMessage group chats
groupPolicyisallowlistby default. The other options areopenanddisabled.- Two checks apply: the sender must be in
groupAllowFrom, then the group must match yourgroupssettings. IfgroupAllowFromis empty, all group messages are dropped. groupsuses each chat's numericchat_idas the key, or"*"for all.- Per-group options include
requireMentionand a customsystemPrompt, for example a different personality for a family group.
Fix common iMessage problems
Doesn't see new messagesGrant Full Disk Access to the process running the gateway, then restart it.
Can read but can't sendGrant Automation permission for Messages. Check Messages is still signed in.
imsg: command not foundInstall imsg as the same user as the gateway, or set cliPath to its full path.
Tapbacks or polls stopped workingThe private API helper fell out after a restart or update. Run imsg launch again.
Group messages ignoredAdd senders to groupAllowFrom. When it's empty, every group message is dropped.
No replies overnightThe Mac went to sleep. Turn off automatic sleep in Energy settings.
More fixes: troubleshooting guide.
OpenClaw iMessage questions
Can I use OpenClaw with iMessage without a Mac?
No. iMessage requires a Mac signed in to Messages. Your gateway can run on another machine, but it must reach imsg on a Mac over SSH.
What does OpenClaw need to use iMessage?
A Mac signed in to Messages, the imsg command-line tool, and Full Disk Access and Automation permissions for the process running the gateway.
Do I have to disable SIP for OpenClaw iMessage?
Only for private API mode, which adds tapbacks, threaded replies, effects, polls, typing indicators and read receipts. Basic texting and attachments work with SIP on.
Is it safe to disable SIP?
It's a real security trade-off. It weakens macOS protections and, on Apple silicon, stops iOS apps from running. Use a dedicated Mac rather than your main computer if you need private API features.
Does OpenClaw still support BlueBubbles?
No. BlueBubbles support was removed. OpenClaw now supports iMessage through imsg only, and old channels.bluebubbles settings should move to channels.imessage.
Can I use iMessage with OpenClaw on a VPS?
Yes, with a Mac as the Messages host. Create an SSH wrapper script that runs imsg on the Mac and set it as cliPath in your OpenClaw config.