Connect Your Messaging App

By the end of this page, your agent will be reachable on your primary messaging app — the one you actually use.

Time: ~25 minutes

Pick your channel

For the Personal Assistant goal, you want a channel that feels native to how you text. Two options:

• WhatsApp — best if you're on iPhone or Android and WhatsApp is your main app
• iMessage — best if you're on Mac and use Messages heavily (requires a Mac running the Gateway)

Both work the same way once configured. Pick whichever feels more natural.

Option A: WhatsApp

WhatsApp uses QR code pairing — no API key needed.

1. Enable the channel:

{
  "channels": {
    "whatsapp": {
      "dmPolicy": "pairing"
    }
  }
}

2. Create the session directory:

mkdir -p ~/.openclaw/sessions/whatsapp

This must exist before authentication or the QR code step will fail with a confusing error.

3. Start the pairing process:

openclaw channels login --channel whatsapp

A QR code will appear in your terminal. On your phone:

1. Open WhatsApp → Settings → Linked Devices
2. Tap "Link a Device"
3. Scan the QR code

Your phone is now linked. The agent appears as a contact you can message directly.

3. Restart and verify:

openclaw gateway restart
openclaw gateway status

You should see whatsapp: connected.

Option B: iMessage

iMessage requires macOS and the Messages app.

1. Enable the channel:

{
  "channels": {
    "imessage": {
      "dmPolicy": "allowlist",
      "allowedContacts": ["+15551234567"]
    }
  }
}

Replace +15551234567 with your own phone number in E.164 format (country code + number, no spaces). This ensures only you can message the agent.

2. Grant permissions:

openclaw channels setup imessage

This walks you through granting the required accessibility and automation permissions in System Preferences.

3. Restart:

openclaw gateway restart

Open Messages and send yourself a message to the address you put in the allowlist. The agent will respond.

Send your first real task

Now that the channel is set up, test it with something useful:

• "Draft a reply to the last email I got from my boss. Keep it polite and brief."
• "Summarize this article: [paste a URL]"
• "Remind me to call the dentist tomorrow at 10am"

Your agent will respond directly in the conversation thread.

DM policies explained

You may have noticed dmPolicy in the config. This controls who can message your agent:

For a personal assistant you're the only one using, allowlist is the most secure. pairing is fine if you want to occasionally let others test it.