Messaging platforms

iMessage

⚠️ For new iMessage deployments, use BlueBubbles.The imsg integration is legacy and may be removed in a future release.

Status: legacy external CLI integration. Gateway spawns imsg rpc and communicates over JSON-RPC on stdio (no separate daemon/port).

BlueBubbles (recommended)

Preferred iMessage path for new setups.

Pairing

iMessage DMs default to pairing mode.

Configuration reference

Full iMessage field reference.

Quick setup

brew install steipete/tap/imsg
imsg rpc --help

Requirements and permissions (macOS)

  • Messages must be signed in on the Mac running imsg.
  • Full Disk Access is required for the process context running OpenClaw/imsg (Messages DB access).
  • Automation permission is required to send messages through Messages.app.

💡 Permissions are granted per process context. If gateway runs headless (LaunchAgent/SSH), run a one-time interactive command in that same context to trigger prompts:

Copy

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

Access control and routing

channels.imessage.dmPolicy controls direct messages:

  • pairing (default)
  • allowlist
  • open (requires allowFrom to include "*")
  • disabled

Allowlist field: channels.imessage.allowFrom.Allowlist entries can be handles or chat targets (chat_id:*, chat_guid:*, chat_identifier:*).

Deployment patterns

Media, chunking, and delivery targets

Config writes

iMessage allows channel-initiated config writes by default (for /config set|unset when commands.config: true). Disable:

{
  channels: {
    imessage: {
      configWrites: false,
    },
  },
}

Troubleshooting

Configuration reference pointers

Google ChatIRC