iMessage

Estado: integración nativa con una CLI externa. El Gateway inicia imsg rpc y se comunica mediante JSON-RPC a través de la entrada y salida estándar, sin un daemon ni un puerto independientes. Se recomienda encarecidamente el modo de API privada para disponer de un canal de iMessage completo; las respuestas, los tapbacks, los efectos, las encuestas, las respuestas a archivos adjuntos y las 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 confirmada por el usuario en el Mac con sesión iniciada en Mensajes. La configuración manual y las topologías con un wrapper SSH siguen estando a cargo del 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)

• Se debe haber iniciado sesión en Mensajes 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 Mensajes).
• Se requiere permiso de automatización para enviar mensajes mediante Messages.app.
• Para las acciones avanzadas (reaccionar / editar / anular el envío / responder en un hilo / efectos / encuestas / operaciones de grupo), se debe deshabilitar 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 se dispone de autorización 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 los usuarios esperan. El modo básico sigue siendo útil para instalaciones de bajo riesgo, verificaciones iniciales o hosts en los que no se pueda 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 forma inmediata con una instalación nueva de brew install steipete/tap/imsg y los permisos estándar de macOS indicados anteriormente.
• Modo de API privada: imsg inyecta una biblioteca auxiliar dinámica en Messages.app para llamar a funciones internas de IMCore. Esto habilita react, edit, unsend, reply (en hilos), 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 archivo README de imsg indica explícitamente el requisito:

Las funciones avanzadas, como read, typing, launch, el envío enriquecido mediante el puente, la modificación de mensajes y la gestión de chats, son opcionales. Requieren que SIP esté deshabilitado y que se inyecte una biblioteca auxiliar dinámica 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 utiliza la propia biblioteca dinámica de imsg para acceder a las API privadas de Mensajes. La ruta de iMessage de OpenClaw no utiliza ningún servidor de terceros ni el entorno de ejecución de BlueBubbles.

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 sobre bridge_version, rpc_methods y el valor de selectors de cada método, para que pueda ver qué admite la compilación actual antes de comenzar.

2. Desactive 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 el componente firmado por Apple Messages.app, es necesario desactivar SIP y relajar la validación de bibliotecas. El paso de SIP en el modo Recuperación depende de la versión de macOS:

   • macOS 10.13-10.15 (Sierra-Catalina): desactive la validación de bibliotecas mediante Terminal, reinicie en el modo Recuperación, ejecute csrutil disable y reinicie.
   • macOS 11+ (Big Sur y posteriores), Intel: acceda al modo Recuperación (o Recuperación por Internet), ejecute csrutil disable y reinicie.
   • macOS 11+, Apple Silicon: use la secuencia de inicio 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, a continuación, ejecute csrutil disable. Las configuraciones de máquinas virtuales siguen un flujo distinto, por lo que primero debe crear una instantánea de la VM.

   En macOS 11 y posteriores, csrutil disable por sí solo no suele ser suficiente. Apple sigue aplicando la validación de bibliotecas a Messages.app como binario de plataforma, por lo que se rechaza un auxiliar con firma 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 junto con el comando DisableLibraryValidation anterior basta 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 omitido con mayor frecuencia cuando falla la inyección en Tahoe:

   • Con el plist: imsg launch realiza la inyección y imsg status informa de 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 con firma 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 que encuentra la mayoría de las personas 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 comienzan 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 ha fallado. Si esos ajustes son correctos y el puente todavía no puede realizar la inyección, recopile imsg status --json junto con la salida de imsg launch e informe al proyecto imsg en lugar de debilitar otros controles de seguridad 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 se completó el paso 2.

4. Verifique el puente desde OpenClaw:

   openclaw channels status --probe

   La entrada de iMessage debería informar de 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; votar 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 actitud optimista y realiza la comprobación en el primer envío.

Si openclaw channels status --probe informa que el canal está works, pero determinadas acciones generan "iMessage <action> requires the imsg private API bridge" durante el envío, vuelva a ejecutar imsg launch; 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 en 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: "Use la ortografía británica." },        "8421": {          requireMention: true,          systemPrompt: "Este es el chat de rotación de guardia. Limite las respuestas a menos de 3 frases.",        },        "9907": {          // supresión explícita: el comodín "Use la ortografía británica." no se aplica aquí          systemPrompt: "",        },      },    },  },}

Vinculaciones de conversaciones ACP

Los chats de iMessage pueden vincularse 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 enrutarán 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 grupos 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 implementación

{  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 habilitadas 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 desactivarlas:

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

Combinación de mensajes directos enviados por separado (comando + URL en una sola composición)

Apple puede almacenar un comando y la vista previa de su URL como filas físicas chat.db independientes. imsg 0.13.1 y versiones posteriores combinan esas filas antes de que la supervisión, el historial o la búsqueda devuelvan el mensaje, por lo que OpenClaw recibe un único mensaje entrante lógico sin añadir latencia específica del canal a los mensajes directos.

No se necesita ninguna opción de combinación de iMessage. openclaw doctor --fix elimina la clave retirada channels.imessage.coalesceSameSenderDms. El retraso genérico messages.inbound sigue disponible cuando se desea agrupar intencionadamente mensajes de texto rápidos en un canal.

Si los envíos de comando más URL llegan como turnos separados del agente, actualice imsg en el Mac con Mensajes:

brew update && brew upgrade imsg

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 antigua «avalancha de mensajes pendientes» que Apple puede liberar tras recuperar Push. El comportamiento predeterminado está siempre activado y se basa en una entrada duradera y un límite de antigüedad.

• Protección duradera contra repeticiones. Antes de avanzar el cursor de recuperación, OpenClaw registra cada fila sin procesar en la cola de entrada SQLite compartida, con su GUID de Apple como identificador del evento. Una fila completada conserva una marca de eliminación durante unas 4 horas, con un límite de 10,000 entradas, por lo que una repetición con el mismo GUID se descarta incluso después de un reinicio. Una fila pendiente sigue siendo recuperable hasta que el envío la adopta.
• Recuperación tras un periodo de inactividad. Al iniciarse, el monitor recuerda el último rowid de chat.db admitido de forma duradera (un cursor persistente por cuenta) y lo pasa a imsg watch.subscribe como since_rowid, de modo que imsg repite las filas que aún no se habían registrado y luego continúa siguiendo los eventos en directo. Las filas registradas antes de un fallo se reanudan desde SQLite. La repetición se limita a las 500 filas más recientes y a mensajes de hasta ~2 horas de antigüedad, y las marcas de eliminación por GUID descartan todo lo ya procesado.
• Límite de antigüedad para mensajes pendientes obsoletos. Las filas posteriores al límite de inicio son realmente eventos en directo; 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 liberados por Push y se suprime. Las filas repetidas (en el límite o antes de él) utilizan en cambio 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 cliPath locales como remotas, porque la repetición de since_rowid se ejecuta mediante la misma conexión RPC imsg. La diferencia es la ventana: cuando el Gateway puede leer chat.db (en local), fija el límite inicial de rowid, limita el intervalo de repetición y entrega mensajes perdidos de hasta un par de horas de antigüedad. Mediante un cliPath SSH remoto no puede leer la base de datos, por lo que la repetición no tiene límite y todas las filas utilizan el límite de antigüedad de eventos en directo: aun así, recupera los mensajes perdidos recientemente y suprime los mensajes pendientes antiguos, pero con la ventana en directo más estrecha. Ejecute el Gateway en el Mac con Mensajes 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 muestra 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 tras periodos de inactividad es automática y no necesita configuración en instalaciones nuevas. Las configuraciones existentes con catchup.enabled: true se siguen respetando como perfil de compatibilidad para la ventana de repetición de recuperación. Los bloques de recuperación desactivados (enabled: false o sin enabled: true) se han retirado; 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: iMessage
• Configuración del Gateway
• Vinculación

Contenido relacionado

• 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 conversión de la 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 refuerzo