iMessage Setup

New to channel setup? For a hands-on, step-by-step tutorial, check out our Channel Setup Tutorial. This page is a comprehensive reference covering all iMessage features and configuration options.

iMessage is Apple's native messaging platform integrated into macOS. OpenClaw (formerly Moltbot, Clawdbot) connects to iMessage using the imsg library, enabling seamless integration with your Messages app for direct messages and group chats.

Setting up iMessage requires macOS and a signed-in Messages app:

1. Ensure you're on macOS
2. Sign in to Messages app with your Apple ID
3. Configure in OpenClaw
4. Start messaging!

macOS Only

iMessage integration is macOS only. This feature requires:

• macOS - Any recent version of macOS (macOS 10.14 or later recommended)
• Messages App - The built-in Messages app must be installed and functional
• Apple ID - You must be signed in to Messages with your Apple ID
• iMessage Enabled - iMessage must be enabled in Messages settings

Messages App Setup

Before configuring OpenClaw, ensure Messages is properly set up:

1. Open the Messages app on your Mac
2. Go to Messages → Settings (or Preferences)
3. Sign in with your Apple ID if not already signed in
4. Enable iMessage in the iMessage tab
5. Verify your phone number and email are registered

Configure iMessage in your OpenClaw configuration file:

{
  "channels": {
    "imessage": {
      "enabled": true
    }
  }
}

Basic Configuration

iMessage requires minimal configuration. Simply enable it in your config file. OpenClaw will automatically detect and connect to your Messages app.

Group Configuration

Control which group chats OpenClaw responds to:

{
  "channels": {
    "imessage": {
      "enabled": true,
      "groups": ["group-id-1", "group-id-2"]
    }
  }
}

When groups is set, it becomes a group allowlist. Only groups listed will receive responses. To allow all groups, include "*" in the array:

{
  "channels": {
    "imessage": {
      "enabled": true,
      "groups": ["*"]
    }
  }
}

OpenClaw supports various iMessage features:

• Direct Messages - One-on-one conversations with contacts
• Group Chats - Participate in iMessage group conversations
• Rich Media - Send and receive images, videos, and files
• Read Receipts - See when messages are read
• Reactions - Support for message reactions
• Threading - Handle reply threads in group chats
• Typing Indicators - Show typing status

Group Allowlist

Control which groups OpenClaw responds to using the groups configuration option. This is important for privacy and to prevent unwanted responses in group chats.

Finding Group IDs

To add a group to the allowlist, you need its group ID. Group IDs are typically long strings that identify the group chat. You can find them in OpenClaw logs when a message is received from a group.

Group Behavior

• Mention-Based - By default, OpenClaw may require mentions in groups
• Always Respond - Can be configured to respond to all messages
• Isolated Sessions - Each group gets its own session

Native Integration

iMessage integration uses macOS's native Messages framework, providing:

• Seamless Access - Direct access to Messages database
• Real-Time Updates - Instant message delivery
• System Integration - Works with macOS notifications
• No External Services - All processing happens locally

Permissions

OpenClaw may require certain macOS permissions:

• Full Disk Access - To access Messages database (may be required)
• Accessibility - For advanced features (optional)

Grant these permissions in System Settings → Privacy & Security if prompted.

Privacy

• Local Processing - All messages are processed locally on your Mac
• No Cloud Sync - Messages stay on your device
• Group Control - Use allowlists to control group access
• Secure Storage - Messages database is encrypted by macOS

Best Practices

• Use Group Allowlists - Control which groups can message the bot
• Monitor Logs - Regularly check OpenClaw logs for issues
• Keep macOS Updated - Ensure macOS is up to date for security
• Secure Your Mac - Use FileVault and strong passwords

Messages Not Received

If messages aren't being received:

1. Verify Messages app is signed in with Apple ID
2. Check iMessage is enabled in Messages settings
3. Ensure OpenClaw Gateway is running
4. Check OpenClaw has necessary permissions
5. Review Gateway logs for iMessage channel errors
6. Restart Messages app if needed

Permission Errors

If you encounter permission errors:

1. Go to System Settings → Privacy & Security
2. Grant Full Disk Access to OpenClaw if prompted
3. Check Accessibility permissions if needed
4. Restart OpenClaw Gateway after granting permissions

Group Messages Not Working

If group messages aren't working:

1. Check groups configuration includes the group ID
2. Verify group ID is correct (check logs)
3. Ensure "*" is in groups array if you want all groups
4. Check group chat is active in Messages app

Messages App Not Responding

If Messages app integration fails:

1. Quit and restart Messages app
2. Sign out and sign back in to Messages
3. Restart OpenClaw Gateway
4. Check macOS system logs for Messages errors
5. Verify macOS version is compatible