# iMessage

## Overview

The iMessage integration is a legacy external CLI tool that connects OpenClaw to Apple Messages on macOS.

**Note:** BlueBubbles is recommended for new setups. The `imsg` channel may be removed in future releases.

## Setup Requirements

The basic configuration involves three steps:

1. Ensure Messages is signed in
2. Install the `imsg` tool via Homebrew
3. Configure two paths in OpenClaw's settings

The system requires:
- Full Disk Access for OpenClaw + `imsg`
- Automation permissions for sending messages

## Account Configuration Options

Users can set up iMessage in single-account or multi-account modes. For isolated bot identities, the documentation describes creating a dedicated Apple ID and separate macOS user account, with Remote Login enabled for SSH access.

## Remote Setup

The integration supports running `imsg` on a remote Mac via SSH, with automatic attachment retrieval through SCP.

### Tailscale Example Architecture

A Linux Gateway connects to a Mac over a private network, enabling iMessage functionality without direct macOS hosting.

## Access Control

Two policy types manage permissions:

- **pairing** (default for DMs): Generates codes for unknown senders
- **allowlist**: Restricts group participation

The system uses mention patterns since iMessage lacks native mention metadata.

## Message Handling

- Messages are chunked to a configurable character limit (default 4000)
- Optional newline-based chunking splits on paragraph boundaries
- Group sessions receive isolated identifiers
- DM sessions share the agent's main context