iMessage

Estado: integración nativa con una CLI externa. El Gateway inicia imsg rpc y se comunica mediante JSON-RPC por la entrada y salida estándar, sin un demonio ni un puerto independientes. Se recomienda encarecidamente el modo de API privada para disponer de un canal de iMessage completo; las respuestas, reacciones tapback, efectos, encuestas, respuestas a archivos adjuntos y acciones de grupo requieren imsg launch y una comprobación correcta de la API privada.

Para la configuración local habitual, el asistente de configuración de OpenClaw puede ofrecer una instalación o actualización de imsg mediante Homebrew, previa confirmación del usuario, en el Mac con sesión iniciada en Mensajes. La configuración manual y las topologías con wrapper SSH siguen estando administradas por el operador: instale o actualice imsg en el mismo contexto de usuario que ejecutará el Gateway o el wrapper.

Configuración rápida

brew install steipete/tap/imsgbrew update && brew upgrade 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>

ssh messages-mac 'brew install steipete/tap/imsg && brew update && brew upgrade imsg'

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

{channels: {imessage: {  enabled: true,  cliPath: "~/.openclaw/scripts/imsg-ssh",  remoteHost: "user@gateway-host", // se usa para obtener archivos adjuntos mediante SCP  includeAttachments: true,  // Opcional: raíces adicionales permitidas para archivos adjuntos (combinadas con la predeterminada  // /Users/*/Library/Messages/Attachments).  attachmentRoots: ["/Users/*/Library/Messages/Attachments"],  remoteAttachmentRoots: ["/Users/*/Library/Messages/Attachments"],},},}

Requisitos y permisos (macOS)

• Debe haber una sesión iniciada en Mensajes en el Mac que ejecuta imsg.
• Se requiere acceso total al disco para el contexto del proceso que ejecuta OpenClaw/imsg (acceso a la base de datos de Mensajes).
• Se requiere permiso de automatización para enviar mensajes mediante Messages.app.
• Para las acciones avanzadas (reaccionar / editar / anular envío / respuesta en hilo / efectos / encuestas / operaciones de grupo), debe deshabilitarse la protección de integridad del sistema; consulte Habilitación de la API privada de imsg. El envío y la recepción básicos de texto y contenido multimedia funcionan sin deshabilitarla.

No autorizado para enviar eventos de Apple a Mensajes. (-1743)

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

Habilitación de la API privada de imsg

imsg incluye dos modos operativos. Para OpenClaw, el modo de API privada es la configuración recomendada porque proporciona al canal las acciones nativas de iMessage que esperan los usuarios. El modo básico sigue siendo útil para instalaciones de bajo riesgo, la verificación inicial o hosts en los que no se puede deshabilitar SIP.

• Modo básico (predeterminado, no requiere cambios en SIP): texto y contenido multimedia salientes mediante send, supervisión e historial de mensajes entrantes y lista de chats. Esto es lo que se obtiene de inmediato con una instalación nueva mediante brew install steipete/tap/imsg y los permisos estándar de macOS indicados anteriormente.
• 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, poll y poll-vote (encuestas nativas de Mensajes), renameGroup, setGroupIcon, addParticipant, removeParticipant, leaveGroup, además de indicadores de escritura y confirmaciones de lectura.

La superficie de acciones recomendada en esta página requiere el modo de API privada. El README de imsg indica explícitamente el requisito:

Las funciones avanzadas como read, typing, launch, el envío enriquecido respaldado por el puente, la modificación de mensajes y la administración de chats son opcionales. Requieren que SIP esté deshabilitado y que se inyecte una dylib auxiliar en Messages.app. imsg launch se niega a realizar la inyección cuando SIP está habilitado.

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

Configuración

1. Instale (o actualice) imsg en el Mac que ejecuta Messages.app:

   brew install steipete/tap/imsgbrew update && brew upgrade imsgimsg --versionimsg status --json

   La salida de imsg status --json informa de bridge_version, rpc_methods y los selectors de cada método, para que pueda consultar lo que admite la compilación actual antes de comenzar.

2. Deshabilite la protección de integridad del sistema y, en versiones modernas de macOS, la validación de bibliotecas. Para inyectar una dylib auxiliar que no sea de Apple en Messages.app, firmado por Apple, es necesario deshabilitar SIP y relajar la validación de bibliotecas. El paso para deshabilitar SIP en el modo de recuperación depende de la versión de macOS:

   • macOS 10.13-10.15 (Sierra-Catalina): deshabilite la validación de bibliotecas mediante Terminal, reinicie en el modo de recuperación, ejecute csrutil disable y vuelva a reiniciar.
   • macOS 11+ (Big Sur y posteriores), Intel: acceda al modo de recuperación (o recuperación por Internet), ejecute csrutil disable y reinicie.
   • macOS 11+, Apple Silicon: use la secuencia de arranque con el botón de encendido para acceder a Recuperación; en versiones recientes de macOS, mantenga pulsada la tecla Left Shift al hacer clic en Continue y, después, ejecute csrutil disable. Las configuraciones de máquinas virtuales siguen un procedimiento diferente, por lo que debe crear primero una instantánea de la máquina virtual.

   En macOS 11 y versiones posteriores, csrutil disable por sí solo normalmente no es suficiente. Apple sigue aplicando la validación de bibliotecas a Messages.app como binario de plataforma, por lo que se rechaza un auxiliar firmado de forma ad hoc (Library Validation failed: ... platform binary, but mapped file is not) incluso con SIP desactivado. Después de desactivar SIP, desactive también la validación de bibliotecas y reinicie:

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

   macOS 26 (Tahoe), verificado en 26.5.1: desactivar SIP más el comando DisableLibraryValidation anterior es suficiente para inyectar el auxiliar desde 26.0 hasta 26.5.x. No se requieren argumentos de arranque. El plist es el factor decisivo y el paso que se omite con mayor frecuencia cuando falla la inyección en Tahoe:

   • Con el plist: imsg launch realiza la inyección y imsg status informa advanced_features: true.
   • Sin el plist (incluso con SIP desactivado): imsg launch falla con Failed to launch: Timeout waiting for Messages.app to initialize. AMFI rechaza el auxiliar ad hoc durante la carga, por lo que el puente nunca queda listo y el inicio agota el tiempo de espera. Ese tiempo de espera agotado es el síntoma más habitual en Tahoe; la solución es el plist anterior, no una medida más drástica.

   Si la inyección de imsg launch o determinados selectors empiezan a devolver falso después de una actualización de macOS, esta restricción suele ser la causa. Compruebe el estado de SIP y de la validación de bibliotecas antes de suponer que el propio paso de SIP falló. Si esos ajustes son correctos y el puente sigue sin poder realizar la inyección, recopile imsg status --json junto con la salida de imsg launch e informe al proyecto imsg en lugar de debilitar controles de seguridad adicionales de todo el sistema.

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

   imsg launch

   imsg launch se niega a realizar la inyección si SIP sigue activado, por lo que esto también sirve para confirmar que el paso 2 se aplicó.

4. Verifique 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 su compilación de macOS. La creación de encuestas requiere selectors.pollPayloadMessage; la votación requiere tanto selectors.pollVoteMessage como el método RPC poll.vote. El Plugin de OpenClaw anuncia únicamente las acciones compatibles con la comprobación almacenada en caché, mientras que una caché vacía mantiene una postura optimista y realiza la comprobación en el primer envío.

Si openclaw channels status --probe informa que el canal works, pero determinadas acciones generan "iMessage <action> requires the imsg private API bridge" al enviarse, ejecute imsg launch de nuevo: el auxiliar puede desconectarse (por un reinicio de Messages.app, una actualización del sistema operativo, etc.) y el estado available: true almacenado en caché seguirá anunciando acciones hasta que la siguiente comprobación lo actualice.

Cuando SIP permanece activado

Si desactivar SIP no es aceptable para su modelo de amenazas:

• imsg recurre al modo básico: solo texto, contenido multimedia y recepción.
• El Plugin de OpenClaw sigue anunciando el envío de texto/contenido multimedia y la supervisión de mensajes entrantes; oculta react, edit, unsend, reply, sendWithEffect y las operaciones de grupo de la superficie de acciones (según la restricción de capacidades de cada método).
• Puede ejecutar un Mac independiente que no use Apple Silicon (o un Mac dedicado al bot) con SIP desactivado para la carga de trabajo de iMessage, mientras mantiene SIP activado en sus dispositivos principales. Consulte Usuario de macOS dedicado al bot (identidad de iMessage independiente) más adelante.

Control de acceso y enrutamiento

{  channels: {    imessage: {      groupPolicy: "allowlist",      groupAllowFrom: ["+15555550123"],      groups: {        "*": { systemPrompt: "Usa la ortografía británica." },        "8421": {          requireMention: true,          systemPrompt: "Este es el chat del turno de guardia. Limita las respuestas a menos de 3 frases.",        },        "9907": {          // supresión explícita: el comodín "Usa la ortografía británica." no se aplica aquí          systemPrompt: "",        },      },    },  },}

Vinculaciones de conversaciones ACP

Los chats de iMessage se pueden vincular a sesiones ACP.

Flujo rápido para operadores:

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

Las vinculaciones persistentes configuradas usan entradas bindings[] de nivel superior con type: "acp" y match.channel: "imessage".

match.peer.id puede usar:

• un identificador normalizado de mensaje directo, como +15555550123 o user@example.com
• chat_id:<id> (recomendado para vinculaciones 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" },    },  ],}

Consulte Agentes ACP para conocer el comportamiento compartido de las vinculaciones 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 "$@"

Contenido multimedia, fragmentación y destinos de entrega

imsg chats --limit 20

Acciones de la API privada

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

Todas las acciones están activadas de forma predeterminada; use channels.imessage.actions para desactivar acciones individuales:

{  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 las escrituras de configuración iniciadas por el canal (para /config set|unset cuando commands.config: true).

Para deshabilitarlas:

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

Agrupación de mensajes directos divididos (comando + URL en una sola composición)

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

1. Un mensaje de texto ("Dump").
2. Un globo de vista previa de URL ("https://...") con imágenes de vista previa de OG como archivos 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 la agrupación, el agente recibe únicamente el comando en el turno 1 (y a menudo responde «envíeme la URL») antes de que la URL llegue en el turno 2. Esto se debe al proceso de envío de Apple, no a nada que introduzcan OpenClaw o imsg.

channels.imessage.coalesceSameSenderDms permite que un MD almacene en búfer 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 únicamente ese envío dividido real y mantiene las demás filas almacenadas en búfer como turnos separados. En versiones anteriores de imsg que no emiten ningún metadato de globo, OpenClaw no puede distinguir un envío dividido de varios envíos separados, por lo que recurre a combinar el conjunto. Esto conserva el comportamiento anterior a los metadatos, en lugar de hacer que los envíos divididos Dump <url> vuelvan a convertirse en dos turnos. Los chats grupales siguen procesando cada mensaje por separado para preservar la estructura de turnos de varios usuarios.

{  channels: {    imessage: {      coalesceSameSenderDms: true, // habilitación voluntaria (valor predeterminado: false)    },  },}

{  messages: {    inbound: {      byChannel: {        // 7000 ms cubren los retrasos observados en las vistas previas de URL de Messages.app.        imessage: 7000,      },    },  },}

Situaciones y lo que ve el agente

La columna «Opción 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 indicadas a continuación como «Dos turnos»/«N turnos» recurren en su lugar a una combinación heredada (un turno): OpenClaw no puede distinguir estructuralmente un envío dividido de varios envíos separados, por lo que conserva la combinación anterior a los metadatos. La separación precisa se activa cuando la versión comienza a emitir metadatos de globo.

Recuperación de mensajes entrantes tras reiniciar un puente o el Gateway

iMessage recupera los mensajes perdidos mientras el Gateway estaba inactivo y, al mismo tiempo, suprime la «bomba de mensajes pendientes» obsoletos que Apple puede descargar después de una recuperación de Push. El comportamiento predeterminado está siempre activado y se basa en la deduplicación de mensajes entrantes.

• Deduplicación de reproducción. Cada mensaje entrante procesado se registra mediante su GUID de Apple en el estado persistente del Plugin (imessage.inbound-dedupe), se reclama durante la ingesta y se confirma después de gestionarlo (se libera tras un fallo transitorio para permitir un nuevo intento). Todo lo que ya se haya gestionado se descarta en lugar de procesarse dos veces. Esto permite que la recuperación reproduzca de forma intensiva sin llevar un registro individual de cada mensaje.
• Recuperación del tiempo de inactividad. Al iniciarse, el monitor recuerda el último rowid procesado de chat.db (un cursor persistente por cuenta) y se lo pasa a imsg watch.subscribe como since_rowid, por lo que imsg reproduce las filas que llegaron mientras el Gateway estaba inactivo y después continúa siguiendo la actividad en tiempo real. La reproducción se limita a las 500 filas más recientes y a mensajes de hasta ~2 horas de antigüedad, y la deduplicación descarta todo lo que ya se haya gestionado.
• Límite de antigüedad para mensajes pendientes obsoletos. Las filas posteriores al límite de inicio son realmente nuevas; si la fecha de envío de una fila es más de ~15 minutos anterior a su llegada, se considera parte de los mensajes pendientes descargados por Push y se suprime. Las filas reproducidas (en el límite o antes de él) utilizan en su lugar la ventana de recuperación más amplia, por lo que se entrega un mensaje perdido recientemente, pero no el historial antiguo.

La recuperación funciona tanto con configuraciones de cliPath locales como remotas, porque la reproducción mediante since_rowid se ejecuta a través de la misma conexión RPC de imsg. La diferencia es la ventana: cuando el Gateway puede leer chat.db (local), fija el límite de rowid de inicio, restringe el intervalo de reproducción y entrega mensajes perdidos de hasta un par de horas de antigüedad. Con un cliPath de SSH remoto no puede leer la base de datos, por lo que la reproducción no tiene límite y cada fila utiliza el límite de antigüedad en tiempo real: sigue recuperando los mensajes perdidos recientemente y suprimiendo los mensajes pendientes antiguos, pero con la ventana en tiempo real más estrecha. Ejecute el Gateway en el Mac con Messages para disponer de la ventana de recuperación más amplia.

Señal visible para el operador

Los mensajes pendientes suprimidos se registran en el nivel predeterminado y nunca se descartan silenciosamente (la marca recovery indica qué ventana se aplicó):

imessage: se suprimieron mensajes entrantes pendientes obsoletos account=<id> sent=<iso> recovery=<bool> (&lt;N&gt; suprimidos desde el inicio)

Migración

channels.imessage.catchup.* está obsoleto: la recuperación del tiempo de inactividad es automática y no requiere configuración en las instalaciones nuevas. Las configuraciones existentes con catchup.enabled: true siguen respetándose como perfil de compatibilidad para la ventana de reproducción de recuperación. Los bloques de recuperación deshabilitados (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"

Referencias de configuración

• Referencia de configuración de iMessage
• Configuración del Gateway
• Vinculación

Temas relacionados

• Descripción general de los canales — todos los canales compatibles
• Eliminación de BlueBubbles y la ruta de iMessage mediante imsg — anuncio y resumen de la migración
• Migración desde BlueBubbles — tabla de equivalencias de configuración y transición paso a paso
• Vinculación — autenticación de mensajes directos y flujo de vinculación
• Grupos — comportamiento de los chats grupales y control mediante menciones
• Enrutamiento de canales — enrutamiento de sesiones para mensajes
• Seguridad — modelo de acceso y protección reforzada