How to Add iMessage to OpenClaw on macOS

The iMessage integration for OpenClaw is the most technically demanding of the four supported channels — but it unlocks something no other channel can offer: a fully private, end-to-end encrypted AI assistant accessible via Apple’s native messaging platform. If you use iMessage as your primary messaging app on iPhone and Mac, this guide explains exactly what’s involved and how to set it up.

Important Caveats Upfront

Before walking through the steps, there are three things you need to understand:

1. This requires a Mac running 24/7. iMessage is tied to Apple’s ecosystem and cannot run on a Linux VPS. You need a macOS node — either a dedicated Mac mini server or a Mac that stays powered on continuously.
2. OpenClaw’s iMessage integration runs as a macOS process. It uses the local Messages app framework via Apple’s Push Notification Service (APNs) and cannot be deployed on a remote Linux server the way Telegram or Discord can.
3. Apple does not offer a public iMessage Business API. This integration uses an unofficial but widely used macOS automation layer — it works reliably, but Apple can change the underlying Messages API at any time.

What You Need

• A Mac (Mac mini M2 or M4 is the recommended choice for a dedicated server)
• macOS Sonoma or later
• An Apple ID registered to the iMessage account you want to connect
• Node.js 24 installed on the Mac via nodejs.org or brew install node@24
• OpenClaw cloned on the Mac and running locally

Step 1: Install OpenClaw on the Mac Node

On your Mac, clone and install OpenClaw exactly as you would on a VPS:

git clone https://github.com/openclaw/openclaw.git ~/openclaw
cd ~/openclaw
npm install

Run the onboarding wizard:

npm run onboard

During onboarding, when prompted for channels, select iMessage. The wizard will guide you through the Apple ID sign-in step.

Step 2: Sign In to iMessage on the Mac

OpenClaw’s iMessage integration relies on the macOS Messages app being signed in to the Apple ID associated with the iMessage address you want your AI to use. This should be a dedicated Apple ID, separate from your personal one — keeping it separate avoids your personal messages being processed by OpenClaw.

Open Messages.app on the Mac, go to Messages → Settings → iMessage, and sign in with the dedicated Apple ID. Enable iMessage for this account.

Step 3: Configure Apple Push Notification Access

OpenClaw iMessage integration communicates via a local socket that interfaces with the macOS Messages framework. It requires the following macOS permissions:

• Full Disk Access for the OpenClaw node process — grant this in System Settings → Privacy & Security → Full Disk Access
• Accessibility Access — required for certain automation hooks — grant in System Settings → Privacy & Security → Accessibility

If you are running macOS on a headless Mac mini (common for server setups), you may need to connect a display or use a HDMI dummy plug to allow the GUI to initialise properly on first boot.

Step 4: Configure the iMessage Channel in OpenClaw

Edit config/openclaw.yaml on the Mac:

channels:
  imessage:
    enabled: true
    apple_id: "[email protected]"
    allowed_senders:
      - "+15551234567"
      - "[email protected]"

The allowed_senders list restricts which phone numbers or Apple IDs can invoke your AI assistant. This is strongly recommended — without it, anyone who knows your Apple ID’s iMessage address can interact with your AI.

Step 5: Keep OpenClaw Running with PM2 on macOS

Install PM2 on the Mac:

npm install -g pm2
cd ~/openclaw
pm2 start npm --name "openclaw" -- start
pm2 startup  # follow the printed launchctl command
pm2 save

On macOS, PM2 uses launchctl (instead of systemd on Linux) to register the startup task. Follow the exact command it prints.

Step 6: Prevent Sleep

A Mac that goes to sleep stops running OpenClaw. Disable sleep on your server Mac:

sudo pmset -a sleep 0
sudo pmset -a disksleep 0
sudo pmset -a displaysleep 0

For a Mac mini used as a dedicated server, also disable Power Nap in System Settings → Battery/Energy Saver.

Step 7: Test the Integration

Send an iMessage to the Apple ID you configured. Your OpenClaw macOS AI assistant should respond within a few seconds. If it doesn’t:

• Check pm2 logs openclaw for errors
• Confirm Messages.app is open and signed in
• Verify Full Disk Access and Accessibility permissions are granted
• Check that the sender’s number/ID is in the allowed_senders list

Is iMessage Worth the Complexity?

For users who live in the Apple ecosystem, absolutely. The privacy properties of iMessage (end-to-end encrypted, no third-party servers involved in the message transport) combined with a self-hosted AI make this the most private configuration possible.

That said, maintaining a 24/7 macOS node is non-trivial. You need to handle macOS updates (which can break permissions), Apple ID token refreshes, and hardware-level uptime.

If you want iMessage integration without managing the macOS infrastructure yourself, our managed installation service includes Mac node setup and ongoing maintenance. Get in touch to discuss your setup.