iMessage (imsg)

Legacy iMessage integration via imsg CLI over JSON-RPC on stdio. New setups should use BlueBubbles instead.

iMessage (legacy) is OpenClaw's original iMessage integration, connecting your AI agent to Apple's messaging ecosystem via the imsg command-line tool. Gateway spawns 'imsg rpc' and communicates over JSON-RPC on stdio — no separate daemon or port required. The imsg CLI reads directly from the macOS Messages chat.db database and sends messages through Messages.app via AppleScript automation. This integration requires a Mac with Full Disk Access permissions (for chat.db access) and Automation permissions (for sending messages). The imsg CLI is installed via Homebrew from steipete's tap. For remote setups, you can point cliPath at a wrapper script that SSHes to a remote Mac, with optional SCP-based attachment fetching when remoteHost is configured. The legacy imsg channel supports text, images, audio, video, files, and group chats — but lacks reactions, message editing, unsend, message effects, and threading that BlueBubbles provides. It's a text-and-media-only integration. Access control follows the standard OpenClaw pairing/allowlist model for DMs, with group policies for group chat management. This channel is officially deprecated. The OpenClaw docs recommend BlueBubbles for all new iMessage setups. The imsg integration may be removed in a future release. If you're currently using it and it works for your needs, it will continue functioning, but new features will only land in BlueBubbles. Community discussions on GitHub have requested retaining imsg support, but the official stance is migration to BlueBubbles.

Tags: messaging, imessage, apple, macos, legacy

Category: Messaging

Use Cases

  • Legacy iMessage automation for users already running the imsg CLI
  • Remote Mac iMessage access via SSH for headless server setups
  • Simple text-and-media iMessage bot without rich features

Tips

  • Migrate to BlueBubbles when possible — it has more features and easier setup
  • For remote setups, create a simple SSH wrapper script that just runs 'exec ssh -T gateway-host imsg "$@"'
  • Test imsg manually before configuring OpenClaw: 'imsg chats --limit 1' and 'imsg send <handle> "test"'
  • Use attachmentRoots to restrict which directories imsg can access for security
  • If running headless, trigger all macOS permission prompts interactively first in the same process context

Known Issues & Gotchas

  • This is a DEPRECATED integration — use BlueBubbles for all new setups
  • Full Disk Access must be granted to the exact process context running OpenClaw — if you run via LaunchAgent or SSH, grant access to that context specifically
  • Run 'imsg chats --limit 1' interactively first to trigger macOS permission prompts — they won't appear in headless mode
  • The dbPath defaults to /Users/<you>/Library/Messages/chat.db — get the exact path right or messages won't be read
  • SSH wrapper scripts must be executable (chmod +x) and the remote host key must exist in ~/.ssh/known_hosts
  • remoteHost must be 'host' or 'user@host' format only — no SSH options or spaces
  • Pairing codes expire after 1 hour
  • If remoteHost is not set, OpenClaw tries to auto-detect it by parsing the SSH wrapper — this can fail with non-standard wrappers

Alternatives

  • BlueBubbles
  • WhatsApp
  • Telegram

Community Feedback

Request: Retain support for the imsg iMessage integration. The current OpenClaw documentation lists imsg as a legacy integration but does not provide any SIP-compatible alternative for Sequoia.

— GitHub Issues

iMessage via imsg has been a nightmare: Installed imsg via brew, set cliPath and dbPath in config. Manual 'imsg chats --limit 1' works fine but OpenClaw can't read messages.

— Reddit r/clawdbot

OpenClaw has a legacy 'imsg' integration (Homebrew CLI), but for new setups the docs recommend BlueBubbles and note imsg is deprecated.

— Discord (Answer Overflow)

Frequently Asked Questions

Should I use iMessage (legacy) or BlueBubbles?

Always use BlueBubbles for new setups. The legacy imsg integration is deprecated and lacks reactions, edits, effects, and group management features. It may be removed in a future OpenClaw release.

Why can't OpenClaw read my messages even though imsg works manually?

Full Disk Access must be granted to the exact process context running OpenClaw. If you test imsg in Terminal but run OpenClaw via LaunchAgent, they're different process contexts. Grant Full Disk Access to the correct binary/app.

Does the imsg integration work on macOS Sequoia?

It can work but may require additional permission configuration. Community reports suggest macOS Sequoia has stricter SIP and permission requirements. There's no officially documented SIP-compatible alternative, which is why BlueBubbles is recommended.

Can I use this for remote iMessage access?

Yes. Point cliPath at an SSH wrapper script that connects to a remote Mac running imsg. Set remoteHost for SCP-based attachment fetching. The remote Mac needs Full Disk Access and Messages signed in.

What happens when this integration is removed?

You'll need to migrate to BlueBubbles. The migration involves installing the BlueBubbles server app on your Mac and updating your OpenClaw config. Your message history stays in Messages.app regardless.

Configuration Examples

Local Mac setup

channels:
  imessage:
    enabled: true
    cliPath: "/usr/local/bin/imsg"
    dbPath: "/Users/myuser/Library/Messages/chat.db"
    dmPolicy: pairing

Remote Mac over SSH

channels:
  imessage:
    enabled: true
    cliPath: "~/.openclaw/scripts/imsg-ssh"
    remoteHost: "user@gateway-host"
    includeAttachments: true
    attachmentRoots:
      - "/Users/*/Library/Messages/Attachments"
    remoteAttachmentRoots:
      - "/Users/*/Library/Messages/Attachments"

Installation

Built-in (bundled with OpenClaw) + brew install steipete/tap/imsg