iMessage Integration

OpenClaw integrates with iMessage on macOS using the imsg CLI tool. This allows you to send and receive iMessages, handle group chats, and manage rich content through your OpenClaw gateway.

Quick Setup

Prerequisites

macOS with Messages app signed in
Homebrew installed
Full Disk Access permissions

Basic Configuration

Install imsg CLI:

brew install steipete/tap/imsg

Configure OpenClaw (~/.openclaw/openclaw.json):

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "/usr/local/bin/imsg",
      dbPath: "/Users/YOUR_USERNAME/Library/Messages/chat.db"
    }
  }
}

Set macOS permissions:
- Open System Settings → Privacy & Security → Full Disk Access
- Add OpenClaw and imsg to the allowed applications
- Grant Automation permissions when prompted
Start the gateway:

openclaw gateway

Configuration Options

Basic Settings

{
  channels: {
    imessage: {
      // Enable/disable iMessage
      enabled: true,

      // CLI configuration
      cliPath: "/usr/local/bin/imsg",
      dbPath: "/Users/YOUR_USERNAME/Library/Messages/chat.db",

      // Contact filtering
      allowFrom: [
        "contact@example.com",
        "+15551234567",
        "John Appleseed"
      ],
      blockFrom: [
        "spam@example.com",
        "+15551112233"
      ],

      // Message handling
      messages: {
        maxMessageLength: 1000,
        mediaEnabled: true,
        readReceipts: true,
        typingIndicator: false
      }
    }
  }
}

Advanced Settings

{
  channels: {
    imessage: {
      // Group chat settings
      groups: {
        enabled: true,
        requireMention: false,
        mentionPatterns: ["@openclaw", "@ai"],
        // Group-specific settings
        "chat1234567890": { // chat_id
          requireMention: true,
          autoRespond: false
        }
      },

      // Media handling
      media: {
        downloadPath: "~/.openclaw/media/imessage",
        maxSize: "100MB",
        autoDownload: false,
        supportedTypes: ["image", "video", "audio", "document"]
      },

      // Command permissions
      commands: {
        enabled: true,
        prefix: "/",
        allowConfigWrites: true,
        allowedCommands: [
          "help", "status", "ping", "config"
        ]
      },

      // Process management
      process: {
        timeout: 30000,
        restartDelay: 5000,
        maxRestarts: 3
      },

      // Database settings
      database: {
        readOnly: false,
        backup: true,
        backupPath: "~/.openclaw/backups/imessage"
      }
    }
  }
}

Features

Direct Messages

Contact filtering: Control who can message your OpenClaw
Rich content: Send and receive images, videos, audio, documents
Read receipts: Optional read receipt functionality
Message history: Access to iMessage history

Group Chats

Group detection: Automatic identification of group chats
Chat-specific settings: Different behavior per group
Mention-based activation: Respond only when mentioned
Group isolation: Separate sessions for different groups

Media Support

Image handling: Send and receive photos
Video support: Handle video messages
Audio messages: Voice note support
Document sharing: File attachments

Command System

Built-in commands: /help, /status, /ping
Config commands: /config set, /config get
Custom commands: Define your own command handlers
Permission control: Restrict command usage

Usage Examples

Basic Commands

# Test iMessage connection
openclaw channels test imessage

# Check iMessage status
openclaw channels status imessage

# Send a message
openclaw message send --channel imessage --target "contact@example.com" --message "Hello from OpenClaw!"

# Send to phone number
openclaw message send --channel imessage --target "+15551234567" --message "Hi there!"

# Send media
openclaw message send --channel imessage --target "contact@example.com" --file ./photo.jpg

# View recent messages
openclaw channels logs imessage --limit 10

Interactive Usage

Once configured, you can interact with OpenClaw directly through iMessage:

You: @openclaw help
OpenClaw: Available commands:
- /help - Show this help message
- /status - Check gateway status
- /ping - Test connectivity
- /config set key=value - Update configuration

You: @openclaw Write a Python script to calculate fibonacci
OpenClaw: Here's a Python script that calculates Fibonacci numbers:

```python
def fibonacci(n):
    if n <= 1:
        return n
    return fibonacci(n-1) + fibonacci(n-2)

# Test the function
for i in range(10):
    print(f"F({i}) = {fibonacci(i)}")

You: @openclaw /status OpenClaw: Gateway Status:

Status: Running
Uptime: 1h 45m
iMessage: Connected
Messages processed: 23
Active chats: 2

## macOS Permissions Setup

### Full Disk Access

1. **Open System Settings**:
   - Go to **System Settings → Privacy & Security → Full Disk Access**

2. **Add applications**:
   - Click the `+` button
   - Add OpenClaw (usually in `/usr/local/bin/openclaw`)
   - Add imsg (usually in `/usr/local/bin/imsg`)

3. **Restart the gateway**:
```bash
openclaw gateway restart

Automation Permissions

When starting the gateway, you may see prompts for:

Messages automation: Allow OpenClaw to control Messages
Database access: Allow access to Messages database

Click OK on these prompts to grant necessary permissions.

Troubleshooting Permissions

# Check if imsg is accessible
imsg version

# Test database access
imsg list-chats

# Check OpenClaw permissions
openclaw channels test imessage --verbose

Advanced Features

Custom Contact Management

{
  channels: {
    imessage: {
      contacts: {
        // Contact aliases
        aliases: {
          "mom": "+15551234567",
          "work": "colleague@company.com"
        },

        // Contact groups
        groups: {
          "family": ["mom", "dad", "sister"],
          "work": ["boss@company.com", "colleague@company.com"]
        },

        // VIP contacts (always allow)
        vip: ["emergency@contact.com"]
      }
    }
  }
}

Message Templates

Create message templates for common responses:

{
  channels: {
    imessage: {
      templates: {
        "busy": "I'm currently busy, but I'll get back to you soon!",
        "away": "I'm away from my computer. I'll respond when I return.",
        "meeting": "I'm in a meeting. Please text me instead."
      }
    }
  }
}

Scheduled Messages

Schedule messages to be sent later:

# Schedule a message
openclaw message schedule --channel imessage --target "contact@example.com" --message "Don't forget our meeting!" --time "2024-01-15 09:00"

# List scheduled messages
openclaw message schedule list

# Cancel scheduled message
openclaw message schedule cancel --id 12345

Message Filtering

Filter incoming messages based on content:

{
  channels: {
    imessage: {
      filtering: {
        enabled: true,
        rules: [
          {
            name: "spam_filter",
            pattern: "\\b(buy now|free money|click here)\\b",
            action: "block",
            caseSensitive: false
          },
          {
            name: "urgent_filter",
            pattern: "\\burgent\\b|\\bemergency\\b",
            action: "priority",
            notify: true
          }
        ]
      }
    }
  }
}

Security Considerations

Privacy Protection

Contact filtering: Strict allowlist for contacts
Content filtering: Filter sensitive content
Message encryption: Messages stored encrypted
Access logs: Log all message access

Data Protection

Database backup: Regular backups of Messages database
Secure storage: Secure storage of sensitive data
Access control: Proper file permissions
Audit logging: Log all configuration changes

Network Security

Local only: iMessage integration is local-only
No external exposure: No network exposure of Messages data
Secure communication: Secure communication with imsg CLI

Troubleshooting

Common Issues

Permission Denied Errors

# Check Full Disk Access permissions
ls -la ~/Library/Messages/chat.db

# Test imsg CLI directly
imsg list-chats

# Grant permissions manually
sudo tccutil reset All com.apple.Messages

Messages Not Sending

# Check iMessage account status
imsg account-status

# Test message sending
imsg send --to "contact@example.com" --message "Test"

# Check gateway logs
openclaw gateway logs --filter imessage

Database Access Issues

# Check database permissions
sqlite3 ~/Library/Messages/chat.db ".tables"

# Repair database (if needed)
imsg repair-database

# Rebuild database index
imsg rebuild-index

imsg CLI Not Found

# Check if imsg is installed
which imsg

# Reinstall imsg
brew reinstall steipete/tap/imsg

# Update imsg
brew upgrade steipete/tap/imsg

Debug Mode

Enable detailed logging for iMessage:

# Enable debug logging
openclaw config set logging.components.imessage debug

# Restart with debug
openclaw gateway restart --debug

# View iMessage logs
openclaw gateway logs --follow --filter imessage

# Test with verbose output
openclaw channels test imessage --verbose

Best Practices

Permission Management
- Grant minimal necessary permissions
- Regular permission audits
- Document permission requirements
- Use secure permission practices
Contact Management
- Use contact aliases for easier management
- Regular contact list updates
- Implement proper contact filtering
- Maintain VIP contact lists
Message Handling
- Set appropriate message length limits
- Use message templates for consistency
- Implement proper content filtering
- Monitor message queue sizes
Performance
- Monitor database performance
- Regular database maintenance
- Optimize message processing
- Implement proper caching

API Reference

Channel Commands

# iMessage channel management
openclaw channels test imessage
openclaw channels status imessage [--detailed]
openclaw channels repair imessage

# Message operations
openclaw message send --channel imessage --target "contact@example.com" --message "Hello"
openclaw message send --channel imessage --target "+15551234567" --file ./image.jpg
openclaw message history --channel imessage --target "contact@example.com" --limit 50

# Contact management
openclaw contacts list --channel imessage
openclaw contacts add --channel imessage --alias "mom" --target "+15551234567"
openclaw contacts remove --channel imessage --alias "mom"

# Configuration
openclaw config set channels.imessage.allowFrom '["contact@example.com"]'
openclaw config get channels.imessage
openclaw config unset channels.imessage.blockFrom

Configuration Schema

interface iMessageConfig {
  enabled: boolean;
  cliPath: string;
  dbPath: string;
  allowFrom?: string[];
  blockFrom?: string[];
  groups?: {
    enabled?: boolean;
    requireMention?: boolean;
    mentionPatterns?: string[];
    [chatId: string]: {
      requireMention?: boolean;
      autoRespond?: boolean;
    };
  };
  messages?: {
    maxMessageLength?: number;
    mediaEnabled?: boolean;
    readReceipts?: boolean;
    typingIndicator?: boolean;
  };
  media?: {
    downloadPath?: string;
    maxSize?: string;
    autoDownload?: boolean;
    supportedTypes?: string[];
  };
  commands?: {
    enabled?: boolean;
    prefix?: string;
    allowConfigWrites?: boolean;
    allowedCommands?: string[];
  };
  contacts?: {
    aliases?: { [alias: string]: string };
    groups?: { [groupName: string]: string[] };
    vip?: string[];
  };
  templates?: { [templateName: string]: string };
  filtering?: {
    enabled?: boolean;
    rules?: Array<{
      name: string;
      pattern: string;
      action: "block" | "priority" | "forward";
      caseSensitive?: boolean;
      notify?: boolean;
    }>;
  };
}

Your iMessage integration is now ready! You can start sending and receiving messages through OpenClaw on macOS. 📱