iMessage

​

Configuración rápida

brew install steipete/tap/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>

#!/usr/bin/env bash
exec 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: extra allowed attachment roots (merged with the default
      // /Users/*/Library/Messages/Attachments).
      attachmentRoots: ["/Users/*/Library/Messages/Attachments"],
      remoteAttachmentRoots: ["/Users/*/Library/Messages/Attachments"],
    },
  },
}

​

Requisitos y permisos (macOS)

• Mensajes debe tener la 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 Mensajes).
• Se requiere permiso de Automatización para enviar mensajes a través de Messages.app.
• Para acciones avanzadas (reaccionar / editar / anular envío / respuesta en hilo / efectos / encuestas / operaciones de grupo), System Integrity Protection debe estar desactivado; consulta Habilitar la API privada de imsg. El envío y la recepción básicos de texto y medios funcionan sin ello.

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

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

• Modo básico (predeterminado, no requiere cambios en SIP): texto y medios salientes mediante send, vigilancia/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, 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, envío enriquecido respaldado por puente, mutación de mensajes y gestión de chats son optativas. Requieren que SIP esté desactivado y que se inyecte una dylib auxiliar en Messages.app. imsg launch se niega a inyectar cuando SIP está activado.

​

Configuración

1. Instala (o actualiza) imsg en el Mac que ejecuta Messages.app:
   brew install steipete/tap/imsg
   imsg --version
   imsg status --json
   
   La salida de imsg status --json informa de bridge_version, rpc_methods y selectors por método para que puedas ver qué admite la compilación actual antes de empezar.
2. Desactiva System Integrity Protection y (en macOS moderno) Library Validation. Inyectar una dylib auxiliar no Apple en la Messages.app firmada por Apple requiere SIP desactivado y validación de bibliotecas relajada. El paso de SIP en modo Recuperación es específico de la versión de macOS:
   • macOS 10.13-10.15 (Sierra-Catalina): desactiva Library Validation mediante Terminal, reinicia en modo Recuperación, ejecuta csrutil disable, reinicia.
   • macOS 11+ (Big Sur y posterior), Intel: modo Recuperación (o Recuperación por Internet), csrutil disable, reinicia.
   • macOS 11+, Apple Silicon: secuencia de inicio con botón de encendido para entrar en Recuperación; en versiones recientes de macOS, mantén pulsada la tecla Mayús izquierda al hacer clic en Continuar y luego csrutil disable. Las configuraciones de máquina virtual siguen un flujo separado, así que toma primero una instantánea de la VM.
   En macOS 11 y posterior, 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 se rechaza un auxiliar firmado ad hoc (Library Validation failed: ... platform binary, but mapped file is not) incluso con SIP desactivado. Después de desactivar SIP, desactiva 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 desactivado más el comando DisableLibraryValidation anterior basta 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 que falta con más frecuencia 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 desactivado): 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 lanzamiento agota el tiempo de espera. Ese tiempo de espera es el síntoma más común en Tahoe; la solución es el plist anterior, no nada más drástico.
   Si la inyección de imsg launch o selectors específicos empiezan a devolver false después de una actualización de macOS, esta barrera 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 inyectarse, 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 en todo el sistema.
3. Inyecta el asistente. Con SIP desactivado y Messages.app con la sesión iniciada:
   imsg launch
   
   imsg launch se niega a inyectar cuando SIP sigue activado, por lo 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 las acciones admitidas por la prueba almacenada en caché, mientras que una caché vacía se mantiene optimista y prueba en el primer envío.

​

Cuando SIP permanece activado

• imsg vuelve al modo básico: solo texto + medios + recepción.
• El Plugin de OpenClaw sigue anunciando envío de texto/medios y supervisión entrante; oculta react, edit, unsend, reply, sendWithEffect y las operaciones de grupo de la superficie de acciones (según la puerta de capacidad por método).
• Puedes ejecutar un Mac independiente 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 macOS dedicado para bot (identidad de iMessage separada) a continuación.

​

Control de acceso y enrutamiento

{
  channels: {
    imessage: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15555550123"],
      groups: { "*": { "requireMention": true } },
    },
  },
}

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

​

Vinculaciones de conversaciones ACP

• 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 la vinculación.

• identificador de MD normalizado como +15555550123 o user@example.com
• chat_id:<id> (recomendado para vinculaciones de grupo 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 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 bash
exec ssh -T bot@mac-mini.tailnet-1234.ts.net imsg "$@"

​

Medios, fragmentación y destinos de entrega

imsg chats --limit 20

​

Acciones de 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,
    },
  },
}

​

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

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

{
  channels: {
    imessage: {
      coalesceSameSenderDms: true, // optar por activar (predeterminado: false)
    },
  },
}

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

​

Escenarios y lo que ve el agente

​

Recuperación de entrada después de reiniciar un puente o Gateway

• Deduplicación de reproducción. Cada mensaje entrante despachado se registra por su GUID de Apple en el estado persistente del Plugin (imessage.inbound-dedupe), se reclama durante la ingesta y se confirma después de manejarlo (se libera ante un fallo transitorio para que pueda reintentarse). Todo lo ya manejado se descarta en lugar de despacharse dos veces. Esto permite que la recuperación reproduzca de forma agresiva sin contabilidad por mensaje.
• Recuperación de tiempo de inactividad. Al iniciar, el monitor recuerda el último chat.db rowid despachado (un cursor persistido por cuenta) y lo pasa a imsg watch.subscribe como since_rowid, de modo que imsg reproduce las filas que llegaron mientras el Gateway estaba inactivo y luego sigue en vivo. 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 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 de descarga Push y se suprime. Las filas reproducidas (en el límite o por debajo) usan en cambio la ventana de recuperación más amplia, de modo que se entrega un mensaje perdido recientemente mientras que el historial antiguo no.

​

Señal visible para el operador

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

​

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"

​

Punteros de referencia de configuración

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

​

Relacionado

• Resumen de canales — todos los canales admitidos
• Eliminación de BlueBubbles y la ruta imsg de iMessage — anuncio y resumen de migración
• Migrar desde BlueBubbles — tabla de traducción de configuración y cambio paso a paso
• Emparejamiento — autenticación DM y flujo de emparejamiento
• Grupos — comportamiento de chat grupal y control por mención
• Enrutamiento de canales — enrutamiento de sesión para mensajes
• Seguridad — modelo de acceso y endurecimiento