Integra iMessage con OpenClaw: Guía BlueBubbles

Plugin incluido

Las versiones actuales de OpenClaw incluyen BlueBubbles, por lo que las instalaciones empaquetadas normales no requieren un paso adicional de openclaw plugins install.

Descripción general

OpenClaw utiliza BlueBubbles para integrar iMessage mediante una API robusta y una configuración sencilla.

Se ejecuta en macOS a través de la aplicación auxiliar BlueBubbles (bluebubbles.app).
Recomendado/probado: macOS Sequoia (15). macOS Tahoe (26) funciona; la edición actualmente no funciona en Tahoe, y las actualizaciones de iconos de grupo pueden reportar éxito pero no sincronizarse.
OpenClaw se comunica a través de su API REST (GET /api/v1/ping, POST /message/text, POST /chat/:id/*).
Los mensajes entrantes llegan a través de webhook; las respuestas salientes, los indicadores de escritura, los recibos de lectura y los tapbacks son llamadas REST.
Los archivos adjuntos y stickers se ingieren como medios entrantes (y se muestran al agente cuando es posible).
El emparejamiento/lista de permitidos funciona de la misma manera que otros canales (/channels/pairing etc) con channels.bluebubbles.allowFrom + códigos de emparejamiento.
Las reacciones se muestran como eventos del sistema al igual que en Slack/Telegram para que los agentes puedan “mencionarlas” antes de responder.
Funciones avanzadas: editar, anular envío, hilos de respuesta, efectos de mensaje, gestión de grupos.

Inicio rápido

Instala el servidor BlueBubbles en tu Mac (sigue las instrucciones en bluebubbles.app/install).
En la configuración de BlueBubbles, habilita la API web y establece una contraseña.

Ejecuta openclaw onboard y selecciona BlueBubbles, o configúralo manualmente:

{
  channels: {
    bluebubbles: {
      enabled: true,
      serverUrl: "http://192.168.1.100:1234",
      password: "example-password",
      webhookPath: "/bluebubbles-webhook",
    },
  },
}

Apunta los webhook de BlueBubbles a tu Gateway (ejemplo: https://your-gateway-host:3000/bluebubbles-webhook?password=<password>).
Inicia el Gateway; registrará el manejador de webhook y comenzará el emparejamiento.

Nota de seguridad:

Establece siempre una contraseña para el webhook.
La autenticación de webhook siempre es obligatoria. OpenClaw rechaza las solicitudes de webhook de BlueBubbles a menos que incluyan una contraseña/guid que coincida con channels.bluebubbles.password (por ejemplo ?password=<password> o x-password), independientemente de la topología de loopback/proxy.
La autenticación por contraseña se verifica antes de leer/analizar los cuerpos completos del webhook.

Mantener Messages.app activo (configuraciones VM / headless)

Algunas configuraciones de macOS en máquinas virtuales o sistemas siempre encendidos pueden hacer que Messages.app entre en estado “inactivo” (los eventos entrantes se detienen hasta que la aplicación se abre o se pone en primer plano). Una solución sencilla es tocar Messages cada 5 minutos usando un AppleScript + LaunchAgent.

1) Guarda el AppleScript

Guárdalo como:

~/Scripts/poke-messages.scpt

Script de ejemplo (no interactivo; no roba el foco):

try
  tell application "Messages"
    if not running then
      launch
    end if

    -- Touch the scripting interface to keep the process responsive.
    set _chatCount to (count of chats)
  end tell
on error
  -- Ignore transient failures (first-run prompts, locked session, etc).
end try

2) Instala un LaunchAgent

Guárdalo como:

~/Library/LaunchAgents/com.user.poke-messages.plist

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>Label</key>
    <string>com.user.poke-messages</string>

    <key>ProgramArguments</key>
    <array>
      <string>/bin/bash</string>
      <string>-lc</string>
      <string>/usr/bin/osascript &quot;$HOME/Scripts/poke-messages.scpt&quot;</string>
    </array>

    <key>RunAtLoad</key>
    <true/>

    <key>StartInterval</key>
    <integer>300</integer>

    <key>StandardOutPath</key>
    <string>/tmp/poke-messages.log</string>
    <key>StandardErrorPath</key>
    <string>/tmp/poke-messages.err</string>
  </dict>
</plist>

Notas:

Esto se ejecuta cada 300 segundos y al iniciar sesión.
La primera ejecución puede activar avisos de Automatización de macOS (osascript → Messages). Aprúebalos en la misma sesión de usuario que ejecuta el LaunchAgent.

Cárgalo:

launchctl unload ~/Library/LaunchAgents/com.user.poke-messages.plist 2>/dev/null || true
launchctl load ~/Library/LaunchAgents/com.user.poke-messages.plist

AI Setup Assistant

Incorporación (Onboarding)

OpenClaw facilita la configuración de BlueBubbles mediante un asistente interactivo que te guía paso a paso.

Ejecuta el siguiente comando para iniciar el asistente:

openclaw onboard

El asistente te solicitará la siguiente información:

Server URL (obligatorio): La dirección de tu servidor BlueBubbles (por ejemplo, http://192.168.1.100:1234).
Password (obligatorio): La contraseña de la API desde la configuración del servidor BlueBubbles.
Webhook path (opcional): Por defecto es /bluebubbles-webhook.
DM policy: Define el comportamiento para mensajes directos (pairing, allowlist, open o disabled).
Allow list: Números de teléfono, correos electrónicos o destinos de chat permitidos.

También puedes añadir BlueBubbles directamente a través de la CLI:

openclaw channels add bluebubbles --http-url http://192.168.1.100:1234 --password <password>

Control de acceso (mensajes directos y grupos)

Puedes gestionar quién interactúa con tu agente configurando políticas de acceso tanto para mensajes directos como para grupos.

Para mensajes directos:

La configuración por defecto es channels.bluebubbles.dmPolicy = "pairing".
Los remitentes desconocidos reciben un código de vinculación; los mensajes se ignoran hasta que se aprueben (los códigos caducan tras 1 hora).
Aprueba el acceso mediante:
- openclaw pairing list bluebubbles
- openclaw pairing approve bluebubbles <CODE>
El emparejamiento es el intercambio de tokens predeterminado. Detalles: Pairing

Para grupos:

channels.bluebubbles.groupPolicy = open | allowlist | disabled (por defecto es allowlist).
channels.bluebubbles.groupAllowFrom controla quién puede activar al agente en grupos cuando se establece allowlist.

Enriquecimiento de nombres de contacto (macOS, opcional)

Los webhook de grupos de BlueBubbles a menudo solo incluyen direcciones de participantes sin procesar. Si prefieres que el contexto de GroupMembers muestre nombres de contactos locales, puedes activar esta función en macOS:

channels.bluebubbles.enrichGroupParticipantsFromContacts = true habilita la búsqueda. El valor por defecto es false.
Las búsquedas se ejecutan solo después de que el acceso al grupo, la autorización de comandos y el filtrado de menciones hayan permitido el mensaje.
Solo se enriquecen los participantes con número de teléfono sin nombre.
Los números de teléfono sin procesar permanecen como respaldo cuando no se encuentra ninguna coincidencia local.

{
  channels: {
    bluebubbles: {
      enrichGroupParticipantsFromContacts: true,
    },
  },
}

Filtrado de menciones (grupos)

BlueBubbles admite el filtrado de menciones para chats grupales, replicando el comportamiento de iMessage o WhatsApp:

Utiliza agents.list[].groupChat.mentionPatterns (o messages.groupChat.mentionPatterns) para detectar menciones.
Cuando requireMention está activado para un grupo, el agente solo responde si se le menciona.
Los comandos de control de remitentes autorizados omiten el filtrado de menciones.

Configuración por grupo:

{
  channels: {
    bluebubbles: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15555550123"],
      groups: {
        "*": { requireMention: true }, // default for all groups
        "iMessage;-;chat123": { requireMention: false }, // override for specific group
      },
    },
  },
}

Autorización de comandos

Los comandos de control (por ejemplo, /config, /model) requieren autorización.
Se utiliza allowFrom y groupAllowFrom para determinar la autorización de los comandos.
Los remitentes autorizados pueden ejecutar comandos de control incluso sin mencionar al agente en los grupos.

Vinculaciones de conversación ACP

Los chats de BlueBubbles pueden convertirse en espacios de trabajo ACP duraderos sin necesidad de cambiar la capa de transporte.

Flujo rápido para operadores:

Ejecuta /acp spawn codex --bind here dentro del mensaje directo o del chat grupal permitido.
Los mensajes futuros en esa misma conversación de BlueBubbles se dirigirán a la sesión ACP iniciada.
/new y /reset reinician la misma sesión ACP vinculada en el mismo lugar.
/acp close cierra la sesión ACP y elimina la vinculación.

Las vinculaciones persistentes configuradas también son compatibles a través de entradas de nivel superior bindings[] con type: "acp" y match.channel: "bluebubbles".

match.peer.id puede utilizar cualquier formato de destino de BlueBubbles compatible:

Identificador de mensaje directo normalizado como +15555550123 o user@example.com
chat_id:<id>
chat_guid:<guid>
chat_identifier:<identifier>

Para vinculaciones de grupo estables, prefiere chat_id:* o chat_identifier:*.

Ejemplo:

{
  agents: {
    list: [
      {
        id: "codex",
        runtime: {
          type: "acp",
          acp: { agent: "codex", backend: "acpx", mode: "persistent" },
        },
      },
    ],
  },
  bindings: [
    {
      type: "acp",
      agentId: "codex",
      match: {
        channel: "bluebubbles",
        accountId: "default",
        peer: { kind: "dm", id: "+15555550123" },
      },
      acp: { label: "codex-imessage" },
    },
  ],
}

Consulta ACP Agents para conocer el comportamiento de las vinculaciones ACP compartidas.

Indicadores de escritura y recibos de lectura

Indicadores de escritura: Se envían automáticamente antes y durante la generación de la respuesta.
Recibos de lectura: Controlados por channels.bluebubbles.sendReadReceipts (por defecto es true).
Indicadores de escritura: OpenClaw envía eventos de inicio de escritura; BlueBubbles borra el estado de escritura automáticamente al enviar o tras un tiempo de espera (la detención manual mediante DELETE no es fiable).

{
  channels: {
    bluebubbles: {
      sendReadReceipts: false, // disable read receipts
    },
  },
}

Acciones avanzadas

BlueBubbles admite acciones de mensajes avanzadas cuando las habilitas en la configuración. Con OpenClaw, puedes gestionar estas funciones de manera eficiente para mejorar la interacción con tu API de mensajería.

{
  channels: {
    bluebubbles: {
      actions: {
        reactions: true, // tapbacks (default: true)
        edit: true, // edit sent messages (macOS 13+, broken on macOS 26 Tahoe)
        unsend: true, // unsend messages (macOS 13+)
        reply: true, // reply threading by message GUID
        sendWithEffect: true, // message effects (slam, loud, etc.)
        renameGroup: true, // rename group chats
        setGroupIcon: true, // set group chat icon/photo (flaky on macOS 26 Tahoe)
        addParticipant: true, // add participants to groups
        removeParticipant: true, // remove participants from groups
        leaveGroup: true, // leave group chats
        sendAttachment: true, // send attachments/media
      },
    },
  },
}

Acciones disponibles:

react: Añadir o eliminar reacciones tapback (messageId, emoji, remove).
edit: Editar un mensaje enviado (messageId, text).
unsend: Cancelar el envío de un mensaje (messageId).
reply: Responder a un mensaje específico (messageId, text, to).
sendWithEffect: Enviar con un efecto de iMessage (text, to, effectId).
renameGroup: Cambiar el nombre de un chat grupal (chatGuid, displayName).
setGroupIcon: Establecer el icono o foto de un chat grupal (chatGuid, media) — puede fallar en macOS 26 Tahoe (la API puede devolver éxito pero el icono no se sincroniza).
addParticipant: Añadir a alguien a un grupo (chatGuid, address).
removeParticipant: Eliminar a alguien de un grupo (chatGuid, address).
leaveGroup: Abandonar un chat grupal (chatGuid).
upload-file: Enviar archivos o contenido multimedia (to, buffer, filename, asVoice).
- Notas de voz: establece asVoice: true con MP3 o CAF para enviar como un mensaje de voz de iMessage. BlueBubbles convierte MP3 a CAF al enviar notas de voz.
- Alias heredado: sendAttachment sigue funcionando, pero upload-file es el nombre de acción canónico.

IDs de mensaje (cortos vs completos)

OpenClaw puede mostrar IDs de mensaje cortos (por ejemplo, 1, 2) para ahorrar tokens.

MessageSid / ReplyToId pueden ser IDs cortos.
MessageSidFull / ReplyToIdFull contienen los IDs completos del proveedor.
Los IDs cortos residen en memoria; pueden expirar al reiniciar o por desalojo de caché.
Las acciones aceptan messageId corto o completo, pero los IDs cortos darán error si ya no están disponibles.

Usa IDs completos para automatizaciones duraderas y almacenamiento:

Plantillas: {{MessageSidFull}}, {{ReplyToIdFull}}.
Contexto: MessageSidFull / ReplyToIdFull en payloads de entrada.

Consulta la Configuración para ver las variables de plantilla.

Transmisión de bloques

Controla si las respuestas se envían como un mensaje único o si se transmiten en bloques mediante OpenClaw y el Gateway.

{
  channels: {
    bluebubbles: {
      blockStreaming: true, // enable block streaming (off by default)
    },
  },
}

Medios y límites

Gestionar archivos adjuntos y restricciones de tamaño es fundamental para mantener el rendimiento de tu integración. OpenClaw utiliza estos límites para asegurar que el procesamiento de mensajes sea eficiente y estable.

Los archivos adjuntos entrantes se descargan y almacenan en la caché de medios.
El límite de medios se controla mediante channels.bluebubbles.mediaMaxMb para archivos entrantes y salientes (el valor predeterminado es 8 MB).
El texto saliente se divide en fragmentos según channels.bluebubbles.textChunkLimit (el valor predeterminado es 4000 caracteres).

Referencia de configuración

Puedes ajustar el comportamiento de tu Gateway modificando los parámetros específicos en tu archivo de configuración. Para obtener una visión completa, consulta la Configuración.

Las opciones disponibles para el proveedor son:

channels.bluebubbles.enabled: Activa o desactiva el canal.
channels.bluebubbles.serverUrl: URL base de la API REST de BlueBubbles.
channels.bluebubbles.password: Contraseña de la API.
channels.bluebubbles.webhookPath: Ruta del endpoint del webhook (el valor predeterminado es /bluebubbles-webhook).
channels.bluebubbles.dmPolicy: pairing | allowlist | open | disabled (el valor predeterminado es pairing).
channels.bluebubbles.allowFrom: Lista blanca de mensajes directos (handles, correos electrónicos, números E.164, chat_id:*, chat_guid:*).
channels.bluebubbles.groupPolicy: open | allowlist | disabled (el valor predeterminado es allowlist).
channels.bluebubbles.groupAllowFrom: Lista blanca de remitentes para grupos.
channels.bluebubbles.enrichGroupParticipantsFromContacts: En macOS, permite enriquecer opcionalmente a los participantes de grupos sin nombre desde los contactos locales después de pasar el filtro. El valor predeterminado es false.
channels.bluebubbles.groups: Configuración por grupo (requireMention, etc.).
channels.bluebubbles.sendReadReceipts: Envía confirmaciones de lectura (el valor predeterminado es true).
channels.bluebubbles.blockStreaming: Activa el streaming de bloques (el valor predeterminado es false; necesario para respuestas en streaming).
channels.bluebubbles.textChunkLimit: Tamaño de fragmento saliente en caracteres (el valor predeterminado es 4000).
channels.bluebubbles.sendTimeoutMs: Tiempo de espera por solicitud en ms para envíos de texto salientes a través de /api/v1/message/text (el valor predeterminado es 30000). Auméntalo en configuraciones de macOS 26 donde los envíos de iMessage mediante API privada pueden bloquearse durante más de 60 segundos dentro del framework de iMessage; por ejemplo, usa 45000 o 60000. Las pruebas, búsquedas de chat, reacciones, ediciones y comprobaciones de estado mantienen actualmente el valor predeterminado más corto de 10s; se planea ampliar la cobertura a reacciones y ediciones próximamente. Sustitución por cuenta: channels.bluebubbles.accounts.<accountId>.sendTimeoutMs.
channels.bluebubbles.chunkMode: length (predeterminado) divide solo cuando se excede el textChunkLimit; newline divide en líneas en blanco (límites de párrafo) antes de aplicar el límite de longitud.
channels.bluebubbles.mediaMaxMb: Límite de medios entrantes/salientes en MB (el valor predeterminado es 8).
channels.bluebubbles.mediaLocalRoots: Lista blanca explícita de directorios locales absolutos permitidos para rutas de medios locales salientes. Los envíos de rutas locales están denegados por defecto a menos que se configure esto. Sustitución por cuenta: channels.bluebubbles.accounts.<accountId>.mediaLocalRoots.
channels.bluebubbles.historyLimit: Máximo de mensajes de grupo para contexto (0 lo deshabilita).
channels.bluebubbles.dmHistoryLimit: Límite de historial de mensajes directos.
channels.bluebubbles.actions: Activa o desactiva acciones específicas.
channels.bluebubbles.accounts: Configuración para múltiples cuentas.

Opciones globales relacionadas:

agents.list[].groupChat.mentionPatterns (o messages.groupChat.mentionPatterns).
messages.responsePrefix.

AI Setup Assistant

Destinos de direccionamiento / entrega

Es mejor usar chat_guid para obtener un enrutamiento estable en tus integraciones con OpenClaw y sus destinos de entrega.

chat_guid:iMessage;-;+15555550123 (preferido para grupos)
chat_id:123
chat_identifier:...
Identificadores directos: +15555550123, user@example.com
- Si un identificador directo no tiene un chat de mensaje directo existente, OpenClaw creará uno mediante POST /api/v1/chat/new. Esto requiere que la API privada de BlueBubbles esté habilitada.

Seguridad

Para mantener tus datos protegidos, debes tratar las credenciales de tu API y los endpoints de webhook con el máximo cuidado, como si fueran contraseñas de acceso.

Las solicitudes de webhook se autentican comparando los parámetros de consulta o encabezados guid/password contra channels.bluebubbles.password.
Mantén la contraseña de la API y el endpoint del webhook en secreto (trátalos como credenciales).
No existe una omisión de localhost para la autenticación de webhook de BlueBubbles. Si utilizas un proxy para el tráfico del webhook, mantén la contraseña de BlueBubbles en la solicitud de extremo a extremo. gateway.trustedProxies no reemplaza a channels.bluebubbles.password en este caso. Consulta la seguridad del Gateway.
Habilita HTTPS y reglas de firewall en el servidor de BlueBubbles si lo expones fuera de tu red local (LAN).

Solución de problemas

Si notas que los eventos de escritura o lectura dejan de funcionar, revisa los registros del webhook de BlueBubbles y verifica que la ruta del Gateway coincida con channels.bluebubbles.webhookPath.

Los códigos de emparejamiento caducan después de una hora; utiliza openclaw pairing list bluebubbles y openclaw pairing approve bluebubbles <code>.
Las reacciones requieren la API privada de BlueBubbles (POST /api/v1/message/react); asegúrate de que la versión del servidor la exponga.
La edición y eliminación de mensajes requieren macOS 13+ y una versión compatible del servidor BlueBubbles. En macOS 26 (Tahoe), la edición no funciona actualmente debido a cambios en la API privada.
Las actualizaciones de iconos de grupo pueden ser inestables en macOS 26 (Tahoe): la API puede devolver éxito, pero el nuevo icono no se sincroniza.
OpenClaw oculta automáticamente las acciones que se sabe que están rotas según la versión de macOS del servidor BlueBubbles. Si la edición sigue apareciendo en macOS 26 (Tahoe), desactívala manualmente con channels.bluebubbles.actions.edit=false.
Para obtener información sobre el estado o la salud del sistema, usa openclaw status —all o openclaw status —deep.

Para obtener información general sobre el flujo de trabajo de los canales, consulta Channels y la guía de Plugins.

Documentación relacionada

Channels Overview — todos los canales compatibles
Pairing — autenticación de mensajes directos y flujo de emparejamiento
Groups — comportamiento de chats grupales y control de menciones
Channel Routing — enrutamiento de sesiones para mensajes
Security — modelo de acceso y endurecimiento de seguridad

AI Setup Assistant

OpenClaw Expert

Sigues atascado?

Si esta pagina no resolvio tu caso, pregunta a OpenClaw Expert para pasos concretos.