iMessage (legacy : imsg)¶

Recommandé : Utilisez BlueBubbles pour les nouvelles configurations iMessage.

Le canal imsg est une intégration CLI externe legacy et peut être supprimé dans une version future.

Statut : intégration CLI externe legacy. La Gateway (passerelle) lance imsg rpc (JSON-RPC sur stdio).

Configurez iMessage et démarrez la passerelle. iMessage DMs default to pairing mode. Full iMessage field reference.

Configuration (chemin rapide)¶

`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>
    ```

channels.imessage.cliPath peut pointer vers toute commande qui proxifie stdin/stdout (par exemple, un script wrapper qui se connecte en SSH à un autre Mac et exécute imsg rpc).

#!/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,
    },
  },
}

```
Si `remoteHost` n’est pas défini, OpenClaw tente de l’auto-détecter en analysant la commande SSH dans votre script wrapper.
```

Requirements and permissions (macOS)¶

Assurez-vous que Messages est connecté sur ce Mac.
Accès complet au disque pour OpenClaw + imsg (accès à la base de données Messages).
Automation permission is required to send messages through Messages.app.

macOS accorde les permissions TCC par contexte application/processus. Approuver les invites dans le même contexte que imsg (par exemple, Terminal/iTerm, une session LaunchAgent ou un processus lancé par SSH).

imsg chats --limit 1
# ou
imsg envoyer <handle> "test"

Access control and routing¶

channels.imessage.dmPolicy controls direct messages:

```
`channels.imessage.groupPolicy` : `open | allowlist | disabled` (par défaut : allowlist).
```

channels.imessage.groupAllowFrom : liste d’autorisation des expéditeurs de groupe.

```
{
  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>Groupes :<chat_id>). - Replies route back to iMessage using originating channel/target metadata.

```
Si un fil à plusieurs participants arrive avec `is_group=false`, vous pouvez quand même l’isoler en `chat_id` à l’aide de `channels.imessage.groups` (voir « Fils de type groupe » ci-dessous).
```

Deployment patterns¶

Si vous voulez que le bot envoie depuis une identité iMessage distincte (et garder vos Messages personnels propres), utilisez un identifiant Apple dédié + un utilisateur macOS dédié.

```
Faites pointer `channels.imessage.accounts.bot.cliPath` vers un wrapper SSH qui exécute `imsg` en tant qu’utilisateur bot.
```

Common topology:

```
Si la Gateway (passerelle) s’exécute sur un hôte/VM Linux mais qu’iMessage doit s’exécuter sur un Mac, Tailscale est le pont le plus simple : la passerelle communique avec le Mac via le tailnet, exécute `imsg` via SSH et récupère les pièces jointes via SCP.
```

{
  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.
```

Pour les configurations à compte unique, utilisez des options à plat (channels.imessage.cliPath, channels.imessage.dbPath) au lieu de la map accounts.

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

Media, chunking, and delivery targets¶

Les envois de médias sont plafonnés par channels.imessage.mediaMaxMb (par défaut 16).

Le texte sortant est découpé à channels.imessage.textChunkLimit (par défaut 4000).

Preferred explicit targets:

```
handles directs : `imessage:+1555` / `sms:+1555` / `user@example.com`
```

imsg chats --limit 20

Écritures de configuration¶

Par défaut, iMessage est autorisé à écrire des mises à jour de configuration déclenchées par /config set|unset (nécessite commands.config: true).

Désactiver avec :

{
  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`.
```

Checklist:

```
`channels.imessage.dmPolicy` : `pairing | allowlist | open | disabled` (par défaut : appairage).
```

Remarques :

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

Approuver via :

```
#!/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" "$@"
```

Exécutez une commande interactive à usage unique dans un terminal GUI pour forcer l'invite de commande, puis recommencez :

`channels.imessage.cliPath` : chemin vers `imsg`.

```
Démarrez la passerelle et approuvez toutes les invites macOS (Automatisation + Accès complet au disque).
```

Configuration reference pointers¶

Référence de configuration (iMessage)
Configuration complète : Configuration
Pairing
BlueBubbles