Connecting iMessage to Your Gateway with imsg

I’ve spent too much time trying to get my notifications into one place, only to hit a wall with closed messaging systems. It’s a common headache: you want your tools to talk to each other, but the one app your family or friends use is the hardest to integrate. If you are trying to bring iMessage into your OpenClaw setup using a Mac, the imsg integration is one way to get it done.

Just a heads-up: this is a legacy integration. If you are starting a brand new setup, I recommend looking at BlueBubbles instead. But if you need imsg, here is how I get it running.

What You’ll Need

Before you start, make sure your environment is ready. You need these four things:

• A Mac with Messages signed in.
• Full Disk Access granted to the process running OpenClaw (to read the Messages database).
• Automation permissions enabled to allow sending messages through Messages.app.
• The imsg CLI tool installed on your system.

Quick Start

You can get this running in about five minutes if you follow these four steps.

1. Install and verify imsg

First, grab the tool using Homebrew and make sure the RPC command is available.

brew install steipete/tap/imsg
imsg rpc --help

2. Configure OpenClaw

Add the iMessage channel to your configuration file. Replace <you> with your actual macOS username.

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

3. Start the gateway

Launch the gateway to initialize the connection.

openclaw gateway

4. Approve your first DM pairing

By default, direct messages use pairing mode. You need to list the pending requests and approve them using the code you receive.

openclaw pairing list imessage
openclaw pairing approve imessage <CODE>

Troubleshooting

Sometimes things don’t go as planned. Here are four common issues and how I fix them:

• imsg not found or RPC unsupported: Check your installation by running imsg rpc --help. If it fails, you might need to update imsg. You can also run openclaw channels status --probe to see what the gateway thinks.
• DMs are being ignored: Double-check your dmPolicy and allowFrom settings. Also, run openclaw pairing list imessage to see if there is a pending request you missed.
• Remote attachments fail: If you are running this over SSH, check your remoteHost setting. Ensure your SSH/SCP keys are set up so the gateway can fetch files without asking for a password.
• Missing macOS permission prompts: If you don’t see the pop-ups for Full Disk Access or Automation, run an interactive command in your terminal. Try imsg chats --limit 1 or imsg send <handle> "test" to trigger the system prompts.

If you hit a wall that isn’t covered here, check the AI Setup Assistant for help.

What’s Next

• Configuration reference - iMessage
• BlueBubbles (Recommended)
• Pairing Mode Details
• Gateway configuration