iMessage troubleshooting

Validate the binary and RPC support:

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

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

A successful channels status --probe checks RPC/read access, not whether Messages can send. Automation failures can therefore coexist with a healthy probe and working inbound messages.

For structured AppleScript failures, OpenClaw includes launch-context guidance with the send error. Error -1743 means Messages Automation was denied. Error -1712 is an Apple event timeout: a missing grant is one possible cause, not a confirmed diagnosis.

Check System Settings → Privacy & Security → Automation on the Mac running Messages:

• For a local app-managed Gateway, check the Gateway/launcher process macOS identifies. An app update that switches Node to Bun, or first moves the service to the stable ~/.openclaw/runtime/service/bun path, needs this grant approved once; later updates keep that path. The error includes the current local Gateway runtime path to help distinguish it from an old entry.
• For SSH or custom wrappers, check that Mac's actual SSH/wrapper launch context, not the remote Gateway host's runtime.
• A grant to Terminal or OpenClaw.app does not by itself establish access for a background service.

Review the required grant in that user session, then verify delivery through the same Gateway and launch context using an explicitly requested test message to a consenting recipient. A Terminal-only test does not validate the background service. Pending replies may drain after recovery; do not resend them manually before checking their delivery outcome.

See iMessage permissions and Gateway hosting. Changing a runtime symlink is not a verified permission-continuity fix.

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

A working inbound connection or successful read probe does not prove that Messages Automation is authorized. OpenClaw reports observed AppleScript Automation send failures in the account warning shown by openclaw channels status, including when inbound remains connected. During the current account run, the warning clears after a successful send, not a successful read probe. Restarting the Gateway resets this observed status; it does not transfer the grant.

On the Messages Mac, open System Settings → Privacy & Security → Automation and allow Messages for the process that runs imsg. For an app-managed background Gateway using bundled Bun, check the current bun entry. App updates use a new concrete runtime path, so a grant for an older node or bun runtime, Terminal, or OpenClaw.app may not cover the running service. Use openclaw gateway status --deep to inspect the service command.

AppleScript -1712 is a timeout, not proof of a denied grant: also check for a hidden permission prompt or an unresponsive Messages.app. After restoring access, retry a send through the Gateway in the same user session. A terminal-only test can use a different permission identity. Review queued replies before manually sending replacements.

This recovery does not preserve or transfer macOS grants between runtime builds. See macOS permissions.

Review Full Disk Access and Messages Automation in the logged-in Messages user’s macOS session for the process context that actually runs OpenClaw/imsg. See Requirements and permissions, including the SSH-wrapper edge case.

A successful command in Terminal only verifies Terminal’s context. It does not establish permissions for a LaunchAgent or SSH wrapper. Verify the configured Gateway’s send path with an explicitly requested test message, not an automatic health-check send.