OpenClaw iMessage Not Working? 7 Common Problems + Fixes

Short answer: The most common OpenClaw iMessage failures are Mac sleep stopping Messages, the wrong binary in Full Disk Access, and old BlueBubbles configs that OpenClaw no longer loads (OpenClaw removed BlueBubbles support). Find your symptom below.

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. To weigh keeping a Mac against a managed plugin, see do I need a Mac mini for OpenClaw iMessage?.

Problem 1: Mac goes offline after 24 hours

Symptoms

• Agent stops responding after ~24 hours of uptime
• Restarting Messages.app or imsg launch fixes it temporarily
• The Mac is still powered on and SSH-accessible
• The gateway shows no errors and believes the channel is running

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 imsg reads. The app is technically running, but it is not processing new message events.

This is not an OpenClaw or imsg bug. It is a macOS behavior on headless machines.

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: Linux gateway keeps losing the Mac that runs imsg

Symptoms

• The OpenClaw gateway runs on Linux and the iMessage channel's cliPath points at an SSH wrapper on a Mac
• Agent works, then stops sending and receiving at random
• Restarting the gateway fixes it temporarily
• Problem recurs after network changes or a Mac restart

Root cause

Three things cause recurring drops:

1. The Mac's address changes. If the Mac gets a new local IP from DHCP, the SSH wrapper points at the wrong host.
2. SSH stops being non-interactive. A password prompt, a changed host key, or an expired key makes the wrapper hang instead of running imsg.
3. The Mac sleeps or logs out. imsg needs the user session that is signed into Messages. See Problem 1.

Fix

Give the Mac a stable address. Assign a static local IP through your router's DHCP reservation table, or use Tailscale, which gives each machine a stable address regardless of local network changes:

# On Mac:
brew install tailscale
sudo tailscale up

# On the Linux gateway:
# Install Tailscale, join the same tailnet,
# then use the Mac's Tailscale name in the SSH wrapper

Make SSH run without prompts. Use key-based login for the gateway's user, then run the wrapper by hand from the gateway and confirm it returns without asking for anything:

# From the Linux gateway, as the user that runs OpenClaw:
ssh you@your-mac imsg --version

Then probe the channel with openclaw channels status --probe. The OpenClaw iMessage deployment docs describe the remote-Mac pattern in full.

Problem 3: BlueBubbles config stopped loading after an OpenClaw update

Symptoms

• Config file has a bluebubbles block but the gateway logs show the channel is not loading
• Setup worked previously but broke after an OpenClaw update
• The guide you followed told you to install BlueBubbles server

Root cause

OpenClaw removed BlueBubbles support. It now supports iMessage through its own @openclaw/imessage plugin and the imsg CLI only. Many older blog posts and forum answers still describe the BlueBubbles setup.

Fix

If you want to keep using a Mac: move the channels.bluebubbles settings to channels.imessage and install imsg on the Mac signed into Messages:

openclaw plugins install @openclaw/imessage
brew install steipete/tap/imsg
imsg launch
openclaw channels status --probe

The OpenClaw iMessage channel docs list the current channels.imessage options. You can stop the BlueBubbles server once the imsg channel works.

If you would rather drop the Mac: switch 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"
    }
  }
}

For OpenClaw, leave service selection unset. Claw Messenger routes each message automatically across iMessage, RCS, and SMS.

See the full setup guide for both configurations.

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 imsg 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). Sends from the Mac can then fail quietly, depending on your macOS version and whether the Mac can relay SMS from an iPhone.

Fix

For Cause A: On the Mac running imsg, 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. With Claw Messenger, leave service selection unset so each message can be routed automatically across iMessage, RCS, and SMS. Group chats on Claw Messenger start on the Growth plan; trial and Base accounts cannot open groups.

Problem 5: Read receipts not syncing

Symptoms

• Messages are delivered and read, but OpenClaw never receives a read receipt event
• The gateway log shows no read events for that thread
• Read receipt delivery is delayed by 30-120 seconds instead of near real-time

Root cause

Read receipts can fail at two points: the sender side (the contact has read receipts turned off, so Apple never reports the read) or the Mac side (imsg cannot see the read state in the Messages database).

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. Your contacts control whether their reads are reported to you.

Step 2. Confirm imsg still has Full Disk Access. macOS updates can reset privacy permissions, and imsg reads read state from the same chat.db it reads messages from.

Step 3. Probe the channel and watch the gateway log while someone reads a message:

openclaw channels status --probe
openclaw gateway logs --tail 100 | grep -i "read"

If messages arrive but no read events appear, check the OpenClaw iMessage channel docs for which events your OpenClaw version reports.

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. If you are starting fresh, the OpenClaw iMessage setup guide walks through the full installation from scratch.

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 the imsg channel and the Claw Messenger plugin

Root cause

This is a one-way problem. Sending and receiving take different paths, so one can work while the other is broken.

For the imsg channel: imsg has to see new rows in the Messages database on the Mac and pass them to the gateway. If imsg lost Full Disk Access, Messages.app went idle, or the SSH wrapper to a remote Mac dropped, replies 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 the imsg channel

Step 1. Probe the channel from the gateway:

openclaw channels status --probe

Step 2. On the Mac, confirm the binary OpenClaw runs (which imsg) is still listed under System Settings → Privacy & Security → Full Disk Access. Re-add it after a macOS or Homebrew update if needed.

Step 3. If the gateway runs on Linux, run the SSH wrapper by hand (see Problem 2) and fix any prompt it shows.

Step 4. Send a message to the Mac's Apple ID from another device and watch the gateway log in real time:

openclaw gateway logs --tail --follow

If nothing appears, the reply is not leaving the Mac. Go back to Problem 1.

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 keep hitting Mac-side issues, the Mac mini versus managed API comparison for OpenClaw walks through when switching to a managed service makes sense. The short setup often removes an entire class of problems.