iMessage AI: Connect OpenClaw to Apple Messages

Your iMessage inbox is probably one of the highest-signal communication channels you have. Team members, family, clients — all mixed together in one place. And right now, your AI agent can't touch any of it.

That changes with OpenClaw's iMessage integration. Whether you want an AI that triages messages while you're heads-down, a personal assistant that drafts replies for you to approve, or a fully autonomous agent that handles support requests from a dedicated Apple ID — it's all possible.

This guide covers both the recommended path (BlueBubbles) and the legacy approach (imsg CLI), with real config examples and the gotchas that will bite you if you skip ahead.

Two Paths to iMessage

OpenClaw supports iMessage via two different mechanisms. Which one you use depends on your setup:

• BlueBubbles (recommended) — A macOS helper app that exposes iMessage via a local REST API. OpenClaw talks to it over HTTP. Richer API, easier setup, better attachment support.
• imsg CLI (legacy) — A command-line tool that wraps the native Messages database over JSON-RPC on stdio. Still works, but officially legacy and may be removed in a future OpenClaw release.

If you're setting this up fresh today, use BlueBubbles.

BlueBubbles Setup (Recommended)

Step 1: Install BlueBubbles on Your Mac

BlueBubbles is a free macOS app that turns your Mac into an iMessage server. Download it from bluebubbles.app and install it.

During setup, enable the web server (it runs on a port you choose — 1234 is common) and set a server password. You'll need both for the OpenClaw config.

Compatibility note: BlueBubbles works on macOS Sequoia (15) and macOS Tahoe (26). On Tahoe, message editing is currently broken, and group icon updates may not sync — but send/receive works fine.

Step 2: Configure OpenClaw

Add the BlueBubbles channel to your OpenClaw config:

{
  channels: {
    bluebubbles: {
      enabled: true,
      serverUrl: "http://127.0.0.1:1234",
      password: "your-bluebubbles-password",
      webhookPath: "/bluebubbles-webhook",
    },
  },
}

If your Mac and OpenClaw gateway are on the same machine, 127.0.0.1 works. If OpenClaw runs on a separate server (VPS, Raspberry Pi), use your Mac's local IP or Tailscale address.

Step 3: Point BlueBubbles Webhooks to OpenClaw

In the BlueBubbles server settings, configure the webhook URL to point to your OpenClaw gateway:

https://your-gateway-host:3000/bluebubbles-webhook?password=your-bluebubbles-password

The password in the query string is required — OpenClaw rejects incoming webhooks that don't include it.

Step 4: Start the Gateway

Run openclaw gateway and OpenClaw will register the webhook handler and start listening. Send yourself a test message to verify the connection.

Legacy imsg Setup

If you have an existing setup using the legacy imsg path, start with the install:

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

Then configure OpenClaw:

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

Before this works, you'll need to grant Full Disk Access and Automation permissions to the process context running OpenClaw.

Access Control: Who Can Talk to Your Agent

Without proper access control, you're handing an AI agent access to every iMessage that hits your Mac. That's not what you want.

DM Policy

The default DM policy is pairing — anyone who messages the Apple ID running OpenClaw must be approved before the agent responds:

{
  channels: {
    imessage: {
      dmPolicy: "pairing",
    },
  },
}

When a new sender messages you, OpenClaw generates a pairing code. You approve it with:

openclaw pairing list imessage
openclaw pairing approve imessage <CODE>

For a tighter setup, switch to allowlist and explicitly whitelist handles:

{
  channels: {
    imessage: {
      dmPolicy: "allowlist",
      allowFrom: [
        "+15551234567",
        "team@company.com",
        "your@email.com",
      ],
    },
  },
}

Group Chats

Group message handling is separate from DMs. The default group policy is allowlist when configured:

{
  channels: {
    imessage: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["chat_id:123456"],
    },
  },
}

For most setups, start with DM-only access and add groups only when you have a clear use case.

Dedicated Apple ID: The Right Architecture

Here's the pattern that actually works well in production: don't run your AI agent on your personal Apple ID. Create a dedicated one.

1. Create a new Apple ID for your agent (e.g., hex-agent@icloud.com)
2. Create a dedicated macOS user on your Mac
3. Sign into Messages with the agent Apple ID in that user
4. Install imsg or BlueBubbles in that user context
5. Configure OpenClaw to use that user's Messages DB path

The advantages: your personal messages stay completely separate, the agent has its own iMessage identity, and you can share that handle without mixing up your inbox.

Remote Mac Setup (Over Tailscale)

One common production pattern: your OpenClaw gateway runs on a Linux server or Raspberry Pi, but iMessage requires a Mac. Here's how to bridge them with the imsg path.

On the Linux gateway, create a wrapper script at ~/.openclaw/scripts/imsg-ssh:

#!/usr/bin/env bash
exec ssh -T bot@mac-mini.tailnet-1234.ts.net imsg "$@"

Make it executable and reference it in your config:

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "~/.openclaw/scripts/imsg-ssh",
      remoteHost: "bot@mac-mini.tailnet-1234.ts.net",
      includeAttachments: true,
      dbPath: "/Users/bot/Library/Messages/chat.db",
    },
  },
}

The remoteHost field enables SCP for attachment fetches — without it, you get text only.

What Your AI Agent Can Do in iMessage

Once connected, OpenClaw gives your agent the standard message tool plus iMessage-specific capabilities:

• Read and reply to DMs and group chats — with the same persona and skills as your Slack/Discord setup
• Send and receive attachments — images, files, links with previews
• Message effects — BlueBubbles supports iMessage effects in replies
• Typing indicators and read receipts — for a more natural feel
• Reply threading — reply to specific messages in a thread
• Edit and unsend (BlueBubbles only, macOS Sequoia)

The agent's responses, tools, and memory work exactly the same as on any other channel.

Practical Use Cases

Personal Message Triage

Connect your personal Apple ID, set a strict allowlist, and have the agent categorize and summarize messages when you're in focus mode.

Team Support Channel

Spin up a dedicated Apple ID for your team's support channel. Everyone on the team texts that number. The agent handles FAQs, escalates to a human when needed, and logs everything to Slack.

Customer Hotline

For businesses where iMessage is a primary customer contact channel, a dedicated agent Apple ID can handle intake, answer common questions, and route complex issues.

Troubleshooting

Agent Ignoring DMs

Check channels.imessage.dmPolicy and channels.imessage.allowFrom. If using pairing mode, list pending requests:

openclaw pairing list imessage

Agent Ignoring Group Messages

Check groupPolicy and groupAllowFrom. If the chat ID isn't listed and groupPolicy is allowlist, messages are silently dropped.

Remote Attachments Failing

Verify remoteHost is set correctly, the host key is in known_hosts, and SSH key auth works non-interactively.

Summary

Getting OpenClaw on iMessage is more involved than Slack or Telegram — it requires a Mac, specific permissions, and either BlueBubbles or the legacy imsg tool. But once it's running, it opens up one of the most personal and high-signal communication channels you have.

The recommended path: BlueBubbles on a dedicated macOS user with a dedicated Apple ID, connected to an OpenClaw gateway running on your always-on machine.

Originally published at openclawplaybook.ai. Get The OpenClaw Playbook — $9.99.