OpenClaw Manual OpenClaw

OpenClaw iMessage (Legacy) Channel

Messaging
Advanced

Connect OpenClaw to Apple iMessage using the imsg CLI tool on macOS. This legacy integration uses a JSON-RPC interface over stdio to read and send iMessages through the native macOS Messages database. Note: This channel is deprecated — for new setups, we strongly recommend using BlueBubbles instead, which provides a more robust REST API-based integration with broader feature support.

Quick Info
Difficulty Advanced
Category Messaging
Features Supported 2 / 6

iMessage (Legacy) Supported Features

Text Messages

Supported

Media & Files

Supported

Reactions

Not Supported

Threads

Not Supported

Voice Messages

Not Supported

Group Chat

Not Supported

iMessage (Legacy) Prerequisites

  • A Mac running macOS with Messages signed in to an Apple ID
  • Full Disk Access permission granted to both OpenClaw and the imsg binary
  • Automation permission for sending messages (granted via macOS TCC prompts)
  • The imsg CLI installed via Homebrew: brew install steipete/tap/imsg
  • OpenClaw Gateway installed and running

iMessage (Legacy) Quick Setup

1

Install the imsg CLI

Run 'brew install steipete/tap/imsg' to install the iMessage CLI tool. After installation, run 'imsg' once in a GUI terminal to trigger the macOS permission prompts for Full Disk Access and Automation.

2

Grant macOS permissions

Open System Settings > Privacy & Security. Grant Full Disk Access to both the imsg binary and the OpenClaw process. The Automation permission for Messages should be granted automatically when imsg first attempts to send a message.

3

Configure and start

Add the iMessage channel configuration to ~/.openclaw/openclaw.json with the cliPath and dbPath settings. Start the Gateway with 'openclaw start' and send a test iMessage to verify the connection.

iMessage (Legacy) Configuration Example

config.json 
{
  "channels": {
    "imessage": {
      "enabled": true,
      "cliPath": "/opt/homebrew/bin/imsg",
      "dbPath": "/Users/<username>/Library/Messages/chat.db"
    }
  }
}

iMessage (Legacy) Deep Dive

Deprecation Notice

The iMessage channel is a legacy integration that may be removed in future OpenClaw releases. It relies on the third-party imsg CLI and macOS-specific permissions (TCC) which can be fragile across OS updates. For new deployments, we strongly recommend migrating to the BlueBubbles channel, which offers: • REST API-based architecture (no CLI dependency) • Emoji reactions support • Group chat support • Cross-platform server management via web UI • More reliable webhook-based message delivery Existing iMessage setups will continue to work, but no new features will be added to this integration.
This channel is deprecated. Please use BlueBubbles for new iMessage integrations.

Architecture Overview

The iMessage integration works by spawning the imsg CLI as a child process using JSON-RPC over stdio: 1. The Gateway starts 'imsg rpc' as a subprocess, communicating via stdin/stdout. 2. The imsg CLI reads incoming messages from the macOS Messages database (chat.db) using SQLite. 3. When a new message arrives, imsg notifies the Gateway via JSON-RPC. 4. The Gateway processes the message through your AI agent and sends the reply back via imsg, which uses macOS Automation to send the iMessage. This architecture requires the Gateway to run on the same Mac where Messages is signed in. Replies are deterministically routed back to iMessage, and each conversation (DM or group) maintains an isolated session.

DM Policies

Direct Message policies control how the bot handles one-on-one iMessage conversations. **pairing (default)** — Unknown senders receive a pairing code that must be confirmed before the bot responds. This prevents unauthorized access. **allowlist** — Only phone numbers or Apple IDs listed in allowFrom can interact with the bot. **open** — Any iMessage sender receives a response. Use allowFrom: ["*"] to enable. **disabled** — The bot ignores all direct messages.
openclaw.json 
{
  "channels": {
    "imessage": {
      "dmPolicy": "pairing",
      "allowFrom": ["+1234567890", "user@icloud.com"]
    }
  }
}

Group Chat Configuration

Group chat policies control the bot's behavior in iMessage group conversations. **open** — The bot responds to all messages in any group it is added to. **allowlist** — The bot only responds in groups explicitly listed in the configuration. **disabled (default)** — The bot does not respond in group chats. When group chat is enabled, mention-based gating can be configured so the bot only responds when its name is mentioned, reducing noise in busy groups.
openclaw.json 
{
  "channels": {
    "imessage": {
      "groupPolicy": "allowlist",
      "mentionPattern": "@bot"
    }
  }
}

Remote Mac Setup via SSH

For headless or remote deployments, the imsg CLI can run on a different Mac via SSH. The Gateway spawns the imsg process over an SSH connection, and attachments are transferred using SCP. This is useful when the Mac running Messages is in a different location (e.g., a Mac Mini server), while the Gateway runs elsewhere. Requirements: • SSH key-based authentication (no interactive prompts) • The remote Mac must have imsg installed and permissions granted • SCP must be available for attachment transfers
openclaw.json 
{
  "channels": {
    "imessage": {
      "remoteHost": "mac-server.local",
      "cliPath": "/usr/local/bin/imsg"
    }
  }
}
Use SSH key authentication to avoid interactive password prompts.
Tools like Tailscale can simplify remote access to the Mac server.

macOS Permissions (TCC)

The iMessage integration requires specific macOS privacy permissions (managed by the TCC framework): **Full Disk Access** — Required for reading the Messages database (chat.db). Both the imsg binary and the OpenClaw process need this permission. **Automation** — Required for sending messages through the Messages app. This permission is typically granted via a system prompt when imsg first attempts to send. If running headless (e.g., via SSH or launchd), permission prompts may not appear. In this case, run 'imsg' once in an interactive GUI terminal session to trigger the prompts, then return to headless operation.
macOS permission prompts only appear in GUI sessions. Run imsg interactively at least once before deploying headlessly.

iMessage (Legacy) Configuration Reference

enabled
Type: boolean Default: true

Enable or disable the iMessage channel

cliPath
Type: string Default: "/usr/local/bin/imsg"

Path to the imsg CLI binary. Homebrew installs to /opt/homebrew/bin/imsg on Apple Silicon Macs or /usr/local/bin/imsg on Intel Macs

dbPath
Type: string Default: "~/Library/Messages/chat.db"

Path to the macOS Messages SQLite database

dmPolicy
Type: string Default: "pairing"

DM access policy: 'pairing', 'allowlist', 'open', or 'disabled'

groupPolicy
Type: string Default: "disabled"

Group chat policy: 'open', 'allowlist', or 'disabled'

allowFrom
Type: string[] Default: []

Phone numbers or Apple IDs allowed to contact the bot

includeAttachments
Type: boolean Default: false

Whether to ingest media attachments from incoming messages

mediaMaxMb
Type: number Default: 10

Maximum file size in MB for media attachments

textChunkLimit
Type: number Default: 4000

Maximum characters per outbound message chunk

chunkMode
Type: string Default: "length"

Text splitting mode: 'length' (character limit) or 'newline' (paragraph boundaries)

historyLimit
Type: number Default: 20

Maximum previous messages included as conversation context

configWrites
Type: boolean Default: true

Allow /config set|unset commands via iMessage

remoteHost
Type: string Default: ""

SSH hostname for running imsg on a remote Mac

iMessage (Legacy) Frequently Asked Questions

iMessage (Legacy) Troubleshooting

Bot does not receive or send messages

Missing macOS permissions (Full Disk Access or Automation) for the imsg binary or OpenClaw process.

Open System Settings > Privacy & Security. Verify Full Disk Access is granted to both imsg and OpenClaw. Run 'imsg' in a GUI terminal to trigger any missing permission prompts. Restart the Gateway after granting permissions.
Permission prompts do not appear

The process is running in a headless environment (SSH, launchd) where macOS cannot display TCC prompts.

Log into the Mac with a GUI session (screen sharing or physical access). Run 'imsg' in Terminal.app to trigger the prompts. Once permissions are granted, you can return to headless operation.
Error: chat.db not found or access denied

The dbPath configuration is incorrect or Full Disk Access has not been granted.

Verify the dbPath points to the correct Messages database (typically ~/Library/Messages/chat.db). Ensure Full Disk Access is enabled for the OpenClaw process in System Settings.
Remote SSH connection fails

SSH key authentication is not configured, or the remote host is unreachable.

Ensure SSH key-based authentication is set up between the Gateway host and the remote Mac. Test the connection manually with 'ssh <remoteHost> imsg --version'. Check firewall and network connectivity.
View Full Documentation Back to All Channels

Related Channels

WhatsApp

Medium

Connect OpenClaw via QR code using Baileys protocol

Setup Guide

Telegram

Easy

OpenClaw bot via Telegram grammY Bot API

Setup Guide

Discord

Easy

OpenClaw bot integration using discord.js

Setup Guide