iMessage (legacy: imsg)

Advertencia: Para nuevas instalaciones de iMessage, usa BlueBubbles.

La integración imsg es legacy y puede eliminarse en una versión futura.

Estado: integración legacy de CLI externo. El gateway ejecuta imsg rpc y se comunica por JSON-RPC sobre stdio (sin daemon/puerto separado).

• BlueBubbles (recomendado) — Ruta preferida para iMessage en nuevas instalaciones.
• Emparejamiento — Los mensajes directos de iMessage usan modo de emparejamiento por defecto.
• Referencia de configuración — Referencia completa de campos de iMessage.

Configuración rápida

Mac local (ruta rápida)

  ### Paso 1: Instala y verifica imsg

brew install steipete/tap/imsg
imsg rpc --help

  ### Paso 2: Configura OpenClaw

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

  ### Paso 3: Inicia el gateway

openclaw gateway

  ### Paso 4: Aprueba el primer emparejamiento de MD (dmPolicy por defecto)

openclaw pairing list imessage
openclaw pairing approve imessage <CODE>

    Las solicitudes de emparejamiento expiran después de 1 hora.

Mac remoto por SSH

OpenClaw solo requiere un `cliPath` compatible con stdio, así que puedes apuntar `cliPath` a un script wrapper que se conecte por SSH a un Mac remoto y ejecute `imsg`.

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

Configuración recomendada cuando los adjuntos están activados:

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "~/.openclaw/scripts/imsg-ssh",
      remoteHost: "user@gateway-host", // usado para obtener adjuntos por SCP
      includeAttachments: true,
      // Opcional: sobrescribir las raíces de adjuntos permitidas.
      // Los valores predeterminados incluyen /Users/*/Library/Messages/Attachments
      attachmentRoots: ["/Users/*/Library/Messages/Attachments"],
      remoteAttachmentRoots: ["/Users/*/Library/Messages/Attachments"],
    },
  },
}

Si `remoteHost` no está establecido, OpenClaw intenta auto-detectarlo analizando el script wrapper de SSH.
`remoteHost` debe ser `host` o `user@host` (sin espacios ni opciones SSH).
OpenClaw usa verificación estricta de claves de host para SCP, así que la clave del host de relevo debe existir previamente en `~/.ssh/known_hosts`.
Las rutas de adjuntos se validan contra las raíces permitidas (`attachmentRoots` / `remoteAttachmentRoots`).

Requisitos y permisos (macOS)

• Messages debe tener sesión iniciada en el Mac que ejecuta imsg.
• Se requiere Acceso Completo al Disco para el contexto del proceso que ejecuta OpenClaw/imsg (acceso a la base de datos de Messages).
• Se requiere permiso de Automatización para enviar mensajes a través de Messages.app.

Consejo: Los permisos se otorgan por contexto de proceso. Si el gateway se ejecuta en modo headless (LaunchAgent/SSH), ejecuta un comando interactivo una sola vez en ese mismo contexto para activar las solicitudes:

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

Control de acceso y enrutamiento

Política de mensajes directos

`channels.imessage.dmPolicy` controla los mensajes directos:

- `pairing` (predeterminado)
- `allowlist`
- `open` (requiere que `allowFrom` incluya `"*"`)
- `disabled`

Campo de lista de permitidos: `channels.imessage.allowFrom`.

Las entradas de la lista de permitidos pueden ser handles o destinos de chat (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`).

Política de grupo + menciones

`channels.imessage.groupPolicy` controla la gestión de grupos:

- `allowlist` (predeterminado cuando se configura)
- `open`
- `disabled`

Lista de permitidos de remitentes de grupo: `channels.imessage.groupAllowFrom`.

Alternativa en runtime: si `groupAllowFrom` no está establecido, la verificación de remitentes de grupo de iMessage recurre a `allowFrom` cuando está disponible.
Nota de runtime: si `channels.imessage` está completamente ausente, el runtime recurre a `groupPolicy="allowlist"` y registra una advertencia (incluso si `channels.defaults.groupPolicy` está establecido).

Control por mención en grupos:

- iMessage no tiene metadatos nativos de mención
- la detección de menciones usa patrones regex (`agents.list[].groupChat.mentionPatterns`, alternativa `messages.groupChat.mentionPatterns`)
- sin patrones configurados, el control por mención no puede aplicarse

Los comandos de control de remitentes autorizados pueden evadir el control por mención en grupos.

Sesiones y respuestas determinísticas

- Los mensajes directos usan enrutamiento directo; los grupos usan enrutamiento de grupo.
- Con `session.dmScope=main` por defecto, los mensajes directos de iMessage se unifican en la sesión principal del agente.
- Las sesiones de grupo están aisladas (`agent:<agentId>:imessage:group:<chat_id>`).
- Las respuestas se enrutan de vuelta a iMessage usando los metadatos de canal/destino de origen.

Comportamiento de hilos de grupo:

Algunos hilos de iMessage con múltiples participantes pueden llegar con `is_group=false`.
Si ese `chat_id` está configurado explícitamente en `channels.imessage.groups`, OpenClaw lo trata como tráfico de grupo (control de grupo + aislamiento de sesión de grupo).

Patrones de despliegue

Usa un Apple ID dedicado y un usuario macOS para que el tráfico del bot esté aislado de tu perfil personal de Messages.

Flujo típico:

1. Crea/inicia sesión con un usuario macOS dedicado.
2. Inicia sesión en Messages con el Apple ID del bot en ese usuario.
3. Instala `imsg` en ese usuario.
4. Crea un script wrapper SSH para que OpenClaw pueda ejecutar `imsg` en ese contexto de usuario.
5. Apunta `channels.imessage.accounts.<id>.cliPath` y `.dbPath` al perfil de ese usuario.

La primera ejecución puede requerir aprobaciones de GUI (Automatización + Acceso Completo al Disco) en la sesión de ese usuario del bot.

Topología común:

- el gateway se ejecuta en Linux/VM
- iMessage + `imsg` se ejecuta en un Mac en tu tailnet
- el wrapper `cliPath` usa SSH para ejecutar `imsg`
- `remoteHost` habilita la obtención de adjuntos por SCP

Ejemplo:

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "~/.openclaw/scripts/imsg-ssh",
      remoteHost: "[email protected]",
      includeAttachments: true,
      dbPath: "/Users/bot/Library/Messages/chat.db",
    },
  },
}

#!/usr/bin/env bash
exec ssh -T [email protected] imsg "$@"

Usa claves SSH para que tanto SSH como SCP sean no interactivos.
Asegúrate de que la clave del host esté registrada primero (por ejemplo `ssh [email protected]`) para que `known_hosts` esté poblado.

iMessage admite configuración por cuenta bajo `channels.imessage.accounts`.

Cada cuenta puede sobrescribir campos como `cliPath`, `dbPath`, `allowFrom`, `groupPolicy`, `mediaMaxMb`, configuraciones de historial y listas de raíces de adjuntos permitidas.

Medios, fragmentación y destinos de entrega

- la ingesta de adjuntos entrantes es opcional: `channels.imessage.includeAttachments`
- las rutas de adjuntos remotos pueden obtenerse por SCP cuando `remoteHost` está establecido
- las rutas de adjuntos deben coincidir con las raíces permitidas:
  - `channels.imessage.attachmentRoots` (local)
  - `channels.imessage.remoteAttachmentRoots` (modo SCP remoto)
  - patrón de raíz predeterminado: `/Users/*/Library/Messages/Attachments`
- SCP usa verificación estricta de claves de host (`StrictHostKeyChecking=yes`)
- el tamaño de medios salientes usa `channels.imessage.mediaMaxMb` (por defecto 16 MB)

- límite de fragmento de texto: `channels.imessage.textChunkLimit` (por defecto 4000)
- modo de fragmentación: `channels.imessage.chunkMode`
  - `length` (predeterminado)
  - `newline` (división primero por párrafo)

Destinos explícitos preferidos:

- `chat_id:123` (recomendado para enrutamiento estable)
- `chat_guid:...`
- `chat_identifier:...`

Los destinos de handle también son compatibles:

- `imessage:+1555...`
- `sms:+1555...`
- `[email protected]`

imsg chats --limit 20

Escrituras de configuración

iMessage permite escrituras de configuración iniciadas desde el canal por defecto (para /config set|unset cuando commands.config: true).

Desactivar:

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

Solución de problemas

Valida el binario y el soporte RPC:

imsg rpc --help
openclaw channels status --probe

Si el sondeo reporta RPC no soportado, actualiza `imsg`.

Verifica:

- `channels.imessage.dmPolicy`
- `channels.imessage.allowFrom`
- aprobaciones de emparejamiento (`openclaw pairing list imessage`)

Verifica:

- `channels.imessage.groupPolicy`
- `channels.imessage.groupAllowFrom`
- comportamiento de la lista de permitidos `channels.imessage.groups`
- configuración de patrones de mención (`agents.list[].groupChat.mentionPatterns`)

Verifica:

- `channels.imessage.remoteHost`
- `channels.imessage.remoteAttachmentRoots`
- autenticación por clave SSH/SCP desde el host del gateway
- la clave del host existe en `~/.ssh/known_hosts` en el host del gateway
- legibilidad de la ruta remota en el Mac que ejecuta Messages

Vuelve a ejecutar en una terminal GUI interactiva en el mismo contexto de usuario/sesión y aprueba las solicitudes:

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

Confirma que el Acceso Completo al Disco + Automatización estén otorgados para el contexto del proceso que ejecuta OpenClaw/`imsg`.

Referencias de configuración

• Referencia de configuración - iMessage
• Configuración del gateway
• Emparejamiento
• BlueBubbles