iMessage Setup Without a Mac (2026) — Free Trial

Short answer: Install the Claw Messenger plugin (openclaw plugins install @emotion-machine/claw-messenger), add your API key to openclaw.json, restart the gateway. Your OpenClaw agent gets iMessage, RCS, and SMS on any platform — Linux, Windows, VPS, Docker — no Mac required. 5-minute setup. If you want to use your own Apple ID instead, use the native imsg CLI (Mac only) or a BlueBubbles bridge.

Does OpenClaw require a Mac for iMessage?

The native imsg CLI requires macOS because iMessage stores messages in a local SQLite database (chat.db) that only macOS can read. There is no official Apple API. But a Mac is not your only option.

There are three paths to connect an iMessage bot to OpenClaw in 2026:

1. Claw Messenger plugin (no Mac, recommended): Your agent connects via WebSocket and we handle the Apple infrastructure. Works on any OS, any VPS. Get started.
2. BlueBubbles bridge (Mac required): Open-source server that exposes Messages.app over REST/WebSocket. Free, but you maintain the Mac hardware and Firebase setup.
3. Native imsg CLI (Mac required): Reads chat.db directly. Full control, but complex permissions setup and maintenance after macOS updates.

This guide covers all three paths, organized by the platform your OpenClaw iMessage bot runs on. Skip to your platform below.

Where is the imsg CLI path?

If you are using the native Mac setup, the first thing you need is the imsg binary path. This is the most common question in OpenClaw iMessage setup — and the value you set as cliPath in your openclaw.json.

# Find your imsg CLI path:
which imsg

# Common locations:
# Apple Silicon (M1/M2/M3/M4): /opt/homebrew/bin/imsg
# Intel Mac:                    /usr/local/bin/imsg
# npm global install:           ~/.openclaw/bin/imsg
# Homebrew tap:                 /opt/homebrew/bin/imsg

# Verify it works:
imsg --version

This is the exact path you add to macOS System Settings → Privacy & Security → Full Disk Access. Do not add Terminal.app — add the actual binary. If which imsg returns a shell wrapper, find the underlying binary with file $(which imsg).

Setup on Linux / VPS

Use the Claw Messenger plugin. It takes 5 minutes and is the only practical iMessage option for Linux VPS environments (DigitalOcean, Hetzner, AWS, etc.) since iMessage does not run natively on Linux. The alternative is a remote Mac bridge, which adds significant complexity.

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.

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

Use the Claw Messenger plugin. OpenClaw runs on Windows via Node.js (WSL is not required) and iMessage has no native Windows path. Setup is identical to Linux — install the plugin, add your API key, restart.

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 run OpenClaw on a Mac and want to use your own Apple ID for iMessage, use the native imsg CLI. Plan for 1-3 hours of setup. The main challenge is macOS permissions — Full Disk Access and Automation must be granted to the correct binary, not Terminal.app.

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

Does OpenClaw iMessage require a Mac?

The native imsg CLI requires macOS because it reads the chat.db SQLite database directly. But you can skip the Mac entirely using the Claw Messenger plugin, which handles Apple infrastructure on our side and connects via WebSocket. Works on Linux, Windows, VPS, and Docker.

Where is the imsg CLI path on macOS?

The imsg binary is typically at /opt/homebrew/bin/imsg (Apple Silicon) or /usr/local/bin/imsg (Intel). Run which imsg to find the exact path. This is the path you add to macOS Full Disk Access and set as cliPath in your openclaw.json config.

How do I set up OpenClaw iMessage with BlueBubbles?

Install BlueBubbles server on a Mac with iMessage signed in. Enable the web API, set a password, and create a Google Firebase project for push notifications. On your VPS, install the @openclaw/bluebubbles plugin and configure the channels.bluebubbles block with the Mac's IP and password. Use Tailscale or ngrok if the Mac is behind NAT. See the BlueBubbles section above for the full walkthrough.

Can I run an iMessage bot with OpenClaw on Linux?

Yes. Install the Claw Messenger plugin (openclaw plugins install @emotion-machine/claw-messenger), add your API key to openclaw.json, and restart the gateway. Your OpenClaw agent gets a dedicated phone number for iMessage, RCS, and SMS. No Mac, no BlueBubbles, 5-minute setup.

What is the difference between BlueBubbles and Claw Messenger for OpenClaw iMessage?

BlueBubbles is a free, self-hosted bridge that requires a physical Mac running 24/7 with iMessage signed in. You maintain the hardware and Firebase setup. Claw Messenger is a managed API — no Mac needed, dedicated phone number included, works on any platform. BlueBubbles uses your Apple ID; Claw Messenger provides a separate agent number.

How do I set up OpenClaw iMessage in Docker?

Use the Claw Messenger plugin with environment variables. Pass OPENCLAW_CLAW_MESSENGER_API_KEY and OPENCLAW_CLAW_MESSENGER_SERVER_URL in your docker-compose.yml, mount your openclaw.json config, and the agent connects to iMessage via WebSocket. No Mac or Apple hardware needed in the container. See the Docker section above for the full example.

Can I use my existing Apple ID with Claw Messenger?

No. Claw Messenger provides a dedicated phone number for your agent. Messages come from that number, not your personal Apple ID. This is preferable for bot 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.

Which plan should I start on?

The Base plan ($5/mo) includes a 7-day free trial and 250 messages per month with full iMessage, RCS, and SMS support. Most individual agents and small teams fit comfortably on this plan. You can upgrade at any time. Start your 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.