OpenClaw iMessage Not Working? 7 Common Problems + Fixes

OpenClaw iMessage can break in ways that produce no obvious error message. Messages silently disappear. The agent stops responding. Sends work but receives do not. You restart everything and it works for a day, then breaks again.

Most of these failures have the same small set of root causes. This guide covers all of them with step-by-step fixes. If you have not set up iMessage on OpenClaw yet, start with the complete setup guide first. For a comparison of self-hosted vs managed options, see BlueBubbles vs Claw Messenger.

Problem 1: Mac goes offline after 24 hours

Symptoms

• Agent stops responding after ~24 hours of uptime
• Restarting the BlueBubbles server fixes it temporarily
• The Mac is still powered on and SSH-accessible
• BlueBubbles server shows no errors — it believes it is running fine

Root cause

This is the headless Mac idle problem. On a Mac with no monitor connected (or with display sleep enabled), macOS enters a low-power state where Messages.app stops processing the chat.db database changes that BlueBubbles depends on. The app is technically running, but it is not processing new message events.

This is not a BlueBubbles bug — it is a macOS behavior for headless machines, and it has been consistent since Ventura.

Fix

Step 1. Install an HDMI dummy plug (~$10 on Amazon). This makes macOS believe a monitor is connected and prevents display sleep mode from engaging. Plug it into the Mac's HDMI or DisplayPort before startup.

Step 2. Create a LaunchAgent that keeps Messages.app active every 5 minutes:

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

Step 3. Disable display sleep in Energy Saver:

sudo pmset -a displaysleep 0 sleep 0

Step 4. Verify the LaunchAgent is running:

launchctl list | grep openclaw

If you see com.openclaw.messages-keepalive in the output, the keep-alive is active. If you do not see it, check /tmp/com.openclaw.messages-keepalive.stdout for errors.

Alternative: Switch to Claw Messenger, which runs on managed infrastructure and does not have a Mac idle dependency.

Problem 2: BlueBubbles bridge keeps dropping connection

Symptoms

• Agent works, then stops receiving messages randomly
• BlueBubbles server log shows webhook delivery failed or connection timeouts
• Restarting OpenClaw gateway fixes it temporarily
• Problem recurs every few hours or after network changes

Root cause

Three things cause recurring drops:

1. Dynamic IP on the Mac. If the Mac gets a new local IP from DHCP, the webhook URL configured in BlueBubbles points to the wrong address.
2. Tunnel instability. ngrok free-tier tunnels expire every 8 hours. If you are using ngrok without a static domain, your webhook URL changes and BlueBubbles cannot reach OpenClaw.
3. Gateway restart without re-registration. When OpenClaw restarts, it may not re-register its webhook URL with BlueBubbles, leaving BlueBubbles sending to a stale address.

Fix

For dynamic IP: Assign a static local IP to the Mac via your router's DHCP reservation table (use the Mac's MAC address). Or switch to Tailscale, which gives each machine a stable IP regardless of local network changes:

# On Mac:
brew install tailscale
sudo tailscale up

# On VPS (if running OpenClaw there):
# Install Tailscale and connect the same tailnet
# Then use the Mac's Tailscale IP in BlueBubbles config

For ngrok tunnel instability: Use a paid ngrok plan with a static subdomain, or replace ngrok with a Cloudflare Tunnel (free, no expiry):

# Install cloudflared on Mac:
brew install cloudflare/cloudflare/cloudflared

# Create a persistent tunnel (requires free Cloudflare account):
cloudflared tunnel login
cloudflared tunnel create openclaw-bb
cloudflared tunnel route dns openclaw-bb your-subdomain.yourdomain.com

For gateway re-registration: Add a restart hook to your OpenClaw config that re-sends the webhook URL to BlueBubbles on startup. Check the OpenClaw docs for the onStart hook.

Problem 3: iMessage legacy deprecation (OpenClaw 6.x config on 7.x)

Symptoms

• Config file has "imessage" channel key but the gateway logs show the channel is not loading
• Error: unknown channel type: imessage or similar
• Setup worked previously but broke after an OpenClaw update
• Docs you followed predate 2025

Root cause

OpenClaw 7.x changed the iMessage channel architecture. The legacy imsg CLI integration used a flat channel key ("imessage": { "enabled": true }). In 7.x, the native Mac integration moved to a plugin model and the BlueBubbles channel config changed its key structure. Many older blog posts and forum answers still reference the 6.x format.

Fix

First, check your OpenClaw version:

openclaw --version

If on OpenClaw 7.x with BlueBubbles: The correct channel block is now nested under imessage.bluebubbles:

// Correct 7.x format for BlueBubbles:
{
  "channels": {
    "imessage": {
      "enabled": true,
      "bluebubbles": {
        "url": "http://your-mac-ip-or-tailscale:1234",
        "password": "your-bluebubbles-password"
      }
    }
  }
}

If switching to Claw Messenger instead:

openclaw plugins install @emotion-machine/claw-messenger

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

This config format works across all OpenClaw 7.x versions and does not change when OpenClaw updates. See the full setup guide for the complete configuration walkthrough.

Problem 4: Delivery failures on group messages

Symptoms

• 1:1 messages work fine but group messages are not delivered
• Group messages appear to send (no error) but contacts do not receive them
• Incoming group messages arrive but the agent cannot reply into the group

Root cause

Group message failures have two common causes:

Cause A: The Mac Apple ID is not in the group. iMessage group chats are tied to specific Apple IDs. If the group thread was started from a different Apple ID or device, the Mac running BlueBubbles may not have that group in its chat.db. The Mac needs to be an active participant in the group — not just have the same Apple ID.

Cause B: Mixed iMessage/SMS group. When an Android user is in a group, Apple switches the whole thread to MMS (green bubbles). BlueBubbles handles MMS differently and may silently fail on these groups depending on your macOS version and BlueBubbles release.

Fix

For Cause A: On the Mac running BlueBubbles, open Messages.app and verify the group thread appears. If it does not, the Apple ID signed in on the Mac was not included in the original group. You will need to create a new group or ask someone to re-add the Mac's Apple ID.

Check the thread exists in chat.db:

sqlite3 ~/Library/Messages/chat.db \
  "SELECT display_name, guid FROM chat WHERE display_name != '' ORDER BY rowid DESC LIMIT 20"

If the group appears in chat.db but not in Messages.app, force a sync by signing out of iMessage and back in on the Mac.

For Cause B: This is a fundamental iMessage limitation. If you need to message mixed groups with Android users, use a service that includes SMS/MMS handling. Claw Messenger handles mixed groups automatically through SMS fallback.

Problem 5: Read receipts not syncing

Symptoms

• Messages are delivered and read, but OpenClaw never receives a read receipt event
• BlueBubbles logs show no read-receipt webhook events
• Read receipt delivery is delayed by 30-120 seconds instead of near real-time

Root cause

Read receipts can fail at two points: the Mac side (Apple does not send them) or the BlueBubbles side (they are not forwarded).

Fix

Step 1. Verify read receipts are enabled at the system level. On the Mac, open Messages.app → Settings → iMessage → enable "Send Read Receipts." This must be on for your Apple ID to report reads to contacts.

Step 2. In the BlueBubbles server settings, confirm Send Read Receipts is enabled under the Notification settings tab.

Step 3. Check that BlueBubbles is on a recent version. Read receipt webhook delivery was broken in some 1.x BlueBubbles releases and fixed in later patches. Update to the latest release:

# Check current BlueBubbles version in the app's top menu:
# BlueBubbles → About BlueBubbles
# Download latest from: https://github.com/BlueBubblesApp/bluebubbles-server/releases

Step 4. On macOS Tahoe (26), read receipt webhooks have a known delay of up to 60 seconds. This is an upstream issue with how Tahoe processes chat.db change events. There is no workaround other than downgrading to Sequoia or accepting the delay.

Step 5. Test read receipt delivery manually with a curl to the BlueBubbles webhook endpoint and check the OpenClaw gateway log:

openclaw gateway logs --tail 100 | grep -i "read"

If you see no read receipt events despite confirmed delivery, the issue is between BlueBubbles and OpenClaw (webhook not reaching the gateway).

Problem 6: Linux VPS setup failures (permissions, paths)

Symptoms

• Plugin install fails with EACCES: permission denied
• Plugin installs but gateway fails to load with Cannot find module errors
• Node.js version error on plugin load: Requires Node.js >= 18
• Config file changes not taking effect after restart

Root cause

Three common causes on Linux:

1. Old Node.js version. Distro package managers often ship Node.js 16 or older. The Claw Messenger plugin and recent OpenClaw versions require Node.js 18+.
2. OpenClaw installed with sudo. If you ran sudo npm install -g openclaw, the global package directory is owned by root. Subsequent plugin installs without sudo fail with permission errors.
3. Wrong config file path. On Linux, the OpenClaw config is at ~/.openclaw/openclaw.json for the current user. If OpenClaw runs as a different user (a systemd service user, for example), it reads from that user's home directory.

Fix

Step 1. Check and fix Node.js version:

node --version   # must be 18.x or higher

# If outdated, install via nvm (recommended):
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc
nvm install 20
nvm use 20
nvm alias default 20

Step 2. Fix permission errors from sudo install:

# Option A: reinstall openclaw without sudo (via nvm):
npm install -g openclaw@latest

# Option B: fix ownership of npm global directory:
sudo chown -R $(whoami) $(npm root -g)
sudo chown -R $(whoami) $(npm bin -g)

Step 3. Verify the correct config path:

# Find where OpenClaw reads config from:
openclaw config --show-path

# If running as a systemd service, check the service user:
systemctl show openclaw-gateway.service | grep User

# If the service user is 'openclaw-bot', the config is at:
# /home/openclaw-bot/.openclaw/openclaw.json

Step 4. Install the plugin as the correct user:

# Switch to the service user if needed:
sudo -u openclaw-bot bash
openclaw plugins install @emotion-machine/claw-messenger

After fixing permissions, restart the gateway as the same user that owns the config and plugins.

Problem 7: Messages sending but not receiving (bridging bug)

Symptoms

• Your agent can send iMessages — they appear on the recipient's iPhone
• When someone replies, the agent never receives the message
• The gateway log shows no incoming message events
• This happens with both BlueBubbles and the Claw Messenger plugin

Root cause

This is a one-way bridge problem. Sending works because the outbound path (OpenClaw → iMessage) does not depend on network connectivity back to the gateway. Receiving fails because the inbound path requires the iMessage bridge (BlueBubbles or Claw Messenger) to push events back to OpenClaw — and that connection is broken or never established.

For BlueBubbles: BlueBubbles needs to send webhooks to your OpenClaw gateway. If the gateway is on a VPS, the VPS must be publicly reachable. If the VPS firewall blocks incoming connections or the URL configured in BlueBubbles is wrong, events never arrive.

For Claw Messenger: The WebSocket connection from your gateway to wss://claw-messenger.onrender.com must be maintained. If an outbound firewall blocks WebSocket connections on port 443, or the connection drops and does not reconnect, incoming messages are lost.

Fix for BlueBubbles

Step 1. Find your gateway's public address and verify it is reachable from the Mac running BlueBubbles:

# From the Mac running BlueBubbles, test connectivity to your gateway:
curl -v http://your-vps-ip:your-gateway-port/health

# Or for a domain:
curl -v https://your-domain.com/health

Step 2. In the BlueBubbles server web panel, go to Settings → Notifications → Webhooks. Verify the webhook URL points to your gateway's public address. The format should be: https://your-domain.com/channels/imessage/webhook

Step 3. Check your VPS firewall:

# On Ubuntu/Debian with ufw:
sudo ufw status
# Ensure the OpenClaw gateway port is allowed:
sudo ufw allow 3001   # replace with your gateway port

# On Hetzner/DigitalOcean, also check the provider-level firewall in the dashboard

Step 4. Test webhook delivery from BlueBubbles by sending a message to the Apple ID associated with your BlueBubbles Mac from another device. Watch the gateway log in real time:

openclaw gateway logs --tail --follow

If you see nothing appear after sending a message, the webhook is not reaching the gateway.

Fix for Claw Messenger

Step 1. Check the gateway log for the WebSocket connection status:

openclaw gateway logs --tail 50 | grep -i "claw-messenger"
# Look for: claw-messenger: connected
# If you see: claw-messenger: disconnected or authentication failed → see below

Step 2. Verify the config uses the correct serverUrl format:

// Correct — must start with wss://
"serverUrl": "wss://claw-messenger.onrender.com"

// Wrong — these will not work:
"serverUrl": "https://claw-messenger.onrender.com"
"serverUrl": "ws://claw-messenger.onrender.com"

Step 3. Check for outbound WebSocket blocking. Some corporate networks and VPS providers block outbound WebSocket connections. Test with:

# Test WebSocket connectivity:
curl -v --include   --no-buffer   --header "Connection: Upgrade"   --header "Upgrade: websocket"   --header "Sec-WebSocket-Key: test"   --header "Sec-WebSocket-Version: 13"   https://claw-messenger.onrender.com/ws

If this returns an error or hangs, your outbound WebSocket connections are blocked. Contact your VPS provider or use a VPN/proxy that allows WebSocket traffic.

Step 4. Rotate your API key. If the key was recently regenerated in the dashboard, the config may still have the old one. Copy the current key from the Claw Messenger dashboard and update openclaw.json.

Still stuck?

If none of these fixes resolved your issue, the next step is checking the full OpenClaw gateway logs with debug mode enabled:

OPENCLAW_LOG_LEVEL=debug openclaw gateway start 2>&1 | tee /tmp/openclaw-debug.log

Share the log output in the OpenClaw community or attach it when contacting support.

If you are running BlueBubbles and repeatedly hitting the same issues, the BlueBubbles vs Claw Messenger comparison walks through when switching to a managed service makes sense. The 7-minute setup investment often eliminates an entire class of problems permanently.