OpenClaw iMessage troubleshooting

An iMessage failure is usually one of three layers: the imsg bridge, the macOS Messages stack underneath it, or an OpenClaw allowlist. The docs' first rule is to find out which layer before changing config, and the test is simple: does the database on the Mac change when a phone sends a message? Here are the checks in the docs' order.

The bridge and the Mac

• For a missing imsg binary or unsupported RPC, validate with the RPC help, the status JSON and the channel probe; a probe that reports RPC unsupported means updating imsg, unavailable private API actions mean running the launch command in the logged-in macOS user session and probing again, and a gateway that is not on macOS uses the remote Mac over SSH setup instead of the default local path.
• When messages send but inbound never arrives, first prove whether the message reached the local Mac: list chats, watch a chat, and query the chat database for its latest message date and rowid, because if the database does not change OpenClaw cannot receive the message even when the 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 kickstart of the Push daemon, the cellular centre, the identity services daemon and the messaging agent, then the launch command and a gateway restart, followed by a fresh message from the phone and a new database row or watch event before debugging sessions.
• That refresh must not become a periodic bridge-relaunch loop, because repeated launches plus gateway restarts during active work can interrupt deliveries and strand in-flight channel runs.

If chat.db does not change, OpenClaw cannot receive the message even when imsg status --json reports a healthy bridge.

Off macOS, DMs, groups

The default CLI path must run on the Mac signed into Messages, so on Linux or Windows the path points at a wrapper script that SSHes to that Mac and runs imsg with the forwarded arguments, after which the channel probe for iMessage confirms it. Ignored DMs come down to the DM policy, the DM allowlist and the pairing approvals listed by the pairing command. Ignored group messages come down to the group policy, the group sender list, the groups registry behaviour, and mention gating, where the patterns are the explicit ones or the routed agent's identity name and emoji, and the fix for processing every message from allowed senders is a false mention requirement for that chat in the effective root or account groups map.

Attachments and permissions

• Failed remote attachments come down to the remote host key, the remote attachment roots, SSH and SCP key auth from the gateway host, the Mac's host key present in the gateway's known hosts, and the remote path being readable on the Mac running Messages.
• Missed macOS permission prompts are recovered by re-running an interactive command in a GUI terminal in the same user and session context, listing one chat or sending a test message, and approving the prompts.
• Then confirm that Full Disk Access and Automation are granted for the process context that runs OpenClaw or imsg, since a grant in another context does not carry over.

OpenClaw on iMessage is the channel post these symptoms belong to, and OpenClaw iMessage access control the allowlists behind ignored DMs and groups.

Prove the layer first

The database check is the whole method: a healthy bridge with a silent database is an Apple problem, and no OpenClaw setting fixes it, which is why the docs put the Push repair before any config change. OpenClaw iMessage message behaviour explains the recovery that replays what the bridge missed once it is back, and OpenClaw iMessage setup the wrapper rules that produce fake outages when a pipe buffers.

On Diali

iMessage is not among the channels Diali connects today: WhatsApp, Telegram, Discord, Slack, Mattermost, Matrix, SMS and voice. Hosted OpenClaw on Diali is the assistant and Diali security describes the boundary that applies to each connected channel.

• No new database row means an Apple problem, not a config one.
• Kickstart the Push stack once; never in a loop.
• Grant permissions in the context that runs imsg.