Si vienes de BlueBubbles

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.

​

Cuándo tiene sentido esta migración

• Ya ejecutas imsg en el mismo Mac (o en uno accesible mediante SSH) donde Messages.app tiene sesión iniciada.
• Quieres una pieza menos que mantener: sin servidor de BlueBubbles separado, sin endpoint REST que autenticar, sin configuración de Webhook. Un único binario de CLI en lugar de un servidor + aplicación cliente + auxiliar.
• Estás en una versión compatible de macOS / imsg donde la prueba de la API privada informa available: true.

​

Qué hace imsg

• Las lecturas provienen de ~/Library/Messages/chat.db mediante un manejador 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 alternativa de sondeo.
• Los envíos usan la automatización de Messages.app para texto normal y envíos de archivos.
• Las acciones avanzadas usan imsg launch para inyectar el auxiliar imsg en Messages.app. Eso es lo que habilita confirmaciones de lectura, indicadores de escritura, envíos enriquecidos, edición, anulación de envío, respuesta en hilo, tapbacks y gestión de grupos.
• Las compilaciones de Linux pueden inspeccionar una copia de chat.db, pero no pueden enviar, observar la base de datos activa del Mac ni controlar Messages.app. Para iMessage en OpenClaw, ejecuta imsg en el Mac con sesión iniciada o mediante un wrapper 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 de SSH que lanza 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
   
   Sustituye 42 por un id de chat real obtenido de imsg chats. El envío requiere permiso de Automatización para Messages.app. Si OpenClaw se ejecutará mediante SSH, ejecuta estos comandos con el mismo wrapper SSH o contexto de usuario que usará OpenClaw.
3. Habilita el puente de API privada cuando necesites acciones avanzadas:
   imsg launch
   imsg status --json
   
   imsg launch requiere que SIP esté desactivado. El envío básico, el historial y la observación funcionan sin imsg launch; las acciones avanzadas no.
4. Verifica el puente mediante OpenClaw:
   openclaw channels status --probe
   
   Busca imessage.privateApi.available: true. Si informa false, corrige eso primero; consulta Detección de capacidades.
5. Haz una instantánea de tu configuración:
   cp ~/.openclaw/openclaw.json5 ~/.openclaw/openclaw.json5.bak
   

​

Traducción de configuración

​

Riesgo del registro de grupos

1. Lista de permitidos de remitente / destino de chat (channels.imessage.groupAllowFrom): verificada por isAllowedIMessageSender. Coincide con mensajes entrantes por identificador de remitente, chat_guid, chat_identifier o chat_id. Misma forma que BlueBubbles.
2. Registro de grupos (channels.imessage.groups): verificado por resolveChannelGroupPolicy desde inbound-processing.ts:199. Con groupPolicy: "allowlist", esta puerta requiere:
   • una entrada comodín groups: { "*": { ... } } (establece allowAll = true), o
   • una entrada explícita por chat_id bajo groups.

• Un warn único al inicio por cuenta cuando groupPolicy: "allowlist" está configurado pero channels.imessage.groups está vacío (sin comodín "*", sin entradas por chat_id), emitido antes de que llegue cualquier mensaje.
• Un warn único por chat_id la primera vez que un grupo específico se descarta en tiempo de ejecución, nombrando el chat_id y la clave exacta que debe agregarse a groups para permitirlo.

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

​

Paso a paso

1. Agrega un bloque de iMessage junto al bloque existente de BlueBubbles. Mantén el bloque anterior solo como fuente de copia hasta verificar la nueva ruta:
   {
     channels: {
       bluebubbles: {
         enabled: true,
         // ... existing config ...
       },
       imessage: {
         enabled: false, // turn on after the dry run below
         cliPath: "/opt/homebrew/bin/imsg",
         dmPolicy: "pairing",
         allowFrom: ["+15555550123"], // copy from bluebubbles.allowFrom
         groupPolicy: "allowlist",
         groupAllowFrom: [], // copy from bluebubbles.groupAllowFrom
         groups: { "*": { requireMention: true } }, // copy from bluebubbles.groups — silently drops groups if missing, see "Group registry footgun" above
         actions: {
           reactions: true,
           edit: true,
           unsend: true,
           reply: true,
           sendWithEffect: true,
           sendAttachment: true,
         },
       },
     },
   }
   
2. Prueba en seco: inicia el Gateway y confirma que iMessage se reporta como saludable:
   openclaw gateway
   openclaw channels status
   openclaw channels status --probe   # expect imessage.privateApi.available: true
   
   Como imessage.enabled todavía es false, aún no se enruta tráfico entrante de iMessage, pero --probe ejercita el puente para que detectes problemas de permisos o instalación antes de la transición.
3. Haz la transición. Elimina la configuración de BlueBubbles y habilita iMessage en una sola edición de configuración:
   {
     channels: {
       imessage: { enabled: true /* ... */ },
     },
   }
   
   Reinicia el Gateway. El tráfico entrante de iMessage ahora fluye a través del Plugin incluido.
4. Verifica los DM. Envía al agente un mensaje directo; confirma que llegue la respuesta.
5. Verifica los grupos por separado. Los DM y los grupos toman rutas de código diferentes; que los DM funcionen no prueba que los grupos se estén enrutando. Envía al agente un mensaje en un chat grupal emparejado y confirma que llegue la respuesta. Si el grupo queda en silencio (sin respuesta del agente, sin error), revisa el log del Gateway para ver si aparece imessage: dropping group message from chat_id=<id> o la línea de inicio imessage: groupPolicy="allowlist" but channels.imessage.groups is empty; ambas se emiten en el nivel de log predeterminado. Si aparece cualquiera de las dos, tu bloque groups falta o está vacío; consulta “Problema del registro de grupos” arriba.
6. Verifica la superficie de acciones: desde un DM emparejado, pide al agente que reaccione, edite, anule el envío, responda, envíe una foto y (en un grupo) cambie el nombre del grupo / agregue o quite un participante. Cada acción debería llegar de forma nativa a Messages.app. Si alguna lanza “iMessage <action> requires the imsg private API bridge”, ejecuta imsg launch de nuevo y actualiza channels status --probe.
7. Elimina el servidor y la configuración de BlueBubbles una vez verificados los DM, los grupos y las acciones de iMessage. OpenClaw no usará channels.bluebubbles.

​

Paridad de acciones de un vistazo

​

Emparejamiento, sesiones y vinculaciones de ACP

• Las aprobaciones de emparejamiento se conservan por identificador. No necesitas volver a aprobar remitentes conocidos: channels.imessage.allowFrom reconoce las mismas cadenas +15555550123 / user@example.com que usaba BlueBubbles.
• Las sesiones permanecen delimitadas por agente + chat. Los DM se agrupan en la sesión principal del agente bajo el valor predeterminado session.dmScope=main; las sesiones de grupo permanecen aisladas por chat_id. Las claves de sesión difieren (agent:<id>:imessage:group:<chat_id> frente al equivalente de BlueBubbles): el historial de conversación anterior bajo claves de sesión de BlueBubbles no se transfiere a las sesiones de iMessage.
• Las vinculaciones de ACP que referencian match.channel: "bluebubbles" deben actualizarse a "imessage". Las formas de match.peer.id (chat_id:, chat_guid:, chat_identifier:, identificador sin prefijo) son idénticas.

​

Sin canal de reversión

​

Relacionado

• iMessage — referencia completa del canal de 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 DM y flujo de emparejamiento.
• Enrutamiento de canales — cómo el Gateway elige un canal para las respuestas salientes.