iMessage

Estado: integración nativa con CLI externa. Gateway inicia imsg rpc y se comunica mediante JSON-RPC por stdio (sin daemon/puerto independiente). Las acciones avanzadas requieren imsg launch y una prueba correcta de 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 la 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 / deshacer envío / respuesta en hilo / efectos / encuestas / operaciones de grupo), System Integrity Protection debe estar deshabilitada; consulta Habilitar la API privada de imsg a continuación. El envío y la recepción básicos de texto y medios funcionan sin ello.

Not authorized to send Apple events to Messages. (-1743)

kTCCServiceAppleEvents | /usr/libexec/sshd-keygen-wrapper | auth_value=0 | com.apple.MobileSMS

Habilitar la API privada de imsg

imsg se distribuye en dos modos operativos:

• Modo básico (predeterminado, sin cambios de SIP necesarios): texto y medios salientes mediante send, observación/historial entrante, lista de chats. Esto es lo que obtienes de fábrica con una instalación nueva de brew install steipete/tap/imsg más los permisos estándar de macOS indicados arriba.
• Modo de API privada: imsg inyecta una dylib auxiliar en Messages.app para llamar a funciones internas de IMCore. Esto desbloquea react, edit, unsend, reply (en hilo), sendWithEffect, poll y poll-vote (encuestas nativas de Messages), 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 puente, mutación de mensajes y gestión de chats son opcionales. Requieren que SIP esté deshabilitada y que se inyecte una dylib auxiliar en Messages.app. imsg launch se niega a inyectar cuando SIP está habilitada.

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

Configuración

1. Instala (o actualiza) imsg en la 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 y (en macOS moderno) Library Validation. Inyectar una dylib auxiliar que no es de Apple en Messages.app, firmada por Apple, necesita SIP desactivada y validación de bibliotecas relajada. El paso de SIP en modo de recuperación depende de la versión de macOS:

   • macOS 10.13-10.15 (Sierra-Catalina): deshabilita Library Validation mediante Terminal, reinicia en modo de recuperación, ejecuta csrutil disable y reinicia.
   • macOS 11+ (Big Sur y posteriores), Intel: modo de recuperación (o Internet Recovery), csrutil disable, reiniciar.
   • macOS 11+, Apple Silicon: secuencia de inicio con el botón de encendido para entrar en recuperación; en versiones recientes de macOS, mantén pulsada la tecla Mayús izquierda cuando hagas clic en Continuar y luego ejecuta csrutil disable. Las configuraciones de máquinas virtuales siguen un flujo separado, así que crea primero una instantánea de la VM.

   En macOS 11 y posteriores, csrutil disable por sí solo normalmente no basta. Apple sigue imponiendo la validación de bibliotecas contra Messages.app como binario de plataforma, por lo que un auxiliar firmado ad hoc se rechaza (Library Validation failed: ... platform binary, but mapped file is not) incluso con SIP desactivada. Después de deshabilitar SIP, deshabilita también la validación de bibliotecas y reinicia:

   sudo defaults write /Library/Preferences/com.apple.security.libraryvalidation.plist DisableLibraryValidation -bool true

   macOS 26 (Tahoe), verificado en 26.5.1: SIP desactivada más el comando DisableLibraryValidation anterior es suficiente para inyectar el auxiliar desde 26.0 hasta 26.5.x. No se requieren boot-args. El plist es el factor decisivo y el paso omitido más común cuando la inyección falla en Tahoe:

   • Con el plist: imsg launch inyecta y imsg status informa advanced_features: true.
   • Sin el plist (incluso con SIP desactivada): imsg launch falla con Failed to launch: Timeout waiting for Messages.app to initialize. AMFI rechaza el auxiliar ad hoc al cargarlo, por lo que el puente nunca queda listo y el inicio agota el tiempo de espera. Ese tiempo de espera es el síntoma que la mayoría de las personas encuentran en Tahoe, y la solución es el plist anterior, no algo más drástico.

   Esto se confirmó con una prueba controlada antes/después en macOS 26.5.1 (Apple Silicon): con el plist, la dylib se mapea en Messages.app y el puente se inicia; elimina el plist y reinicia, y imsg launch produce el fallo de tiempo de espera anterior sin que la dylib se mapee.

   Si la inyección de imsg launch o selectors específicos empiezan a devolver falso después de una actualización de macOS, esta compuerta suele ser la causa. Comprueba el estado de SIP y de validación de bibliotecas antes de asumir que el propio paso de SIP falló. Si esos ajustes son correctos y el puente aún no puede inyectar, recopila imsg status --json junto con la salida de imsg launch y repórtalo al proyecto imsg en lugar de debilitar controles de seguridad adicionales de todo el sistema.

   Sigue el flujo de modo de recuperación de Apple para tu Mac para desactivar SIP antes de ejecutar imsg launch.

3. Inyecta el helper. Con SIP desactivado y la sesión iniciada en Messages.app:

   imsg launch

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

4. Verifica el puente desde OpenClaw:

   openclaw channels status --probe

   La entrada de iMessage debería informar works, y imsg status --json | jq '{rpc_methods, selectors}' debería mostrar las capacidades expuestas por tu compilación de macOS. La creación de encuestas requiere selectors.pollPayloadMessage; votar requiere tanto selectors.pollVoteMessage como el método RPC poll.vote. El Plugin de OpenClaw anuncia solo acciones admitidas por la prueba en caché, mientras que una caché vacía se mantiene optimista y prueba en el primer envío.

Si openclaw channels status --probe informa que el canal está works, pero acciones específicas arrojan "iMessage <action> requiere el puente de API privada de imsg" en el momento del envío, vuelve a ejecutar imsg launch: el helper puede desconectarse (reinicio de Messages.app, actualización del sistema operativo, etc.) y el estado en caché available: true seguirá anunciando acciones hasta que la siguiente prueba lo actualice.

Cuando no puedes desactivar SIP

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

• imsg recurre 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 dedicado para bot) con SIP desactivado para la carga de trabajo de iMessage, mientras mantienes SIP activado en tus dispositivos principales. Consulta Usuario de macOS dedicado para bot (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 conversaciones ACP

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

Flujo rápido para operador:

• 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 creada.
• /new y /reset restablecen la misma sesión ACP enlazada 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 user@example.com
• 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 el comportamiento compartido de enlaces ACP.

Patrones de despliegue

{  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 bashexec ssh -T bot@mac-mini.tailnet-1234.ts.net imsg "$@"

Multimedia, 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,        polls: true,      },    },  },}

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

Escrituras de configuración

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

Desactivar:

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

Combinación de DM de envío dividido (comando + URL en una composición)

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

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 ~0.8-2.0 s de diferencia en la mayoría de configuraciones. Sin combinación, 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ó. Este es el flujo de envío de Apple, no algo que introduzcan OpenClaw o imsg.

channels.imessage.coalesceSameSenderDms activa para un DM el almacenamiento en búfer de filas consecutivas del mismo remitente. Cuando imsg expone el marcador estructural de vista previa de URL balloon_bundle_id: "com.apple.messages.URLBalloonProvider" en una de las filas de origen, OpenClaw combina solo ese envío dividido real y mantiene cualquier otra fila en búfer como turnos separados. En compilaciones antiguas de imsg que no emiten ningún metadato de globo, OpenClaw no puede distinguir un envío dividido de envíos separados, por lo que recurre a combinar el grupo. Eso conserva el comportamiento previo a los metadatos en lugar de hacer que los envíos divididos Dump <url> regresen a dos turnos. Los chats grupales siguen despachándose por mensaje para preservar la estructura de turnos multiusuario.

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

{  messages: {    inbound: {      byChannel: {        // 7000 ms covers observed Messages.app URL-preview delays.        imessage: 7000,      },    },  },}

Escenarios y lo que ve el agente

La columna "Marca activada" muestra el comportamiento en una versión de imsg que emite balloon_bundle_id. En versiones anteriores de imsg que no emiten ningún metadato de globo, las filas siguientes marcadas como "Dos turnos" / "N turnos" recurren en su lugar a una fusión heredada (un turno): OpenClaw no puede distinguir estructuralmente un envío dividido de envíos separados, así que conserva la fusión previa a los metadatos. La separación precisa se activa cuando la versión emite metadatos de globo.

Recuperación de entrada tras reiniciar un puente o Gateway

iMessage recupera los mensajes perdidos mientras el Gateway estuvo caído y, al mismo tiempo, suprime la "bomba de backlog" obsoleta que Apple puede descargar tras una recuperación Push. El comportamiento predeterminado siempre está activado, construido sobre la desduplicación de entrada.

• Desduplicación de repetición. Cada mensaje entrante enviado se registra por su GUID de Apple en el estado persistente del Plugin (imessage.inbound-dedupe), se reclama al ingerirse y se confirma después del manejo (se libera ante un fallo transitorio para que pueda reintentarse). Todo lo que ya se manejó se descarta en lugar de enviarse dos veces. Esto permite que la recuperación repita de forma agresiva sin contabilidad por mensaje.
• Recuperación de inactividad. Al iniciar, el monitor recuerda el último rowid de chat.db enviado (un cursor persistido por cuenta) y lo pasa a imsg watch.subscribe como since_rowid, para que imsg reproduzca las filas que llegaron mientras el Gateway estaba caído y luego siga en vivo. La repetición se limita a las filas más recientes y a mensajes de hasta ~2 horas de antigüedad, y la desduplicación descarta todo lo ya manejado.
• Valla de antigüedad para backlog obsoleto. Las filas por encima del límite de inicio son realmente en vivo; una cuya fecha de envío sea más de ~15 minutos anterior a su llegada es backlog descargado por Push y se suprime. Las filas reproducidas (en el límite o por debajo) usan en su lugar la ventana de recuperación más amplia, por lo que se entrega un mensaje perdido recientemente mientras que el historial antiguo no.

La recuperación funciona tanto con configuraciones cliPath locales como remotas, porque la repetición since_rowid se ejecuta sobre la misma conexión RPC de imsg. La diferencia es la ventana: cuando el Gateway puede leer chat.db (local), ancla el límite rowid de inicio, limita el intervalo de repetición y entrega mensajes perdidos de hasta un par de horas de antigüedad. Con un cliPath SSH remoto no puede leer la base de datos, así que la repetición no tiene límite y cada fila usa la valla de antigüedad en vivo: sigue recuperando mensajes perdidos recientemente y sigue suprimiendo backlog antiguo, solo que con la ventana en vivo más estrecha. Ejecuta el Gateway en el Mac de Messages para obtener la ventana de recuperación más amplia.

Señal visible para el operador

El backlog suprimido se registra en el nivel predeterminado, nunca se descarta en silencio (la marca recovery muestra qué ventana se aplicó):

imessage: suppressed stale inbound backlog account=<id> sent=<iso> recovery=<bool> (&lt;N&gt; suppressed since start)

Migración

channels.imessage.catchup.* está obsoleto: la recuperación de inactividad ahora es automática y no necesita configuración para instalaciones nuevas. Las configuraciones existentes con catchup.enabled: true siguen respetándose como perfil de compatibilidad para la ventana de repetición de recuperación. Los bloques de catchup desactivados (enabled: false o sin enabled: true) se retiran; openclaw doctor --fix los elimina.

Solución de problemas

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

imsg chats --limit 10 --jsonimsg watch --chat-id <chat-id> --jsonsqlite3 ~/Library/Messages/chat.db \"select datetime(max(date)/1000000000 + 978307200, 'unixepoch', 'localtime'), max(ROWID) from message;"

launchctl kickstart -k system/com.apple.apsdlaunchctl kickstart -k gui/$(id -u)/com.apple.CommCenterlaunchctl kickstart -k gui/$(id -u)/com.apple.identityservicesdlaunchctl kickstart -k gui/$(id -u)/com.apple.imagentimsg launchopenclaw gateway restart

#!/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 con imsg — anuncio y resumen de migración
• Migrar desde BlueBubbles — tabla de traducción de configuración y cambio paso a paso
• Emparejamiento — autenticación de MD y flujo de emparejamiento
• Grupos — comportamiento de chat grupal y control por menciones
• Enrutamiento de canales — enrutamiento de sesión para mensajes
• Seguridad — modelo de acceso y endurecimiento