BlueBubbles

Status: Plugin legado incluído que se comunica com o servidor macOS do BlueBubbles por HTTP. Configurações existentes do BlueBubbles continuam funcionando, mas novas implantações do OpenClaw iMessage devem preferir o Plugin nativo iMessage quando seus requisitos forem adequados ao seu host.

# Visão geral

• Executa no macOS por meio do aplicativo auxiliar BlueBubbles (bluebubbles.app).
• Fallback legado para instalações que já dependem de IDs de canal do BlueBubbles, estado de Webhook, destinos de grupo, entrega por Cron ou roteamento de workspace.
• Recomendado/testado: macOS Sequoia (15). macOS Tahoe (26) funciona; a edição está atualmente quebrada no Tahoe, e atualizações de ícone de grupo podem relatar sucesso, mas não sincronizar.
• O OpenClaw se comunica com ele por meio de sua API REST (GET /api/v1/ping, POST /message/text, POST /chat/:id/*).
• Mensagens recebidas chegam por Webhooks; respostas enviadas, indicadores de digitação, confirmações de leitura e tapbacks são chamadas REST.
• Anexos e stickers são ingeridos como mídia de entrada (e expostos ao agente quando possível).
• Respostas Auto-TTS que sintetizam áudio MP3 ou CAF são entregues como balões de memorando de voz do iMessage em vez de anexos de arquivo comuns.
• O pareamento/lista de permissão funciona da mesma forma que outros canais (/channels/pairing etc.) com channels.bluebubbles.allowFrom + códigos de pareamento.
• Reações são expostas como eventos de sistema, assim como Slack/Telegram, para que agentes possam "mencioná-las" antes de responder.
• Recursos avançados: editar, cancelar envio, encadeamento de respostas, efeitos de mensagem, gerenciamento de grupos.

# Início rápido

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

# Mantendo o Messages.app ativo (configurações de VM / headless)

Algumas configurações de VM macOS / sempre ativas podem acabar com o Messages.app ficando "ocioso" (eventos recebidos param até que o app seja aberto/colocado em primeiro plano). Uma solução alternativa simples é tocar o Messages a cada 5 minutos usando um AppleScript + LaunchAgent.

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

<?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>

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

# Onboarding

O BlueBubbles está disponível no onboarding interativo:

openclaw onboard

O assistente solicita:

Você também pode adicionar o BlueBubbles via CLI:

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

# Controle de acesso (DMs + grupos)

# Enriquecimento de nome de contato (macOS, opcional)

Webhooks de grupo do BlueBubbles frequentemente incluem apenas endereços brutos dos participantes. Se você quiser que o contexto GroupMembers mostre nomes de contatos locais em vez disso, pode optar por enriquecimento local de Contatos no macOS:

• channels.bluebubbles.enrichGroupParticipantsFromContacts = true habilita a consulta. Padrão: false.
• As consultas são executadas somente depois que acesso ao grupo, autorização de comando e gating de menção permitiram a passagem da mensagem.
• Somente participantes por telefone sem nome são enriquecidos.
• Números de telefone brutos permanecem como fallback quando nenhuma correspondência local é encontrada.

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

# Gating de menção (grupos)

O BlueBubbles oferece suporte a gating de menção para chats em grupo, correspondendo ao comportamento do iMessage/WhatsApp:

• Usa agents.list[].groupChat.mentionPatterns (ou messages.groupChat.mentionPatterns) para detectar menções.
• Quando requireMention está habilitado para um grupo, o agente responde somente quando mencionado.
• Comandos de controle de remetentes autorizados ignoram o gating de menção.

Configuração por grupo:

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

# Gating de comandos

• Comandos de controle (por exemplo, /config, /model) exigem autorização.
• Usa allowFrom e groupAllowFrom para determinar a autorização de comando.
• Remetentes autorizados podem executar comandos de controle mesmo sem mencionar em grupos.

# Prompt de sistema por grupo

Cada entrada em channels.bluebubbles.groups.* aceita uma string systemPrompt opcional. O valor é injetado no prompt de sistema do agente em cada turno que processa uma mensagem nesse grupo, para que você possa definir persona ou regras comportamentais por grupo sem editar prompts de agente:

{
  channels: {
    bluebubbles: {
      groups: {
        "iMessage;-;chat123": {
          systemPrompt: "Keep responses under 3 sentences. Mirror the group's casual tone.",
        },
      },
    },
  },
}

A chave corresponde ao que o BlueBubbles relata como chatGuid / chatIdentifier / chatId numérico para o grupo, e uma entrada curinga "*" fornece um padrão para cada grupo sem correspondência exata (o mesmo padrão usado por requireMention e políticas de ferramenta por grupo). Correspondências exatas sempre vencem o curinga. DMs ignoram este campo; use personalização de prompt no nível do agente ou da conta em vez disso.

# Exemplo prático: respostas encadeadas e reações tapback (API privada)

Com a API privada do BlueBubbles habilitada, mensagens recebidas chegam com IDs curtos de mensagem (por exemplo, [[reply_to:5]]) e o agente pode chamar action=reply para encadear em uma mensagem específica ou action=react para adicionar um tapback. Um systemPrompt por grupo é uma forma confiável de manter o agente escolhendo a ferramenta certa:

{
  channels: {
    bluebubbles: {
      groups: {
        "iMessage;+;chat-family": {
          systemPrompt: "When replying in this group, always call action=reply with the [[reply_to:N]] messageId from context so your response threads under the triggering message. Never send a new unlinked message. For short acknowledgements ('ok', 'got it', 'on it'), use action=react with an appropriate tapback emoji (❤️, 👍, 😂, ‼️, ❓) instead of sending a text reply.",
        },
      },
    },
  },
}

Reações tapback e respostas encadeadas exigem a API privada do BlueBubbles; consulte Ações avançadas e IDs de mensagem para a mecânica subjacente.

# Bindings de conversa ACP

Chats do BlueBubbles podem ser transformados em workspaces ACP duráveis sem alterar a camada de transporte.

Fluxo rápido de operador:

• Execute /acp spawn codex --bind here dentro da DM ou do chat em grupo permitido.
• Mensagens futuras nessa mesma conversa do BlueBubbles são roteadas para a sessão ACP gerada.
• /new e /reset redefinem a mesma sessão ACP vinculada no lugar.
• /acp close fecha a sessão ACP e remove o binding.

Bindings persistentes configurados também são compatíveis por meio de entradas de nível superior bindings[] com type: "acp" e match.channel: "bluebubbles".

match.peer.id pode usar qualquer forma de destino compatível do BlueBubbles:

• identificador de DM normalizado, como +15555550123 ou [email protected]
• chat_id:<id>
• chat_guid:<guid>
• chat_identifier:<identifier>

Para vínculos de grupo estáveis, prefira chat_id:* ou chat_identifier:*.

Exemplo:

{
  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" },
    },
  ],
}

Consulte Agentes ACP para o comportamento compartilhado de vínculo ACP.

# Digitação + confirmações de leitura

• Indicadores de digitação: Enviados automaticamente antes e durante a geração da resposta.
• Confirmações de leitura: Controladas por channels.bluebubbles.sendReadReceipts (padrão: true).
• Indicadores de digitação: O OpenClaw envia eventos de início de digitação; o BlueBubbles limpa a digitação automaticamente ao enviar ou após tempo limite (a parada manual via DELETE não é confiável).

{
  channels: {
    bluebubbles: {
      sendReadReceipts: false, // desativar confirmações de leitura
    },
  },
}

# Ações avançadas

O BlueBubbles oferece suporte a ações avançadas de mensagem quando habilitadas na configuração:

{
  channels: {
    bluebubbles: {
      actions: {
        reactions: true, // tapbacks (padrão: true)
        edit: true, // editar mensagens enviadas (macOS 13+, quebrado no macOS 26 Tahoe)
        unsend: true, // desfazer envio de mensagens (macOS 13+)
        reply: true, // encadeamento de respostas por GUID da mensagem
        sendWithEffect: true, // efeitos de mensagem (slam, loud etc.)
        renameGroup: true, // renomear conversas em grupo
        setGroupIcon: true, // definir ícone/foto da conversa em grupo (instável no macOS 26 Tahoe)
        addParticipant: true, // adicionar participantes a grupos
        removeParticipant: true, // remover participantes de grupos
        leaveGroup: true, // sair de conversas em grupo
        sendAttachment: true, // enviar anexos/mídia
      },
    },
  },
}

# IDs de mensagem (curtos vs. completos)

O OpenClaw pode expor IDs de mensagem curtos (por exemplo, 1, 2) para economizar tokens.

• MessageSid / ReplyToId podem ser IDs curtos.
• MessageSidFull / ReplyToIdFull contêm os IDs completos do provedor.
• IDs curtos ficam em memória; eles podem expirar ao reiniciar ou por remoção do cache.
• As ações aceitam messageId curto ou completo, mas IDs curtos gerarão erro se não estiverem mais disponíveis.

Use IDs completos para automações e armazenamento duráveis:

• Modelos: {{MessageSidFull}}, {{ReplyToIdFull}}
• Contexto: MessageSidFull / ReplyToIdFull em payloads de entrada

Consulte Configuração para variáveis de modelo.

# Agrupamento de DMs de envio dividido (comando + URL em uma composição)

Quando um usuário digita um comando e uma URL juntos no iMessage - por exemplo, Dump https://example.com/article - a Apple divide o envio em duas entregas de Webhook separadas:

1. Uma mensagem de texto ("Dump").
2. Um balão de prévia de URL ("https://...") com imagens de prévia OG como anexos.

Os dois webhooks chegam ao OpenClaw com ~0,8-2,0 s de diferença na maioria das configurações. Sem agrupamento, o agente recebe apenas o comando no turno 1, responde (geralmente "envie a URL") e só vê a URL no turno 2 - momento em que o contexto do comando já foi perdido.

channels.bluebubbles.coalesceSameSenderDms opta uma DM por mesclar webhooks consecutivos do mesmo remetente em um único turno do agente. Conversas em grupo continuam a usar a chave por mensagem para preservar a estrutura de turnos com vários usuários.

{
  channels: {
    bluebubbles: {
      coalesceSameSenderDms: true, // optar por habilitar (padrão: false)
    },
  },
}

{
  messages: {
    inbound: {
      byChannel: {
        // 2500 ms funciona para a maioria das configurações; aumente para 4000 ms se o seu Mac estiver lento
        // ou sob pressão de memória (a lacuna observada pode passar de 2 s nesses casos).
        bluebubbles: 2500,
      },
    },
  },
}

# Cenários e o que o agente vê

# Solução de problemas de agrupamento de envio dividido

Se a flag estiver ativada e envios divididos ainda chegarem como dois turnos, verifique cada camada:

grep coalesceSameSenderDms ~/.openclaw/openclaw.json

grep -E "Dispatching event to webhook" main.log | tail -20

# Streaming em blocos

Controle se as respostas são enviadas como uma única mensagem ou transmitidas em blocos:

{
  channels: {
    bluebubbles: {
      blockStreaming: true, // habilitar streaming em blocos (desativado por padrão)
    },
  },
}

# Mídia + limites

• Anexos de entrada são baixados e armazenados no cache de mídia.
• Limite de mídia via channels.bluebubbles.mediaMaxMb para mídia de entrada e saída (padrão: 8 MB).
• O texto de saída é dividido em blocos conforme channels.bluebubbles.textChunkLimit (padrão: 4000 caracteres).

# Referência de configuração

Configuração completa: Configuração

Opções globais relacionadas:

• agents.list[].groupChat.mentionPatterns (ou messages.groupChat.mentionPatterns).
• messages.responsePrefix.

# Endereçamento / destinos de entrega

Prefira chat_guid para roteamento estável:

• chat_guid:iMessage;-;+15555550123 (preferido para grupos)
• chat_id:123
• chat_identifier:...
• Identificadores diretos: +15555550123, [email protected]
  • Se um identificador direto não tiver um chat de DM existente, o OpenClaw criará um via POST /api/v1/chat/new. Isto exige que a Private API do BlueBubbles esteja habilitada.

# Roteamento iMessage vs SMS

Quando o mesmo identificador tem tanto um chat do iMessage quanto um chat SMS no Mac (por exemplo, um número de telefone registrado no iMessage que também recebeu fallbacks de balão verde), o OpenClaw prefere o chat do iMessage e nunca rebaixa silenciosamente para SMS. Para forçar o chat SMS, use um prefixo de destino sms: explícito (por exemplo, sms:+15555550123). Identificadores sem um chat do iMessage correspondente ainda enviam por qualquer chat que o BlueBubbles informar.

# Segurança

• Solicitações de Webhook são autenticadas comparando parâmetros de consulta ou cabeçalhos guid/password com channels.bluebubbles.password.
• Mantenha a senha da API e o endpoint de Webhook em segredo (trate-os como credenciais).
• Não há bypass de localhost para autenticação de Webhook do BlueBubbles. Se você encaminhar tráfego de Webhook por proxy, mantenha a senha do BlueBubbles na solicitação de ponta a ponta. gateway.trustedProxies não substitui channels.bluebubbles.password aqui. Consulte Segurança do Gateway.
• Habilite HTTPS + regras de firewall no servidor BlueBubbles se o expuser fora da sua LAN.

# Solução de problemas

• Se eventos de digitação/leitura pararem de funcionar, verifique os logs de Webhook do BlueBubbles e confirme se o caminho do Gateway corresponde a channels.bluebubbles.webhookPath.
• Códigos de pareamento expiram após uma hora; use openclaw pairing list bluebubbles e openclaw pairing approve bluebubbles <code>.
• Reações exigem a API privada do BlueBubbles (POST /api/v1/message/react); certifique-se de que a versão do servidor a exponha.
• Editar/desfazer envio exige macOS 13+ e uma versão compatível do servidor BlueBubbles. No macOS 26 (Tahoe), a edição está atualmente quebrada devido a mudanças na API privada.
• Atualizações de ícone de grupo podem ser instáveis no macOS 26 (Tahoe): a API pode retornar sucesso, mas o novo ícone não sincroniza.
• O OpenClaw oculta automaticamente ações conhecidamente quebradas com base na versão de macOS do servidor BlueBubbles. Se a edição ainda aparecer no macOS 26 (Tahoe), desabilite-a manualmente com channels.bluebubbles.actions.edit=false.
• coalesceSameSenderDms habilitado, mas envios divididos (por exemplo, Dump + URL) ainda chegam como duas vezes: consulte a lista de verificação de solução de problemas de combinação de envios divididos - causas comuns são uma janela de debounce curta demais, timestamps do log de sessão interpretados incorretamente como chegada de Webhook ou um envio com citação de resposta (que usa replyToBody, não um segundo Webhook).
• Para informações de status/integridade: openclaw status --all ou openclaw status --deep.

Para referência geral do fluxo de trabalho de canais, consulte Canais e o guia de Plugins.

# Relacionados

• Roteamento de canais - roteamento de sessão para mensagens
• Visão geral dos canais - todos os canais compatíveis
• Grupos - comportamento de chat em grupo e filtragem por menção
• Pareamento - autenticação de DM e fluxo de pareamento
• Segurança - modelo de acesso e reforço de segurança