iMessage (Legacy: imsg)¶

Empfohlen: Verwenden Sie BlueBubbles für neue iMessage-Setups.

Der Kanal imsg ist eine Legacy-Integration über eine externe CLI und kann in einer zukünftigen Version entfernt werden.

Status: Legacy-Integration über externe CLI. Der Gateway startet imsg rpc (JSON-RPC über stdio).

Preferred iMessage path for new setups. iMessage DMs default to pairing mode. Full iMessage field reference.

Schnellsetup (Einsteiger)¶

`brew install steipete/tap/imsg`

    </Step>

    <Step title="Configure OpenClaw">

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

    </Step>

    <Step title="Start gateway">

openclaw gateway

    </Step>

    <Step title="Approve first DM pairing (default dmPolicy)">

`openclaw pairing approve imessage <CODE>`

    ```
        Pairing requests expire after 1 hour.
      </Step>
    </Steps>
    ```

Wenn Sie iMessage auf einem anderen Mac betreiben möchten, setzen Sie channels.imessage.cliPath auf einen Wrapper, der imsg auf dem entfernten macOS-Host über SSH ausführt. OpenClaw benötigt nur stdio.

#!/usr/bin/env bash
exec ssh -T gateway-host imsg "$@"

```
Recommended config when attachments are enabled:
```

{
  channels: {
    imessage: {
      cliPath: "~/imsg-ssh", // SSH wrapper to remote Mac
      remoteHost: "user@gateway-host", // for SCP file transfer
      includeAttachments: true,
    },
  },
}

```
Wenn `remoteHost` nicht gesetzt ist, versucht OpenClaw, dies durch Parsen des SSH-Befehls in Ihrem Wrapper-Skript automatisch zu erkennen.
```

Requirements and permissions (macOS)¶

iMessage-Kanal auf Basis von imsg unter macOS.
Vollzugriff auf die Festplatte für OpenClaw + imsg (Zugriff auf die Nachrichten-Datenbank).
Automationsberechtigung beim Senden.

Permissions are granted per process context. If gateway runs headless (LaunchAgent/SSH), run a one-time interactive command in that same context to trigger prompts:

imsg chats --limit 1
# or
imsg send <handle> "test"

Access control and routing¶

channels.imessage.dmPolicy controls direct messages:

```
`channels.imessage.groupPolicy`: `open | allowlist | disabled` (Standard: Allowlist).
```

channels.imessage.groupAllowFrom: Gruppen-Absender-Allowlist.

```
{
  channels: {
    imessage: {
      enabled: true,
      accounts: {
        bot: {
          name: "Bot",
          enabled: true,
          cliPath: "/path/to/imsg-bot",
          dbPath: "/Users/<bot-macos-user>/Library/Messages/chat.db",
        },
      },
    },
  },
}
```

- DMs use direct routing; groups use group routing. - With default session.dmScope=main, iMessage DMs collapse into the agent main session. - Group sessions are isolated (agent:<agentId>Gruppen:<chat_id>). - Replies route back to iMessage using originating channel/target metadata.

```
Wenn ein Thread mit mehreren Teilnehmern mit `is_group=false` eingeht, können Sie ihn dennoch isolieren, indem Sie `chat_id` unter Verwendung von `channels.imessage.groups` konfigurieren (siehe „Gruppenähnliche Threads“ unten).
```

Deployment patterns¶

Wenn der Bot von einer separaten iMessage-Identität senden soll (und Ihre persönlichen Nachrichten sauber bleiben sollen), verwenden Sie eine dedizierte Apple-ID + einen dedizierten macOS-Benutzer.

```
Verweisen Sie `channels.imessage.accounts.bot.cliPath` auf einen SSH-Wrapper, der `imsg` als Bot-Benutzer ausführt.
```

Common topology:

```
Wenn der Gateway auf einem Linux-Host/VM läuft, iMessage jedoch auf einem Mac laufen muss, ist Tailscale die einfachste Brücke: Der Gateway spricht über das Tailnet mit dem Mac, führt `imsg` per SSH aus und lädt Anhänge per SCP zurück.
```

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "~/.openclaw/scripts/imsg-ssh",
      remoteHost: "bot@mac-mini.tailnet-1234.ts.net",
      includeAttachments: true,
      dbPath: "/Users/bot/Library/Messages/chat.db",
    },
  },
}

#!/usr/bin/env bash
exec ssh -T bot@mac-mini.tailnet-1234.ts.net imsg "$@"

```
Use SSH keys so both SSH and SCP are non-interactive.
```

Für Setups mit nur einem Konto verwenden Sie flache Optionen (channels.imessage.cliPath, channels.imessage.dbPath) anstelle der accounts-Map.

```
Each account can override fields such as `cliPath`, `dbPath`, `allowFrom`, `groupPolicy`, `mediaMaxMb`, and history settings.
```

Media, chunking, and delivery targets¶

Medien-Uploads sind durch channels.imessage.mediaMaxMb begrenzt (Standard 16).

Optionale Zeilenumbruch-Segmentierung: Setzen Sie channels.imessage.chunkMode="newline", um an Leerzeilen (Absatzgrenzen) vor der Längensegmentierung zu trennen.

Preferred explicit targets:

```
- `chat_id:123` (recommended for stable routing)
- `chat_guid:...`
- `chat_identifier:...`

Handle targets are also supported:

- `imessage:+1555...`
- `sms:+1555...`
- `user@example.com`
```

imsg chats --limit 20

Konfigurationsschreibzugriffe¶

Standardmäßig darf iMessage Konfigurationsaktualisierungen schreiben, die durch /config set|unset ausgelöst werden (erfordert commands.config: true).

Deaktivieren mit:

{
  channels: { imessage: { configWrites: false } },
}

Troubleshooting¶

Validate the binary and RPC support:

imsg rpc --help
openclaw channels status --probe

```
If probe reports RPC unsupported, update `imsg`.
```

Hinweise:

```
`channels.imessage.groupPolicy = open | allowlist | disabled`.
```

Genehmigung über:

```
`channels.imessage.groupAllowFrom` steuert, wer in Gruppen auslösen darf, wenn `allowlist` gesetzt ist.
```

Checkliste:

```
#!/usr/bin/env bash
set -euo pipefail

# Run an interactive SSH once first to accept host keys:
#   ssh <bot-macos-user>@localhost true
exec /usr/bin/ssh -o BatchMode=yes -o ConnectTimeout=5 -T <bot-macos-user>@localhost \
  "/usr/local/bin/imsg" "$@"
```

Re-run in an interactive GUI terminal in the same user/session context and approve prompts:

imsg chats --limit 1
imsg send <handle> "test"

```
**Automation → Nachrichten**: Erlauben Sie dem Prozess, der OpenClaw ausführt (und/oder Ihrem Terminal), **Messages.app** für ausgehende Sendungen zu steuern.
```

Configuration reference pointers¶

Konfigurationsreferenz (iMessage)
Vollständige Konfiguration: Konfiguration
Pairing
BlueBubbles