On this page
💙 Why iMessage?
| Advantage | Details |
|---|---|
| Native experience | Messages appear in your regular iMessage threads — blue bubbles, typing indicators, read receipts. |
| Apple ecosystem | Pairs naturally with Apple Notes, Apple Reminders, and Calendar skills. |
| No extra app | If you're deep in Apple ecosystem, your AI lives where your texts already are. |
| Dedicated Apple account option | Create a separate Apple ID for your bot so it has its own contact card and iMessage address. |
⚠️ Important: iMessage requires macOS. OpenClaw must run on a Mac (or have access to a Mac running BlueBubbles). This channel does not work on Linux VPS or Docker containers without a Mac somewhere in the chain.
🔀 Two paths
| Native iMessage (legacy) | BlueBubbles | |
|---|---|---|
| How | OpenClaw reads Messages.app DB directly | Runs a server on Mac, OpenClaw connects via API |
| Requires | OpenClaw running on same Mac | Mac running BlueBubbles + OpenClaw anywhere |
| Remote access | ❌ Must be on the Mac | ✅ Connect from VPS, Docker, etc. |
| Reliability | ⚠️ Legacy, less maintained | ✅ Actively maintained, better webhook support |
| Setup | Easier (just permissions) | More steps (install BlueBubbles server) |
✅ Recommendation: Use BlueBubbles if your OpenClaw runs on a VPS or separate machine. Use Native if OpenClaw runs on the same Mac where you have Messages.
🖥️ Path A: Native iMessage (legacy)
Prerequisites
- macOS with Messages.app signed into iMessage
- OpenClaw running on the same Mac
- Full Disk Access granted to OpenClaw (or Terminal)
Grant permissions
# OpenClaw needs access to the Messages database
# System Settings → Privacy & Security → Full Disk Access
# Add Terminal (or your terminal app) and grant access
# Verify access:
ls ~/Library/Messages/chat.db
# Should not return "Operation not permitted"
Configure
// ~/.openclaw/openclaw.json
{
"channels": {
"imessage": {
"enabled": true,
"dmPolicy": "allowlist",
"allowFrom": ["+40712345678"]
}
}
}
💡 Signed builds matter: macOS permissions stick across rebuilds only for signed applications. See
docs/mac/permissions.md in the OpenClaw repo for details.🫧 Path B: BlueBubbles (recommended)
What is BlueBubbles?
BlueBubbles is an open-source server that runs on your Mac and exposes iMessage via HTTP API + webhooks. OpenClaw connects to it like any other channel — the Mac acts as an iMessage relay.
Step 1: Install BlueBubbles on your Mac
# Download from https://bluebubbles.app
# Install and run BlueBubbles Server
# Sign in with your Apple ID
# Note the server URL and password
Step 2: Configure OpenClaw
// ~/.openclaw/openclaw.json
{
"channels": {
"bluebubbles": {
"enabled": true,
"dmPolicy": "allowlist",
"allowFrom": ["+40712345678"]
}
}
}
BlueBubbles handles outbound message-id fallback recovery by matching on chat identifier and account context, which makes it reliable for tracking conversation state.
Dedicated bot Apple account (power move)
Some users create a separate Apple ID for their bot:
- The bot gets its own iMessage address and contact card
- Friends and family can text the bot directly
- Your personal iMessage stays separate
✅ From the community: “Got a Mac Mini for OpenClaw. Instead of access to my accounts, I gave it: its own Apple account for messages, its own Gmail to sign up for stuff, its own GitHub to push code.” — OpenClaw Showcase
⚙️ Configuration
DM policies (same as all channels)
| Policy | Best for |
|---|---|
allowlist | Personal use — only your phone number can chat |
pairing | Family setup — approve new contacts as they message |
open | ⚠️ Anyone with the number can chat (not recommended) |
Heartbeat delivery
{
"agents": {
"defaults": {
"heartbeat": {
"target": "imessage"
}
}
}
}
🍏 Apple ecosystem integration
iMessage pairs beautifully with macOS-only OpenClaw skills:
| Skill | What it does |
|---|---|
apple-notes | Read and write Apple Notes — create notes, search, append content |
apple-reminders | Create/complete/list reminders across all your lists |
apple-calendar | Check events, create meetings, manage your schedule |
apple-shortcuts | Trigger Apple Shortcuts automations from chat |
💡 The Jarvis dream: “Hey, add milk to my shopping list” via iMessage → creates an Apple Reminder in your Groceries list → syncs to your iPhone instantly. All through the Messages app.
✨ Supported features
| Feature | Native | BlueBubbles |
|---|---|---|
| Text messages | ✅ | ✅ |
| Images / photos | ✅ | ✅ |
| Files / attachments | ✅ | ✅ |
| Group chats | ⚠️ Limited | ✅ |
| Tapbacks / reactions | ⚠️ Read only | ✅ |
| Typing indicators | ❌ | ✅ |
| Read receipts | ❌ | ✅ |
| Voice notes | ⚠️ Receive only | ⚠️ Receive only |
| Remote access (VPS) | ❌ | ✅ |
| Slash commands | ✅ | ✅ |
🔧 Troubleshooting
| Problem | Fix |
|---|---|
| “Operation not permitted” | Grant Full Disk Access to Terminal / OpenClaw in System Settings → Privacy & Security. |
| Messages not detected | Ensure Messages.app is signed in and iMessage is active on this Mac. |
| BlueBubbles disconnects | Check the Mac running BlueBubbles hasn't gone to sleep. Disable Energy Saver sleep settings. |
| Outbound messages fail | BlueBubbles: check server URL is accessible from OpenClaw. Native: check AppleScript permissions. |
| Duplicate messages | If running both native and BlueBubbles, disable one. Only one iMessage channel should be active. |
| Can't use on Linux/Docker | iMessage requires macOS. Use BlueBubbles on a Mac Mini as a relay, then connect OpenClaw on your VPS to it. |
💡 The Mac Mini relay: Many users buy a Mac Mini M4 specifically to run OpenClaw + BlueBubbles. It acts as a 24/7 always-on iMessage bridge while OpenClaw handles the AI logic. The Mac Mini consumes ~5W idle — cheaper than a light bulb.