OpenClaw iMessage Setup: What Mac Users Need to Know First

Seventy percent of failed iMessage setups come from one skipped step: Full Disk Access. The other twenty percent come from testing with the wrong sender. Get those two things right and the rest of the setup is mechanical — run a command, approve a notification, send a test message.

Prerequisites Checklist

Work through this list before opening a terminal. Every item is a hard dependency. Missing one means the setup will fail, and the error messages from OpenClaw aren't always obvious about which requirement was skipped.

• macOS Ventura (13.0) or later — Check: Apple menu → About This Mac. Monterey and earlier will not work.
• OpenClaw installed — Verify with openclaw --version. If it fails, complete the installation guide first.
• OpenClaw authenticated — Run openclaw auth status. It should show your account as connected.
• Messages app installed and opened at least once — This initializes the chat.db database file that OpenClaw reads.
• Apple ID signed into iMessage — Open Messages → Settings (or Preferences) → iMessage tab. Your Apple ID must show as active with a green indicator.
• Full Disk Access granted to OpenClaw — See next section. This is the critical one.

Granting Full Disk Access to OpenClaw

This is the step that breaks most setups. OpenClaw needs to read ~/Library/Messages/chat.db — a file macOS explicitly protects with the Full Disk Access permission. Without it, OpenClaw can start, appear to connect, and silently fail to receive any messages.

Here's where most people stop. The permission was never granted, the pairing "worked," but messages never trigger the agent. Hours of debugging later, someone finds the System Settings toggle.

Grant it first. The steps:

1. Open System Settings (not System Preferences — that's Monterey and earlier).
2. Click Privacy & Security in the left sidebar.
3. Scroll down to Full Disk Access and click it.
4. Click the lock icon and authenticate with your Mac password.
5. Click the + button and navigate to the OpenClaw binary. By default it's at /usr/local/bin/openclaw or wherever your shell resolves which openclaw.
6. Ensure the toggle next to OpenClaw is turned on (blue).

Step-by-Step Channel Pairing

With prerequisites confirmed and Full Disk Access granted, the actual pairing is fast. We'll cover it completely — including exactly what each terminal output line means.

# Confirm OpenClaw can see the Messages database
openclaw doctor --channel imessage

# If doctor returns OK on all checks, proceed:
openclaw channels add imessage

After running openclaw channels add imessage, your terminal will display a pairing code and begin waiting. It looks like this:

OpenClaw iMessage Channel Setup
================================
Checking permissions...       ✓ Full Disk Access granted
Checking Messages database... ✓ Found at ~/Library/Messages/chat.db
Checking Apple ID...          ✓ Apple ID active

Pairing code: 7842-A19C
Waiting for approval in Messages app...
(Timeout in 120 seconds)

While the terminal is waiting, watch Messages. A system notification will appear asking to approve the OpenClaw connection. Click Approve. The terminal will confirm:

Connection approved.
Channel "imessage" added successfully.
Status: connected

Test your setup:
  Send a message to your Apple ID from another device
  Run: openclaw logs --channel imessage --tail 20

What if the notification doesn't appear?

Check that macOS notifications for Messages are not silenced. Go to System Settings → Notifications → Messages and confirm alerts are enabled. If Focus mode is on, it may suppress the pairing notification — disable it temporarily during setup.

Testing the Connection

Here's where most people make their second mistake. They send a test iMessage from their own Apple ID on the same Mac and wonder why nothing fires.

The rule: test with a message from a different Apple ID or a different phone number. The Messages database logs incoming messages differently depending on whether they're self-sent. Use your iPhone, ask a friend to send one message, or use a secondary Apple ID.

# Watch for incoming messages in real time
openclaw logs --channel imessage --tail 20 --follow

# From another device: send "hello openclaw" to your Mac's Apple ID
# You should see:
# [iMessage] Incoming from +1-555-0100: "hello openclaw"
# [Agent] Routing to default pipeline...
# [Agent] Reply sent: "..."

If the log shows the incoming message but no reply was sent, your agent pipeline may not have a default handler configured. Check your openclaw.config.yaml for an imessage pipeline block.

The 3 Common Errors and Exact Fixes

Error 1: Permission Denied on chat.db

Terminal output: PermissionError: [Errno 13] Permission denied: '/Users/yourname/Library/Messages/chat.db'

Fix: Full Disk Access is not granted or the toggle is off. Return to System Settings → Privacy & Security → Full Disk Access. If OpenClaw is listed but the toggle is off, turn it on. If it's not listed, use the + button to add it. After adding, run openclaw channels restart imessage.

Error 2: Pairing Timeout

Terminal output: Pairing timed out after 120s. Run 'openclaw channels add imessage' to try again.

Fix: The approval notification was missed or never appeared. Check that Messages notifications are not silenced in System Settings → Notifications. Disable Focus mode if active. Re-run openclaw channels add imessage — a new pairing code is generated each time.

Error 3: Messages Not Received by Agent

Status shows connected, but sending a message produces no agent response and nothing in the logs.

Fix checklist: (1) Confirm you're testing from a different Apple ID — not from yourself. (2) Confirm Messages is open on your Mac. (3) Run openclaw channels status imessage — if it shows polling_error, Full Disk Access was revoked. (4) Check your agent pipeline config in openclaw.config.yaml for a valid handler under the imessage channel key.

Frequently Asked Questions

Do I need to keep Messages app open for the OpenClaw iMessage channel to work?

Yes. OpenClaw reads from the Messages SQLite database, which only receives new entries when Messages is running. Close the app and incoming messages stop triggering your agent. Set Messages to launch at login to avoid this.

Why does openclaw channels add imessage say 'permission denied'?

This means Full Disk Access hasn't been granted to OpenClaw in System Settings. Go to System Settings → Privacy & Security → Full Disk Access, add OpenClaw, then restart the channel command. This is the most common setup blocker.

Can I run the iMessage channel without an Apple ID signed into Messages?

No. The Apple ID must be actively signed into iMessage in the Messages app. Without it, the chat.db file that OpenClaw monitors won't receive iMessage entries — only SMS messages if you have an iPhone paired via Continuity.

How do I test that the iMessage channel is working after setup?

Send a message from a different phone number or Apple ID to your Mac's iMessage address. Do not send from the same Apple ID — self-messages don't trigger the polling logic. Run openclaw logs --channel imessage to confirm the event was captured.

Does the iMessage setup process require any paid OpenClaw plan?

The iMessage channel is included in the free tier of OpenClaw. No paid plan is required for setup or basic operation. Rate limits on agent responses may apply depending on the model provider you have configured.

What happens if Full Disk Access is revoked after successful setup?

The channel stops receiving messages immediately. OpenClaw logs will show permission errors on the next polling cycle. Re-grant Full Disk Access in System Settings and run openclaw channels restart imessage to restore operation.