iMessage (heredado: imsg)

Para las nuevas implementaciones de iMessage, usa BlueBubbles.La integración imsg es heredada y puede eliminarse en una versión futura.

Estado: integración heredada de CLI externa. Gateway inicia imsg rpc y se comunica mediante JSON-RPC sobre stdio (sin daemon/puerto independiente).

BlueBubbles (recomendado)

Ruta preferida de iMessage para configuraciones nuevas.

Emparejamiento

Los mensajes directos de iMessage usan el modo de emparejamiento de forma predeterminada.

Referencia de configuración

Referencia completa de campos de iMessage.

Configuración rápida

Mac local (ruta rápida)
Mac remoto por SSH

Instala y verifica imsg

brew install steipete/tap/imsg
imsg rpc --help

Configura OpenClaw

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

Inicia Gateway

openclaw gateway

Aprueba el primer emparejamiento de mensaje directo (`dmPolicy` predeterminado)

openclaw pairing list imessage
openclaw pairing approve imessage <CODE>

Las solicitudes de emparejamiento vencen después de 1 hora.

OpenClaw solo requiere un cliPath compatible con stdio, por lo que puedes hacer que cliPath apunte a un script contenedor que use SSH hacia un Mac remoto y ejecute imsg.

#!/usr/bin/env bash
exec ssh -T gateway-host imsg "$@"

Configuración recomendada cuando los adjuntos están habilitados:

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "~/.openclaw/scripts/imsg-ssh",
      remoteHost: "user@gateway-host", // usado para recuperar adjuntos con SCP
      includeAttachments: true,
      // Opcional: reemplaza las raíces de adjuntos permitidas.
      // Los valores predeterminados incluyen /Users/*/Library/Messages/Attachments
      attachmentRoots: ["/Users/*/Library/Messages/Attachments"],
      remoteAttachmentRoots: ["/Users/*/Library/Messages/Attachments"],
    },
  },
}

Si remoteHost no está configurado, OpenClaw intenta detectarlo automáticamente analizando el script contenedor SSH. remoteHost debe ser host o user@host (sin espacios ni opciones de SSH). OpenClaw usa verificación estricta de clave de host para SCP, por lo que la clave de host del relay ya debe existir en ~/.ssh/known_hosts. Las rutas de adjuntos se validan frente a las raíces permitidas (attachmentRoots / remoteAttachmentRoots).

Requisitos y permisos (macOS)

Messages debe haber iniciado sesión 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.

Los permisos se conceden por contexto de proceso. Si Gateway se ejecuta sin interfaz (LaunchAgent/SSH), ejecuta un comando interactivo una sola vez en ese mismo contexto para activar las solicitudes:

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

Control de acceso y enrutamiento

Política de mensajes directos
Política de grupos + menciones
Sesiones y respuestas deterministas

channels.imessage.dmPolicy controla los mensajes directos:

pairing (predeterminado)
allowlist
open (requiere que allowFrom incluya "*")
disabled

Campo de lista de permitidos: channels.imessage.allowFrom.Las entradas de la lista de permitidos pueden ser identificadores o destinos de chat (chat_id:*, chat_guid:*, chat_identifier:*).

channels.imessage.groupPolicy controla el manejo de grupos:

allowlist (predeterminado cuando está configurado)
open
disabled

Lista de permitidos de remitentes de grupo: channels.imessage.groupAllowFrom.Reserva en tiempo de ejecución: si groupAllowFrom no está configurado, las comprobaciones de remitentes de grupos de iMessage recurren a allowFrom cuando está disponible. Nota de tiempo de ejecución: si channels.imessage falta por completo, el tiempo de ejecución recurre a groupPolicy="allowlist" y registra una advertencia (aunque channels.defaults.groupPolicy esté configurado).Restricción por menciones para grupos:

iMessage no tiene metadatos nativos de menciones
la detección de menciones usa patrones regex (agents.list[].groupChat.mentionPatterns, con reserva en messages.groupChat.mentionPatterns)
sin patrones configurados, no se puede aplicar la restricción por menciones

Los comandos de control de remitentes autorizados pueden omitir la restricción por menciones en grupos.

Los mensajes directos usan enrutamiento directo; los grupos usan enrutamiento de grupo.
Con el valor predeterminado session.dmScope=main, los mensajes directos de iMessage se agrupan en la sesión principal del agente.
Las sesiones de grupo están aisladas (agent:<agentId>:imessage:group:<chat_id>).
Las respuestas se enrutan de vuelta a iMessage usando los metadatos del canal/destino de origen.

Comportamiento de hilos tipo grupo:Algunos hilos de iMessage con varios participantes pueden llegar con is_group=false. Si ese chat_id está configurado explícitamente en channels.imessage.groups, OpenClaw lo trata como tráfico de grupo (restricción de grupo + aislamiento de sesión de grupo).

Enlaces de conversación de ACP

Los chats heredados de iMessage también pueden vincularse a sesiones de ACP. Flujo rápido para operadores:

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

Se admiten vínculos persistentes configurados mediante entradas bindings[] de nivel superior con type: "acp" y match.channel: "imessage". match.peer.id puede usar:

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

Consulta ACP Agents para ver el comportamiento compartido de los vínculos de ACP.

Patrones de implementación

Usuario dedicado de bot en macOS (identidad de iMessage separada)

Usa un Apple ID y un usuario de macOS dedicados para que el tráfico del bot quede aislado de tu perfil personal de Messages.Flujo típico:

Crea o inicia sesión en un usuario dedicado de macOS.
Inicia sesión en Messages con el Apple ID del bot en ese usuario.
Instala imsg en ese usuario.
Crea un contenedor SSH para que OpenClaw pueda ejecutar imsg en el contexto de ese usuario.
Haz que channels.imessage.accounts.<id>.cliPath y .dbPath apunten al perfil de ese usuario.

La primera ejecución puede requerir aprobaciones en la interfaz gráfica (Automatización + Acceso total al disco) en la sesión de ese usuario del bot.

Mac remoto por Tailscale (ejemplo)

Topología habitual:

Gateway se ejecuta en Linux/VM
iMessage + imsg se ejecuta en un Mac dentro de tu tailnet
el contenedor cliPath usa SSH para ejecutar imsg
remoteHost permite recuperar adjuntos con SCP

Ejemplo:

{
  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 "$@"

Usa claves SSH para que tanto SSH como SCP no sean interactivos. Asegúrate de que primero se confíe en la clave del host (por ejemplo ssh bot@mac-mini.tailnet-1234.ts.net) para que se complete known_hosts.

Patrón de varias cuentas

iMessage admite configuración por cuenta en channels.imessage.accounts.Cada cuenta puede reemplazar campos como cliPath, dbPath, allowFrom, groupPolicy, mediaMaxMb, ajustes de historial y listas de permitidos de raíces de adjuntos.

Multimedia, fragmentación y destinos de entrega

Adjuntos y multimedia

la ingesta de adjuntos entrantes es opcional: channels.imessage.includeAttachments
las rutas de adjuntos remotos pueden recuperarse mediante SCP cuando remoteHost está configurado
las rutas de adjuntos deben coincidir con las raíces permitidas:
- channels.imessage.attachmentRoots (local)
- channels.imessage.remoteAttachmentRoots (modo SCP remoto)
- patrón de raíz predeterminado: /Users/*/Library/Messages/Attachments
SCP usa verificación estricta de clave de host (StrictHostKeyChecking=yes)
el tamaño de multimedia saliente usa channels.imessage.mediaMaxMb (predeterminado: 16 MB)

Fragmentación saliente

límite de fragmento de texto: channels.imessage.textChunkLimit (predeterminado: 4000)
modo de fragmentación: channels.imessage.chunkMode
- length (predeterminado)
- newline (división priorizando párrafos)

Formatos de direccionamiento

Destinos explícitos preferidos:

chat_id:123 (recomendado para un enrutamiento estable)
chat_guid:...
chat_identifier:...

También se admiten destinos por identificador:

imessage:+1555...
sms:+1555...
user@example.com

imsg chats --limit 20

Escrituras de configuración

iMessage permite por defecto escrituras de configuración iniciadas por el canal (para /config set|unset cuando commands.config: true). Desactivar:

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

Resolución de problemas

No se encuentra imsg o RPC no es compatible

Valida el binario y la compatibilidad con RPC:

imsg rpc --help
openclaw channels status --probe

Si la sonda informa que RPC no es compatible, actualiza imsg.

Se ignoran los mensajes directos

Comprueba:

channels.imessage.dmPolicy
channels.imessage.allowFrom
aprobaciones de emparejamiento (openclaw pairing list imessage)

Se ignoran los mensajes de grupo

Comprueba:

channels.imessage.groupPolicy
channels.imessage.groupAllowFrom
comportamiento de lista de permitidos de channels.imessage.groups
configuración del patrón de menciones (agents.list[].groupChat.mentionPatterns)

Fallan los adjuntos remotos

Comprueba:

channels.imessage.remoteHost
channels.imessage.remoteAttachmentRoots
autenticación por clave SSH/SCP desde el host de Gateway
la clave del host existe en ~/.ssh/known_hosts en el host de Gateway
legibilidad de la ruta remota en el Mac que ejecuta Messages

Se omitieron las solicitudes de permisos de macOS

Vuelve a ejecutar en una terminal GUI interactiva en el mismo contexto de usuario/sesión y aprueba las solicitudes:

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

Confirma que Acceso total al disco + Automatización estén concedidos al contexto de proceso que ejecuta OpenClaw/imsg.

Punteros a la referencia de configuración

Relacionado

Resumen de canales — todos los canales compatibles
Emparejamiento — autenticación de mensajes directos y flujo de emparejamiento
Grupos — comportamiento del chat de grupo y restricción por menciones
Enrutamiento de canales — enrutamiento de sesiones para mensajes
Seguridad — modelo de acceso y endurecimiento

Overview

Messaging platforms

Configuration

iMessage

iMessage (heredado: imsg)

BlueBubbles (recomendado)

Emparejamiento

Referencia de configuración

Configuración rápida

Requisitos y permisos (macOS)

Control de acceso y enrutamiento

Enlaces de conversación de ACP

Patrones de implementación

Multimedia, fragmentación y destinos de entrega

Escrituras de configuración

Resolución de problemas

Punteros a la referencia de configuración

Relacionado

Overview

Messaging platforms

Configuration

​iMessage (heredado: imsg)

BlueBubbles (recomendado)

Emparejamiento

Referencia de configuración

​Configuración rápida

​Requisitos y permisos (macOS)

​Control de acceso y enrutamiento

​Enlaces de conversación de ACP

​Patrones de implementación

​Multimedia, fragmentación y destinos de entrega

​Escrituras de configuración

​Resolución de problemas

​Punteros a la referencia de configuración

​Relacionado

iMessage (heredado: imsg)

Configuración rápida

Requisitos y permisos (macOS)

Control de acceso y enrutamiento

Enlaces de conversación de ACP

Patrones de implementación

Multimedia, fragmentación y destinos de entrega

Escrituras de configuración

Resolución de problemas

Punteros a la referencia de configuración

Relacionado