Procedente de BlueBubbles

​

Lista de comprobación para la migración

1. Verificar imsg directamente en el Mac que ejecuta Messages.app (imsg chats, imsg history, imsg send, imsg rpc --help).
2. Copiar las claves de comportamiento de channels.bluebubbles a channels.imessage: dmPolicy, allowFrom, groupPolicy, groupAllowFrom, groups, includeAttachments, attachmentRoots, mediaMaxMb, textChunkLimit y actions.
3. Eliminar las claves de transporte que ya no existen: serverUrl, password, las URL de webhooks y la configuración del servidor de BlueBubbles.
4. Si el Gateway no se ejecuta en el Mac de Messages, establecer channels.imessage.cliPath en un contenedor SSH y configurar remoteHost para la obtención remota de archivos adjuntos.
5. Habilitar channels.imessage, reiniciar el Gateway y, a continuación, ejecutar openclaw channels status --probe --channel imessage.
6. Probar un mensaje directo, un grupo permitido, los archivos adjuntos si están habilitados y todas las acciones de la API privada que se espere que utilice el agente.
7. Eliminar el servidor de BlueBubbles y la configuración antigua de channels.bluebubbles después de verificar la ruta de iMessage.

​

Qué hace imsg

• Las lecturas proceden de ~/Library/Messages/chat.db mediante un identificador de SQLite de solo lectura.
• Los mensajes entrantes en tiempo real proceden de imsg watch / watch.subscribe, que sigue los eventos del sistema de archivos de chat.db con un mecanismo alternativo de sondeo.
• Los envíos utilizan la automatización de Messages.app para enviar texto normal y archivos.
• Las acciones avanzadas utilizan imsg launch para inyectar el asistente imsg en Messages.app. Esto habilita las confirmaciones de lectura, los indicadores de escritura, los envíos enriquecidos, la edición, la anulación de envíos, las respuestas en hilos, las reacciones, las encuestas y la gestión de grupos.
• Las compilaciones de Linux pueden inspeccionar una copia de chat.db, pero no pueden enviar mensajes, observar la base de datos activa del Mac ni controlar Messages.app. Para utilizar iMessage con OpenClaw, se debe ejecutar imsg en el Mac con la sesión iniciada o mediante un contenedor SSH que se conecte a ese Mac.

​

Antes de comenzar

1. Instalar imsg en el Mac que ejecuta Messages.app:
   brew install steipete/tap/imsg
   brew update && brew upgrade imsg
   imsg --version
   imsg chats --limit 3
   
   Para la configuración local habitual, la configuración de OpenClaw puede ofrecer una instalación o actualización de Homebrew de imsg confirmada por el usuario en el Mac con la sesión de Messages iniciada. La configuración manual y las topologías con contenedores SSH siguen estando administradas por el operador: se debe repetir la actualización de Homebrew en el mismo contexto de usuario local o remoto que ejecutará imsg. Si imsg chats falla con unable to open database file, no produce ninguna salida o muestra authorization denied, se debe conceder acceso total al disco al terminal, editor, proceso de Node, servicio Gateway o proceso principal de SSH que inicia imsg y, a continuación, volver a abrir ese proceso principal.
2. Verificar las superficies de lectura, observación, envío y RPC antes de cambiar la configuración de OpenClaw:
   imsg chats --limit 10 --json | jq -s
   imsg history --chat-id 42 --limit 10 --attachments --json | jq -s
   imsg watch --chat-id 42 --reactions --json
   imsg send --chat-id 42 --text "OpenClaw imsg test"
   imsg rpc --help
   
   Sustituir 42 por un identificador de chat real obtenido de imsg chats. El envío requiere permiso de automatización para Messages.app. Si OpenClaw se ejecutará mediante SSH, se deben ejecutar estos comandos a través del mismo contenedor SSH o contexto de usuario que utilizará OpenClaw. Si las lecturas funcionan, pero los envíos fallan con el error -1743 de AppleEvents, se debe comprobar si el permiso de automatización se concedió a /usr/libexec/sshd-keygen-wrapper; véase Los envíos mediante el contenedor SSH fallan con el error -1743 de AppleEvents.
3. Habilitar el puente de la API privada. Se recomienda encarecidamente para iMessage con OpenClaw, ya que las respuestas, las reacciones, los efectos, las encuestas, las respuestas a archivos adjuntos y las acciones de grupo dependen de él:
   imsg launch
   imsg status --json
   
   imsg launch requiere que SIP esté deshabilitado (y, en las versiones modernas de macOS, que la validación de bibliotecas esté flexibilizada; véase Habilitación de la API privada de imsg). El envío básico, el historial y la observación funcionan sin imsg launch; la superficie completa de acciones de iMessage de OpenClaw no.
4. Después de habilitar channels.imessage e iniciar el Gateway, verificar el puente mediante OpenClaw:
   openclaw channels status --probe
   
   La cuenta de iMessage debería indicar works; con --json, la carga útil de la comprobación incluye privateApi.available: true. Si indica false, se debe corregir primero; véase Detección de capacidades. La comprobación requiere un Gateway accesible (de lo contrario, la CLI recurre a una salida basada únicamente en la configuración) y solo comprueba las cuentas configuradas y habilitadas.
5. Crear una copia de la configuración:
   cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak
   

​

Traducción de la configuración

​

Riesgo del registro de grupos

1. Lista de remitentes u objetivos de chat permitidos (channels.imessage.groupAllowFrom): coincide con el identificador del remitente o con el objetivo del chat (entradas chat_id:, chat_guid:, chat_identifier:). Cuando groupAllowFrom no está establecido, este filtro recurre a allowFrom; un groupAllowFrom: [] explícito desactiva ese mecanismo alternativo y descarta todos los mensajes de grupo con groupPolicy: "allowlist".
2. Registro de grupos (channels.imessage.groups): usa como clave el chat_id numérico de iMessage:
   • Sin bloque groups (o con uno vacío): los grupos superan este filtro siempre que el filtro 1 tenga una lista efectiva de remitentes permitidos que no esté vacía; el filtrado de remitentes controla el acceso y no se activa ninguna advertencia de descarte total durante el inicio.
   • groups con entradas pero sin "*": solo se aceptan las claves chat_id indicadas. Incluir cualquier grupo convierte el registro en una lista de permitidos, incluso con groupPolicy: "open".
   • groups: { "*": { ... } }: todos los grupos superan este filtro.

• Una vez por cuenta durante el inicio, cuando se establece groupPolicy: "allowlist" y la lista efectiva de remitentes de grupo permitidos está vacía: imessage: groupPolicy="allowlist" for account "<id>" but no group sender allowlist is configured .... Establezca groupAllowFrom (o allowFrom) para admitir remitentes; añadir solo groups no satisface el filtro de remitentes.
• Una vez por chat_id durante la ejecución, cuando el registro descarta un grupo: imessage: dropping group message from chat_id=<id> ... not in channels.imessage.groups allowlist, indicando la clave exacta que debe añadirse.

{
  channels: {
    imessage: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15555550123", "chat_guid:any;-;..."],
    },
  },
}

​

Paso a paso

1. Traduzca la configuración. Mantenga el nuevo bloque desactivado mientras lo edita; el bloque antiguo channels.bluebubbles se ignora en la versión actual de OpenClaw y puede conservarse junto al nuevo como referencia:
   {
     channels: {
       imessage: {
         enabled: false, // cambie a true cuando esté listo para realizar la transición
         cliPath: "/opt/homebrew/bin/imsg",
         dmPolicy: "pairing",
         allowFrom: ["+15555550123"], // copie desde bluebubbles.allowFrom
         groupPolicy: "allowlist",
         groupAllowFrom: [], // copie desde bluebubbles.groupAllowFrom
         groups: { "*": { requireMention: true } }, // el comodín se copia literalmente; cambie las claves de las entradas por chat para usar chat_id
         // las acciones están activadas de forma predeterminada; establezca conmutadores individuales en false para desactivarlas
       },
     },
   }
   
2. Realice la transición y compruebe el funcionamiento. Establezca channels.imessage.enabled: true, reinicie el Gateway y confirme que el canal indique que funciona correctamente:
   openclaw gateway restart
   openclaw channels status --probe --channel imessage   # se espera "works"; --json muestra privateApi.available: true
   
   La comprobación requiere un Gateway accesible y solo comprueba las cuentas configuradas y habilitadas. Use los comandos directos imsg de Antes de empezar para validar el propio Mac.
3. Verifique los mensajes directos. Envíe un mensaje directo al agente y confirme que llega la respuesta.
4. Verifique los grupos por separado. Los mensajes directos y los grupos siguen rutas de código diferentes: que los mensajes directos funcionen no demuestra que los grupos se enruten correctamente. Envíe un mensaje en un chat grupal permitido y confirme que llega la respuesta. Si el grupo queda en silencio (sin respuesta del agente ni error), compruebe en el registro del Gateway las dos líneas warn de «Group registry footgun» más arriba. La advertencia de inicio significa que la lista efectiva de remitentes permitidos está vacía; una advertencia por chat_id significa que un registro groups con entradas no contiene ese chat.
5. Verifique las acciones disponibles. Desde un mensaje directo emparejado, pida al agente que añada una reacción, edite, anule el envío, responda, envíe una foto y, en un grupo, cambie el nombre del grupo o añada o elimine un participante. Cada acción debe reflejarse de forma nativa en Messages.app. Si alguna acción genera iMessage <action> requires the imsg private API bridge, vuelva a ejecutar imsg launch y actualice con openclaw channels status --probe.
6. Elimine el servidor BlueBubbles y el bloque channels.bluebubbles una vez verificados los mensajes directos, los grupos y las acciones de iMessage. OpenClaw no lee channels.bluebubbles.

​

Comparación rápida de acciones

​

Emparejamiento, sesiones y vinculaciones ACP

• Las listas de permitidos se conservan por identificador. channels.imessage.allowFrom reconoce las mismas cadenas +15555550123 / user@example.com que utilizaba BlueBubbles; cópielas literalmente.
• Las aprobaciones del almacén de emparejamiento no se transfieren. El almacén de emparejamiento es específico de cada canal y nada migra el antiguo almacén de BlueBubbles. Los remitentes aprobados únicamente mediante emparejamiento deben volver a emparejarse una vez en iMessage, o bien se deben añadir sus identificadores a allowFrom.
• Las sesiones siguen estando delimitadas por agente y chat. Los mensajes directos se agrupan en la sesión principal del agente con el valor predeterminado session.dmScope=main; las sesiones grupales permanecen aisladas por chat_id (agent:<agentId>:imessage:group:<chat_id>). El historial de conversaciones anterior asociado a claves de sesión de BlueBubbles no se transfiere a las sesiones de iMessage.
• Las vinculaciones ACP que hagan referencia a match.channel: "bluebubbles" deben cambiarse a "imessage". Los formatos match.peer.id (chat_id:, chat_guid:, chat_identifier:, identificador sin formato) son idénticos.

​

No existe un canal de reversión

​

Contenido relacionado

• Eliminación de BlueBubbles y la ruta de iMessage mediante imsg — anuncio breve y resumen para operadores.
• iMessage — referencia completa del canal iMessage, incluida la configuración de imsg launch y la detección de capacidades.
• /channels/bluebubbles — URL heredada que redirige a esta guía de migración.
• Emparejamiento — autenticación de mensajes directos y flujo de emparejamiento.
• Enrutamiento de canales — cómo el Gateway selecciona un canal para las respuestas salientes.