iMessage

Status: External CLI integration. Gateway will spawn imsg rpc (JSON-RPC over stdio).

1. Ensure Messages is logged in on this Mac.

2. Install imsg:

- brew install steipete/tap/imsg

3. Configure channels.imessage.cliPath and channels.imessage.dbPath in OpenClaw.

4. Start gateway and approve macOS prompts (Automation + Full Disk Access).

Minimal configuration:

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "/usr/local/bin/imsg",
      dbPath: "/Users/<you>/Library/Messages/chat.db",
    },
  },
}

- Provides iMessage channel capabilities via imsg on macOS.

- Deterministic routing: replies always return to iMessage.

- DMs fold into agent's main session; groups are isolated as ''agent:'':imessage:group:''''.

- If a multi-participant thread appears with is_group=false, you can still treat it as a group thread by chat_id via channels.imessage.groups (see "Group-like threads" below).

By default, allows iMessage to write updates triggered by /config set|unset back to the config file (requires commands.config: true).

Disable:

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

- macOS with Messages logged in.

- Grant Full Disk Access to OpenClaw and imsg (to read Messages DB).

- Automation permission prompt required when sending messages.

- channels.imessage.cliPath can point to any "stdin/stdout proxy command" (e.g., wrapper script: run imsg rpc via SSH on another Mac).

1. Ensure Messages is logged in.

2. Configure iMessage and start gateway.

#

If you want the bot to send with a separate iMessage identity (and keep your personal Messages clean), you can use a separate Apple ID + separate macOS user:

1. Create a separate Apple ID (e.g., [email protected]).

- Apple may require a phone number for verification/2FA.

2. Create a macOS user (e.g., openclawhome) and log in as that user.

3. Open Messages under that user and log in to iMessage with the bot Apple ID.

4. Enable Remote Login (System Settings → General → Sharing → Remote Login).

5. Install imsg:

- brew install steipete/tap/imsg

6. Configure SSH so ''ssh ''@localhost true'' succeeds without password.

7. Point channels.imessage.accounts.bot.cliPath to an SSH wrapper that runs imsg under the bot user identity.

First run hint: Sending/receiving may require approving GUI permissions (Automation + Full Disk Access) under the bot user. If imsg rpc appears stuck or exits immediately, switch to that user (you can use screen sharing), run imsg chats --limit 1 / imsg send ... once, approve the prompts, then retry.

Example wrapper (remember ''chmod +x'', and replace '''''' with your username):

#!/usr/bin/env bash
set -euo pipefail


exec /usr/bin/ssh -o BatchMode=yes -o ConnectTimeout=5 -T '<bot-macos-user>'@localhost \
  "/usr/local/bin/imsg" "$@"

Example configuration:

{
  channels: {
    imessage: {
      enabled: true,
      accounts: {
        bot: {
          name: "Bot",
          enabled: true,
          cliPath: "/path/to/imsg-bot",
          dbPath: "/Users/<bot-macos-user>/Library/Messages/chat.db",
        },
      },
    },
  },
}

Single-account scenario can use flattened fields (channels.imessage.cliPath, channels.imessage.dbPath), no need to write accounts.

#

If you want to put iMessage on another Mac, let channels.imessage.cliPath point to a wrapper that runs imsg remotely via SSH. OpenClaw only needs stdio.

Example wrapper:

#!/usr/bin/env bash
exec ssh -T gateway-host imsg "$@"

Remote attachments: When cliPath points to a remote host, attachment paths in the Messages database are local paths on the remote machine. You can set channels.imessage.remoteHost to let OpenClaw automatically fetch attachments via SCP:

{
  channels: {
    imessage: {
      cliPath: "~/imsg-ssh",
      remoteHost: "user@gateway-host",
      includeAttachments: true,
    },
  },
}

If remoteHost is not set, OpenClaw will try to infer from the SSH command in your wrapper script, but explicit configuration is recommended for reliability.

##

If gateway runs on a Linux host/VM but iMessage must run on Mac, Tailscale is the simplest bridge: gateway connects to Mac via tailnet, runs imsg via SSH, and fetches attachments via SCP.

Architecture:

┌──────────────────────────────┐          SSH (imsg rpc)          ┌──────────────────────────┐
│ Gateway host (Linux/VM)      │──────────────────────────────────▶│ Mac with Messages + imsg │
│ - openclaw gateway           │          SCP (attachments)        │ - Messages signed in     │
│ - channels.imessage.cliPath  │◀──────────────────────────────────│ - Remote Login enabled   │
└──────────────────────────────┘                                   └──────────────────────────┘
              ▲
              │ Tailscale tailnet (hostname or 100.x.y.z)
              ▼
        user@gateway-host

Configuration example (using Tailscale hostname):

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "~/.openclaw/scripts/imsg-ssh",
      remoteHost: "[email protected]",
      includeAttachments: true,
      dbPath: "/Users/bot/Library/Messages/chat.db",
    },
  },
}

Wrapper example (~/.openclaw/scripts/imsg-ssh):

#!/usr/bin/env bash
exec ssh -T [email protected] imsg "$@"

Notes:

- Ensure Mac is logged into Messages and Remote Login is enabled.

- Use SSH key to ensure ssh [email protected] works without prompts.

- remoteHost should match SSH target for SCP to fetch attachments.

Multi-account: Use ''channels.imessage.accounts'' to configure per account (optional ''name''). See shared structure at ''/gateway/configuration''. Do not commit ''~/.openclaw/openclaw.json'' (it usually contains tokens).

DMs:

- Default: channels.imessage.dmPolicy = "pairing".

- Unknown senders receive a pairing code; messages are not processed before approval (1 hour expiry).

- Approve:

- openclaw pairing list imessage

- ''openclaw pairing approve imessage ''''

- Pairing is the default token exchange for iMessage DMs. See ''Pairing''.

Groups:

- channels.imessage.groupPolicy = open | allowlist | disabled.

- When allowlist, channels.imessage.groupAllowFrom controls which senders can trigger.

- iMessage has no native mention metadata, so mention gating relies on agents.list[].groupChat.mentionPatterns (or messages.groupChat.mentionPatterns).

- With multiple agents, you can override per agent in agents.list[].groupChat.mentionPatterns.

- imsg streams message events; gateway normalizes them to a common channel envelope.

- Replies always return to the same chat id or handle.

Some iMessage threads may have multiple participants but still appear with is_group=false (depending on how Messages stores chat identifiers).

If you explicitly configure a chat_id in channels.imessage.groups, OpenClaw will treat that thread as a "group" (session isolation and group policies apply).