Skip to main content
Symptom-first fixes for the iMessage channel, plus the configuration reference links.

​
Troubleshooting

Validate the binary and RPC support:
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.
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:
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 "$@".
Then run:
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:
Confirm Full Disk Access + Automation are granted for the process context that runs OpenClaw/imsg.

​
Configuration reference pointers