Viniendo de BlueBubbles

​

Lista de verificación de migración

1. Verifica imsg directamente en el Mac que ejecuta Messages.app (imsg chats, imsg history, imsg send, imsg rpc --help).
2. Copia las claves de comportamiento de channels.bluebubbles a channels.imessage: dmPolicy, allowFrom, groupPolicy, groupAllowFrom, groups, includeAttachments, attachmentRoots, mediaMaxMb, textChunkLimit, coalesceSameSenderDms y actions.
3. Elimina las claves de transporte que ya no existen: serverUrl, password, URL de Webhook y configuración del servidor BlueBubbles.
4. Si el Gateway no se ejecuta en el Mac de Messages, define channels.imessage.cliPath como un contenedor SSH y define remoteHost para la obtención remota de adjuntos.
5. Habilita channels.imessage, reinicia el Gateway y luego ejecuta openclaw channels status --probe --channel imessage.
6. Prueba un MD, un grupo permitido, adjuntos si están habilitados y cada acción de API privada que esperas que use el agente.
7. Elimina el servidor BlueBubbles y la configuración antigua de channels.bluebubbles después de verificar la ruta de iMessage.

​

Qué hace imsg

• Las lecturas provienen de ~/Library/Messages/chat.db usando un identificador SQLite de solo lectura.
• Los mensajes entrantes en vivo provienen de imsg watch / watch.subscribe, que sigue los eventos del sistema de archivos de chat.db con una reserva de sondeo.
• Los envíos usan automatización de Messages.app para envíos normales de texto y archivos.
• Las acciones avanzadas usan imsg launch para inyectar el helper de imsg en Messages.app. Eso desbloquea confirmaciones de lectura, indicadores de escritura, envíos enriquecidos, edición, anulación de envío, respuesta en hilo, tapbacks, encuestas y administración de grupos.
• Las compilaciones de Linux pueden inspeccionar un chat.db copiado, pero no pueden enviar, observar la base de datos del Mac en vivo ni controlar Messages.app. Para iMessage en OpenClaw, ejecuta imsg en el Mac con sesión iniciada o mediante un contenedor SSH hacia ese Mac.

​

Antes de empezar

1. Instala imsg en el Mac que ejecuta Messages.app:
   brew install steipete/tap/imsg
   imsg --version
   imsg chats --limit 3
   
   Si imsg chats falla con unable to open database file, salida vacía o authorization denied, concede Acceso total al disco al terminal, editor, proceso de Node, servicio Gateway o proceso padre SSH que inicia imsg, y luego vuelve a abrir ese proceso padre.
2. Verifica 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
   
   Reemplaza 42 por un id de chat real de imsg chats. Enviar requiere permiso de automatización para Messages.app. Si OpenClaw se ejecutará a través de SSH, ejecuta estos comandos mediante el mismo contenedor SSH o contexto de usuario que usará OpenClaw. Si las lecturas funcionan pero los envíos fallan con AppleEvents -1743, comprueba si Automation terminó en /usr/libexec/sshd-keygen-wrapper; consulta Los envíos del contenedor SSH fallan con AppleEvents -1743.
3. Habilita el puente de API privada cuando necesites acciones avanzadas:
   imsg launch
   imsg status --json
   
   imsg launch requiere que SIP esté deshabilitado (y en macOS moderno, que la validación de bibliotecas esté relajada; consulta Habilitar la API privada de imsg). El envío básico, el historial y la observación funcionan sin imsg launch; las acciones avanzadas no.
4. Después de habilitar channels.imessage e iniciar el Gateway, verifica el puente a través de OpenClaw:
   openclaw channels status --probe
   
   La cuenta de iMessage debería informar works; con --json, la carga útil de la sonda incluye privateApi.available: true. Si informa false, corrige eso primero; consulta Detección de capacidades. El sondeo necesita un Gateway accesible (si no, la CLI recurre a una salida solo de configuración) y solo sondea cuentas configuradas y habilitadas.
5. Toma una instantánea de tu configuración:
   cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak
   

​

Traducción de configuración

​

Trampa del registro de grupos

1. Lista de permitidos de remitente / destino de chat (channels.imessage.groupAllowFrom): coincide con el identificador del remitente o el destino del chat (entradas chat_id:, chat_guid:, chat_identifier:). Cuando groupAllowFrom no está definido, esta puerta recurre a allowFrom; un groupAllowFrom: [] explícito desactiva esa alternativa y descarta todos los mensajes de grupo bajo groupPolicy: "allowlist".
2. Registro de grupos (channels.imessage.groups): indexado por el chat_id numérico de iMessage:
   • Sin bloque groups (o con uno vacío): los grupos pasan esta puerta siempre que la puerta 1 tenga una lista efectiva no vacía de remitentes permitidos; el filtrado de remitentes gobierna el acceso y no se emite ninguna advertencia de inicio que descarte todo.
   • groups con entradas pero sin "*": solo pasan las claves chat_id enumeradas. Enumerar cualquier grupo convierte el registro en una lista de permitidos incluso bajo groupPolicy: "open".
   • groups: { "*": { ... } }: todos los grupos pasan esta puerta.

• Una vez por cuenta al iniciar, cuando groupPolicy: "allowlist" está configurado 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 .... Configura groupAllowFrom (o allowFrom) para admitir remitentes; agregar solo groups no satisface la puerta de remitente.
• Una vez por chat_id en tiempo de 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 debes agregar.

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

​

Paso a paso

1. Traduce la configuración. Mantén el bloque nuevo deshabilitado mientras editas; el bloque antiguo channels.bluebubbles es ignorado por el OpenClaw actual y puede quedarse junto a él como referencia:
   {
     channels: {
       imessage: {
         enabled: false, // flip to true when ready to cut over
         cliPath: "/opt/homebrew/bin/imsg",
         dmPolicy: "pairing",
         allowFrom: ["+15555550123"], // copy from bluebubbles.allowFrom
         groupPolicy: "allowlist",
         groupAllowFrom: [], // copy from bluebubbles.groupAllowFrom
         groups: { "*": { requireMention: true } }, // wildcard copies verbatim; re-key per-chat entries by chat_id
         // actions default to enabled; set individual toggles false to disable
       },
     },
   }
   
2. Migra y prueba. Configura channels.imessage.enabled: true, reinicia el Gateway y confirma que el canal informa que está en buen estado:
   openclaw gateway restart
   openclaw channels status --probe --channel imessage   # expect "works"; --json shows privateApi.available: true
   
   La prueba requiere un Gateway accesible y solo prueba cuentas configuradas y habilitadas. Usa los comandos directos de imsg en Antes de empezar para validar el Mac en sí.
3. Verifica los DM. Envía al agente un mensaje directo; confirma que llega la respuesta.
4. Verifica los grupos por separado. Los DM y los grupos usan rutas de código distintas; que los DM funcionen no demuestra que los grupos estén enrutando. Envía un mensaje en un chat de grupo permitido y confirma que llega la respuesta. Si el grupo queda en silencio (sin respuesta del agente, sin error), revisa el registro del gateway para ver las dos líneas warn de “Group registry footgun” anteriores. La advertencia de arranque significa que la lista efectiva de remitentes permitidos está vacía; una advertencia por chat_id significa que un registro groups con contenido no contiene ese chat.
5. Verifica la superficie de acciones. Desde un DM emparejado, pide al agente que reaccione, edite, cancele el envío, responda, envíe una foto y (en un grupo) cambie el nombre del grupo o agregue/elimine un participante. Cada acción debería llegar de forma nativa a Messages.app. Si alguna acción lanza iMessage <action> requires the imsg private API bridge, ejecuta imsg launch de nuevo y actualiza con openclaw channels status --probe.
6. Elimina el servidor BlueBubbles y el bloque channels.bluebubbles una vez que se hayan verificado los DM, grupos y acciones de iMessage. OpenClaw no lee channels.bluebubbles.

​

Paridad de acciones de un vistazo

​

Emparejamiento, sesiones y enlaces ACP

• Las listas de permitidos se transfieren por handle. channels.imessage.allowFrom reconoce las mismas cadenas +15555550123 / user@example.com que usaba BlueBubbles; cópialas tal cual.
• Las aprobaciones del almacén de emparejamiento no se transfieren. El almacén de emparejamiento es por canal y nada migra el antiguo almacén de BlueBubbles. Los remitentes que fueron aprobados solo mediante emparejamiento deben emparejarse una vez más en iMessage, o puedes agregar sus handles a allowFrom.
• Las sesiones permanecen delimitadas por agente + chat. Los DM se colapsan en la sesión principal del agente bajo el valor predeterminado session.dmScope=main; las sesiones de grupo permanecen aisladas por chat_id (agent:<agentId>:imessage:group:<chat_id>). El historial de conversación antiguo bajo claves de sesión de BlueBubbles no se traslada a las sesiones de iMessage.
• Los enlaces ACP que referencian match.channel: "bluebubbles" deben cambiar a "imessage". Las formas de match.peer.id (chat_id:, chat_guid:, chat_identifier:, handle simple) son idénticas.

​

Sin canal de reversión

​

Relacionado

• Eliminación de BlueBubbles y la ruta imsg de iMessage — 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 por DM y flujo de emparejamiento.
• Enrutamiento de canales — cómo el gateway elige un canal para las respuestas salientes.