🦞
Channel Integration

Connect OpenClaw to iMessage

Use your AI assistant directly through Apple Messages on macOS. Supports both iMessage and SMS.

macOS Only

The iMessage integration requires macOS with the Messages app configured. It uses the imsg CLI tool to read from the local Messages database.

Why Use iMessage?
  • +Native Apple Integration — Works with your existing Messages app
  • +iMessage + SMS — Supports both protocols seamlessly
  • +Read Receipts — Know when messages are delivered and read
  • +Reactions — iMessage reactions are supported
  • +Group Chats — Participate in group conversations
  • +Remote Gateway — Can work via SSH to a remote Mac
Requirements
  • 1.
    macOS

    With the Messages app configured and signed into your Apple ID

  • 2.
    Full Disk Access Permission

    Required for OpenClaw to read ~/Library/Messages/chat.db

  • 3.
    imsg CLI

    Command-line tool for interacting with Messages

Setup Steps

1

Install imsg CLI

Install the imsg command-line tool that OpenClaw uses to interact with Messages:

brew install imsg

Or download from the imsg GitHub releases page

2

Grant Full Disk Access

OpenClaw needs permission to read the Messages database:

  • - Open System Settings (or System Preferences)
  • - Go to Privacy & Security > Full Disk Access
  • - Click the + button and add Terminal (or iTerm)
  • - Also add the OpenClaw executable if running as a binary
3

Configure OpenClaw

Add the iMessage configuration to your openclaw.json config file:

{
  "channels": {
    "imessage": {
      "enabled": true,
      "cliPath": "imsg",
      "dbPath": "~/Library/Messages/chat.db",
      "allowFrom": ["+15555550123", "user@example.com"]
    }
  }
}
4

Set Up allowFrom

Specify who can interact with your bot:

  • - Phone numbers with country code: +15555550123
  • - Apple IDs (email addresses): user@example.com
5

Test the Connection

Verify the iMessage channel is working:

openclaw channels status imessage

Then send a message from an allowed contact to test the integration.

Advanced Configuration

Full configuration options for the iMessage channel:

{
  "channels": {
    "imessage": {
      "enabled": true,
      "cliPath": "imsg",
      "dbPath": "~/Library/Messages/chat.db",
      "remoteHost": "user@gateway-host",
      "dmPolicy": "pairing",
      "allowFrom": ["+15555550123", "user@example.com"],
      "historyLimit": 50,
      "includeAttachments": false,
      "mediaMaxMb": 16,
      "service": "auto",
      "region": "US"
    }
  }
}
  • cliPath — Path to the imsg CLI executable
  • dbPath — Path to the Messages database
  • remoteHost — SSH host for remote gateway setup
  • dmPolicy — How to handle direct messages
  • allowFrom — Phone numbers or Apple IDs allowed to message
  • historyLimit — Number of messages to include as context
  • includeAttachments — Enable attachment handling
  • mediaMaxMb — Maximum attachment size in MB
  • service — Force iMessage or SMS, or use auto
  • region — Region for phone number formatting
Remote Gateway Setup (Optional)

If you want to run OpenClaw on a server but access iMessage from a Mac at home, you can use SSH:

{
  "channels": {
    "imessage": {
      "enabled": true,
      "remoteHost": "user@your-mac.local",
      "cliPath": "/usr/local/bin/imsg"
    }
  }
}
  • - Ensure SSH key authentication is set up
  • - The Mac must be always on and connected
  • - imsg and Full Disk Access must be configured on the Mac
Supported Features
OKRead Receipts
OKiMessage Reactions
OKGroup Chats
OKSMS Support
OPTAttachments (optional)
OKMessage History
Troubleshooting

Permission denied when reading chat.db?

Make sure you have granted Full Disk Access to Terminal/iTerm and the OpenClaw executable. You may need to restart the terminal after granting access.

Bot not responding to messages?

Verify the phone number or Apple ID in allowFrom matches exactly. Phone numbers need the + and country code.

Can't find chat.db?

The default path is ~/Library/Messages/chat.db. Make sure the Messages app has been opened at least once and you are signed in.

imsg command not found?

Ensure imsg is installed and in your PATH. You can specify the full path in cliPath.

Remote gateway not connecting?

Verify SSH key authentication works with ssh user@host and that the remote Mac has imsg installed with Full Disk Access.

iMessage Connected!

Add more channels or configure skills to customize your AI assistant.

Add WhatsAppExplore Skills