iMessage

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

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: 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 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 Messages).
• Se requiere permiso de Automatización para enviar mensajes mediante Messages.app.
• Para acciones avanzadas (reaccionar / editar / anular envío / respuesta en hilo / efectos / operaciones de grupo), System Integrity Protection debe estar deshabilitado — consulta Habilitar la API privada de imsg más abajo. El envío/recepción básico de texto y multimedia funciona sin ello.

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

​

Habilitar la API privada de imsg

• Modo básico (predeterminado, no requiere cambios en SIP): texto y multimedia salientes mediante send, observación/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, 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 bridge, mutación de mensajes y gestión de chats son optativas. Requieren que SIP esté deshabilitado y que se inyecte una dylib auxiliar en Messages.app. imsg launch se niega a inyectar cuando SIP está habilitado.

​

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 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. Esto depende de la versión de macOS porque el requisito subyacente de Apple depende del SO y del hardware:
   • macOS 10.13–10.15 (Sierra–Catalina): deshabilita Library Validation mediante Terminal, reinicia en Recovery Mode, ejecuta csrutil disable, reinicia.
   • macOS 11+ (Big Sur y posterior), Intel: Recovery Mode (o Internet Recovery), csrutil disable, reinicia.
   • macOS 11+, Apple Silicon: secuencia de inicio con el botón de encendido para entrar en Recovery; en versiones recientes de macOS mantén pulsada la tecla Left Shift cuando hagas clic en Continue, luego csrutil disable. Las configuraciones de máquinas virtuales siguen un flujo separado — toma primero una instantánea de la VM.
   • macOS 26 / Tahoe: las políticas de validación de bibliotecas y las comprobaciones de derechos privados de imagent se han endurecido aún más; imsg puede necesitar una compilación actualizada para mantenerse al día. Si la inyección de imsg launch o selectors específicos empiezan a devolver falso después de una actualización mayor de macOS, revisa las notas de versión de imsg antes de asumir que el paso de SIP se completó correctamente.
   Sigue el flujo de Recovery Mode de Apple para tu Mac para deshabilitar SIP antes de ejecutar imsg launch.
3. Inyecta el auxiliar. Con SIP deshabilitado y sesión iniciada en Messages.app:
   imsg launch
   
   imsg launch se niega a inyectar cuando SIP sigue habilitado, por lo que esto también sirve como confirmación de que el paso 2 surtió efecto.
4. Verifica el bridge desde OpenClaw:
   openclaw channels status --probe
   
   La entrada de iMessage debe informar works, y imsg status --json | jq '.selectors' debe mostrar retractMessagePart: true más los selectores de edición / escritura / lectura que exponga tu compilación de macOS. La compuerta por método del Plugin de OpenClaw en actions.ts solo anuncia acciones cuyo selector subyacente es true, por lo que la superficie de acciones que ves en la lista de herramientas del agente refleja lo que el bridge realmente puede hacer en este host.

​

Cuando no puedes deshabilitar SIP

• imsg vuelve 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 bot dedicado) con SIP desactivado para la carga de trabajo de iMessage, mientras mantienes SIP habilitado en tus dispositivos principales. Consulta Usuario macOS bot dedicado (identidad de iMessage separada) más abajo.

​

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

​

Enlaces de conversación 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 el enlace.

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

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

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

​

Escrituras de configuración

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

​

Fusión de mensajes directos 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, // opt in (default: false)
    },
  },
}

{
  messages: {
    inbound: {
      byChannel: {
        // 2500 ms works for most setups; raise to 4000 ms if your Mac is
        // slow or under memory pressure (observed gap can stretch past 2 s
        // then).
        imessage: 2500,
      },
    },
  },
}

​

Escenarios y lo que ve el agente

​

Ponerse al día tras una caída del Gateway

channels: {
  imessage: {
    catchup: {
      enabled: true,             // master switch (default: false)
      maxAgeMinutes: 120,        // skip rows older than now - 2h (default: 120, clamp 1..720)
      perRunLimit: 50,           // max rows replayed per startup (default: 50, clamp 1..500)
      firstRunLookbackMinutes: 30, // first run with no cursor: look back 30 min (default: 30)
      maxFailureRetries: 10,     // give up on a wedged guid after 10 dispatch failures (default: 10)
    },
  },
}

​

Cómo se ejecuta

​

Semántica de cursor y reintento

{
  "lastSeenMs": 1717900800000,
  "lastSeenRowid": 482910,
  "updatedAt": 1717900801234,
  "failureRetries": { "<guid>": 1 }
}

• El cursor avanza tras cada despacho correcto y se mantiene cuando el despacho de una fila lanza una excepción; el siguiente inicio reintenta la misma fila desde el cursor retenido.
• Después de maxFailureRetries excepciones consecutivas contra el mismo guid, la recuperación registra un warn y fuerza el avance del cursor más allá del mensaje bloqueado para que los inicios posteriores puedan progresar.
• Los GUID ya abandonados se omiten al detectarlos (sin intento de despacho) en ejecuciones posteriores y se contabilizan bajo skippedGivenUp en el resumen de ejecución.

​

Señales visibles para el operador

imessage catchup: replayed=N skippedFromMe=… skippedGivenUp=… failed=… givenUp=… fetchedCount=…
imessage catchup: giving up on guid=<guid> after <N> failures; advancing cursor past it
imessage catchup: fetched <X> rows across chats, capped to perRunLimit=<Y>

​

Cuándo dejarlo desactivado

• El Gateway se ejecuta continuamente con reinicio automático por watchdog y las interrupciones siempre son de menos de unos segundos; el valor predeterminado desactivado está bien.
• El volumen de DM es bajo y los mensajes perdidos no cambiarían el comportamiento del agente; la ventana inicial firstRunLookbackMinutes puede despachar contexto antiguo inesperado al habilitarlo por primera vez.

​

Solución de problemas

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

#!/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 del Gateway
• Emparejamiento

​

Relacionado

• Resumen de canales — todos los canales compatibles
• Eliminación de BlueBubbles y la ruta iMessage de imsg — anuncio y resumen de migración
• Migrar desde BlueBubbles — tabla de traducción de configuración y migración paso a paso
• Emparejamiento — autenticación de DM y flujo de emparejamiento
• Grupos — comportamiento de chats grupales y compuerta por mención
• Enrutamiento de canales — enrutamiento de sesiones para mensajes
• Seguridad — modelo de acceso y endurecimiento