iMessage

​

Configuración rápida

brew install steipete/tap/imsg
brew update && brew upgrade imsg
imsg rpc --help
imsg launch
openclaw channels status --probe

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

openclaw gateway

openclaw pairing list imessage
openclaw pairing approve imessage <CODE>

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

#!/usr/bin/env bash
exec 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.

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

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

• 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.

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.

​

Configuración

1. Instale (o actualice) imsg en el Mac que ejecuta Messages.app:
   brew install steipete/tap/imsg
   brew update && brew upgrade imsg
   imsg --version
   imsg 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.

​

Cuando SIP permanece activado

• 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: { "*": { "requireMention": true } },
    },
  },
}

{
  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

• 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.

• 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>

{
  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" },
    },
  ],
}

​

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 bash
exec 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

{
  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

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

​

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

brew update && brew upgrade imsg

​

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

• 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.

​

Señal visible para el operador

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

​

Migración

​

Solución de problemas

imsg rpc --help
imsg status --json
openclaw channels status --probe

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

launchctl kickstart -k system/com.apple.apsd
launchctl kickstart -k gui/$(id -u)/com.apple.CommCenter
launchctl kickstart -k gui/$(id -u)/com.apple.identityservicesd
launchctl kickstart -k gui/$(id -u)/com.apple.imagent
imsg launch
openclaw gateway restart

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

openclaw channels status --probe --channel imessage

imsg chats --limit 1
imsg 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