iMessage Channel

Connect OpenClaw to iMessage on macOS using Messages.app integration

iMessage integration on macOS allows OpenClaw to send and receive messages through Apple’s Messages app. This requires system-level access to the Messages database and AppleScript automation.

macOS only - iMessage integration is only available on macOS. It requires Full Disk Access permissions and cannot be sandboxed.

Prerequisites

• macOS 10.15 (Catalina) or later
• Messages.app configured with iMessage
• imsg CLI tool (optional but recommended)
• Full Disk Access for Terminal/OpenClaw

Quick Start

The interactive onboarding can guide you through iMessage setup:

openclaw init

Select iMessage and follow the prompts.

Installing imsg

Using Homebrew

brew install imsg

From Source

git clone https://github.com/CamHenlin/imsg.git
cd imsg
npm install -g .

Verify Installation

imsg --version

Granting Permissions

1. Grant Full Disk Access

   iMessage integration requires access to the Messages database.

   1. Open System Settings → Privacy & Security → Full Disk Access
   2. Click the + button
   3. Add:
      • Terminal.app (if running OpenClaw from Terminal)
      • OpenClaw.app (if using the Mac app)
   4. Restart Terminal/OpenClaw after granting access
2. Grant Automation Access

   AppleScript automation requires explicit permission.

   1. Open System Settings → Privacy & Security → Automation
   2. Find Terminal or OpenClaw in the list
   3. Enable Messages.app

   You may be prompted to grant access the first time OpenClaw tries to send a message.

3. Verify Messages.app is signed in

   Open Messages.app and ensure you’re signed in with your Apple ID. Send a test message to verify iMessage is working.

Configuration

Basic Setup

Configure iMessage in openclaw.config.json:

{
  "channels": {
    "imessage": {
      "enabled": true,
      "cliPath": "imsg",
      "dmPolicy": "pairing",
      "allowFrom": []
    }
  }
}

Key	Type	Default	Description
enabled	boolean	false	Enable iMessage channel
cliPath	string	"imsg"	Path to imsg binary
dbPath	string	Auto-detected	Path to Messages database (usually ~/Library/Messages/chat.db)
dmPolicy	string	"pairing"	DM access policy: pairing, allowlist, open, disabled
allowFrom	string[]	[]	Allowed handles (phone numbers, emails, or chat IDs)

DM Policies

• pairing (recommended): Unknown senders get a pairing code; approve with openclaw pairing approve imessage <handle>
• allowlist: Only handles in allowFrom can message
• open: Anyone can message (set allowFrom: ["*"])
• disabled: Ignore all iMessages

AllowFrom Formats

iMessage supports several identifier formats:

Phone numbers (E.164 format):

{
  "channels": {
    "imessage": {
      "allowFrom": ["[phone]", "[phone]"]
    }
  }
}

Email addresses:

{
  "channels": {
    "imessage": {
      "allowFrom": ["[e-mail]", "[e-mail]"]
    }
  }
}

Chat identifiers:

{
  "channels": {
    "imessage": {
      "allowFrom": [
        "chat_id:123",
        "chat_guid:iMessage;-;[phone]",
        "chat_identifier:chat123456789"
      ]
    }
  }
}

Group Chat Configuration

iMessage group chats are identified by a chat ID or GUID. To configure per-group settings:

{
  "channels": {
    "imessage": {
      "chats": {
        "chat123": {
          "enabled": true,
          "requireMention": false,
          "allowFrom": ["[phone]"],
          "toolPolicy": "open"
        }
      }
    }
  }
}

Get chat IDs with:

imsg chats --limit 20

Listing Chats

To see available chats:

imsg chats --limit 50

Output includes:

• Chat ID
• Display name (for group chats)
• Participants
• Last message date

Media Handling

iMessage supports:

• Images (JPEG, PNG, HEIC)
• Videos (MOV, MP4)
• Audio files
• Voice memos
• Files and documents

Media attachments are automatically downloaded and processed.

Reactions

iMessage supports “Tapback” reactions:

• ❤️ Love
• 👍 Thumbs Up
• 👎 Thumbs Down
• 😂 Laugh
• !! Emphasize
• ?? Question

{
  "channels": {
    "imessage": {
      "reactions": {
        "enabled": true
      }
    }
  }
}

Multi-Account Support

You can configure multiple iMessage accounts (rare, but supported):

{
  "channels": {
    "imessage": {
      "accounts": {
        "personal": {
          "enabled": true,
          "service": "iMessage",
          "allowFrom": ["[phone]"]
        },
        "sms": {
          "enabled": true,
          "service": "SMS",
          "allowFrom": ["[phone]"]
        }
      }
    }
  }
}

Troubleshooting

Full Disk Access denied

Without Full Disk Access, OpenClaw cannot read the Messages database.

1. Open System Settings → Privacy & Security → Full Disk Access
2. Add Terminal.app or OpenClaw.app
3. Restart the application after granting access

Verify access:

ls ~/Library/Messages/chat.db

If this shows “Operation not permitted”, access is not granted.

Cannot send messages

This usually means Automation permission is missing.

1. Try sending a message manually - you should see a permission prompt
2. If no prompt appears:
   • Open System Settings → Privacy & Security → Automation
   • Find Terminal or OpenClaw
   • Enable Messages.app
3. Restart OpenClaw

Test with imsg:

imsg send -h "[phone]" -m "Test message"

imsg not found

Ensure imsg is installed and in your PATH:

which imsg

If not found:

1. Install via Homebrew: brew install imsg
2. Or specify full path in config:

{
  "channels": {
    "imessage": {
      "cliPath": "/usr/local/bin/imsg"
    }
  }
}

Messages not being received

Check these:

1. Messages.app is running and signed in
2. Sender is in allowFrom (if using allowlist policy)
3. Database polling is working

Check logs:

openclaw logs --follow | grep imessage

Verify database access:

imsg chats --limit 10

Database locked error

The Messages database can only be accessed by one process at a time.

• Close Messages.app preferences if open
• Ensure no other tools are accessing the database
• Restart Messages.app

If persistent, restart macOS.

Group chats not working

Group chats require:

1. All participants using iMessage (blue bubbles)
2. Correct chat ID in configuration

List group chats:

imsg chats --limit 50 | grep -i group

Add the chat ID to your config.

Limitations

• macOS only - Cannot run on Linux or Windows
• Requires Messages.app - Must be running and signed in
• SMS limitations - SMS (green bubbles) may have limited features
• Polling-based - Message delivery is not instant (typically 1-5 seconds)
• No read receipts - Cannot detect when messages are read
• Sandbox incompatible - Cannot run in a sandboxed environment

Advanced Configuration

Custom Database Path

{
  "channels": {
    "imessage": {
      "dbPath": "/Users/username/Library/Messages/chat.db"
    }
  }
}

Service Type

iMessage supports both iMessage and SMS:

{
  "channels": {
    "imessage": {
      "service": "iMessage"
    }
  }
}

Options:

• "iMessage" (default) - iMessage only (blue bubbles)
• "SMS" - SMS/MMS (green bubbles, requires iPhone)

Polling Interval

{
  "channels": {
    "imessage": {
      "pollInterval": 2000
    }
  }
}

Interval in milliseconds (default: 2000 = 2 seconds).

Security Considerations

• Full Disk Access is required - this grants broad system access
• Messages database contains all your iMessage history
• Automation access allows sending messages on your behalf
• Use allowlist mode to restrict who can access your bot
• Backup your database regularly (it’s in ~/Library/Messages/)

Next Steps

Pairing Guide

Learn about pairing codes and approvals

WhatsApp Setup

Set up WhatsApp as another channel

Configuration Reference

Full configuration options

Multi-Channel

Using multiple channels together