Can I use OpenClaw via iMessage from my iPhone?

Yes — that's the main use case. You message the agent from your iPhone using iMessage, and it responds through the Mac running OpenClaw. Your iPhone and Mac need to share the same Apple ID and have iMessage enabled on both devices. Messages appear in your standard Messages app.

Does it work if my Mac is asleep?

No. The Mac needs to be awake and running the OpenClaw Gateway for iMessage to work. If your Mac sleeps, messages you sent will be delivered when it wakes, but the agent won't respond until then. Use Power Nap on Mac or adjust sleep settings if you need more availability.

Can I run this on Linux or Windows?

No. iMessage integration uses the macOS Messages framework, which only exists on Apple hardware running macOS 13 Ventura or later. It cannot run inside a virtual machine either — the Messages framework requires a real Apple environment. For cross-platform use, set up Telegram or Signal instead.

iMessage – HowOpenClaw

iMessage integration requires a Mac running the agent because it relies on the macOS Messages framework. You can't run the iMessage channel on Linux or Windows — even in a VM, the Messages framework won't be available.

If you're on macOS and want the most natural, personal channel, this is the one to set up first. iMessage is the one OpenClaw channel that requires a Mac — see system requirements for details. Like every other channel, it adds no subscription cost — you pay only your AI provider's API fees.

Check prerequisites

macOS 13 Ventura or later
Apple ID signed into the Messages app
OpenClaw gateway running on that Mac

The Mac must remain powered on and awake for iMessage to work. If it sleeps, messages queue and deliver when it wakes — but proactive cron-triggered messages won't fire during sleep.

Configure OpenClaw

Add the iMessage channel to ~/.openclaw/openclaw.json:

{
  "channels": {
    "imessage": {
      "enabled": true,
      "dmPolicy": "allowlist",
      "allowedContacts": [
        "+15551234567",
        "+447700900123"
      ],
      "groupPolicy": "mention",
      "requireMention": true,
      "responseDelay": 2500
    }
  }
}

Phone numbers must include the country code in E.164 format — this is the #1 source of allowlist failures:

Format	Works?
`+15551234567`	✅ Yes
`+1 555 123 4567`	❌ No
`(555) 123-4567`	❌ No
`5551234567`	❌ No

Restart the gateway

openclaw gateway restart

Test the connection

Send yourself a test message from another Apple device:

Hello, are you there?

If configured correctly, your agent will respond. If not:

openclaw logs --filter imessage

Common issues: Messages app not signed in, Mac in sleep mode, phone number format errors in allowedContacts.

Group Chat Behavior

With requireMention: true, your agent only responds in group chats when explicitly @mentioned. Without this, it will respond to every message in every group — which is almost never what you want.

Recommended group policies by use case:

Family group chat: groupPolicy: mention — respond only when asked
Dedicated work group: groupPolicy: always — always respond
Social groups: groupPolicy: never — don't respond at all

Startup Reliability (v2026.4.12)

As of v2026.4.12, iMessage startup has been improved:

Transient watch.subscribe startup failures now retry before tearing down the monitor
Startup error logging is sanitized so brief local transport stalls don't bounce the channel or leak raw imsg RPC payloads into logs
The channel is now more resilient to temporary network hiccups during initialization

New in v2026.4.15

The startup reliability improvements from v2026.4.12 remain the current baseline. If you are upgrading from a version prior to v2026.4.12 and experiencing startup issues with the iMessage channel, ensure you have completed the upgrade fully — the retry logic and sanitized error logging described above require at least v2026.4.12.

Self-Chat Detection

OpenClaw correctly distinguishes between normal DM outbound messages and true self-chat. It uses destination_caller_id plus chat participants to identify self-chat scenarios, preserves multi-handle self-chat aliases, drops ambiguous reflected echoes, and strips wrapped RPC text fields.

WhatsApp — Android users or those without a Mac running the agent
Telegram — cross-platform alternative that doesn't require macOS

Tips for Daily Use

Set a response delay. A 2–3 second delay (responseDelay: 2500) makes responses feel more conversational and less robotic. The instant response of a chatbot is actually jarring in a personal messaging context.

Use reactions. If you've installed the Reactions skill, your agent can send iMessage reactions (hearts, thumbs up, etc.) in addition to text responses.

Voice notes. With the audio transcription skill installed, you can send voice messages and your agent will transcribe and respond to them.

Something not working?

Check the troubleshooting guide for common issues with gateway startup, channel connections, and automations.