¿Por qué necesito un Mac para BlueBubbles?

iMessage es un servicio exclusivo de Apple que requiere macOS y un Apple ID. BlueBubbles se ejecuta en el Mac para acceder directamente al framework de Messages. No hay forma de conectarse a iMessage sin un Mac — un Mac Mini dedicado o una VM macOS es la configuración típica para operación permanente.

¿Cuál es la diferencia entre BlueBubbles y el antiguo canal iMessage?

BlueBubbles usa una API REST moderna con soporte webhook, ofreciendo funciones ricas como reacciones tapback, edición de mensajes, efectos y gestión de grupos. El antiguo canal iMessage (imsg CLI) está obsoleto y tiene funcionalidad limitada. BlueBubbles es el enfoque recomendado para todas las nuevas integraciones de iMessage.

¿BlueBubbles requiere la API privada?

La mensajería de texto básica funciona sin la API privada, pero las funciones avanzadas como reacciones tapback, edición de mensajes, eliminación, gestión de grupos y envío de efectos requieren habilitar la API privada de BlueBubbles. Se recomienda habilitarla para el conjunto completo de funciones.

¿Puedo usar BlueBubbles con múltiples Apple IDs?

Cada instancia del servidor BlueBubbles está vinculada a un Apple ID. Si necesitas conectar múltiples Apple IDs, necesitarás instancias Mac separadas ejecutando BlueBubbles, cada una configurada como una cuenta diferente en OpenClaw.

¿Qué pasa si mi Mac se desconecta?

Si el Mac que ejecuta BlueBubbles se desconecta, los iMessages entrantes se pondrán en cola en los servidores de Apple. Cuando el Mac vuelva a estar en línea, los mensajes en cola serán entregados. Sin embargo, los eventos webhook durante el tiempo de inactividad se pierden — el Gateway no recibirá esas notificaciones. Los mensajes durante la inactividad aparecerán en Messages.app pero no activarán respuestas de IA.

¿Cómo funcionan los códigos de emparejamiento?

Cuando dmPolicy es 'pairing' (predeterminado), los remitentes desconocidos reciben un código de emparejamiento aleatorio al enviar su primer mensaje. El código expira después de 1 hora. Aprueba con 'openclaw pairing approve bluebubbles ' en tu terminal. Una vez aprobado, el remitente puede chatear libremente sin verificación adicional.

OpenClaw GuideOpenClaw

Comenzar

Canal BlueBubbles de OpenClaw

Mensajería

Medio

Conecta OpenClaw a iMessage a través de la API REST de BlueBubbles. Esta integración convierte tu Mac en una pasarela iMessage — instala la aplicación servidor BlueBubbles, habilita la API Web, y tu asistente de IA podrá enviar y recibir mensajes iMessage, reacciones tapback y archivos adjuntos multimedia. BlueBubbles es el canal iMessage recomendado, reemplazando el antiguo enfoque imsg CLI.

Info rápida

DificultadMedio

CategoríaMensajería

Funciones compatibles4 / 6

BlueBubbles Funciones compatibles

Mensajes de texto

Compatible

Medios y archivos

Compatible

Reacciones

Compatible

Hilos

No compatible

Mensajes de voz

No compatible

Chat grupal

Compatible

BlueBubbles Requisitos previos

Un Mac con macOS High Sierra (10.13) o posterior (Ventura 13+ recomendado para todas las funciones; Tahoe 26 compatible con limitaciones)
Aplicación servidor BlueBubbles instalada desde bluebubbles.app
API Web habilitada con contraseña establecida en la configuración de BlueBubbles
OpenClaw Gateway en ejecución y configurado

BlueBubbles Configuración rápida

Instalar el servidor BlueBubbles en tu Mac

Descarga e instala la aplicación servidor BlueBubbles desde bluebubbles.app/install. Inicia la aplicación, inicia sesión con tu Apple ID y completa la configuración inicial. Asegúrate de que iMessage funcione correctamente en el Mac.

Habilitar la API Web

En la configuración del servidor BlueBubbles, habilita la API Web/REST y establece una contraseña segura. Anota la URL del servidor (ej. http://localhost:1234) — la necesitarás para la configuración de OpenClaw.

Añadir la configuración del canal BlueBubbles

Ejecuta 'openclaw onboard' y selecciona BlueBubbles, o añade manualmente la configuración del canal en ~/.openclaw/openclaw.json con tu serverUrl y password. Configura el webhookPath si es necesario.

Configurar webhook y probar

Apunta los webhooks de BlueBubbles a tu Gateway: https://your-gateway-host:3000/bluebubbles-webhook?password=<password>. Inicia el Gateway y envía un iMessage de prueba para verificar la conexión. Si usas la política de emparejamiento, aprueba al remitente con 'openclaw pairing approve bluebubbles <code>'.

BlueBubbles Ejemplo de configuración

config.json

{
  "channels": {
    "bluebubbles": {
      "enabled": true,
      "serverUrl": "http://localhost:1234",
      "password": "YOUR_BLUEBUBBLES_PASSWORD",
      "webhookPath": "/bluebubbles-webhook",
      "dmPolicy": "pairing"
    }
  }
}

BlueBubbles Documentación Detallada

Descripción de la arquitectura

OpenClaw se conecta a iMessage a través de la aplicación servidor BlueBubbles ejecutándose en un Mac. BlueBubbles expone una API REST que el Gateway utiliza para enviar mensajes, reacciones y gestionar chats. Los mensajes entrantes se entregan mediante webhooks — BlueBubbles envía los eventos de nuevos mensajes al endpoint webhook del Gateway. El flujo de arquitectura es: iMessage llega al Mac → Servidor BlueBubbles → Webhook push al Gateway → OpenClaw procesa con IA → Llamada API REST a BlueBubbles → iMessage entregado. Este enfoque requiere un Mac permanentemente en línea (físico o VM), ya que iMessage es un servicio exclusivo de Apple. El Mac actúa como puente entre el ecosistema de mensajería de Apple y tu asistente OpenClaw.

Un Mac Mini dedicado o una VM macOS es ideal para ejecutar BlueBubbles como pasarela iMessage permanente.

BlueBubbles soporta la API privada para funciones avanzadas como reacciones tapback, edición de mensajes y eliminación — asegúrate de activarla en la configuración de BlueBubbles.

Configuración del servidor BlueBubbles

Configurar BlueBubbles requiere instalar la aplicación servidor en tu Mac: 1. Descarga BlueBubbles desde bluebubbles.app/install e inicia la aplicación. 2. Inicia sesión con tu Apple ID y verifica que iMessage funcione en el Mac. 3. Habilita la API Web/REST en la configuración de BlueBubbles. 4. Establece una contraseña API segura — esta contraseña autentica todas las solicitudes API y entregas webhook. 5. Anota la URL del servidor mostrada en la aplicación (por defecto: http://localhost:1234). 6. Opcional: habilita la API privada para funciones avanzadas (reacciones, edición, eliminación). El servidor debe permanecer en ejecución para que el puente iMessage funcione. Configura BlueBubbles para inicio automático para mayor fiabilidad.

webhook URL

# Formato de URL webhook para tu Gateway
https://your-gateway-host:3000/bluebubbles-webhook?password=YOUR_PASSWORD

Mantén tu contraseña API de BlueBubbles segura. Si el servidor está expuesto en la red, habilita HTTPS en BlueBubbles y usa reglas de firewall para restringir el acceso. Los proxys inversos en el mismo host evitan la autenticación por contraseña — añade autenticación a nivel de proxy y configura gateway.trustedProxies.

Políticas de DM

Las políticas de DM (Mensaje Directo) controlan quién puede interactuar con tu asistente de IA a través de iMessage. OpenClaw soporta cuatro políticas: • pairing (predeterminado) — Los remitentes desconocidos reciben un código de emparejamiento con tiempo limitado (expira después de 1 hora). Aprueba o rechaza con 'openclaw pairing approve bluebubbles <CODE>'. Una vez aprobado, pueden chatear libremente. • allowlist — Solo los números de teléfono y direcciones de correo electrónico en allowFrom pueden enviar mensajes. Los demás son ignorados silenciosamente. Formato E.164 soportado para números de teléfono. • open — Cualquiera que envíe un mensaje recibe respuesta. Usar con precaución. • disabled — El procesamiento de DM está completamente desactivado.

openclaw.json

{
  "channels": {
    "bluebubbles": {
      "dmPolicy": "allowlist",
      "allowFrom": ["+15551234567", "user@example.com"]
    }
  }
}

El campo allowFrom acepta tanto números de teléfono (formato E.164, ej: +15551234567) como direcciones de correo electrónico para enrutamiento iMessage.

Gestión de chats grupales

OpenClaw soporta chats grupales de iMessage a través de BlueBubbles con control de acceso flexible: • groupPolicy controla quién puede activar el bot en chats grupales: - open — Cualquier miembro del grupo puede interactuar - allowlist — Solo las direcciones de groupAllowFrom pueden activar - disabled (predeterminado) — Los mensajes de grupo son ignorados • Detección de mención — Cuando requireMention es true (predeterminado para grupos), el bot solo responde cuando es mencionado. Los patrones de mención se configuran en agents.list[].groupChat.mentionPatterns. • Configuración por grupo — Usa el objeto groups para establecer reglas requireMention diferentes para chats específicos.

openclaw.json

{
  "channels": {
    "bluebubbles": {
      "groupPolicy": "allowlist",
      "groupAllowFrom": ["+15551234567"],
      "groups": {
        "iMessage;+;chat123456": {
          "requireMention": false
        }
      }
    }
  }
}

Acciones y efectos de iMessage

BlueBubbles expone un rico conjunto de acciones nativas de iMessage a través de la API privada. Cada acción puede activarse/desactivarse individualmente: • reactions — Enviar y recibir reacciones tapback (corazón, pulgar arriba, pulgar abajo, risa, énfasis, pregunta) • edit — Modificar mensajes enviados (requiere macOS 13+; actualmente roto en macOS Tahoe) • unsend — Eliminar mensajes enviados (macOS 13+) • reply — Hilos de mensajes por GUID • sendWithEffect — Enviar mensajes con efectos de burbuja (slam, fuerte, suave, tinta invisible, etc.) • sendAttachment — Enviar archivos multimedia y memos de voz (formato MP3/CAF para voz; BlueBubbles maneja la conversión MP3→CAF) Acciones de gestión de grupo: • renameGroup — Renombrar chats grupales • setGroupIcon — Establecer foto de grupo (inestable en macOS Tahoe) • addParticipant / removeParticipant / leaveGroup — Gestionar miembros del grupo

openclaw.json

{
  "channels": {
    "bluebubbles": {
      "actions": {
        "reactions": true,
        "edit": true,
        "unsend": true,
        "reply": true,
        "sendWithEffect": true,
        "sendAttachment": true
      }
    }
  }
}

En macOS Tahoe (26), la acción edit está actualmente rota debido a cambios en la API privada, y setGroupIcon no es confiable (la API devuelve éxito pero el icono no se sincroniza). Si ejecutas Tahoe, desactiva estas acciones manualmente.

Entrega y fragmentación de mensajes

OpenClaw ofrece entrega configurable por fragmentos para respuestas largas de IA: • textChunkLimit — Caracteres máximos por fragmento de mensaje (predeterminado: 4000). iMessage no tiene un límite estricto, pero los mensajes demasiado largos pueden no mostrarse bien en todos los dispositivos. • chunkMode — Controla el método de fragmentación del texto: - length (predeterminado) — División forzada en textChunkLimit caracteres - newline — División en límites de párrafo para una lectura más natural • blockStreaming — Cuando es true, las respuestas se envían en bloques durante la generación, sin esperar la respuesta completa. Los acuses de lectura se envían por defecto para mantener un flujo de conversación natural. Los indicadores de escritura se envían automáticamente antes y durante la generación de respuestas de IA.

openclaw.json

{
  "channels": {
    "bluebubbles": {
      "textChunkLimit": 4000,
      "chunkMode": "newline",
      "blockStreaming": false,
      "sendReadReceipts": true
    }
  }
}

Medios y archivos adjuntos

BlueBubbles soporta el envío y recepción de medios a través de iMessage: • Los archivos adjuntos entrantes son descargados y almacenados en caché automáticamente por el Gateway. El tamaño máximo de archivo entrante se controla con mediaMaxMb (predeterminado: 8 MB). • Los memos de voz se pueden enviar con la acción sendAttachment usando asVoice: true. BlueBubbles convierte automáticamente MP3 a CAF para reproducción nativa de memos de voz en iMessage. • Los medios salientes se envían mediante la acción sendAttachment con los parámetros buffer, filename y tipo mime opcional.

Para memos de voz, usa formato MP3 o CAF. BlueBubbles convertirá MP3 a CAF automáticamente para reproducción nativa en iMessage.

Ajusta mediaMaxMb si necesitas manejar adjuntos más grandes — el valor predeterminado de 8 MB cubre la mayoría de fotos y videos cortos.

Gestión de ID de mensaje

BlueBubbles utiliza dos tipos de identificadores de mensaje: • IDs cortos — Tokens temporales en memoria (como 1, 2, 3). Rápidos pero efímeros. Expiran al reiniciar el Gateway o al limpiar la caché. • IDs completos — Identificadores de proveedor persistentes (MessageSidFull, ReplyToIdFull). Sobreviven a los reinicios y son estables para referencias a largo plazo. Ambos formatos se aceptan en los parámetros de acción (messageId, replyTo, etc.). Para automatizaciones duraderas que necesiten referenciar mensajes entre reinicios, usa siempre IDs completos.

Usa IDs de mensaje completos para cualquier automatización que necesite sobrevivir a reinicios del Gateway. Los IDs cortos son convenientes para uso interactivo pero se invalidan después de un reinicio.

Direccionamiento y enrutamiento

BlueBubbles soporta múltiples formatos de direccionamiento para la entrega de mensajes. Orden de enrutamiento preferido por estabilidad: 1. chat_guid — Formato más estable: chat_guid:iMessage;-;+15555550123 2. chat_id — Identificador numérico de chat: chat_id:123 3. chat_identifier — Cadena de identificador de chat 4. Direcciones directas — Número de teléfono (+15555550123) o correo electrónico (user@example.com) Al enviar a una dirección directa sin chat existente, BlueBubbles crea automáticamente un nuevo DM mediante POST /api/v1/chat/new (requiere API privada).

Usa el formato chat_guid en automatizaciones para el enrutamiento de mensajes más confiable.

Seguridad y autenticación webhook

BlueBubbles autentica las entregas webhook con la contraseña configurada. El Gateway verifica que el parámetro de contraseña (vía query string o cabecera) coincida con la configuración channels.bluebubbles.password. Consideraciones de seguridad: • Las solicitudes localhost son automáticamente confiables y omiten la verificación de contraseña. • Los proxys inversos en el mismo host también omiten la verificación — si usas un proxy inverso en la misma máquina, añade autenticación a nivel de proxy y configura gateway.trustedProxies. • Habilita HTTPS en el servidor BlueBubbles para cifrar las comunicaciones. • Usa reglas de firewall para restringir el acceso externo al puerto API de BlueBubbles. Para despliegues en producción, usa siempre HTTPS y asegúrate de que el endpoint webhook no sea accesible públicamente sin autenticación.

Los proxys inversos en el mismo host omiten la autenticación por contraseña de BlueBubbles. Al usar un proxy inverso, configura siempre la autenticación a nivel de proxy y establece gateway.trustedProxies.

Mantener activo Messages.app (Headless/VM)

Si ejecutas BlueBubbles en un Mac headless o VM, Messages.app puede entrar en modo inactivo y dejar de procesar mensajes. La solución es configurar un LaunchAgent que ejecute un AppleScript cada 5 minutos para tocar la interfaz de scripting de Messages. Este script de mantenimiento ignora de forma segura los errores transitorios y no roba el foco de otras aplicaciones. Es esencial para el funcionamiento fiable sin supervisión del puente iMessage. Configura un plist de macOS LaunchAgent para ejecutar el AppleScript periódicamente y mantener la capacidad de respuesta de Messages.app.

Esto solo es necesario para entornos headless/VM. Si tu Mac tiene una sesión de escritorio activa con Messages.app visible, el mantenimiento no es necesario.

Usa launchctl para gestionar el LaunchAgent — cárgalo al arrancar para operación completamente sin supervisión.

BlueBubbles Referencia de Configuración

Key	Type	Default	Description
enabled	boolean	false	Activar o desactivar el canal BlueBubbles
serverUrl	string	""	URL base de la API REST de BlueBubbles (ej: http://localhost:1234)
password	string	""	Contraseña API de BlueBubbles para autenticación
webhookPath	string	"/bluebubbles-webhook"	Ruta del endpoint webhook para recibir mensajes entrantes
dmPolicy	string	"pairing"	Controla quién puede enviar DM al bot. Opciones: pairing, allowlist, open, disabled
allowFrom	string[]	[]	Números de teléfono y correos autorizados para enviar mensajes (formato E.164 para teléfonos)
groupPolicy	string	"allowlist"	Política de chat grupal. Opciones: open, allowlist, disabled
groupAllowFrom	string[]	[]	Direcciones de remitentes autorizados para activar el bot en chats grupales
sendReadReceipts	boolean	true	Enviar confirmación de lectura al procesar mensajes
blockStreaming	boolean	false	Habilitar streaming de respuesta por bloques en lugar de esperar la respuesta completa
textChunkLimit	number	4000	Caracteres máximos por fragmento de mensaje de texto saliente
chunkMode	string	"length"	Modo de fragmentación de texto. Opciones: length (por tamaño), newline (por párrafo)
mediaMaxMb	number	8	Tamaño máximo de archivos adjuntos entrantes en megabytes
historyLimit	number	-	Máximo de mensajes de grupo incluidos como contexto de IA (0 para desactivar)
dmHistoryLimit	number	-	Límite de historial de conversación DM para contexto de IA
actions.reactions	boolean	true	Habilitar reacciones tapback (requiere API privada)
actions.edit	boolean	true	Habilitar edición de mensajes (requiere macOS 13+; roto en Tahoe)
actions.unsend	boolean	true	Habilitar eliminación de mensajes (requiere macOS 13+)
actions.reply	boolean	true	Habilitar hilos de mensajes por GUID
actions.sendWithEffect	boolean	true	Habilitar efectos de burbuja iMessage (slam, fuerte, suave, etc.)
actions.sendAttachment	boolean	true	Habilitar entrega de medios y memos de voz

enabled

Type: booleanDefault: false

Activar o desactivar el canal BlueBubbles

serverUrl

Type: stringDefault: ""

URL base de la API REST de BlueBubbles (ej: http://localhost:1234)

password

Type: stringDefault: ""

Contraseña API de BlueBubbles para autenticación

webhookPath

Type: stringDefault: "/bluebubbles-webhook"

Ruta del endpoint webhook para recibir mensajes entrantes

dmPolicy

Type: stringDefault: "pairing"

Controla quién puede enviar DM al bot. Opciones: pairing, allowlist, open, disabled

allowFrom

Type: string[]Default: []

Números de teléfono y correos autorizados para enviar mensajes (formato E.164 para teléfonos)

groupPolicy

Type: stringDefault: "allowlist"

Política de chat grupal. Opciones: open, allowlist, disabled

groupAllowFrom

Type: string[]Default: []

Direcciones de remitentes autorizados para activar el bot en chats grupales

sendReadReceipts

Type: booleanDefault: true

Enviar confirmación de lectura al procesar mensajes

blockStreaming

Type: booleanDefault: false

Habilitar streaming de respuesta por bloques en lugar de esperar la respuesta completa

textChunkLimit

Type: numberDefault: 4000

Caracteres máximos por fragmento de mensaje de texto saliente

chunkMode

Type: stringDefault: "length"

Modo de fragmentación de texto. Opciones: length (por tamaño), newline (por párrafo)

mediaMaxMb

Type: numberDefault: 8

Tamaño máximo de archivos adjuntos entrantes en megabytes

historyLimit

Type: numberDefault: -

Máximo de mensajes de grupo incluidos como contexto de IA (0 para desactivar)

dmHistoryLimit

Type: numberDefault: -

Límite de historial de conversación DM para contexto de IA

actions.reactions

Type: booleanDefault: true

Habilitar reacciones tapback (requiere API privada)

actions.edit

Type: booleanDefault: true

Habilitar edición de mensajes (requiere macOS 13+; roto en Tahoe)

actions.unsend

Type: booleanDefault: true

Habilitar eliminación de mensajes (requiere macOS 13+)

actions.reply

Type: booleanDefault: true

Habilitar hilos de mensajes por GUID

actions.sendWithEffect

Type: booleanDefault: true

Habilitar efectos de burbuja iMessage (slam, fuerte, suave, etc.)

actions.sendAttachment

Type: booleanDefault: true

Habilitar entrega de medios y memos de voz

BlueBubbles Preguntas Frecuentes

BlueBubbles Solución de Problemas

El webhook no recibe mensajes

La URL del webhook en BlueBubbles no coincide con el endpoint del Gateway, o el parámetro de contraseña es incorrecto.

Verifica que la URL del webhook esté establecida en https://your-gateway-host:3000/bluebubbles-webhook?password=YOUR_PASSWORD. Comprueba que channels.bluebubbles.webhookPath coincida con la ruta en la URL. Revisa los logs del Gateway para intentos de webhook entrantes.

El Gateway se conecta pero las acciones fallan (reacciones, edición, eliminación)

La API privada de BlueBubbles no está habilitada, o la versión del servidor no soporta los endpoints API requeridos.

Habilita la API privada en la configuración del servidor BlueBubbles. Actualiza BlueBubbles a la última versión. Si acciones específicas fallan en macOS Tahoe, desactívalas individualmente: channels.bluebubbles.actions.edit=false.

Messages.app deja de responder en Mac headless

Messages.app entra en modo inactivo en configuraciones headless/VM y deja de procesar la interfaz de scripting.

Configura el LaunchAgent de mantenimiento AppleScript para tocar la interfaz de scripting de Messages cada 5 minutos. Asegúrate de que el LaunchAgent esté cargado vía launchctl y se ejecute al arrancar.

Los mensajes del bot no son iMessages (burbujas verdes)

El número de teléfono o correo del destinatario no está registrado en iMessage, o el Apple ID en el Mac tiene iMessage desactivado.

Verifica que iMessage esté habilitado en las preferencias de Messages.app en el Mac. Comprueba que el destinatario use un dispositivo Apple con iMessage habilitado. Las burbujas verdes indican fallback a SMS, que BlueBubbles puede no soportar según la configuración.

La acción de edición falla en macOS Tahoe

Problema conocido — macOS Tahoe (26) rompió el endpoint de la API privada para edición de mensajes.

Desactiva la acción de edición: establece channels.bluebubbles.actions.edit en false. Esta es una limitación conocida de BlueBubbles en Tahoe. Vigila las versiones de BlueBubbles para una corrección.

Ver documentación completa Volver a todos los canales