iMessage troubleshooting

Validate the binary and RPC support:

imsg rpc --helpimsg status --jsonopenclaw channels status --probe

If the probe reports RPC unsupported, update imsg. If private API actions are unavailable, run imsg launch in the logged-in macOS user session and probe again. If the Gateway is not running on macOS, use the Remote Mac over SSH setup instead of the default local imsg path.

First prove whether the message reached the local Mac. If chat.db does not change, OpenClaw cannot receive the message even when imsg status --json reports a healthy bridge.

imsg chats --limit 10 --jsonimsg watch --chat-id <chat-id> --jsonsqlite3 ~/Library/Messages/chat.db \"select datetime(max(date)/1000000000 + 978307200, 'unixepoch', 'localtime'), max(ROWID) from message;"

If phone-sent messages create no new rows, repair the macOS Messages and Apple Push layer before changing OpenClaw config. A one-shot service refresh is often enough:

launchctl kickstart -k system/com.apple.apsdlaunchctl kickstart -k gui/$(id -u)/com.apple.CommCenterlaunchctl kickstart -k gui/$(id -u)/com.apple.identityservicesdlaunchctl kickstart -k gui/$(id -u)/com.apple.imagentimsg launchopenclaw gateway restart

Send a fresh iMessage from the phone and confirm a new chat.db row or imsg watch event before debugging OpenClaw sessions. Do not run this as a periodic bridge-relaunch loop; repeated imsg launch plus gateway restarts during active work can interrupt deliveries and strand in-flight channel runs.

The default cliPath: "imsg" must run on the Mac signed into Messages. On Linux or Windows, set channels.imessage.cliPath to a wrapper script that SSHes to that Mac and runs imsg "$@".

#!/usr/bin/env bashexec ssh -T messages-mac imsg "$@"

Then run:

openclaw channels status --probe --channel imessage

Check:

• channels.imessage.dmPolicy
• channels.imessage.allowFrom
• pairing approvals (openclaw pairing list imessage)

Check:

• channels.imessage.groupPolicy
• channels.imessage.groupAllowFrom
• channels.imessage.groups allowlist behavior
• mention gating: explicit patterns or the routed agent's identity name/emoji; set requireMention: false for the chat in the effective root or account groups map to process all messages from allowed senders

Check:

• channels.imessage.remoteHost
• channels.imessage.remoteAttachmentRoots
• SSH/SCP key auth from the gateway host
• host key exists in ~/.ssh/known_hosts on the gateway host
• remote path readability on the Mac running Messages

Re-run in an interactive GUI terminal in the same user/session context and approve prompts:

imsg chats --limit 1imsg send <handle> "test"

Confirm Full Disk Access + Automation are granted for the process context that runs OpenClaw/imsg.