OpenClaw iMessage Setup: Complete 2026 Guide (Any Platform)

Does OpenClaw require a Mac for iMessage?

Technically, iMessage itself requires Apple hardware. Messages live in a local SQLite database (chat.db) that only macOS can read. There is no official Apple API. OpenClaw's native imsg CLI reads from that database directly — so yes, the native integration requires a Mac.

But that is not the whole picture. There are two paths to iMessage on OpenClaw:

1. Self-hosted (Mac required): Run the imsg CLI or BlueBubbles on a Mac you own or rent. Full control, no subscription fee, but significant setup and maintenance overhead.
2. Managed API (no Mac required): Use the Claw Messenger plugin. Your agent connects via WebSocket and we handle the Apple infrastructure. Works on any OS, any VPS.

This guide covers both paths, organized by the platform your OpenClaw agent runs on. Skip to your platform below.

Setup on Linux / VPS

This is the most common OpenClaw setup — a DigitalOcean droplet, Hetzner VPS, or similar. iMessage does not run natively here. The only options are a remote Mac bridge (complex) or the Claw Messenger plugin (5 minutes).

Option A: Claw Messenger plugin (recommended)

Step 1. Install the plugin:

openclaw plugins install @emotion-machine/claw-messenger

Step 2. Get your API key from the Claw Messenger dashboard. Free trial included.

Step 3. Add the channel block to your config:

// ~/.openclaw/openclaw.json
{
  "channels": {
    "claw-messenger": {
      "enabled": true,
      "apiKey": "cm_live_xxxxxxxxxxxxxxxx",
      "serverUrl": "wss://claw-messenger.onrender.com"
    }
  }
}

Step 4. Restart the gateway:

openclaw gateway restart

Step 5. Send a test iMessage to your Claw Messenger number. Your agent should respond within a second.

Option B: Remote Mac bridge (advanced)

If you already own a Mac and want to use your own Apple ID rather than a dedicated number, you can bridge your VPS to the Mac over Tailscale. This means two machines to maintain and all the Mac-side setup described in the Mac section below. See the full VPS setup guide for the Tailscale approach.

Setup on Windows

OpenClaw runs on Windows via Node.js (WSL is not required). iMessage has no Windows path through native Apple tools — you need the Claw Messenger plugin.

Step 1. Verify OpenClaw is installed (PowerShell or CMD):

openclaw --version

Step 2. Install the plugin:

openclaw plugins install @emotion-machine/claw-messenger

Step 3. The config file is at %USERPROFILE%\.openclaw\openclaw.json on Windows. Open it and add the channel block:

{
  "channels": {
    "claw-messenger": {
      "enabled": true,
      "apiKey": "cm_live_xxxxxxxxxxxxxxxx",
      "serverUrl": "wss://claw-messenger.onrender.com"
    }
  }
}

Step 4. Restart the gateway:

openclaw gateway restart

That is the entire Windows iMessage setup. No WSL, no virtual machines, no Apple hardware.

Setup on Mac (native imsg CLI)

If you are running OpenClaw on a Mac and want to use iMessage through your Apple ID directly, this is the path. Plan for 1-3 hours of setup and occasional maintenance after macOS updates.

Requirements

• macOS Sequoia (15) or later recommended
• Apple ID signed into Messages.app
• HDMI dummy plug (~$10) if running headless
• OpenClaw 1.x or later

Step-by-step

Step 1. Install OpenClaw if you have not already:

npm install -g openclaw@latest

Step 2. Run the onboarding wizard:

openclaw onboard --install-daemon

Select iMessage (native) when prompted for the channel type.

Step 3. Grant Full Disk Access to the correct binary. This is the step where most people get stuck.

Open System Settings → Privacy & Security → Full Disk Access. Do not add Terminal.app — macOS does not inherit permissions to subprocesses. Add the actual binary that OpenClaw uses for iMessage:

# Find the correct binary path:
which imsg
# typically: /opt/homebrew/bin/imsg or ~/.openclaw/bin/imsg

# If installed via npm, check:
ls -la $(npm root -g)/openclaw/bin/

Add that specific path to Full Disk Access. Then add it to Automation as well, with access to Messages.app.

Step 4. Test that the binary can read chat.db:

imsg list --limit 5

If you see recent conversations, permissions are correct. If you get a "permission denied" error, the wrong binary is in Full Disk Access.

Step 5. If running headless (no monitor), install the Messages keep-alive LaunchAgent:

# Create ~/Library/LaunchAgents/com.openclaw.messages-keepalive.plist
cat > ~/Library/LaunchAgents/com.openclaw.messages-keepalive.plist << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.openclaw.messages-keepalive</string>
  <key>ProgramArguments</key>
  <array>
    <string>/usr/bin/osascript</string>
    <string>-e</string>
    <string>tell application "Messages" to activate</string>
  </array>
  <key>StartInterval</key>
  <integer>300</integer>
  <key>RunAtLoad</key>
  <true/>
</dict>
</plist>
EOF

launchctl load ~/Library/LaunchAgents/com.openclaw.messages-keepalive.plist

This pings Messages.app every 5 minutes to prevent it from going idle on headless setups.

Step 6. Enable the iMessage channel in your config:

// ~/.openclaw/openclaw.json
{
  "channels": {
    "imessage": {
      "enabled": true
    }
  }
}

Step 7. Restart the gateway and send a test:

openclaw gateway restart

Known issues on Mac

• Echo loop: The bot sees its own outgoing messages before the is_from_me flag is written to chat.db. This can trigger infinite loops. If it happens, add "deduplicateMs": 500 to your iMessage channel config.
• Permission dialogs in headless mode: macOS can show permission prompts you cannot see over SSH. If the agent goes silent after an update, check the Mac physically or via screen sharing.
• npm binary wrapper rejection: macOS Full Disk Access rejects shell scripts. If your binary is a wrapper script, you need to find the underlying compiled binary and add that instead.

For a full comparison of why this is complex versus the plugin approach, see BlueBubbles vs Claw Messenger.

Alternative: use Claw Messenger on Mac instead

Even on a Mac, many developers use the Claw Messenger plugin to get a dedicated number separate from their personal Apple ID, or to add RCS and SMS alongside iMessage. The plugin setup is identical to the Linux version above — 5 minutes, no Full Disk Access required.

Setup on VPS with BlueBubbles bridge

Some teams run OpenClaw on a Linux VPS but already have a Mac available (a Mac Mini in the office, a personal MacBook, etc.). In this case BlueBubbles can expose the Mac's Messages.app over a REST/WebSocket API that OpenClaw reads remotely.

Architecture

Your Linux VPS (OpenClaw gateway)
    │
    │  WebSocket  (ngrok / Tailscale / public IP)
    ▼
Mac running BlueBubbles server
    │
    │  chat.db read
    ▼
Messages.app (iMessage)

Mac side: BlueBubbles setup

1. Download BlueBubbles server from bluebubbles.app
2. Sign into iMessage on the Mac
3. Grant Full Disk Access and Accessibility in System Settings
4. Create a Google Firebase project (required for BlueBubbles push notifications) and paste the credentials into BlueBubbles server
5. Set a password in the BlueBubbles web panel and note the port

For reactions (tapbacks) and message editing, you also need to disable System Integrity Protection (SIP). The BlueBubbles docs describe this as "similar to jailbreaking your iPhone." Skip this if you do not need those features.

VPS side: OpenClaw config

// ~/.openclaw/openclaw.json
{
  "channels": {
    "imessage": {
      "enabled": true,
      "bluebubbles": {
        "url": "http://your-mac-ip-or-tailscale-addr:1234",
        "password": "your-bluebubbles-password"
      }
    }
  }
}

If the Mac is behind NAT or a residential ISP, use Tailscale or an ngrok tunnel to make it reachable from the VPS.

Common BlueBubbles issues

• Missing messages: BlueBubbles sometimes skips database change events due to a stale timestamp comparison. If incoming messages disappear silently, check the BlueBubbles server log for "Not processing DB change."
• Attachment drops: Text + image messages fire two webhooks ~350ms apart. OpenClaw may process only the first (text only). Fixed in OpenClaw with debouncing — ensure you are on a recent version.
• Firebase required: BlueBubbles will not function without a Google Firebase project, even if you do not use their mobile app. This is a hard dependency.

Expected setup time: 1-3 hours. See the full comparison for a detailed breakdown of trade-offs.

Setup in Docker

OpenClaw runs in Docker. iMessage does not. The only supported path for Dockerized agents is the Claw Messenger plugin — pass the API key as an environment variable.

Docker Compose example

# docker-compose.yml
services:
  openclaw:
    image: openclaw/openclaw:latest
    environment:
      OPENCLAW_CLAW_MESSENGER_API_KEY: cm_live_xxxxxxxxxxxxxxxx
      OPENCLAW_CLAW_MESSENGER_SERVER_URL: wss://claw-messenger.onrender.com
    volumes:
      - ./openclaw.json:/root/.openclaw/openclaw.json:ro
    restart: unless-stopped

// openclaw.json (mounted into container)
{
  "channels": {
    "claw-messenger": {
      "enabled": true,
      "apiKey": "${OPENCLAW_CLAW_MESSENGER_API_KEY}",
      "serverUrl": "${OPENCLAW_CLAW_MESSENGER_SERVER_URL}"
    }
  }
}

If OpenClaw does not support environment variable substitution in your version, write the config directly or use a Docker entrypoint script to inject values at startup.

Troubleshooting

Plugin installed but messages not arriving

1. Check the gateway log: openclaw gateway logs --tail 50
2. Look for claw-messenger: connected. If you see authentication failed, your API key is wrong or expired.
3. Verify the serverUrl starts with wss:// (not ws:// or https://).
4. If behind a corporate firewall or proxy, WebSocket connections to port 443 may be blocked. Contact your network team or try a different network.

Messages send but do not receive

This is almost always a routing issue. The Claw Messenger server needs to push incoming messages to your OpenClaw gateway. Check:

• Your gateway is publicly reachable or you have configured a webhook URL in the Claw Messenger dashboard
• The openclaw.json channel block has "enabled": true
• No firewall is blocking inbound WebSocket connections

iMessage sending as SMS (green bubble)

When Claw Messenger sends to a phone number, it uses RCS or SMS if the recipient is not on iMessage. This is expected behavior. If you want iMessage-only delivery, verify the recipient has an iPhone with iMessage enabled and the number is registered with Apple.

Mac native setup: "No such file or directory" on chat.db

# Verify the database path:
ls ~/Library/Messages/chat.db

# If it exists but imsg cannot read it:
# → Full Disk Access is missing for the binary
# Add the binary (not Terminal.app) to System Settings → Privacy → Full Disk Access

Frequently asked questions

Can I use my existing Apple ID with Claw Messenger?

No. Claw Messenger provides a dedicated phone number. Messages come from that number, not your personal Apple ID. This is actually preferable for agent deployments — your agent gets its own identity separate from your personal contacts.

Does the OpenClaw mac requirement apply to all channels?

No. The Mac requirement only applies to the native iMessage channel via the imsg CLI or BlueBubbles. WhatsApp, Telegram, Discord, Slack, Signal, and other channels work on any platform without Apple hardware.

What is the openclaw mac requirement exactly?

iMessage is a proprietary Apple protocol. The only public interface is chat.db, a SQLite database on macOS. OpenClaw's native iMessage integration reads from this file, so it requires macOS. There is no official Apple API for iMessage. The Claw Messenger plugin bypasses this by running on Apple hardware on our side and exposing a platform-agnostic WebSocket API.

Can I run openclaw imessage on Linux without a Mac?

Not natively. But the Claw Messenger plugin gives you full iMessage capability on Linux, Windows, VPS, or Docker. Your agent does not need to know or care that Apple hardware is involved somewhere.

Which plan should I start on?

The Base plan ($5/mo) includes 1,000 messages per month and full iMessage, RCS, and SMS support. Most individual agents and small teams fit comfortably on this plan. You can upgrade at any time. All plans include a free trial.

Does this work with OpenClaw self-hosted?

Yes. Claw Messenger is a plugin, not a hosted service for OpenClaw itself. Your OpenClaw gateway stays wherever you run it — your VPS, your laptop, your Docker cluster. Only the iMessage routing goes through Claw Messenger.

Which setup is right for you?

Running on a Linux VPS or any non-Mac platform: Use the Claw Messenger plugin. It is the only practical option and takes 5 minutes.

Running on a Mac and want to use your Apple ID: Use the native imsg CLI or BlueBubbles. Plan for a longer setup and maintenance when macOS updates change permission behavior.

Running on a Mac but want a dedicated agent number: Use the Claw Messenger plugin. It gives your agent its own phone number and adds SMS and RCS alongside iMessage, without any Full Disk Access setup.

Running in Docker: Use the Claw Messenger plugin with environment variables. It is the only supported path.