{
  "title": "iMessage (legacy: imsg)",
  "content": "> **Recommended:** Use [BlueBubbles](/channels/bluebubbles) for new iMessage setups.\n>\n> The `imsg` channel is a legacy external-CLI integration and may be removed in a future release.\n\nStatus: legacy external CLI integration. Gateway spawns `imsg rpc` (JSON-RPC over stdio).\n\n## Quick setup (beginner)\n\n1. Ensure Messages is signed in on this Mac.\n2. Install `imsg`:\n   * `brew install steipete/tap/imsg`\n3. Configure OpenClaw with `channels.imessage.cliPath` and `channels.imessage.dbPath`.\n4. Start the gateway and approve any macOS prompts (Automation + Full Disk Access).\n\n* iMessage channel backed by `imsg` on macOS.\n* Deterministic routing: replies always go back to iMessage.\n* DMs share the agent's main session; groups are isolated (`agent:<agentId>:imessage:group:<chat_id>`).\n* If a multi-participant thread arrives with `is_group=false`, you can still isolate it by `chat_id` using `channels.imessage.groups` (see “Group-ish threads” below).\n\nBy default, iMessage is allowed to write config updates triggered by `/config set|unset` (requires `commands.config: true`).\n\n* macOS with Messages signed in.\n* Full Disk Access for OpenClaw + `imsg` (Messages DB access).\n* Automation permission when sending.\n* `channels.imessage.cliPath` can point to any command that proxies stdin/stdout (for example, a wrapper script that SSHes to another Mac and runs `imsg rpc`).\n\n1. Ensure Messages is signed in on this Mac.\n2. Configure iMessage and start the gateway.\n\n### Dedicated bot macOS user (for isolated identity)\n\nIf you want the bot to send from a **separate iMessage identity** (and keep your personal Messages clean), use a dedicated Apple ID + a dedicated macOS user.\n\n1. Create a dedicated Apple ID (example: `my-cool-bot@icloud.com`).\n   * Apple may require a phone number for verification / 2FA.\n2. Create a macOS user (example: `openclawhome`) and sign into it.\n3. Open Messages in that macOS user and sign into iMessage using the bot Apple ID.\n4. Enable Remote Login (System Settings → General → Sharing → Remote Login).\n5. Install `imsg`:\n   * `brew install steipete/tap/imsg`\n6. Set up SSH so `ssh <bot-macos-user>@localhost true` works without a password.\n7. Point `channels.imessage.accounts.bot.cliPath` at an SSH wrapper that runs `imsg` as the bot user.\n\nFirst-run note: sending/receiving may require GUI approvals (Automation + Full Disk Access) in the *bot macOS user*. If `imsg rpc` looks stuck or exits, log into that user (Screen Sharing helps), run a one-time `imsg chats --limit 1` / `imsg send ...`, approve prompts, then retry.\n\nExample wrapper (`chmod +x`). Replace `<bot-macos-user>` with your actual macOS username:\n\n```bash theme={null}\n#!/usr/bin/env bash\nset -euo pipefail",
  "code_samples": [
    {
      "code": "## What it is\n\n* iMessage channel backed by `imsg` on macOS.\n* Deterministic routing: replies always go back to iMessage.\n* DMs share the agent's main session; groups are isolated (`agent:<agentId>:imessage:group:<chat_id>`).\n* If a multi-participant thread arrives with `is_group=false`, you can still isolate it by `chat_id` using `channels.imessage.groups` (see “Group-ish threads” below).\n\n## Config writes\n\nBy default, iMessage is allowed to write config updates triggered by `/config set|unset` (requires `commands.config: true`).\n\nDisable with:",
      "language": "unknown"
    },
    {
      "code": "## Requirements\n\n* macOS with Messages signed in.\n* Full Disk Access for OpenClaw + `imsg` (Messages DB access).\n* Automation permission when sending.\n* `channels.imessage.cliPath` can point to any command that proxies stdin/stdout (for example, a wrapper script that SSHes to another Mac and runs `imsg rpc`).\n\n## Setup (fast path)\n\n1. Ensure Messages is signed in on this Mac.\n2. Configure iMessage and start the gateway.\n\n### Dedicated bot macOS user (for isolated identity)\n\nIf you want the bot to send from a **separate iMessage identity** (and keep your personal Messages clean), use a dedicated Apple ID + a dedicated macOS user.\n\n1. Create a dedicated Apple ID (example: `my-cool-bot@icloud.com`).\n   * Apple may require a phone number for verification / 2FA.\n2. Create a macOS user (example: `openclawhome`) and sign into it.\n3. Open Messages in that macOS user and sign into iMessage using the bot Apple ID.\n4. Enable Remote Login (System Settings → General → Sharing → Remote Login).\n5. Install `imsg`:\n   * `brew install steipete/tap/imsg`\n6. Set up SSH so `ssh <bot-macos-user>@localhost true` works without a password.\n7. Point `channels.imessage.accounts.bot.cliPath` at an SSH wrapper that runs `imsg` as the bot user.\n\nFirst-run note: sending/receiving may require GUI approvals (Automation + Full Disk Access) in the *bot macOS user*. If `imsg rpc` looks stuck or exits, log into that user (Screen Sharing helps), run a one-time `imsg chats --limit 1` / `imsg send ...`, approve prompts, then retry.\n\nExample wrapper (`chmod +x`). Replace `<bot-macos-user>` with your actual macOS username:",
      "language": "unknown"
    }
  ],
  "headings": [
    {
      "level": "h2",
      "text": "Quick setup (beginner)",
      "id": "quick-setup-(beginner)"
    },
    {
      "level": "h2",
      "text": "What it is",
      "id": "what-it-is"
    },
    {
      "level": "h2",
      "text": "Config writes",
      "id": "config-writes"
    },
    {
      "level": "h2",
      "text": "Requirements",
      "id": "requirements"
    },
    {
      "level": "h2",
      "text": "Setup (fast path)",
      "id": "setup-(fast-path)"
    },
    {
      "level": "h3",
      "text": "Dedicated bot macOS user (for isolated identity)",
      "id": "dedicated-bot-macos-user-(for-isolated-identity)"
    }
  ],
  "url": "llms-txt#imessage-(legacy:-imsg)",
  "links": []
}