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. The rest of this guide covers both, but I'll spend more time on BlueBubbles because that's what you should actually use.

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. This isn't optional; it's enforced before the request body is even read.

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. Run this in the same terminal context that runs your gateway to trigger the permission prompts:

imsg chats --limit 1
imsg send your@email.com "test"

If OpenClaw runs headless (via LaunchAgent or SSH), permissions must be granted in that user context — not your normal GUI session.

Access Control: Who Can Talk to Your Agent

This is the part most guides skip. 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",  // default
    },
  },
}

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

openclaw pairing list imessage
openclaw pairing approve imessage <CODE>

Pairing codes expire after 1 hour. 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. iMessage has no native mention metadata, so the agent will respond to every message in an allowed group unless you configure mention patterns:

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

For most setups, I'd recommend starting with DM-only access and adding 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 are significant: your personal messages stay completely separate, the agent has its own iMessage identity, and you can share that handle with whoever needs to contact it 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. Make sure the host key is in ~/.ssh/known_hosts before starting the gateway, otherwise attachment fetches fail silently.

Keeping Messages.app Alive

This one bites people on headless/VM setups. Messages.app can go "idle" — incoming events stop arriving until the app is foregrounded. The fix is to poke it every 5 minutes via AppleScript.

Save this as ~/Scripts/poke-messages.scpt:

try
  tell application "Messages"
    if not running then
      launch
    end if
    set _chatCount to (count of chats)
  end tell
on error
end try

Then install a LaunchAgent to run it on a 5-minute schedule. This is one of those annoying macOS quirks that's worth solving upfront — you don't want to discover at 2am that your agent has been missing messages for hours.

What Your AI Agent Can Do in iMessage

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

• 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 — it's the same OpenClaw session, just with an iMessage interface.

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. It can flag urgent messages, draft replies for your review, or respond to routine requests automatically.

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 — without any human needing to monitor the inbox.

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

Group handling is separately controlled. Check groupPolicy and groupAllowFrom. If the chat ID isn't explicitly 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. Test with:

ssh -T bot@your-mac "imsg chats --limit 1"

imsg RPC Unsupported

imsg rpc --help
openclaw channels status --probe

If probe reports RPC unsupported, update imsg:

brew upgrade steipete/tap/imsg

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. Strict allowlist to start, expand access as you build confidence in the agent's behavior.

For everything else — the full workspace setup, memory architecture, agent identity design, and the operational patterns that make AI agents actually useful — the playbook has it all.

Want the complete guide? Get The OpenClaw Playbook — $9.99