iMessage (heredado: imsg)

Para 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 por 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 remota 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/<you>/Library/Messages/chat.db",
    },
  },
}

Inicia gateway

openclaw gateway

Aprueba el primer emparejamiento de mensaje directo (dmPolicy predeterminada)

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 a una Mac remota y ejecute imsg.

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

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

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "~/.openclaw/scripts/imsg-ssh",
      remoteHost: "user@gateway-host", // usado para recuperar archivos adjuntos por SCP
      includeAttachments: true,
      // Opcional: reemplaza las raíces de archivos 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 del host de retransmisión ya debe existir en ~/.ssh/known_hosts. Las rutas de archivos adjuntos se validan con respecto a las raíces permitidas (attachmentRoots / remoteAttachmentRoots).

Requisitos y permisos (macOS)

Messages debe tener sesión iniciada en la Mac que ejecuta imsg.
Se requiere Full Disk Access para el contexto de proceso que ejecuta OpenClaw/imsg (acceso a la base de datos de Messages).
Se requiere permiso de Automation para enviar mensajes a través de Messages.app.

Los permisos se conceden por contexto de proceso. Si gateway se ejecuta sin interfaz (LaunchAgent/SSH), ejecuta un comando interactivo una 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 y menciones
Sesiones y respuestas deterministas

channels.imessage.dmPolicy controla los mensajes directos:

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

Campo de allowlist: channels.imessage.allowFrom.Las entradas de la allowlist 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

Allowlist de remitentes de grupo: channels.imessage.groupAllowFrom.Respaldo 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 (incluso si channels.defaults.groupPolicy está configurado).Filtrado por menciones para grupos:

iMessage no tiene metadatos nativos de mención
la detección de menciones usa patrones regex (agents.list[].groupChat.mentionPatterns, con respaldo en messages.groupChat.mentionPatterns)
sin patrones configurados, el filtrado por menciones no puede aplicarse

Los comandos de control de remitentes autorizados pueden omitir el filtrado 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 hilo similar a 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 (filtrado de grupo + aislamiento de sesión de grupo).

Bindings de conversaciones ACP

Los chats heredados de iMessage también pueden vincularse a sesiones 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 ACP iniciada.
/new y /reset restablecen esa misma sesión ACP vinculada en su lugar.
/acp close cierra la sesión ACP y elimina el binding.

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

identificador normalizado de mensaje directo, como +15555550123 o user@example.com
chat_id:<id> (recomendado para bindings 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 Agentes ACP para el comportamiento compartido de los bindings ACP.

Patrones de implementación

Usuario bot dedicado de macOS (identidad de iMessage independiente)

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 script contenedor SSH para que OpenClaw pueda ejecutar imsg en el contexto de ese usuario.
Haz que channels.imessage.accounts.<id>.cliPath y .dbPath apunten a ese perfil de usuario.

La primera ejecución puede requerir aprobaciones en la GUI (Automation + Full Disk Access) en la sesión de ese usuario bot.

Mac remota por Tailscale (ejemplo)

Topología habitual:

gateway se ejecuta en Linux/VM
iMessage + imsg se ejecuta en una Mac de tu tailnet
el contenedor cliPath usa SSH para ejecutar imsg
remoteHost habilita la recuperación de archivos adjuntos por 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 la clave del host sea de confianza primero (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, configuración del historial y allowlists de raíces de archivos adjuntos.

Contenido multimedia, fragmentación y destinos de entrega

Archivos adjuntos y multimedia

la ingesta de archivos adjuntos entrantes es opcional: channels.imessage.includeAttachments
las rutas remotas de archivos adjuntos pueden recuperarse por SCP cuando remoteHost está configurado
las rutas de archivos 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 del contenido multimedia saliente usa channels.imessage.mediaMaxMb (16 MB de forma predeterminada)

Fragmentación saliente

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

Formatos de direccionamiento

Destinos explícitos preferidos:

chat_id:123 (recomendado para 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). Deshabilitar:

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

Solución de problemas

imsg no encontrado o RPC no 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.

Los mensajes directos se ignoran

Comprueba:

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

Los mensajes de grupo se ignoran

Comprueba:

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

Fallan los archivos adjuntos remotos

Comprueba:

channels.imessage.remoteHost
channels.imessage.remoteAttachmentRoots
autenticación por clave SSH/SCP desde el host gateway
la clave del host existe en ~/.ssh/known_hosts en el host gateway
legibilidad de la ruta remota en la 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 Full Disk Access y Automation estén concedidos para el contexto de proceso que ejecuta OpenClaw/imsg.

Punteros a la referencia de configuración

Relacionado

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

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

Bindings de conversaciones ACP

Patrones de implementación

Contenido multimedia, fragmentación y destinos de entrega

Escrituras de configuración

Solució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

​Bindings de conversaciones ACP

​Patrones de implementación

​Contenido multimedia, fragmentación y destinos de entrega

​Escrituras de configuración

​Solució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

Bindings de conversaciones ACP

Patrones de implementación

Contenido multimedia, fragmentación y destinos de entrega

Escrituras de configuración

Solución de problemas

Punteros a la referencia de configuración

Relacionado