iMessage

Estado: integración nativa de CLI externa. Gateway inicia imsg rpc y se comunica mediante JSON-RPC por stdio (sin demonio/puerto separado). Las acciones avanzadas requieren imsg launch y una comprobación correcta de la API privada.

Configuración rápida

brew install steipete/tap/imsgimsg rpc --helpimsg launchopenclaw channels status --probe

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

openclaw gateway

openclaw pairing list imessageopenclaw pairing approve imessage <CODE>

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

{channels: {imessage: {  enabled: true,  cliPath: "~/.openclaw/scripts/imsg-ssh",  remoteHost: "user@gateway-host", // used for SCP attachment fetches  includeAttachments: true,  // Optional: override allowed attachment roots.  // Defaults include /Users/*/Library/Messages/Attachments  attachmentRoots: ["/Users/*/Library/Messages/Attachments"],  remoteAttachmentRoots: ["/Users/*/Library/Messages/Attachments"],},},}

Requisitos y permisos (macOS)

• Messages debe tener sesión iniciada en el Mac que ejecuta imsg.
• Se requiere Acceso total al disco para el contexto de proceso que ejecuta OpenClaw/imsg (acceso a la base de datos de Messages).
• Se requiere permiso de Automatización para enviar mensajes mediante Messages.app.
• Para acciones avanzadas (reaccionar / editar / anular envío / respuesta en hilo / efectos / operaciones de grupo), System Integrity Protection debe estar deshabilitado — consulta Habilitar la API privada de imsg más abajo. El envío/recepción básico de texto y multimedia funciona sin ello.

Habilitar la API privada de imsg

imsg se distribuye en dos modos operativos:

• Modo básico (predeterminado, no requiere cambios en SIP): texto y multimedia salientes mediante send, observación/historial entrante, lista de chats. Esto es lo que obtienes de inmediato con una instalación nueva de brew install steipete/tap/imsg más los permisos estándar de macOS anteriores.
• Modo de API privada: imsg inyecta una dylib auxiliar en Messages.app para llamar a funciones internas de IMCore. Esto habilita react, edit, unsend, reply (en hilo), sendWithEffect, renameGroup, setGroupIcon, addParticipant, removeParticipant, leaveGroup, además de indicadores de escritura y confirmaciones de lectura.

Para acceder a la superficie de acciones avanzadas que documenta esta página del canal, necesitas el modo de API privada. El README de imsg es explícito sobre el requisito:

Las funciones avanzadas como read, typing, launch, envío enriquecido respaldado por bridge, mutación de mensajes y gestión de chats son optativas. Requieren que SIP esté deshabilitado y que se inyecte una dylib auxiliar en Messages.app. imsg launch se niega a inyectar cuando SIP está habilitado.

La técnica de inyección del auxiliar usa la propia dylib de imsg para acceder a las API privadas de Messages. No hay servidor de terceros ni runtime de BlueBubbles en la ruta de iMessage de OpenClaw.

Configuración

1. Instala (o actualiza) imsg en el Mac que ejecuta Messages.app:

   brew install steipete/tap/imsgimsg --versionimsg status --json

   La salida de imsg status --json informa bridge_version, rpc_methods y selectors por método para que puedas ver qué admite la compilación actual antes de empezar.

2. Deshabilita System Integrity Protection. Esto depende de la versión de macOS porque el requisito subyacente de Apple depende del SO y del hardware:

   • macOS 10.13–10.15 (Sierra–Catalina): deshabilita Library Validation mediante Terminal, reinicia en Recovery Mode, ejecuta csrutil disable, reinicia.
   • macOS 11+ (Big Sur y posterior), Intel: Recovery Mode (o Internet Recovery), csrutil disable, reinicia.
   • macOS 11+, Apple Silicon: secuencia de inicio con el botón de encendido para entrar en Recovery; en versiones recientes de macOS mantén pulsada la tecla Left Shift cuando hagas clic en Continue, luego csrutil disable. Las configuraciones de máquinas virtuales siguen un flujo separado — toma primero una instantánea de la VM.
   • macOS 26 / Tahoe: las políticas de validación de bibliotecas y las comprobaciones de derechos privados de imagent se han endurecido aún más; imsg puede necesitar una compilación actualizada para mantenerse al día. Si la inyección de imsg launch o selectors específicos empiezan a devolver falso después de una actualización mayor de macOS, revisa las notas de versión de imsg antes de asumir que el paso de SIP se completó correctamente.

   Sigue el flujo de Recovery Mode de Apple para tu Mac para deshabilitar SIP antes de ejecutar imsg launch.

3. Inyecta el auxiliar. Con SIP deshabilitado y sesión iniciada en Messages.app:

   imsg launch

   imsg launch se niega a inyectar cuando SIP sigue habilitado, por lo que esto también sirve como confirmación de que el paso 2 surtió efecto.

4. Verifica el bridge desde OpenClaw:

   openclaw channels status --probe

   La entrada de iMessage debe informar works, y imsg status --json | jq '.selectors' debe mostrar retractMessagePart: true más los selectores de edición / escritura / lectura que exponga tu compilación de macOS. La compuerta por método del Plugin de OpenClaw en actions.ts solo anuncia acciones cuyo selector subyacente es true, por lo que la superficie de acciones que ves en la lista de herramientas del agente refleja lo que el bridge realmente puede hacer en este host.

Si openclaw channels status --probe informa que el canal está en works pero acciones específicas lanzan "iMessage <action> requires the imsg private API bridge" en el momento de despacho, ejecuta imsg launch de nuevo — el auxiliar puede dejar de estar activo (reinicio de Messages.app, actualización del SO, etc.) y el estado en caché available: true seguirá anunciando acciones hasta que la siguiente comprobación lo actualice.

Cuando no puedes deshabilitar SIP

Si SIP deshabilitado no es aceptable para tu modelo de amenazas:

• imsg vuelve al modo básico — solo texto + multimedia + recepción.
• El Plugin de OpenClaw sigue anunciando envío de texto/multimedia y monitoreo entrante; simplemente oculta react, edit, unsend, reply, sendWithEffect y operaciones de grupo de la superficie de acciones (según la compuerta de capacidad por método).
• Puedes ejecutar un Mac separado que no sea Apple Silicon (o un Mac bot dedicado) con SIP desactivado para la carga de trabajo de iMessage, mientras mantienes SIP habilitado en tus dispositivos principales. Consulta Usuario macOS bot dedicado (identidad de iMessage separada) más abajo.

Control de acceso y enrutamiento

{  channels: {    imessage: {      groupPolicy: "allowlist",      groupAllowFrom: ["+15555550123"],      groups: {        "*": { systemPrompt: "Use British spelling." },        "8421": {          requireMention: true,          systemPrompt: "This is the on-call rotation chat. Keep replies under 3 sentences.",        },        "9907": {          // explicit suppression: the wildcard "Use British spelling." does not apply here          systemPrompt: "",        },      },    },  },}

Enlaces de conversación ACP

Los chats heredados de iMessage también se pueden vincular a sesiones ACP.

Flujo rápido para operadores:

• Ejecuta /acp spawn codex --bind here dentro del MD o chat de grupo permitido.
• Los mensajes futuros en esa misma conversación de iMessage se enrutan a la sesión ACP generada.
• /new y /reset restablecen la misma sesión ACP vinculada en el lugar.
• /acp close cierra la sesión ACP y elimina el enlace.

Se admiten enlaces persistentes configurados mediante entradas de nivel superior bindings[] con type: "acp" y match.channel: "imessage".

match.peer.id puede usar:

• identificador de MD normalizado como +15555550123 o [email protected]
• chat_id:<id> (recomendado para enlaces de grupo estables)
• chat_guid:<guid>
• chat_identifier:<identifier>

Ejemplo:

{  agents: {    list: [      {        id: "codex",        runtime: {          type: "acp",          acp: { agent: "codex", backend: "acpx", mode: "persistent" },        },      },    ],  },  bindings: [    {      type: "acp",      agentId: "codex",      match: {        channel: "imessage",        accountId: "default",        peer: { kind: "group", id: "chat_id:123" },      },      acp: { label: "codex-group" },    },  ],}

Consulta Agentes ACP para ver el comportamiento compartido de los enlaces ACP.

Patrones de despliegue

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

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

Medios, fragmentación y destinos de entrega

imsg chats --limit 20

Acciones de API privada

Cuando imsg launch está en ejecución y openclaw channels status --probe informa privateApi.available: true, la herramienta de mensajes puede usar acciones nativas de iMessage además de los envíos de texto normales.

{  channels: {    imessage: {      actions: {        reactions: true,        edit: true,        unsend: true,        reply: true,        sendWithEffect: true,        sendAttachment: true,        renameGroup: true,        setGroupIcon: true,        addParticipant: true,        removeParticipant: true,        leaveGroup: true,      },    },  },}

{  channels: {    imessage: {      sendReadReceipts: false,    },  },}

Escrituras de configuración

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

Desactivar:

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

Fusión de mensajes directos de envío dividido (comando + URL en una composición)

Cuando un usuario escribe un comando y una URL juntos — por ejemplo, Dump https://example.com/article — la app Mensajes de Apple divide el envío en dos filas separadas de chat.db:

1. Un mensaje de texto ("Dump").
2. Un globo de vista previa de URL ("https://...") con imágenes de vista previa OG como adjuntos.

Las dos filas llegan a OpenClaw con una separación de ~0,8-2,0 s en la mayoría de las configuraciones. Sin fusionarlas, el agente recibe solo el comando en el turno 1, responde (a menudo "envíame la URL") y solo ve la URL en el turno 2, momento en el que el contexto del comando ya se perdió. Esto es parte del canal de envío de Apple, no algo que OpenClaw o imsg introduzcan.

channels.imessage.coalesceSameSenderDms permite que un DM fusione filas consecutivas del mismo remitente en un único turno del agente. Los chats grupales siguen despachándose por mensaje para preservar la estructura de turnos de múltiples usuarios.

{  channels: {    imessage: {      coalesceSameSenderDms: true, // opt in (default: false)    },  },}

{  messages: {    inbound: {      byChannel: {        // 2500 ms works for most setups; raise to 4000 ms if your Mac is        // slow or under memory pressure (observed gap can stretch past 2 s        // then).        imessage: 2500,      },    },  },}

Escenarios y lo que ve el agente

Ponerse al día tras una caída del Gateway

Cuando el Gateway está sin conexión (cierre inesperado, reinicio, reposo del Mac, máquina apagada), imsg watch se reanuda desde el estado actual de chat.db cuando el Gateway vuelve a estar disponible; por defecto, cualquier cosa que haya llegado durante la interrupción nunca se ve. La recuperación reproduce esos mensajes en el siguiente inicio para que el agente no pierda tráfico entrante silenciosamente.

La recuperación está deshabilitada de forma predeterminada. Habilítala por canal:

channels: {  imessage: {    catchup: {      enabled: true,             // master switch (default: false)      maxAgeMinutes: 120,        // skip rows older than now - 2h (default: 120, clamp 1..720)      perRunLimit: 50,           // max rows replayed per startup (default: 50, clamp 1..500)      firstRunLookbackMinutes: 30, // first run with no cursor: look back 30 min (default: 30)      maxFailureRetries: 10,     // give up on a wedged guid after 10 dispatch failures (default: 10)    },  },}

Cómo se ejecuta

Una pasada por cada inicio de monitorIMessageProvider, secuenciada como imsg launch listo → watch.subscribe → performIMessageCatchup → bucle de despacho en vivo. La recuperación usa chats.list + messages.history por chat contra el mismo cliente JSON-RPC que usa imsg watch. Cualquier cosa que llegue durante la pasada de recuperación fluye por el despacho en vivo normalmente; la caché de deduplicación entrante existente absorbe cualquier solapamiento con las filas reproducidas.

Cada fila reproducida se envía por la ruta de despacho en vivo (evaluateIMessageInbound + dispatchInboundMessage), por lo que las listas de permitidos, la política de grupos, el debouncer, la caché de eco y las confirmaciones de lectura se comportan de forma idéntica en mensajes reproducidos y en vivo.

Semántica de cursor y reintento

La recuperación mantiene un cursor por cuenta en <openclawStateDir>/imessage/catchup/<account>__<hash>.json (el directorio de estado de OpenClaw tiene como valor predeterminado ~/.openclaw, se puede sobrescribir con OPENCLAW_STATE_DIR):

{  "lastSeenMs": 1717900800000,  "lastSeenRowid": 482910,  "updatedAt": 1717900801234,  "failureRetries": { "<guid>": 1 }}

• El cursor avanza tras cada despacho correcto y se mantiene cuando el despacho de una fila lanza una excepción; el siguiente inicio reintenta la misma fila desde el cursor retenido.
• Después de maxFailureRetries excepciones consecutivas contra el mismo guid, la recuperación registra un warn y fuerza el avance del cursor más allá del mensaje bloqueado para que los inicios posteriores puedan progresar.
• Los GUID ya abandonados se omiten al detectarlos (sin intento de despacho) en ejecuciones posteriores y se contabilizan bajo skippedGivenUp en el resumen de ejecución.

Señales visibles para el operador

imessage catchup: replayed=N skippedFromMe=… skippedGivenUp=… failed=… givenUp=… fetchedCount=…imessage catchup: giving up on guid=<guid> after &lt;N&gt; failures; advancing cursor past itimessage catchup: fetched &lt;X&gt; rows across chats, capped to perRunLimit=&lt;Y&gt;

Una línea WARN ... capped to perRunLimit significa que un único inicio no agotó todo el backlog. Aumenta perRunLimit (máximo 500) si tus interrupciones superan regularmente la pasada predeterminada de 50 filas.

Cuándo dejarlo desactivado

• El Gateway se ejecuta continuamente con reinicio automático por watchdog y las interrupciones siempre son de menos de unos segundos; el valor predeterminado desactivado está bien.
• El volumen de DM es bajo y los mensajes perdidos no cambiarían el comportamiento del agente; la ventana inicial firstRunLookbackMinutes puede despachar contexto antiguo inesperado al habilitarlo por primera vez.

Cuando activas la recuperación, el primer inicio sin cursor solo mira hacia atrás firstRunLookbackMinutes (30 min de forma predeterminada), no la ventana completa de maxAgeMinutes; esto evita reproducir un historial largo de mensajes anteriores a la habilitación.

Solución de problemas

imsg rpc --helpimsg status --jsonopenclaw channels status --probe

#!/usr/bin/env bashexec ssh -T messages-mac imsg "$@"

openclaw channels status --probe --channel imessage

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

Punteros de referencia de configuración

• Referencia de configuración - iMessage
• Configuración del Gateway
• Emparejamiento

Relacionado

• Resumen de canales — todos los canales compatibles
• Eliminación de BlueBubbles y la ruta iMessage de imsg — anuncio y resumen de migración
• Migrar desde BlueBubbles — tabla de traducción de configuración y migración paso a paso
• Emparejamiento — autenticación de DM y flujo de emparejamiento
• Grupos — comportamiento de chats grupales y compuerta por mención
• Enrutamiento de canales — enrutamiento de sesiones para mensajes
• Seguridad — modelo de acceso y endurecimiento