# iMessage troubleshooting

> Fixes for a missing imsg binary, silent inbound, ignored DMs and groups, and failed remote attachments

- 网址：https://funcoding.ai/agents/openclaw/channels/imessage/troubleshooting/
- 来源：OpenClaw 官方文档原文（英文），MIT 许可，同步于 2026-10-11
- 官方原文：https://docs.openclaw.ai/zh-CN/channels/imessage/troubleshooting

---
Symptom-first fixes for the iMessage channel, plus the configuration reference links.

## Troubleshooting

<details>
<summary>imsg not found or RPC unsupported</summary>

Validate the binary and RPC support:

```bash
imsg rpc --help
imsg status --json
openclaw 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](https://funcoding.ai/agents/openclaw/channels/imessage/setup/#remote-mac-over-ssh) setup instead of the default local `imsg` path.

</details>

<details>
<summary>Messages send but inbound iMessages do not arrive</summary>

    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.

```bash
imsg chats --limit 10 --json
imsg watch --chat-id <chat-id> --json
sqlite3 ~/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:

```bash
launchctl kickstart -k system/com.apple.apsd
launchctl kickstart -k gui/$(id -u)/com.apple.CommCenter
launchctl kickstart -k gui/$(id -u)/com.apple.identityservicesd
launchctl kickstart -k gui/$(id -u)/com.apple.imagent
imsg launch
openclaw 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.

</details>

<details>
<summary>Gateway is not running on macOS</summary>

    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 "$@"`.

```bash
#!/usr/bin/env bash
exec ssh -T messages-mac imsg "$@"
```

    Then run:

```bash
openclaw channels status --probe --channel imessage
```

</details>

<details>
<summary>DMs are ignored</summary>

Check:

- `channels.imessage.dmPolicy`
- `channels.imessage.allowFrom`
- pairing approvals (`openclaw pairing list imessage`)

</details>

<details>
<summary>Group messages are ignored</summary>

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

</details>

<details>
<summary>Remote attachments fail</summary>

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

</details>

<details>
<summary>macOS permission prompts were missed</summary>

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

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

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

</details>

## Configuration reference pointers

- [Configuration reference - iMessage](https://funcoding.ai/agents/openclaw/gateway/config-channels/#imessage)
- [Gateway configuration](https://funcoding.ai/agents/openclaw/gateway/configuration/)
- [Pairing](https://funcoding.ai/agents/openclaw/channels/pairing/)

## Related

- [Channels Overview](https://funcoding.ai/agents/openclaw/channels/) — all supported channels
- [BlueBubbles removal and the imsg iMessage path](https://funcoding.ai/agents/openclaw/announcements/bluebubbles-imessage/) — announcement and migration summary
- [Coming from BlueBubbles](https://funcoding.ai/agents/openclaw/channels/imessage-from-bluebubbles/) — config translation table and step-by-step cutover
- [Pairing](https://funcoding.ai/agents/openclaw/channels/pairing/) — DM authentication and pairing flow
- [Groups](https://funcoding.ai/agents/openclaw/channels/groups/) — group chat behavior and mention gating
- [Channel routing](https://funcoding.ai/agents/openclaw/channels/channel-routing/) — session routing for messages
- [Security](https://funcoding.ai/agents/openclaw/gateway/security/) — access model and hardening